@mudlet/mudlet-web 0.3.0

package/dist-lib/ui/windows/WindowManager.d.ts

@@ -0,0 +1,694 @@
+import { type OutputRendererControls } from '../output/OutputRenderer';
+import type { Console } from '../../mud/text/Console';
+import type { AnsiAwareBuffer } from '../../mud/text/FormatState';
+import type { DockSide, WindowHandle, WindowOpenOptions, ScriptWindowRenderData } from './types';
+import { MapStore } from '../../map/MapStore';
+import { OverlayLayerOrder } from '../layout/overlayLayerOrder';
+/** Live handle onto a mounted map renderer, registered by MapPanel. Backs the
+ *  Lua getMapZoom/setMapZoom/updateMap APIs, which need to read and drive the
+ *  renderer state that lives inside the React component. */
+export interface MapControl {
+    getZoom: () => number | null;
+    setZoom: (zoom: number) => void;
+    redraw: () => void;
+    /** Mudlet `exportAreaImage` — render an area (optionally a single z-level) to
+     *  PNG bytes via a headless renderer, leaving the live view untouched.
+     *  Returns null when the area is unknown / unrenderable. */
+    exportArea: (areaId: number, zLevel?: number) => Uint8Array | null;
+}
+/** Progress of an in-flight streamed map load, as published by
+ *  {@link WindowManager.subscribeMapLoadProgress}.
+ *
+ *  `total` is 0 until the worker has decoded the map header (the room count is
+ *  summed from the areas' room-id lists, which the header carries) — until then
+ *  the load is genuinely indeterminate and the UI should say so rather than
+ *  guess a denominator. */
+export interface MapLoadProgress {
+    /** Rooms folded into the store so far. */
+    loaded: number;
+    /** Total rooms the map declares, or 0 while the header is still decoding. */
+    total: number;
+    /**
+     * `rooms` — streaming rooms into the store; `loaded`/`total` advance.
+     *
+     * `building` — every room has landed and the renderer is indexing the map
+     * and building its first scene. That work is synchronous and, on a large
+     * map, by far the longest part of the wait, so it gets its own phase rather
+     * than leaving the bar parked at 99% looking hung.
+     */
+    phase: 'rooms' | 'building';
+}
+export type WindowsChangedFn = (windows: ScriptWindowRenderData[], dockExtents: Record<DockSide, number>) => void;
+export declare class WindowManager {
+    readonly overlayZ: OverlayLayerOrder;
+    readonly mapStore: MapStore;
+    private readonly windows;
+    private readonly controls;
+    private readonly elements;
+    /** Outer panel element used by getSize / sysUserWindowResizeEvent. Distinct
+     *  from `elements` (the writable text/HTML target) so size queries report the
+     *  full user-window box that labels live in, not the inner output area. */
+    private readonly viewports;
+    private readonly lineBuffers;
+    /** Per-window scroll/scrollbar overrides applied via CSS classes when the
+     *  console's wrapper element registers. Mudlet's enable/disable Scrolling
+     *  and (Horizontal)ScrollBar APIs back into this. */
+    private readonly scrollState;
+    private readonly portalTargets;
+    /** Hidden, detached div in the *main* document used as a temporary parking
+     *  spot for a portal target while a popout window is torn down — re-adopting
+     *  the node here before the child window closes keeps its content alive (a
+     *  node orphaned in a closed window's document would be lost). */
+    private portalHolding;
+    private readonly resizeObservers;
+    private readonly lastEmittedSize;
+    /** Per-window last reported character grid (cols, rows) — used to gate
+     *  sysConsoleSizeChanged so the event fires only on actual grid changes. */
+    private readonly lastEmittedGrid;
+    private readonly activeTabGroups;
+    /** Per-window command-line state. Keyed by window id; entry exists only
+     *  after enableCommandLine. The actual rendered <input> lives in TextPanel
+     *  /HtmlPanel and pulls its enabled/css/value from the ScriptWindowRenderData
+     *  payload that notify() emits — this map only carries non-serializable
+     *  state (the Lua callback). */
+    private readonly cmdLineState;
+    private readonly mapCallbacks;
+    private readonly mapControls;
+    /** Per-window teardown for the mousedown/mouseup listeners observeMouse
+     *  attaches. Keyed by window id ('main' for the central output). */
+    private readonly mouseCleanups;
+    /** Per-window teardown for the dragenter/dragover/drop listeners
+     *  observeDrop attaches — these power Mudlet's sysDropEvent /
+     *  sysDropUrlEvent on viewports. */
+    private readonly dropCleanups;
+    private mapLoadCallback;
+    /** Live progress of a streamed map load, or null when none is running.
+     *  Held here (rather than pushed only to subscribers) so a MapPanel that
+     *  mounts mid-load — the normal case at cold start, where bootstrapMap
+     *  begins before the panel exists — can render the bar straight away. */
+    private mapLoadProgress;
+    private readonly mapProgressSubscribers;
+    /** Single in-flight bootstrap promise — both ScriptingEngine.start (which
+     *  awaits the map before applying scripts, Mudlet parity) and MapPanel on
+     *  mount call into this; whichever lands first triggers the work. */
+    private mapBootstrapInflight;
+    private mapSaveTimer;
+    private mapSavePending;
+    /** MMP map URL announced by the game via GMCP `Client.Map` (Mudlet
+     *  TMap::mMmpMapLocation). Lives here rather than on ScriptingEngine so it
+     *  survives script reloads, like Mudlet's TMap does. */
+    private _mmpMapLocation;
+    private _connectionId;
+    /** Names of windows created by Lua createMiniConsole — distinguishes them
+     *  from openUserWindow panels for windowType() reporting. */
+    private mainViewportEl;
+    private readonly miniConsoles;
+    private consoleRegistry;
+    private windowHints;
+    private nextZ;
+    private nextDockOrder;
+    private readonly dockExtents;
+    constructor(overlayZ?: OverlayLayerOrder);
+    /** Resolves the same "nested under which parent" id FloatingWindowLayer's
+     *  resolveParent uses: an explicit non-'main' parent, else 'main' when this
+     *  is a mini-console (createMiniConsole/createMapper without an explicit
+     *  parent still nests under the main viewport), else null for a genuine
+     *  root floating window — which shares no stacking context with any
+     *  parent's labels, so there's nothing to touch. */
+    private overlayParentId;
+    private touchOverlayWindows;
+    private sinkOverlayWindows;
+    onWindowsChange?: WindowsChangedFn;
+    onWindowHint?: (id: string, hint: WindowOpenOptions) => void;
+    /** Called when a window is explicitly closed — use to clear its auto-open flag. */
+    onWindowClosed?: (id: string) => void;
+    /** Called when a dock side's extent changes — use to persist it. */
+    onDockExtentsChange?: (extents: Record<DockSide, number>) => void;
+    /** Called when a map window is opened or made visible. */
+    onMapOpen?: (id: string) => void;
+    /** Bridge to ScriptingEngine.raiseEvent — used to fire system events
+     *  (e.g. sysUserWindowResizeEvent) from window-lifecycle code. */
+    onRaiseEvent?: (event: string, args: unknown[]) => void;
+    /** Called when a real File is dropped on a window. The handler (wired by
+     *  ScriptingEngine) writes the bytes into the profile VFS and then raises
+     *  Mudlet's sysDropEvent with a readable path — browsers don't expose a
+     *  filesystem path on the dropped File, so we can't raise it inline here. */
+    onFileDrop?: (file: File, x: number, y: number, id: string) => void;
+    /** Called whenever the *main* console's character grid changes (columns ×
+     *  rows). MudSession wires this to the client so NAWS (telnet window size)
+     *  tracks the output area. Distinct from onRaiseEvent (which drives Lua
+     *  sysConsoleSizeChanged) so window-size reporting doesn't depend on the
+     *  scripting layer being attached. */
+    onMainConsoleResize?: (cols: number, rows: number) => void;
+    /** Set by MapPanel — mirrors Mudlet's signal_mmpMapLocationChanged, which
+     *  drives the mapper's "download map" affordance appearing/disappearing. */
+    onMmpMapLocationChanged?: (url: string) => void;
+    /** Bridge to ScriptingEngine.downloadMap — the map UI's "download map from
+     *  game" action (Mudlet dlgMapper's Download button). */
+    onDownloadMap?: () => void;
+    /** The MMP map URL from GMCP `Client.Map`, or '' when none announced. */
+    get mmpMapLocation(): string;
+    /** Record the game-announced map URL (Mudlet TMap::setMmpMapLocation). */
+    setMmpMapLocation(url: string): void;
+    setConsoleRegistry(registry: Map<string, Console>): void;
+    setWindowHints(hints: Record<string, WindowOpenOptions>): void;
+    /** Restore saved dock extents from storage (called on connect, before setWindowHints). */
+    setDockExtentsFromStorage(extents: Record<string, number>): void;
+    /** Call after setting onWindowsChange to deliver current state immediately.
+     *  Needed because windows may have been opened (e.g. autoOpen) before the
+     *  React subscriber mounted. */
+    initialize(): void;
+    /**
+     * Snapshot the current window hints + dock extents. Returned object is a
+     * deep copy — safe to persist without aliasing the live state. Backs
+     * Mudlet's `saveWindowLayout()`.
+     */
+    captureLayoutSnapshot(): {
+        hints: Record<string, WindowOpenOptions>;
+        dockExtents: Record<DockSide, number>;
+    };
+    /**
+     * Re-apply a previously captured snapshot to the live state. Backs
+     * Mudlet's `loadWindowLayout()`. Behaviour:
+     *   - Replaces the stored windowHints + dockExtents with the snapshot.
+     *   - For each currently open window with a snapshot entry, rewrites its
+     *     geometry / dock state / style fields in place (keeps pendingText,
+     *     controls, miniconsole content intact).
+     *   - For each snapshot hint with no current window, opens the window when
+     *     the snapshot recorded it as visible (hidden !== true).
+     * `onWindowHint` / `onDockExtentsChange` callbacks fire so the persistence
+     * layer mirrors the restored state.
+     */
+    applyLayoutSnapshot(snapshot: {
+        hints: Record<string, WindowOpenOptions>;
+        dockExtents: Record<string, number>;
+    }): void;
+    /** Returns the stable portal-target div for a window, creating it on first call.
+     *  This div is physically moved between dock slots and floating frames — the
+     *  panel component rendered into it never unmounts during transitions. */
+    getOrCreatePortalTarget(id: string): HTMLDivElement;
+    getPortalTarget(id: string): HTMLDivElement | undefined;
+    /** A hidden, detached holding element in the main document. PopoutWindow
+     *  re-parents a portal target here before closing its child window so the
+     *  panel's DOM survives the teardown; the next docked/floating frame to
+     *  mount appendChilds it back out. Lazily created. */
+    getPortalHolding(): HTMLDivElement;
+    /** Detach a panel into its own browser window. Layout fields (docked side /
+     *  floating rect) are left untouched so popIn() restores the panel in place.
+     *  The PopoutWindow component reacts to the state change and opens the window. */
+    popOut(id: string): void;
+    /** Re-dock/re-float a popped-out panel back into the main window. Triggered
+     *  explicitly or automatically when the popout window closes. */
+    popIn(id: string): void;
+    isPoppedOut(id: string): boolean;
+    registerTextPanel(id: string, controls: OutputRendererControls, element: HTMLElement): void;
+    /** Registers the outer panel element for size queries and sysUserWindowResizeEvent.
+     *  Distinct from the writable element registered via registerTextPanel /
+     *  register('html'): labels position against this rectangle, so getUserWindowSize
+     *  must report it (not the inner output area). */
+    registerViewport(id: string, element: HTMLElement): void;
+    getViewport(id: string): HTMLElement | undefined;
+    /** OutputArea registers the main `.output-wrapper` here so getColumnCount()
+     *  can measure character width against the actual rendered element. */
+    registerMainOutput(element: HTMLElement | null): void;
+    /**
+     * Registers the full main-viewport element (the one that spans the entire
+     * console area including any setBorderTop/Bottom/Left/Right insets). Used
+     * by getMainWindowSize so label-positioning scripts always see the full
+     * window bounds, matching Mudlet semantics where labels live in window
+     * coordinates and borders carve space *out of* them.
+     */
+    registerMainViewport(element: HTMLElement | null): void;
+    getMainViewportElement(): HTMLElement | null;
+    /**
+     * The DOM element main-parented nested windows (mini-consoles, embedded
+     * mapper) portal into. This is `.main-overlay-root` — the SAME wrapper the
+     * main labels / command lines / scroll boxes render into — so a window's
+     * z-index and a label's z-index compete in one CSS stacking context and the
+     * overlayZ ordinals actually take visual effect. It must NOT be a separate
+     * sibling of the label overlay: `.main-overlay-root` carries an explicit
+     * `z-index` (a stacking context that keeps all overlay content below
+     * floating windows / modals), so a nested window portaled anywhere else
+     * would either be trapped in a different context or leak its z above the
+     * labels — which was the long-standing "map paints over every label" bug.
+     * Both `.main-overlay-root` and the console viewport are `inset:0` over the
+     * same main-viewport, so the portal target swap doesn't shift coordinates.
+     * Falls back to the console viewport if the host hasn't registered yet.
+     */
+    private mainOverlayHostEl;
+    registerMainOverlayHost(element: HTMLElement | null): void;
+    getMainOverlayHost(): HTMLElement | null;
+    /** The overlay host element that widgets under `parentId` (labels AND
+     *  nested windows) share so their z-indices compete in one stacking
+     *  context: `.main-overlay-root` for 'main', else the userwindow's own
+     *  viewport (where its panel already renders the label overlays). */
+    getOverlayHost(parentId: string): HTMLElement | null;
+    register(id: string, element: HTMLElement, _kind: 'html'): void;
+    pushBuffer(id: string, buffer: AnsiAwareBuffer): void;
+    /** Push the current partial-line buffer (script echo without a trailing
+     *  newline) so the renderer can paint it in-place via the 'script-partial'
+     *  path. Repeated calls update the same DOM element; a subsequent
+     *  pushBuffer completes the partial. Pre-mount, the latest partial is
+     *  cached on the window and flushed by registerTextPanel. */
+    pushPartialBuffer(id: string, buffer: AnsiAwareBuffer): void;
+    registerConsole(id: string, console: Console): void;
+    unregister(id: string): void;
+    /** Watch `element` for size changes and raise sysUserWindowResizeEvent
+     *  whenever its rendered dimensions differ from the last reported pair.
+     *  Catches both floating-window user drags and dock splitter drags through
+     *  the same DOM-level signal, so script-driven setSize() calls also fire
+     *  the event once the layout settles. */
+    private observeResize;
+    /** Force an immediate measure-and-emit for the main viewport, if it's
+     *  registered. ResizeObserver's own first callback is spec-deferred (never
+     *  synchronous with observe()) — registerMainViewport runs from
+     *  OutputArea's mount effect, which commits before ScriptingEngine's
+     *  constructor exists to wire up onRaiseEvent, so that deferred callback
+     *  can easily land *after* Lua bootstrap has already dispatched
+     *  sysLoadEvent/sysInstallPackage and run scripts that build
+     *  percentage-positioned Geyser containers. GeyserReposition (the bundled
+     *  Mudlet Lua that actually resolves that percentage geometry into pixels)
+     *  only runs in response to sysWindowResizeEvent, so those containers —
+     *  and anything gated on their resolved get_x()/get_width(), e.g.
+     *  Adjustable.Container:attachToBorder's validAttachPositions() check —
+     *  silently see stale/unresolved geometry and fail with no error. Called
+     *  by ScriptingEngine right after it wires up onRaiseEvent (and after the
+     *  Lua runtime exists to receive the event — see the guard in
+     *  measureAndEmitResize), guaranteeing at least one sysWindowResizeEvent
+     *  has already landed before any script-load event fires. The dedup check
+     *  inside measureAndEmitResize makes the real (later) ResizeObserver tick
+     *  a same-size no-op rather than a duplicate event. */
+    primeMainResize(): void;
+    /** Shared by observeResize's ResizeObserver callback and primeMainResize's
+     *  eager call — measures `element`, and raises sysWindowResizeEvent/
+     *  sysUserWindowResizeEvent plus the console-grid and overflow events when
+     *  the size actually changed since last reported. */
+    private measureAndEmitResize;
+    /** Measure one monospace cell (px) by probing `el` with its own inherited
+     *  font — the same technique getColumnCount uses, so the NAWS grid and
+     *  getColumnCount agree. Falls back to a fontSize estimate when the probe
+     *  can't measure (detached element / happy-dom tests). */
+    private measureCharCell;
+    /** Synchronously re-measure the main console's char grid and emit it
+     *  (sysConsoleSizeChanged + onMainConsoleResize) so NAWS can seed with the
+     *  real on-screen size at connect time, rather than whatever the async
+     *  resize observer last reported — which on a fast/mobile connect may be
+     *  stale or not yet fired. No-op when the main element isn't mounted, or
+     *  when the size is unchanged (the dedup guard in emitConsoleGridIfChanged). */
+    remeasureMainGrid(): void;
+    /** Compute the rendered char-grid for `id` and emit sysConsoleSizeChanged
+     *  when (cols, rows) changes. Metrics are measured against the registered
+     *  text element (which carries the MUD output font), not the observed
+     *  viewport — the viewport's computed font is the app's base font, so
+     *  estimating cells off it reports the wrong column count and, through
+     *  onMainConsoleResize → NAWS, hands the server the wrong window width (so
+     *  MOTDs / room art don't fit the screen). This matches getColumnCount,
+     *  which probes the same element. Falls back to the viewport box when the
+     *  text element isn't mounted yet. */
+    private emitConsoleGridIfChanged;
+    /** Mudlet sysWindowOverflowEvent(name, overflowLines). Fires when a console
+     *  whose scrolling is disabled has more content than fits in the viewport.
+     *  scrollHeight − clientHeight gives the pixel overflow; dividing by the
+     *  estimated line height converts it to lines for the event payload. */
+    private emitWindowOverflowIfPresent;
+    /** Raise Mudlet's sysWindowMousePress/ReleaseEvent for clicks anywhere on a
+     *  window's box. Args mirror Mudlet: (button, x, y, name) where button is
+     *  1=left, 2=right, 3=middle, 4=back, 5=forward (0 = anything else), x/y are
+     *  pixel coordinates relative to the window, and name is the window id
+     *  ('main' for the central output). */
+    private observeMouse;
+    /** Mudlet `sysDropEvent(filepath, suffix, x, y, name)` and
+     *  `sysDropUrlEvent(url, schema, x, y, name)` — fired when the user drags
+     *  a file or URL onto a window. We only acknowledge drops we can identify
+     *  (a real File for sysDropEvent, a textual URL for sysDropUrlEvent); the
+     *  default DragEvent behaviour is suppressed in both cases so the browser
+     *  doesn't navigate away from the page. */
+    private observeDrop;
+    registerMapCallback(id: string, cb: (roomId: number) => void): void;
+    unregisterMapCallback(id: string): void;
+    centerView(roomId: number): boolean;
+    registerMapControl(id: string, ctrl: MapControl): void;
+    unregisterMapControl(id: string): void;
+    /** Live zoom of the displayed 2D map, or null when no map panel is mounted.
+     *  mudix shows one area at a time through a single shared renderer, so the
+     *  Mudlet `areaID` argument has no per-area analogue here — callers get the
+     *  current view's zoom regardless. */
+    getMapZoom(): number | null;
+    /** Set the displayed map's zoom and redraw. Returns false when no map panel
+     *  is mounted to receive the change. */
+    setMapZoom(zoom: number): boolean;
+    /** Force the map to re-read MapStore and redraw (Mudlet `updateMap`). */
+    updateMap(): boolean;
+    private readonly mapViews;
+    /** View ids start at 1 — Mudlet treats 0 as "no view". */
+    private nextMapViewId;
+    /** The window id backing a map view. */
+    private static mapViewWindowId;
+    /**
+     * Mudlet `createMapView([areaID])` — open a secondary map window. Returns
+     * the new view id, or a message when the areaID doesn't name an area (0 or
+     * omitted means "wherever the player is").
+     */
+    createMapView(areaId: number): number | string;
+    /** Mudlet `closeMapView(viewID)`. False when no view has that id. */
+    closeMapView(viewId: number): boolean;
+    /** Mudlet `closeAllMapViews()` → how many were closed. */
+    closeAllMapViews(): number;
+    /** Mudlet `getMapViewIds()` — every open view, in creation order. */
+    getMapViewIds(): number[];
+    /** Mudlet `getMapViewInfo(viewID)`. Undefined when no view has that id. */
+    getMapViewInfo(viewId: number): {
+        areaId: number;
+        zoom: number;
+        zLevel: number;
+        centeredRoomId: number;
+    } | undefined;
+    /** The area a map window should show, when it is a secondary view rather
+     *  than the primary mapper. Undefined for the primary one, which follows the
+     *  player as before. */
+    mapViewAreaFor(windowId: string): number | undefined;
+    /** Record what a mounted secondary view is actually showing, so
+     *  getMapViewInfo reports the live state rather than the creation-time one. */
+    noteMapViewState(windowId: string, state: {
+        areaId?: number;
+        zoom?: number;
+        zLevel?: number;
+        centeredRoomId?: number;
+    }): void;
+    /** Mudlet `exportAreaImage(areaID, filePath[, zLevel])` — render an area to
+     *  PNG bytes. Prefers a mounted map widget so the export picks up that
+     *  panel's live Mapper settings, but falls back to a standalone render off
+     *  the same MapStore: the export never needed a panel (see mapImageExport),
+     *  and requiring one would make the API unreachable from a script that runs
+     *  before React has mounted the widget. Null when the area is unknown or the
+     *  render fails. */
+    exportAreaImage(areaId: number, zLevel?: number): Uint8Array | null;
+    /** Set by MapPanel on mount; cleared on unmount. The callback parses+renders
+     *  a buffer (when given) or reloads from IndexedDB (when omitted). */
+    registerMapLoadCallback(cb: (buf?: ArrayBuffer) => boolean): void;
+    unregisterMapLoadCallback(): void;
+    /**
+     * Subscribe to streamed map-load progress. The callback fires on every
+     * ingested batch and once with `null` when the load ends (either way), so a
+     * progress UI can drive itself entirely off this channel. Fires immediately
+     * with the current value on subscribe, so a panel mounting mid-load doesn't
+     * have to wait for the next batch to render something.
+     */
+    subscribeMapLoadProgress(cb: (progress: MapLoadProgress | null) => void): () => void;
+    /** Current streamed-load progress, or null when no load is running. */
+    getMapLoadProgress(): MapLoadProgress | null;
+    private publishMapLoadProgress;
+    setConnectionId(id: string): void;
+    /**
+     * Parse a Mudlet `.dat` buffer and apply it to this session's MapStore.
+     * Rooms / areas / hashes / labels / env colours / map-level user data all
+     * land in {@link MapStore} via {@link MapStore.loadFromBinary}; the
+     * renderer reads it back through the live {@link MudixMapReader}. Throws
+     * on parse failure so callers can surface the error (the file-upload path
+     * in MapPanel turns it into status='error'; bootstrap logs and moves on).
+     */
+    ingestMapBuffer(buf: ArrayBuffer): void;
+    /**
+     * Async sibling of {@link ingestMapBuffer} that parses in a worker so the
+     * main thread stays free for paint. `buf` is transferred — callers that
+     * also need the bytes (e.g. IndexedDB persistence) must clone first.
+     *
+     * The worker streams the map room-by-room and the store folds each batch in
+     * as it lands, so neither side ever holds two copies of the room graph.
+     * Subscribers see nothing until the load completes (one notification, from
+     * `endBinaryLoad`) — a half-populated store would have the renderer draw a
+     * map with dangling exits.
+     *
+     * Batch progress is published on {@link subscribeMapLoadProgress} for the
+     * map panel's progress bar; `onProgress` is an extra per-call hook.
+     */
+    ingestMapBufferAsync(buf: ArrayBuffer, onProgress?: (loaded: number, total: number) => void): Promise<void>;
+    /**
+     * Mudlet parity: a map is available to scripts before `sysLoadEvent` fires.
+     * ScriptingEngine awaits this in its start() path so the initial script
+     * load runs against an initialized MapStore (and the binary's hashes + user
+     * data when one is persisted). Idempotent — the first caller kicks off the
+     * IndexedDB fetch, everyone else awaits the same promise. Returns true
+     * when a persisted map was successfully ingested.
+     */
+    bootstrapMap(): Promise<boolean>;
+    /**
+     * Mudlet `loadMap([location])`. With a buffer the bytes are persisted to
+     * IndexedDB (so the map survives panel close/reopen and reload), parsed
+     * into the manager/store, and any open MapPanel is asked to re-render.
+     * Without a buffer the panel is told to reload from cache. Returns false
+     * on synchronous parse failure; the IndexedDB write is fire-and-forget
+     * (failures appear in console.warn). Fires sysMapLoadEvent on success.
+     */
+    loadMap(buf?: ArrayBuffer): boolean;
+    /**
+     * Async sibling of {@link loadMap} with identical effects — IndexedDB
+     * persistence, store ingest, panel re-render, `sysMapLoadEvent` — but the
+     * parse runs in the worker and streams into the store, publishing progress
+     * as it goes.
+     *
+     * Use this for every UI-driven load (file picker, map download, editor
+     * hand-back): the synchronous {@link loadMap} blocks the main thread for the
+     * whole parse, which on a large map means a frozen window and a progress bar
+     * that could never paint. `loadMap` stays for Lua's synchronous
+     * `loadMap()` contract.
+     *
+     * `buf` is transferred to the worker and must not be reused by the caller.
+     */
+    loadMapAsync(buf: ArrayBuffer): Promise<boolean>;
+    /**
+     * Mudlet `saveMap([location])`. Serialises the in-memory MapStore to the
+     * Mudlet binary `.dat` format and persists it to this connection's
+     * IndexedDB slot — the equivalent of Mudlet's default profile map path,
+     * picked up by {@link bootstrapMap} on next session start. Returns the
+     * serialised bytes so the Lua binding can also write them to a VFS path
+     * when the caller supplies one. Returns null when there is no connection
+     * or serialisation fails.
+     */
+    saveMap(): ArrayBuffer | null;
+    /**
+     * Background counterpart to {@link saveMap}: serialise the map to the binary
+     * format in a worker (so the encode never blocks the main thread) and persist
+     * it to this connection's IndexedDB slot. Used for automatic saves — notably
+     * to persist the per-area zoom held in the map's area userData — so they can
+     * run frequently without jank. Returns true on success.
+     */
+    saveMapAsync(): Promise<boolean>;
+    /**
+     * Request a debounced background map save. Multiple calls within `delayMs`
+     * collapse into a single {@link saveMapAsync}. Used by the map panel when the
+     * per-area zoom changes so the view is persisted shortly after the user stops
+     * adjusting it, without serialising on every wheel tick.
+     */
+    scheduleMapSave(delayMs?: number): void;
+    /**
+     * Drain a pending debounced save immediately — called on session close so a
+     * zoom change made just before disconnecting/switching profiles isn't lost.
+     * The write is still async (worker + IndexedDB); on an in-app close it
+     * completes because the worker and IDB outlive the session instance.
+     */
+    flushMapSave(): void;
+    /**
+     * Mudlet `saveJsonMap(path)` backbone — serialise the current MapStore
+     * to a JSON string. Used by the Lua binding, which writes the result to
+     * the VFS path the script provided.
+     */
+    saveJsonMap(): string;
+    /**
+     * Mudlet `loadJsonMap(path)` backbone — parse a JSON payload previously
+     * produced by `saveJsonMap` and replace MapStore's contents, then ask any
+     * open map panel to re-render. Returns false on parse failure or when the
+     * JSON doesn't carry the expected MudletMap shape.
+     */
+    loadJsonMap(json: string): boolean;
+    /**
+     * Import an IRE-style XML map (Mudlet TConsole::importMap →
+     * XMLimport::readMap) — the format `loadMap("...xml")` and MMP map
+     * downloads deliver. Replaces the MapStore contents, persists in the
+     * canonical binary form so the next session bootstraps it from IndexedDB,
+     * and asks any open MapPanel to re-render. Returns false when the text is
+     * not a well-formed XML map.
+     */
+    loadMapXml(xmlText: string): boolean;
+    markAsMiniConsole(id: string): void;
+    isMiniConsole(id: string): boolean;
+    getRoomIDbyHash(hash: string): number | undefined;
+    setPosition(id: string, x: number, y: number): void;
+    /** Mudlet setWindow for miniconsole / mapper panels — re-portal the panel
+     *  into another window's viewport; `undefined` re-attaches it to the main
+     *  viewport. Parent is runtime-only state (deliberately not part of the
+     *  saved hint): scripts re-establish it on every load, matching Mudlet. */
+    setParent(id: string, parent?: string): boolean;
+    /** Mudlet setFontSize for a userwindow / miniconsole. Returns false if the
+     *  window doesn't exist. Mudlet clamps font size between 1 and 99. */
+    setFontSize(id: string, size: number): boolean;
+    getFontSize(id: string): number | null;
+    /** Mudlet setFont for a userwindow / miniconsole. Empty string clears the
+     *  override and lets the inherited font take over. */
+    setFont(id: string, family: string): boolean;
+    getFont(id: string): string | null;
+    /** Mudlet setWindowWrap. 0 (or any non-positive value) clears the override. */
+    setWrap(id: string, wrapAt: number): boolean;
+    getWrap(id: string): number | null;
+    /** Companions to {@link getWrap} for the two indents — read by wrapLine,
+     *  which has to re-wrap to the same shape the renderer would. */
+    getWrapIndent(id: string): number;
+    getWrapHangingIndent(id: string): number;
+    /** Mudlet setWindowWrapIndent — indent (in characters) of newline-started
+     *  lines. 0 (or negative) clears the override. */
+    setWrapIndent(id: string, indent: number): boolean;
+    /** Mudlet setWindowWrapHangingIndent — indent (in characters) of wrapped
+     *  continuation lines. 0 (or negative) clears the override. */
+    setWrapHangingIndent(id: string, indent: number): boolean;
+    /** Mudlet enable/disableScrollBar — toggle the vertical scrollbar's visibility
+     *  on a console wrapper. Wheel/keyboard scrolling continues regardless; only
+     *  the gutter rendering is affected. Persists across mounts; idempotent. */
+    setScrollBarVisible(id: string, visible: boolean): void;
+    /** Mudlet enable/disableHorizontalScrollBar — toggle a horizontal scrollbar
+     *  on a console wrapper. mudix wraps long lines by default so this is rarely
+     *  needed; included for parity. */
+    setHorizontalScrollBarVisible(id: string, visible: boolean): void;
+    /** Mudlet enable/disableScrolling — when disabled, the wrapper sticks to the
+     *  bottom (wheel/touch/keys cannot scroll back). Mudlet forbids this on the
+     *  main window; we follow that policy. Returns false on 'main', true otherwise. */
+    setScrollingEnabled(id: string, enabled: boolean): boolean;
+    /** Buffer-line index of the topmost visible line in `id`'s wrapper. In tail
+     *  mode returns the last line number (matching Mudlet's mCursorY behaviour at
+     *  the end of the buffer). Returns 0 if the element is unmounted or empty.
+     *
+     *  Uses getBoundingClientRect rather than offsetTop because `.output-container`
+     *  is `position: relative` — child offsetTop is relative to *that*, not to the
+     *  scroll-container `.output-wrapper`, so the rectangles are the unambiguous
+     *  way to relate child position to the scroll viewport. */
+    getScrollLine(id: string): number;
+    /** Scroll `id`'s wrapper so `line` (0-indexed) sits at the top. `undefined`
+     *  resumes tail mode (scroll-to-bottom); negative values count from the end
+     *  (Mudlet semantics). Returns false if the wrapper is not mounted. */
+    scrollToLine(id: string, line: number | undefined): boolean;
+    private getScrollStateMut;
+    private applyScrollClasses;
+    /** Direct line-element children of the wrapper (skips the sticky-output
+     *  sentinel, which sits at the end with height: 0). */
+    private lineElements;
+    /** Mudlet setBackgroundColor for a userwindow / miniconsole. */
+    setBackgroundColor(id: string, r: number, g: number, b: number, a?: number): boolean;
+    getBackgroundColor(id: string): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    } | null;
+    /** Mudlet setBackgroundImage for a userwindow / miniconsole. */
+    setBackgroundImage(id: string, url: string, mode: number): boolean;
+    /** Mudlet resetBackgroundImage for a userwindow / miniconsole. */
+    resetBackgroundImage(id: string): boolean;
+    setSize(id: string, width: number, height: number): void;
+    /** Mudlet enableCommandLine(name). Idempotent. Returns false when the
+     *  window doesn't exist. */
+    enableCommandLine(id: string): boolean;
+    /** Mudlet disableCommandLine(name). Idempotent. Returns false when the
+     *  window doesn't exist. The action callback is kept so re-enabling
+     *  resumes the same binding (matches Mudlet's behaviour). */
+    disableCommandLine(id: string): boolean;
+    /** Mudlet setCmdLineStyleSheet(name, qss). Stored as raw QSS; the panel
+     *  translates it through cmdLineQssToScopedCss at render time. Returns
+     *  false when the window doesn't exist. */
+    setCmdLineStyleSheet(id: string, qss: string): boolean;
+    /** Bind the Lua callback fired when the user presses Enter in this
+     *  window's command line. Pass null to clear. Returns false when the
+     *  window doesn't exist. */
+    setCmdLineAction(id: string, cb: ((text: string) => void) | null): boolean;
+    /** Whether a script has bound a per-window Enter handler. */
+    hasCmdLineAction(id: string): boolean;
+    /** Read the bound callback (or null). The TextPanel input invokes this
+     *  directly on Enter so the React tree never sees the function. */
+    getCmdLineAction(id: string): ((text: string) => void) | null;
+    /** Mudlet clearCmdLine([name]) when name is a userwindow — wipes the
+     *  input contents. The seq bump forces React to apply the seed even
+     *  when the value didn't change. Returns false when the window doesn't
+     *  exist or has no command line. */
+    clearWindowCmdLine(id: string): boolean;
+    /** Mudlet printCmdLine([name], text) when name is a userwindow — replaces
+     *  the input contents and moves the caret to the end (React side). */
+    printWindowCmdLine(id: string, text: string): boolean;
+    /** Mudlet appendCmdLine([name], text) when name is a userwindow — pushes
+     *  `text` onto the end of the current contents. */
+    appendWindowCmdLine(id: string, text: string): boolean;
+    /** Used by ScriptingAPI.getCmdLine([name]) when the name targets a window;
+     *  returns the cached value last seeded. The actual live input value is
+     *  reported by the TextPanel through a register callback (see
+     *  registerCmdLineValueProbe). */
+    private cmdLineValueProbes;
+    registerCmdLineValueProbe(id: string, probe: () => string): () => void;
+    getCmdLineValue(id: string): string;
+    bringToFront(id: string): void;
+    /** Mudlet lowerWindow for a userwindow — drop below every other floating
+     *  window. Computes a fresh below-min zIndex so successive lowerWindow
+     *  calls maintain relative order. */
+    sendToBack(id: string): void;
+    dock(id: string, side: DockSide, slotIndex?: number): void;
+    /** Stack panel `id` as a tab with panel `targetId` (or into its existing group). */
+    tabIntoGroup(id: string, targetId: string): void;
+    setActiveTab(panelId: string): void;
+    /** Split panel `id` above or below `targetId` (cross-axis within the same dock slot). */
+    splitIntoGroup(id: string, targetId: string, splitBefore: boolean): void;
+    setSplitFlex(panelId: string, flex: number): void;
+    /** Undock. Pass the panel's screen rect so the floating window appears in-place. */
+    undock(id: string, visualWidth?: number, visualHeight?: number, screenX?: number, screenY?: number): void;
+    getDockExtent(side: DockSide): number;
+    setDockExtent(side: DockSide, size: number): void;
+    setDockFlex(id: string, flex: number): void;
+    /** Set flex for all panels in the same slot (by panel ID, tab-group ID, or split-group ID). */
+    setSlotFlex(slotId: string, flex: number): void;
+    open(id: string, options?: WindowOpenOptions): WindowHandle;
+    close(id: string): void;
+    clearAll(): void;
+    hide(id: string): void;
+    show(id: string): boolean;
+    isVisible(id: string): boolean;
+    /** Stored geometry for a user window / miniconsole — deliberately the saved
+     *  x/y/width/height rather than {@link getSize}'s live DOM rect, so it is an
+     *  exact inverse of moveWindow/resizeWindow (Mudlet's getWindowGeometry
+     *  reads back through the dock widget the same way). Null if unknown. */
+    getGeometry(id: string): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /** The window this one nests inside, or null for a root floating window.
+     *  Used by the ancestor-aware windowVisible walk. */
+    parentOf(id: string): string | null;
+    write(id: string, text: string): void;
+    flushLine(id: string): void;
+    flushAllLines(): void;
+    clear(id: string): void;
+    /**
+     * Mudlet setUserWindowTitle(name, [title]) → bool. With a non-empty title
+     * the panel header shows that string; with an empty/missing title the
+     * window's id is used as the title (matches Mudlet's "reset to default"
+     * behaviour). Returns false when the named window doesn't exist.
+     */
+    setTitle(id: string, title?: string): boolean;
+    focus(id: string): void;
+    has(id: string): boolean;
+    getElement(id: string): HTMLElement | null;
+    /** Mudlet getUserWindowSize. Reports the live rendered size of a userwindow
+     *  / miniconsole when mounted (so docked panels return their actual on-screen
+     *  pixels rather than the stored hint), else falls back to the saved width
+     *  /height. Returns null if the window doesn't exist. Prefers the viewport
+     *  element so the reported box matches the rectangle labels position against —
+     *  not the inner output area, which has paddings and a scrollbar gutter. */
+    getSize(id: string): {
+        width: number;
+        height: number;
+    } | null;
+    private pushLine;
+    private defaultX;
+    private defaultY;
+    private notify;
+    private saveHint;
+    private removeFromSplitGroup;
+    private removeFromGroup;
+    private makeHandle;
+}