mudlet-map-editor 0.1.0

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

@@ -0,0 +1,100 @@
+import type { MapRenderer } from 'mudlet-map-renderer';
+import type { MudletMap } from '../mapIO';
+import type { Direction, HitItem, LabelResizeHandle } from './types';
+import type { EditorMapReader } from './reader/EditorMapReader';
+/**
+ * Hit-test map labels. Labels are axis-aligned rects. Returns the topmost label
+ * (last in the list, rendered on top) whose render-space rect contains (mapX, mapY).
+ * MapData.Label stores X/Y in Mudlet space; render position is (X, -Y).
+ */
+export declare function labelAt(areaId: number, z: number, mapX: number, mapY: number, reader: EditorMapReader): {
+    id: number;
+    areaId: number;
+} | null;
+/**
+ * Like labelAt but returns ALL labels whose rect contains (mapX, mapY), in
+ * draw order (topmost — last in the list — is last in the returned array).
+ */
+export declare function allLabelsAt(areaId: number, z: number, mapX: number, mapY: number, reader: EditorMapReader): {
+    id: number;
+    areaId: number;
+}[];
+/**
+ * Returns ALL elements under (mapX, mapY) in visual-priority order:
+ *   1. All rooms occupying the same grid cell (stacked rooms)
+ *   2. All overlapping labels (topmost first)
+ *   3. Custom line (if any)
+ *   4. Exit (if any)
+ * Used for Alt+click cycling and the right-click disambiguate menu.
+ */
+export declare function allHitsAt(renderer: MapRenderer, map: MudletMap, areaId: number, z: number, mapX: number, mapY: number, roomSize: number, reader: EditorMapReader): HitItem[];
+/**
+ * 8 handle positions relative to a label's padded selection rect.
+ * Returns the handle under the cursor, or null.
+ * `hitRadius` is the capture radius in map units (typically 8px worth of units).
+ */
+export declare function labelResizeHandleAt(bounds: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, mapX: number, mapY: number, hitRadius: number): LabelResizeHandle | null;
+/** Does any room occupy the exact raw grid cell (x, y, z) on the given area? */
+export declare function roomAtCell(map: MudletMap, areaId: number, x: number, y: number, z: number): import("mudlet-map-binary-reader").MudletRoom | null;
+/**
+ * 8 handle offsets (signs relative to room centre, each scaled by roomSize/2).
+ * Used both for hit-testing and for rendering the ConnectHandlesEffect.
+ */
+export declare const HANDLE_OFFSETS: ReadonlyArray<readonly [number, number, Direction]>;
+/**
+ * Given a cursor in render space and a room's render-space centre, return
+ * which handle direction the cursor is pointing at. Assumes the caller has
+ * already established the cursor is within the room's hit-test region — this
+ * function just maps the angular offset to one of 8 sectors, so there is
+ * never a "body" / null result and the direction transitions smoothly around
+ * the room.
+ */
+export declare function handleDirFor(cursor: {
+    x: number;
+    y: number;
+}, roomCentre: {
+    x: number;
+    y: number;
+}, _roomSize: number): Direction;
+/**
+ * Hit-test an inter-room exit against the geometry the renderer actually
+ * drew. Walks every polyline segment of every drawn exit's `lines` and
+ * `arrows` so dashed lines, one-way arrows, cross-z stubs, and the
+ * renderer's suppression rules (e.g. both-sides-customLine two-ways) are
+ * honoured by construction — we never hover an exit that wasn't rendered.
+ */
+export declare function exitAt(renderer: MapRenderer, mapX: number, mapY: number, roomSize: number): {
+    fromId: number;
+    toId: number;
+    dir: Direction;
+} | null;
+/**
+ * Hit-test a custom line polyline against the geometry the renderer drew.
+ * `points` on each drawn entry already mirror what went to the canvas —
+ * including the prepended room-centre segment — so stroke style doesn't
+ * matter; we just walk segments.
+ */
+export declare function customLineAt(renderer: MapRenderer, mapX: number, mapY: number, roomSize: number): {
+    roomId: number;
+    exitName: string;
+} | null;
+/**
+ * Hit-test a line segment of a specific custom line. Returns the raw-points
+ * index at which a new waypoint should be inserted so it lands on the clicked
+ * segment (between waypoint `insertIndex - 1` and `insertIndex`). Waypoint
+ * handles are skipped — caller should check `customLinePointAt` first.
+ */
+export declare function customLineSegmentAt(renderer: MapRenderer, roomId: number, exitName: string, mapX: number, mapY: number, roomSize: number): {
+    insertIndex: number;
+} | null;
+/**
+ * Hit-test a waypoint handle on a specific custom line. Returns the 0-based
+ * index into the *raw* customLine.points array (which excludes the
+ * renderer-prepended room centre), or null.
+ */
+export declare function customLinePointAt(renderer: MapRenderer, roomId: number, exitName: string, mapX: number, mapY: number, roomSize: number): number | null;

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

@@ -0,0 +1,12 @@
+import type { LabelSnapshot } from './types';
+/**
+ * Render a label into an offscreen canvas sized to label.size (in map units
+ * × PX_PER_UNIT) and return a PNG data URL.
+ *
+ * The background fills the entire rect. Text is centered horizontally and
+ * vertically. Multi-line text is split on '\n'. Font decorations (underline,
+ * strikeout) are drawn manually so they work across all browsers.
+ */
+export declare function generateLabelPixmap(label: LabelSnapshot): string;
+/** Convert a PNG data URL to a Buffer for storage in the binary map. */
+export declare function dataUrlToBuffer(dataUrl: string): Uint8Array;

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

@@ -0,0 +1,2 @@
+export declare function loadUrlIntoStore(url: string, onProgress?: (pct: number | null) => void): Promise<void>;
+export declare function loadFileIntoStore(file: File): Promise<void>;

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

@@ -0,0 +1 @@
+export declare function getMapBytes(): Uint8Array | null;

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

@@ -0,0 +1,17 @@
+import type { MudletMap, MudletRoom } from '../mapIO';
+import type { Direction } from './types';
+import { OPPOSITE } from './types';
+export declare function nextAreaId(map: MudletMap): number;
+export declare function nextRoomId(map: MudletMap): number;
+export declare function createDefaultRoom(id: number, areaId: number, x: number, y: number, z: number): MudletRoom;
+export declare function inferDirection(sx: number, sy: number, tx: number, ty: number): Direction;
+export declare function getExit(room: MudletRoom, dir: Direction): number;
+export declare function setExit(room: MudletRoom, dir: Direction, value: number): void;
+/** Returns all incoming cardinal-exit references to `targetId` from any room in the map. */
+export declare function findNeighborsPointingAt(map: MudletMap, targetId: number): Array<{
+    roomId: number;
+    dir: Direction;
+}>;
+/** Cardinals that use 2D map geometry (not up/down/in/out). */
+export declare function is2DCardinal(dir: Direction): boolean;
+export { OPPOSITE };

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

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { MudletMap } from '../mapIO';
+import type { SwatchSet } from './types';
+import type { SceneHandle } from './scene';
+export interface SidebarTab {
+    id: string;
+    label: string;
+    render(sceneRef: {
+        current: SceneHandle | null;
+    }): ReactNode;
+}
+export interface EditorPlugin {
+    onAppReady?(): Promise<void>;
+    onMapOpened?(map: MudletMap): void;
+    onMapClosed?(): void;
+    onMapSave?(bytes: Uint8Array): void;
+    renderOverlay?(): ReactNode;
+    sidebarTabs?(): SidebarTab[];
+    swatchSets?(): SwatchSet[];
+}

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

@@ -0,0 +1,2 @@
+import { type ToolContext } from './tools';
+export declare function attachPointerController(ctx: ToolContext): () => void;

package/dist-lib/editor/reader/EditorMapReader.d.ts

@@ -0,0 +1,175 @@
+import type { MudletMap, MudletRoom, MudletColor } from '../../mapIO';
+import type { LabelSnapshot } from '../types';
+import { type Direction, type LabelFont } from '../types';
+/** Editor-side Exit — mirrors the renderer's Exit type. */
+export interface EditorExit {
+    a: number;
+    b: number;
+    aDir?: Direction;
+    bDir?: Direction;
+    zIndex: number[];
+}
+/** Live view over a raw MudletRoom. Y is flipped for render-space consumption. */
+export interface LiveRoom {
+    readonly id: number;
+    x: number;
+    y: number;
+    z: number;
+    readonly area: number;
+    readonly name: string;
+    readonly weight: number;
+    readonly env: number | undefined;
+    readonly roomChar: string | undefined;
+    readonly userData: Record<string, string>;
+    readonly doors: Record<string, number>;
+    readonly isLocked: boolean;
+    readonly exitLocks: number[];
+    readonly stubs: number[];
+    readonly exitWeights: Record<string, number>;
+    readonly mSpecialExitLocks: number[];
+    readonly exits: Record<string, number>;
+    readonly specialExits: Record<string, number>;
+    readonly customLines: Record<string, any>;
+    readonly hash?: string;
+    /** Backing raw room (for direct mutation). */
+    readonly __raw: MudletRoom;
+}
+export declare class EditorPlane {
+    private rooms;
+    private labels;
+    constructor(rooms: LiveRoom[], labels: any[]);
+    getRooms(): LiveRoom[];
+    getLabels(): any[];
+    getBounds(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    setRooms(rooms: LiveRoom[]): void;
+    setLabels(labels: any[]): void;
+}
+export declare class EditorArea {
+    private readonly areaId;
+    private readonly areaName;
+    private rooms;
+    private labels;
+    private planes;
+    private exits;
+    private version;
+    constructor(areaId: number, areaName: string, rooms: LiveRoom[], labels: any[]);
+    getAreaId(): number;
+    getAreaName(): string;
+    getVersion(): number;
+    markDirty(): void;
+    getPlane(z: number): EditorPlane;
+    getPlanes(): EditorPlane[];
+    getZLevels(): number[];
+    getRooms(): LiveRoom[];
+    getFullBounds(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    getLinkExits(zIndex: number): EditorExit[];
+    setLabels(labels: any[]): void;
+    addRoomLive(room: LiveRoom): void;
+    removeRoomById(id: number): void;
+    removeRoomsById(ids: Set<number>): void;
+    rebuildPlanes(): void;
+    rebuildExits(): void;
+}
+/**
+ * Editor-side MapReader. Drop-in replacement for `mudlet-map-renderer`'s MapReader
+ * — exposes the same read surface the renderer needs, but:
+ *  - Rooms are live getters over raw `MudletRoom` objects (no clone, no snapshot).
+ *  - Y is flipped via a getter so mutations to raw.y propagate with correct sign.
+ *  - Mutation methods are public: `moveRoom`, `setExit`, `addRoom`, `removeRoom`,
+ *    `setRoomField`. Each updates the raw map and invalidates the relevant Area
+ *    cache, so `renderer.refresh()` picks up the change.
+ */
+export declare class EditorMapReader {
+    private readonly raw;
+    private readonly rooms;
+    private readonly areas;
+    private readonly colors;
+    constructor(raw: MudletMap);
+    private toRendererLabel;
+    private syncRendererLabels;
+    getRoom(id: number): LiveRoom | undefined;
+    getArea(areaId: number): EditorArea | undefined;
+    getAreas(): EditorArea[];
+    getRooms(): LiveRoom[];
+    getExplorationArea(): undefined;
+    decorateWithExploration(): Set<number> | undefined;
+    getVisitedRooms(): Set<number> | undefined;
+    clearExplorationDecoration(): void;
+    isExplorationEnabled(): boolean;
+    setVisitedRooms(): Set<number>;
+    addVisitedRoom(): boolean;
+    addVisitedRooms(): number;
+    hasVisitedRoom(): boolean;
+    getColorValue(envId: number): string;
+    getSymbolColor(envId: number, opacity?: number): string;
+    /** Move a room. Coordinates are in RENDER space (same as what culling returns / cursor maps to). */
+    moveRoom(id: number, x: number, y: number, z: number): void;
+    /** Set a cardinal exit. `toId < 0` removes it. */
+    setExit(fromId: number, dir: Direction, toId: number): void;
+    setRoomField(id: number, field: 'name' | 'environment' | 'weight' | 'symbol', value: string | number): void;
+    setRoomLock(id: number, lock: boolean): void;
+    setUserDataEntry(id: number, key: string, value: string | null): void;
+    /** Add a raw room (expected `raw.rooms[id]` already set or not, we set it). */
+    addRoom(id: number, rawRoom: MudletRoom): void;
+    setSpecialExit(roomId: number, name: string, toId: number): void;
+    removeSpecialExit(roomId: number, name: string): void;
+    setDoor(roomId: number, dir: Direction, value: number): void;
+    setSpecialExitDoor(roomId: number, name: string, value: number): void;
+    setExitWeight(roomId: number, dir: Direction, value: number): void;
+    setSpecialExitWeight(roomId: number, name: string, value: number): void;
+    setExitLock(roomId: number, dir: Direction, lock: boolean): void;
+    setStub(roomId: number, dir: Direction, stub: boolean): void;
+    /** Move a single custom line waypoint. renderX/renderY are render-space (y-down). */
+    setCustomLinePoint(roomId: number, exitName: string, index: number, renderX: number, renderY: number): void;
+    setCustomLine(roomId: number, exitName: string, points: [number, number][], color: MudletColor, style: number, arrow: boolean): void;
+    removeCustomLine(roomId: number, exitName: string): void;
+    addArea(id: number, name: string): void;
+    removeArea(id: number): void;
+    moveRoomsToArea(roomIds: number[], fromAreaId: number, toAreaId: number): void;
+    renameArea(id: number, name: string): void;
+    setCustomEnvColor(envId: number, color: MudletColor | null): void;
+    getLabelSnapshot(areaId: number, labelId: number): LabelSnapshot | null;
+    addLabel(areaId: number, snapshot: LabelSnapshot): void;
+    removeLabel(areaId: number, labelId: number): void;
+    /** Move a label. renderX/renderY are render-space (y-down); stored as raw Mudlet (y-up). */
+    moveLabel(areaId: number, labelId: number, renderX: number, renderY: number): void;
+    setLabelText(areaId: number, labelId: number, text: string): void;
+    setLabelSize(areaId: number, labelId: number, width: number, height: number): void;
+    setLabelPixmap(areaId: number, labelId: number, dataUrl: string): void;
+    setLabelImageSrc(areaId: number, labelId: number, imageSrc: string | undefined): void;
+    setLabelFont(areaId: number, labelId: number, font: LabelFont): void;
+    setLabelOutlineColor(areaId: number, labelId: number, color: import('../../mapIO').MudletColor | undefined): void;
+    setLabelNoScaling(areaId: number, labelId: number, noScaling: boolean): void;
+    setLabelShowOnTop(areaId: number, labelId: number, showOnTop: boolean): void;
+    setLabelColors(areaId: number, labelId: number, fg: MudletColor, bg: MudletColor): void;
+    getAllEnvColors(): {
+        envId: number;
+        rgbValue: string;
+    }[];
+    /**
+     * Bulk-delete an entire area and its rooms. Assumes the caller has already
+     * severed cross-area incoming exits on raw rooms (same pattern as `deleteRoom`
+     * using `neighborEdits`). Rebuilds exit caches on `affectedOtherAreaIds` once
+     * at the end — cheap, vs. N× rebuild-all-areas from the per-room path.
+     */
+    removeAreaWithRooms(areaId: number, roomIds: number[], affectedOtherAreaIds: number[]): void;
+    /** Restore an area + its rooms (for `deleteAreaWithRooms` undo). */
+    restoreAreaWithRooms(areaId: number, areaName: string, rooms: Array<{
+        id: number;
+        room: MudletRoom;
+    }>, affectedOtherAreaIds: number[]): void;
+    removeRoom(id: number): void;
+    /** Bulk-remove many rooms. Caller must have already severed neighbor exits in raw map.
+     *  Does one rebuildPlanes/rebuildExits per affected area instead of one per room. */
+    removeRooms(ids: number[]): void;
+}

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

@@ -0,0 +1,22 @@
+import { MapRenderer, type Settings } from 'mudlet-map-renderer';
+import type { MudletMap } from '../mapIO';
+import { EditorMapReader, type LiveRoom } from './reader/EditorMapReader';
+export interface SceneHandle {
+    renderer: MapRenderer;
+    reader: EditorMapReader;
+    settings: Settings;
+    /** Render-space room (y flipped). Reads pass through to raw. */
+    getRenderRoom(id: number): LiveRoom | undefined;
+    /** Switch displayed area / z-level. Redraws and fits the viewport. */
+    setArea(areaId: number, z: number, insets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    }): void;
+    /** Switch displayed area / z-level and pan to a specific map-space point, keeping the current zoom. */
+    setAreaAt(areaId: number, z: number, mapX: number, mapY: number): void;
+    refresh(): void;
+    destroy(): void;
+}
+export declare function createScene(map: MudletMap, container: HTMLDivElement): SceneHandle;

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

@@ -0,0 +1,19 @@
+import { type MudletMap } from '../mapIO';
+import type { Command } from './types';
+export interface SessionData {
+    id: string;
+    fileName: string;
+    mapBytes: ArrayBuffer;
+    imageSrcs: Record<string, string>;
+    undoStack: Command[];
+    currentAreaId: number | null;
+    currentZ: number;
+    savedAt: number;
+    roomCount: number;
+}
+export declare function saveSession(fileName: string, map: MudletMap, undoStack: Command[], currentAreaId: number | null, currentZ: number, existingId?: string): Promise<string>;
+export declare function listSessions(): Promise<SessionData[]>;
+export declare function clearAllSessions(): Promise<void>;
+export declare function clearSession(id: string): Promise<void>;
+/** Reconstruct a MudletMap from a SessionData, re-applying editor-only fields (imageSrc). */
+export declare function restoreMapFromSession(session: SessionData): MudletMap;

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

@@ -0,0 +1,98 @@
+import type { MudletMap } from '../mapIO';
+import type { Command, HitItem, HoverTarget, LoadedMap, Pending, Selection, SwatchSet, ToolId } from './types';
+interface UserSettings {
+    snapToGrid: boolean;
+}
+export declare function saveUserSettings(patch: Partial<UserSettings>): void;
+export declare function saveSwatchState(sets: SwatchSet[], activeSetId: string | null, activeSwatchId: string | null): void;
+export interface EditorState {
+    map: MudletMap | null;
+    loaded: LoadedMap | null;
+    currentAreaId: number | null;
+    currentZ: number;
+    activeTool: ToolId;
+    selection: Selection;
+    hover: HoverTarget;
+    pending: Pending;
+    snapToGrid: boolean;
+    gridStep: number;
+    /** When true (Space held), pointer input defers to the renderer's pan regardless of active tool. */
+    spaceHeld: boolean;
+    undo: Command[];
+    redo: Command[];
+    status: string;
+    /** Bumped on structural changes (room added/removed, area/z changed) that need a full rebuild. */
+    structureVersion: number;
+    /** Bumped on every mutation (coord, exits, props) to trigger React re-renders of panels. */
+    dataVersion: number;
+    /** Snapped cursor position in render-space, tracked by tools that show a snap indicator. */
+    snapCursor: {
+        x: number;
+        y: number;
+    } | null;
+    sidebarTab: string;
+    panelCollapsed: boolean;
+    contextMenu: ContextMenuState;
+    savedUndoLength: number;
+    /** When set, the next area/z navigation pans to this map-space point instead of fitting. Consumed and cleared by App. */
+    navigateTo: {
+        mapX: number;
+        mapY: number;
+    } | null;
+    /** When set, App pans to this map-space point without changing area/z. Consumed and cleared by App. */
+    panRequest: {
+        mapX: number;
+        mapY: number;
+    } | null;
+    /** Tracks the last Alt+click position (integer cell) and cycle index for overlapping-element cycling. */
+    hitCycle: {
+        x: number;
+        y: number;
+        index: number;
+    } | null;
+    /** When true, label resize preserves the aspect ratio at the start of the drag. */
+    labelAspectRatioLocked: boolean;
+    swatchSets: SwatchSet[];
+    pluginSwatchSets: SwatchSet[];
+    activeSwatchSetId: string | null;
+    activeSwatchId: string | null;
+    swatchPaletteOpen: boolean;
+    sessionId: string | null;
+}
+export type ContextMenuState = {
+    kind: 'customLinePoint';
+    roomId: number;
+    exitName: string;
+    pointIndex: number;
+    screenX: number;
+    screenY: number;
+} | {
+    kind: 'room';
+    roomId: number;
+    screenX: number;
+    screenY: number;
+} | {
+    kind: 'disambiguate';
+    hits: HitItem[];
+    screenX: number;
+    screenY: number;
+} | {
+    kind: 'label';
+    areaId: number;
+    labelId: number;
+    screenX: number;
+    screenY: number;
+} | null;
+type Listener = (state: EditorState) => void;
+declare class Store {
+    private state;
+    private listeners;
+    getState: () => EditorState;
+    setState: (patch: Partial<EditorState> | ((s: EditorState) => Partial<EditorState>)) => void;
+    subscribe: (listener: Listener) => (() => void);
+    bumpData: () => void;
+    bumpStructure: () => void;
+}
+export declare const store: Store;
+export declare function useEditorState<T>(selector: (s: EditorState) => T): T;
+export {};

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

@@ -0,0 +1,52 @@
+import type { MapRenderer, Settings } from 'mudlet-map-renderer';
+import type { HitItem, Selection, ToolId } from './types';
+import type { SceneHandle } from './scene';
+export interface ToolContext {
+    renderer: MapRenderer;
+    container: HTMLElement;
+    settings: Settings;
+    refresh: () => void;
+    scene: SceneHandle;
+}
+export interface Tool {
+    id: ToolId;
+    cursor?: string;
+    onPointerDown?(ev: PointerEvent, ctx: ToolContext): boolean;
+    onPointerMove?(ev: PointerEvent, ctx: ToolContext): boolean | void;
+    onPointerUp?(ev: PointerEvent, ctx: ToolContext): boolean | void;
+    onContextMenu?(ev: MouseEvent, ctx: ToolContext): boolean | void;
+    onCancel?(ctx: ToolContext): void;
+}
+type PickSpecialExitCb = (roomId: number) => void;
+export declare function registerSpecialExitPickCb(cb: PickSpecialExitCb | 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
+ * differs from the room's current cell, so micro-jitter on a click doesn't trigger a move.
+ */
+export declare const selectTool: Tool;
+/**
+ * Connect is a drag interaction. Pointer-down on a room picks the source; if
+ * the cursor is near one of the 8 handle positions (corners + midpoints) the
+ * source direction is fixed explicitly. Otherwise the direction is inferred
+ * from the target on drop.
+ */
+export declare const connectTool: Tool;
+export declare const unlinkTool: Tool;
+export declare const addRoomTool: Tool;
+export declare const deleteTool: Tool;
+export declare const panTool: Tool;
+export declare const customLineTool: Tool;
+/**
+ * Revert any raw mutations made during the in-progress draw. Safe to call even
+ * when no raw write happened yet (restores / removes based on previousSnapshot).
+ */
+export declare function restorePendingCustomLine(pending: import('./types').PendingCustomLine, scene: SceneHandle): void;
+export declare function finishCustomLine(pending: import('./types').PendingCustomLine, ctx?: ToolContext): void;
+export declare const addLabelTool: Tool;
+export declare function getActiveSwatch(s: import('./store').EditorState): import('./types').Swatch | null;
+export declare const paintTool: Tool;
+export declare const TOOLS: Record<ToolId, Tool>;
+export declare function hitToSelection(hit: HitItem): Selection;
+export declare function hitStatusLabel(hit: HitItem): string;
+export {};