@mudlet/mudlet-web 0.3.0

package/dist-lib/ui/cmdline/CommandLineManager.d.ts

@@ -0,0 +1,97 @@
+import { OverlayLayerOrder } from '../layout/overlayLayerOrder';
+export interface CmdLineCreateOptions {
+    /** Parent window id ('main' for the main viewport). */
+    parent?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CmdLineState {
+    name: string;
+    parent: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    visible: boolean;
+    /** Last value pushed from script (printCmdLine / clearCmdLine / appendCmdLine).
+     *  The React input owns its own typed state; this seed is only applied when
+     *  `valueSeq` changes, mirroring the per-userwindow command-line pattern. */
+    value: string;
+    valueSeq: number;
+    /** When false, the input is rendered with the `disabled` attribute so the
+     *  user can't focus/type. Mudlet disableCommandLine(name). */
+    enabled: boolean;
+    /** Raw Qt-style CSS string from setCmdLineStyleSheet. Translated to scoped
+     *  CSS at render time via {@link cmdLineQssToScopedCss}. */
+    styleSheet?: string;
+    /** Lua-side Enter handler. Plain field; not part of the React snapshot. */
+    action: ((text: string) => void) | null;
+}
+type Listener = (cmdLines: CmdLineState[]) => void;
+/**
+ * Registry for overlay command-line widgets (Mudlet createCommandLine). Mirrors
+ * {@link LabelManager}'s shape: per-parent subscribers, one Map keyed by name.
+ *
+ * Distinct from {@link WindowManager}'s per-userwindow command lines — those are
+ * dockview-panel inputs gated by enableCommandLine; these are absolutely-
+ * positioned overlay `<input>` elements on top of a parent viewport, sibling to
+ * createLabel.
+ */
+export declare class CommandLineManager {
+    readonly overlayZ: OverlayLayerOrder;
+    private readonly cmdLines;
+    private readonly listeners;
+    /** Per-cmdline live value probe registered by the React mount. Lets
+     *  ScriptingAPI.getCmdLine read the current typed text without round-
+     *  tripping through React state. */
+    private readonly valueProbes;
+    /** Per-cmdline imperative control registered by the React mount —
+     *  selectAll() drives <input>.select() (Mudlet selectCmdLineText). */
+    private readonly controls;
+    constructor(overlayZ?: OverlayLayerOrder);
+    /** Mudlet createCommandLine(name, x, y, w, h) — false when a cmd line with
+     *  that name already exists. */
+    create(name: string, opts: CmdLineCreateOptions): boolean;
+    has(name: string): boolean;
+    /** Read-only handle on a command line's stored state, for the geometry and
+     *  visibility getters (getWindowGeometry, windowVisible). */
+    get(name: string): Readonly<CmdLineState> | undefined;
+    destroy(name: string): boolean;
+    move(name: string, x: number, y: number): boolean;
+    resize(name: string, width: number, height: number): boolean;
+    /** Mudlet setWindow — reparent a command line into another window's
+     *  overlay. Both the old and the new parent's overlays re-render. */
+    setParent(name: string, parent: string): boolean;
+    show(name: string): boolean;
+    hide(name: string): boolean;
+    raise(name: string): boolean;
+    lower(name: string): boolean;
+    enable(name: string): boolean;
+    disable(name: string): boolean;
+    setStyleSheet(name: string, css: string): boolean;
+    /** Mudlet printCmdLine — replace contents, caret to end. */
+    setValue(name: string, text: string): boolean;
+    /** Mudlet appendCmdLine — push onto the end of the current contents. */
+    appendValue(name: string, text: string): boolean;
+    /** Mudlet clearCmdLine — wipe the contents. */
+    clearValue(name: string): boolean;
+    /** Mudlet getCmdLine — live value via the React-registered probe, falling
+     *  back to the last seed when nothing has mounted yet. */
+    getValue(name: string): string;
+    setAction(name: string, cb: ((text: string) => void) | null): boolean;
+    getAction(name: string): ((text: string) => void) | null;
+    hasAction(name: string): boolean;
+    /** Mudlet selectCmdLineText — highlight all text in the input. */
+    selectAll(name: string): boolean;
+    registerValueProbe(name: string, probe: () => string): () => void;
+    registerControl(name: string, ctrl: {
+        selectAll: () => void;
+    }): () => void;
+    list(parent: string): CmdLineState[];
+    subscribe(parent: string, fn: Listener): () => void;
+    clearAll(): void;
+    private notify;
+}
+export {};

package/dist-lib/ui/cmdline/CommandLineOverlay.d.ts

@@ -0,0 +1,8 @@
+import type { CommandLineManager } from './CommandLineManager';
+import './CommandLineOverlay.css';
+interface CommandLineOverlayProps {
+    manager: CommandLineManager;
+    parent: string;
+}
+export declare function CommandLineOverlay({ manager, parent }: CommandLineOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-lib/ui/codemirror/theme.d.ts

@@ -0,0 +1,5 @@
+import { Compartment } from '@codemirror/state';
+import { syntaxHighlighting } from '@codemirror/language';
+export declare const mudixCmTheme: import("@codemirror/state").Extension;
+export declare const highlightCompartment: Compartment;
+export declare function highlightFor(theme: string): ReturnType<typeof syntaxHighlighting>;

package/dist-lib/ui/commandHistory.d.ts

@@ -0,0 +1,31 @@
+export declare const MAX_HISTORY = 500;
+/** Default number of entries persisted to localStorage when the profile hasn't
+ *  set Mudlet's `commandLineHistorySaveSize`. Matches MAX_HISTORY so existing
+ *  histories survive untouched until the user opts into a smaller save cap. */
+export declare const DEFAULT_HISTORY_SAVE_SIZE = 500;
+/** localStorage key for a profile's command history. History is per-profile —
+ *  one MUD's commands shouldn't surface in another's. The bare prefix (no
+ *  connection) backs the connection screen before a profile is open. */
+export declare function historyStorageKey(connectionId: string | null): string;
+export declare function loadHistory(key: string): string[];
+/** Persist the MRU history, keeping at most `saveSize` entries (Mudlet's
+ *  `commandLineHistorySaveSize`). A negative size means "no cap"; the in-memory
+ *  list is still bounded by MAX_HISTORY via {@link addToHistory}. */
+export declare function saveHistory(items: string[], key: string, saveSize?: number): void;
+export declare function addToHistory(history: string[], item: string): string[];
+export type MatchKind = 'prefix-start' | 'prefix-mid' | 'subseq';
+export interface Match {
+    item: string;
+    mruIndex: number;
+    kind: MatchKind;
+    /** First match position used as the LCP anchor. */
+    anchor: number;
+    /** [start, end) ranges over `item` to visually highlight. */
+    ranges: Array<[number, number]>;
+}
+export declare function matchHistory(prefix: string, history: string[], limit?: number): Match[];
+/** Longest common prefix across all matches, measured from each match's anchor.
+ *  Returns the would-be replacement string if it extends the current prefix,
+ *  null otherwise. Case-insensitive comparison; the returned string preserves
+ *  the casing of the top-ranked match. */
+export declare function computeLcp(matches: Match[], prefix: string): string | null;

package/dist-lib/ui/components/Button.d.ts

@@ -0,0 +1,9 @@
+import type { ButtonHTMLAttributes } from 'react';
+type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'icon' | 'danger';
+type ButtonSize = 'sm' | 'md';
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+}
+export declare function Button({ variant, size, className, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/components/ConfirmDialog.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+export interface ConfirmButton<T = unknown> {
+    label: string;
+    value: T;
+    variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+    autoFocus?: boolean;
+}
+export interface ConfirmOptions<T = unknown> {
+    title?: string;
+    message?: ReactNode;
+    /** Buttons rendered in order, left to right. Last button is treated as the default if none specifies `autoFocus`. */
+    buttons?: ConfirmButton<T>[];
+    /** Returned when the user dismisses via ESC or backdrop click. */
+    dismissValue?: T;
+    /** Disable backdrop-click and ESC dismissal. */
+    blocking?: boolean;
+    /** Visual hint that the action is destructive — adds an icon and styling. */
+    tone?: 'default' | 'danger';
+}
+interface DialogProps<T> extends ConfirmOptions<T> {
+    onResolve: (value: T | undefined) => void;
+}
+export declare function ConfirmDialog<T>({ title, message, buttons, dismissValue, blocking, tone, onResolve, }: DialogProps<T>): import("react/jsx-runtime").JSX.Element;
+type ConfirmFn = <T = boolean>(options: ConfirmOptions<T>) => Promise<T | undefined>;
+export declare function ConfirmProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useConfirm(): ConfirmFn;
+export {};

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

@@ -0,0 +1,9 @@
+import './ContextMenu.css';
+interface ContextMenuProps {
+    x: number;
+    y: number;
+    onClose: () => void;
+    children: React.ReactNode;
+}
+export declare function ContextMenu({ x, y, onClose, children }: ContextMenuProps): import("react").ReactPortal;
+export {};

package/dist-lib/ui/components/FontPicker.d.ts

@@ -0,0 +1,9 @@
+import type { ProfileVFS } from '../../scripting/vfs/ProfileVFS';
+import type { OutputFontSource } from '../../storage';
+interface FontPickerProps {
+    value: OutputFontSource | undefined;
+    onChange: (next: OutputFontSource | undefined) => void;
+    vfs: ProfileVFS | null;
+}
+export declare function FontPicker({ value, onChange, vfs }: FontPickerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/components/FormField.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+interface FormFieldProps {
+    label: string;
+    htmlFor?: string;
+    className?: string;
+    children: ReactNode;
+}
+export declare function FormField({ label, htmlFor, className, children }: FormFieldProps): import("react/jsx-runtime").JSX.Element;
+interface CheckFieldProps {
+    label: string;
+    htmlFor?: string;
+    className?: string;
+    children: ReactNode;
+}
+export declare function CheckField({ label, htmlFor, className, children }: CheckFieldProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/components/HelpTip.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+interface HelpTipProps {
+    label?: string;
+    children: ReactNode;
+}
+export declare function HelpTip({ label, children }: HelpTipProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/components/Input.d.ts

@@ -0,0 +1,6 @@
+import { type InputHTMLAttributes } from 'react';
+interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+    noAutofill?: boolean;
+}
+export declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<HTMLInputElement>>;
+export {};

package/dist-lib/ui/components/Toggle.d.ts

@@ -0,0 +1,10 @@
+interface ToggleProps {
+    id?: string;
+    checked: boolean;
+    onChange: (next: boolean) => void;
+    disabled?: boolean;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+}
+export declare function Toggle({ id, checked, onChange, disabled, ...aria }: ToggleProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/components/index.d.ts

@@ -0,0 +1,9 @@
+export { Button } from './Button';
+export { Input } from './Input';
+export { FormField, CheckField } from './FormField';
+export { ContextMenu } from './ContextMenu';
+export { ConfirmDialog, ConfirmProvider, useConfirm } from './ConfirmDialog';
+export type { ConfirmButton, ConfirmOptions } from './ConfirmDialog';
+export { FontPicker } from './FontPicker';
+export { Toggle } from './Toggle';
+export { HelpTip } from './HelpTip';

package/dist-lib/ui/components/useModalFocus.d.ts

@@ -0,0 +1,18 @@
+/** Visible (Tab-reachable) focusable descendants of `container`, in DOM order. */
+export declare function focusableWithin(container: HTMLElement): HTMLElement[];
+/**
+ * Where a Tab/Shift+Tab should send focus to keep it inside the dialog, or null
+ * to let the browser move focus normally (the common case, mid-list). Wraps at
+ * the ends and pulls focus back in if it has escaped the dialog. Pure — the
+ * caller reads the return and focuses it. Exported for testing.
+ */
+export declare function focusTrapTarget(items: HTMLElement[], active: HTMLElement | null, shiftKey: boolean): HTMLElement | null;
+export interface ModalFocusOptions {
+    /** Move focus into the dialog on open. Default true. Set false when the
+     *  modal manages its own initial focus (e.g. a specific field or button). */
+    autoFocus?: boolean;
+    /** Close on Escape via `onClose`. Default true. Set false when the modal has
+     *  its own Escape handling (then `onClose` may be omitted). */
+    closeOnEscape?: boolean;
+}
+export declare function useModalFocus<T extends HTMLElement = HTMLDivElement>(onClose?: () => void, opts?: ModalFocusOptions): React.RefObject<T | null>;

package/dist-lib/ui/labels/LabelManager.d.ts

@@ -0,0 +1,220 @@
+import type { MoviePlayer } from './gifMovie';
+import { OverlayLayerOrder } from '../layout/overlayLayerOrder';
+export interface LabelCreateOptions {
+    /** Parent window id ('main' for main viewport). Defaults to 'main'. */
+    parent?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Whether to draw the label's background fill. */
+    fillBackground: boolean;
+    /** Whether clicks pass through to whatever is underneath. */
+    clickThrough?: boolean;
+}
+export interface LabelState {
+    name: string;
+    parent: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fillBackground: boolean;
+    clickThrough: boolean;
+    visible: boolean;
+    /** Inner HTML content set via echo()/setLabelText. */
+    html: string;
+    /** rgba 0..255 channels; alpha defaults to 255 when set via setBackgroundColor. */
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /** Mudlet setBackgroundImage(labelName, imageLocation) — resolved CSS URL.
+     *  Labels have no `mode` (unlike consoles): Mudlet just calls
+     *  `QLabel::setPixmap()`, which paints the image at its native pixel size
+     *  (no scaling), left-aligned and vertically centered, clipped to the
+     *  label's geometry. `width`/`height` are the image's resolved intrinsic
+     *  size (filled in asynchronously for SVGs, which otherwise have no CSS
+     *  intrinsic size — see backgroundImageSize.ts); until resolved, or for
+     *  formats CSS already sizes natively, they're left unset. */
+    backgroundImage?: {
+        url: string;
+        width?: number;
+        height?: number;
+    };
+    /** Qt-style CSS string set via setLabelStyleSheet; parsed at render time. */
+    styleSheet?: string;
+    /** Sticky Qt `alignment` widget property, captured from a
+     *  `qproperty-alignment` declaration in any setStyleSheet call. In Qt,
+     *  qproperty-* declarations set the widget property permanently — a later
+     *  setStyleSheet that omits it does NOT revert it (ordinary style is
+     *  replaced wholesale, but the property sticks). So we track it separately
+     *  from `styleSheet` and re-apply it at render. Raw Qt value, e.g.
+     *  "AlignLeft | AlignTop"; translated by qtAlignmentToFlex at render. */
+    alignment?: string;
+    /** Sticky Qt `scaledContents` widget property, captured from a
+     *  `qproperty-scaledContents` declaration in any setStyleSheet call. When
+     *  true, Qt's QLabel::setScaledContents scales the pixmap
+     *  (setBackgroundImage) to fill the entire label instead of painting it at
+     *  native size; LabelOverlay maps that to `background-size: 100% 100%`. Like
+     *  `alignment`, it's a widget property that persists across a later
+     *  stylesheet that omits it. */
+    scaledContents?: boolean;
+    /** Mudlet setLinkStyle(labelName, linkColor, linkVisitedColor, underline) —
+     *  styling for `<a>` links inside the label's HTML. Cleared by
+     *  resetLinkStyle. Colors are any CSS color string (empty = leave default). */
+    linkStyle?: {
+        color?: string;
+        visitedColor?: string;
+        underline: boolean;
+    };
+    /** Click handler installed by setLabelClickCallback. The event table mirrors
+     *  Mudlet's `mudlet.mouse_button` shape: `{button, x, y, alt, ctrl, shift, meta}`. */
+    onClick?: (event: LabelMouseEvent) => void;
+    /** Pointer down (Mudlet release callback fires on mouseup; press is implicit). */
+    onMouseDown?: (event: LabelMouseEvent) => void;
+    /** Pointer up — Mudlet setLabelReleaseCallback. */
+    onMouseUp?: (event: LabelMouseEvent) => void;
+    /** Double-click — Mudlet setLabelDoubleClickCallback. */
+    onDoubleClick?: (event: LabelMouseEvent) => void;
+    /** Pointer move — Mudlet setLabelMoveCallback. */
+    onMouseMove?: (event: LabelMouseEvent) => void;
+    /** Wheel — Mudlet setLabelWheelCallback. event.angleDelta carries the scroll. */
+    onWheel?: (event: LabelWheelEvent) => void;
+    /** Pointer enter — Mudlet setLabelOnEnter. */
+    onMouseEnter?: (event: LabelMouseEvent) => void;
+    /** Pointer leave — Mudlet setLabelOnLeave. */
+    onMouseLeave?: (event: LabelMouseEvent) => void;
+    /** Tooltip text rendered via the title attribute. */
+    tooltip?: string;
+    /** CSS cursor value (e.g. 'pointer', 'crosshair', 'none'). */
+    cursor?: string;
+    /** Animated GIF player installed by Mudlet's setMovie. Rendered as a
+     *  <canvas> instead of the html content (QLabel shows one or the other). */
+    movie?: MoviePlayer;
+}
+/** Event payload for label mouse callbacks. `button` is the Qt button *name*
+ *  Mudlet reports ("LeftButton" / "RightButton" / "MidButton" / "NoButton" / …),
+ *  so ported Geyser scripts that branch on `event.button == "LeftButton"` work. */
+export interface LabelMouseEvent {
+    button: string;
+    x: number;
+    y: number;
+    globalX: number;
+    globalY: number;
+    alt: boolean;
+    ctrl: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+export interface LabelWheelEvent extends LabelMouseEvent {
+    /** Mudlet exposes wheel deltas via `angleDelta.x` / `angleDelta.y` (Qt naming). */
+    angleDelta: {
+        x: number;
+        y: number;
+    };
+}
+type Listener = (labels: LabelState[]) => void;
+export declare class LabelManager {
+    readonly overlayZ: OverlayLayerOrder;
+    private readonly labels;
+    private readonly byParent;
+    private readonly listeners;
+    private indexAdd;
+    private indexRemove;
+    constructor(overlayZ?: OverlayLayerOrder);
+    /** Returns true if a new label was created. Mudlet's createLabel returns
+     *  false when a label with the same name already exists. */
+    create(name: string, opts: LabelCreateOptions): boolean;
+    has(name: string): boolean;
+    /** Read-only handle on a label's stored state, for the geometry/visibility/
+     *  text getters (getWindowGeometry, windowVisible, getLabelText). */
+    get(name: string): Readonly<LabelState> | undefined;
+    destroy(name: string): boolean;
+    move(name: string, x: number, y: number): boolean;
+    resize(name: string, width: number, height: number): boolean;
+    /** Mudlet setWindow — reparent a label into another window's overlay
+     *  ('main', a userwindow / miniconsole id, or a scroll box name). Both
+     *  the old and the new parent's overlays re-render. */
+    setParent(name: string, parent: string): boolean;
+    /** Mudlet `getLabelSizeHint(name)` → the label's preferred `{width,height}`.
+     *  Mudlet returns the QLabel sizeHint (the size its content wants); the
+     *  browser analogue is the rendered node's content extent
+     *  (`scrollWidth`/`scrollHeight`), read off the `data-mudix-label` element.
+     *  Falls back to the configured geometry when the label isn't in the DOM
+     *  yet (hidden, or rendered before mount). null when no such label. */
+    getSizeHint(name: string): {
+        width: number;
+        height: number;
+    } | null;
+    show(name: string): boolean;
+    hide(name: string): boolean;
+    setHtml(name: string, html: string): boolean;
+    /** Mudlet setMovie — install (or replace) the label's GIF player. */
+    setMovie(name: string, player: MoviePlayer): boolean;
+    getMovie(name: string): MoviePlayer | null;
+    /** Mudlet scaleMovie — autoscale tracks the label size (CSS 100%);
+     *  autoscale=false freezes the scale at the label's current geometry.
+     *  False when the label has no movie (matches Mudlet's warning case). */
+    setMovieScale(name: string, autoscale: boolean): boolean;
+    setBackgroundColor(name: string, r: number, g: number, b: number, a?: number): boolean;
+    getBackgroundColor(name: string): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    } | null;
+    setBackgroundImage(name: string, url: string): boolean;
+    /** Fills in the intrinsic pixel size resolved asynchronously for `url`
+     *  (see backgroundImageSize.ts). No-ops if the label's image has since
+     *  changed away from `url` (stale resolution racing a newer call). */
+    setBackgroundImageSize(name: string, url: string, width: number, height: number): boolean;
+    resetBackgroundImage(name: string): boolean;
+    setStyleSheet(name: string, css: string): boolean;
+    /** Mudlet `setLinkStyle(labelName, linkColor, linkVisitedColor, underline)`. */
+    setLinkStyle(name: string, color: string, visitedColor: string, underline: boolean): boolean;
+    /** Mudlet `resetLinkStyle(labelName)` — drop any setLinkStyle override. */
+    resetLinkStyle(name: string): boolean;
+    /** Mudlet `getLabelStyleSheet(name)` — the Qt-style CSS last set via
+     *  {@link setStyleSheet}, or `""` when none is set. Returns `undefined`
+     *  when the label doesn't exist so the caller can distinguish that case. */
+    getStyleSheet(name: string): string | undefined;
+    setClickCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
+    setMouseUpCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
+    setDoubleClickCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
+    setMouseMoveCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
+    setWheelCallback(name: string, fn: ((e: LabelWheelEvent) => void) | undefined): boolean;
+    setMouseEnterCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
+    setMouseLeaveCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
+    setTooltip(name: string, text: string | undefined): boolean;
+    setClickThrough(name: string, value: boolean): boolean;
+    setCursor(name: string, cursor: string | undefined): boolean;
+    raise(name: string): boolean;
+    lower(name: string): boolean;
+    list(parent: string): LabelState[];
+    subscribe(parent: string, fn: Listener): () => void;
+    clearAll(): void;
+    /**
+     * Mark a parent's overlay dirty, flushed once on the next frame.
+     *
+     * A Geyser reflow re-issues moveWindow/resizeWindow for every widget in a
+     * subtree (Geyser.Container:reposition recurses into every child), and
+     * f2ce-tools' table resize walks every row and cell the same way. Notifying
+     * synchronously per call meant one overlay re-render per widget — hundreds
+     * of renders for a single layout pass. Qt has no equivalent cost, which is
+     * why the same package stays smooth in desktop Mudlet.
+     *
+     * The whole cascade is synchronous, so it collapses into one flush per
+     * parent afterwards. Listeners only ever saw the final state anyway — the
+     * intermediate values were never painted, being on the same blocked task.
+     * subscribe() keeps its synchronous first call so mounts stay immediate.
+     */
+    private dirty;
+    private flushScheduled;
+    private notify;
+    /** Immediate, uncoalesced notification for one parent. */
+    private flushParent;
+}
+export {};

package/dist-lib/ui/labels/LabelOverlay.d.ts

@@ -0,0 +1,9 @@
+import type { LabelManager } from './LabelManager';
+import './LabelOverlay.css';
+export declare function domButtonToMudlet(type: string, domButton: number): string;
+interface LabelOverlayProps {
+    manager: LabelManager;
+    parent: string;
+}
+export declare function LabelOverlay({ manager, parent }: LabelOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-lib/ui/labels/backgroundImageSize.d.ts

@@ -0,0 +1,10 @@
+export declare function resolveSvgIntrinsicSize(url: string): Promise<{
+    width: number;
+    height: number;
+} | null>;
+/** Exported for tests. Mirrors Qt's defaultSize(): explicit width+height
+ *  wins, else the viewBox extent, else no intrinsic size (null). */
+export declare function parseSvgIntrinsicSize(svgText: string): {
+    width: number;
+    height: number;
+} | null;

package/dist-lib/ui/labels/cursorShapes.d.ts

@@ -0,0 +1,6 @@
+export declare const QT_CURSOR_TO_CSS: Record<number, string>;
+/** Reverse map of Mudlet's `mudlet.cursor` table (CursorShapes.lua). Used so
+ *  setLabelCursor accepts the string name directly without requiring the
+ *  bundled GUIUtils.lua wrapper to be loaded. -1 ('Reset') clears the cursor.
+ */
+export declare const QT_CURSOR_NAME_TO_INT: Record<string, number>;

package/dist-lib/ui/labels/gifMovie.d.ts

@@ -0,0 +1,100 @@
+export interface GifFrame {
+    /** Full-canvas RGBA pixels, already composited (disposal applied).
+     *  Explicitly ArrayBuffer-backed so it satisfies the ImageData ctor. */
+    pixels: Uint8ClampedArray<ArrayBuffer>;
+    /** Frame hold time in ms. Sub-2cs delays are bumped to 100ms, matching the
+     *  de-facto browser behaviour for degenerate "0 delay" GIFs. */
+    delayMs: number;
+}
+export interface DecodedGif {
+    width: number;
+    height: number;
+    /** Total number of times the animation plays; Infinity for looping GIFs
+     *  (NETSCAPE2.0 loop count 0). No extension → plays once, like QMovie. */
+    plays: number;
+    frames: GifFrame[];
+}
+/** Decode a GIF87a/GIF89a file into composited full frames. Throws on data
+ *  that isn't a GIF or is structurally broken; tolerates a truncated tail the
+ *  way browsers do (keeps the frames decoded so far). */
+export declare function decodeGif(bytes: Uint8Array): DecodedGif;
+/** How the movie canvas is sized inside its label — mirrors QMovie/QLabel:
+ *  'none' shows the GIF at native size; 'auto' tracks the label size (CSS
+ *  100%, so a label resize rescales for free — Mudlet's autoscale reconnect);
+ *  'fixed' is scaleMovie(name, false): scaled once to the size at call time. */
+export type MovieScale = {
+    mode: 'none';
+} | {
+    mode: 'auto';
+} | {
+    mode: 'fixed';
+    width: number;
+    height: number;
+};
+/**
+ * Playback controller for one decoded GIF on one label. The React layer
+ * attaches/detaches the actual <canvas>; the player keeps ticking regardless
+ * (QMovie also runs while hidden) and repaints the current frame on attach.
+ */
+export declare class MoviePlayer {
+    /** Consumed by the label renderer; set via LabelManager.setMovieScale so
+     *  the overlay re-renders when it changes. */
+    scale: MovieScale;
+    private _gif;
+    private canvas;
+    private timer;
+    private frame;
+    private speedPct;
+    private playing;
+    /** start()/pause() intent, remembered separately from `playing` so a
+     *  pending player (frames still decoding) knows whether to begin playback
+     *  when resolveFrames delivers them. */
+    private wantsPlaying;
+    private playsLeft;
+    constructor(gif: DecodedGif);
+    /** A player whose frames arrive later via {@link resolveFrames} — used for
+     *  the async ImageDecoder path (animated WebP / APNG) so setMovie can
+     *  install the movie synchronously; dimensions come from the file header. */
+    static pending(width: number, height: number): MoviePlayer;
+    get gif(): DecodedGif;
+    get frameCount(): number;
+    get currentFrame(): number;
+    get isPlaying(): boolean;
+    get speed(): number;
+    /** Register the mounted canvas (null on unmount) and paint the current frame. */
+    attach(canvas: HTMLCanvasElement | null): void;
+    /** QMovie::start — begins/resumes playback; restarts when at the end. */
+    start(): void;
+    /** QMovie::setPaused(true) — stays on the current frame. */
+    pause(): void;
+    /** Deliver asynchronously-decoded frames to a {@link pending} player.
+     *  Honors the intent expressed meanwhile: playback begins only if start()
+     *  was called and no pause()/stop() followed it. */
+    resolveFrames(gif: DecodedGif): void;
+    /** Full teardown when the label goes away or the movie is replaced. */
+    stop(): void;
+    /** QMovie::jumpToFrame — 0-based; false when the frame doesn't exist. */
+    jumpToFrame(n: number): boolean;
+    /** QMovie::setSpeed — percent, 100 = recorded speed. <= 0 halts advancing
+     *  (paused-in-place) until a positive speed is set again. */
+    setSpeed(percent: number): boolean;
+    private schedule;
+    private clearTimer;
+    private draw;
+}
+/** Whether the async decode path (animated WebP / APNG) exists in this
+ *  browser. Firefox lacks ImageDecoder as of 2026 — GIFs still work there. */
+export declare function supportsImageDecoder(): boolean;
+/** Identify non-GIF bytes the ImageDecoder path accepts for setMovie:
+ *  WebP (animated or static) and PNG (APNG or static). Returns the MIME type
+ *  and the header-derived dimensions a pending player needs; null otherwise. */
+export declare function sniffDecodableImage(bytes: Uint8Array): {
+    mime: 'image/png' | 'image/webp';
+    width: number;
+    height: number;
+} | null;
+/** Decode WebP/APNG through ImageDecoder into the DecodedGif shape. Each
+ *  decoded VideoFrame is already fully composited (the decoder applies
+ *  blending/disposal), so frames just need rasterizing to RGBA — done by
+ *  drawing onto an OffscreenCanvas (available wherever ImageDecoder is). */
+export declare function decodeAnimatedImage(bytes: Uint8Array, mime: string): Promise<DecodedGif>;