@mudlet/mudlet-web 0.5.0 → 1.0.1

package/dist-lib/map/MudletHighlightOverlay.d.ts

@@ -1,13 +1,13 @@
 import type { MapState, SceneOverlay, SceneOverlayContext, Shape, ViewportBounds } from 'mudlet-map-renderer';
 import type { MapStore } from './MapStore';
-import type { MudixMapReader } from './MudixMapReader';
+import type { MudletMapReader } from './MudletMapReader';
 export declare class MudletHighlightOverlay implements SceneOverlay {
     private readonly mapStore;
     private readonly reader;
     private ctx?;
     private mapStoreUnsub?;
     private areaHandler?;
-    constructor(mapStore: MapStore, reader: MudixMapReader);
+    constructor(mapStore: MapStore, reader: MudletMapReader);
     attach(ctx: SceneOverlayContext): void;
     detach(): void;
     /** Force a re-render from outside. The renderer's `refresh()` doesn't

package/dist-lib/map/{MudixMapReader.d.ts → MudletMapReader.d.ts}

@@ -2,7 +2,7 @@ import type { MapReader, IArea, IMapReader, ViewportBounds, ViewportDataSource,
 import type { MapStore } from './MapStore';
 type RoomShape = ReturnType<MapReader['getRoom']>;
 /**
- * Live {@link IMapReader} backed by Mudix's {@link MapStore}.
+ * Live {@link IMapReader} backed by Mudlet's {@link MapStore}.
  *
  * The renderer is constructed once on panel mount and held for the lifetime of
  * the panel. Whenever the store mutates (script-built rooms, binary load,
@@ -33,7 +33,7 @@ type RoomShape = ReturnType<MapReader['getRoom']>;
  * binary-reader pipeline applies. Doing it inside the reader (instead of in
  * the panel) keeps `MapPanel` pure-view: it never sees the wire format.
  */
-export declare class MudixMapReader implements IMapReader, ViewportDataSource, HashLookupCapable {
+export declare class MudletMapReader implements IMapReader, ViewportDataSource, HashLookupCapable {
     private readonly store;
     readonly viewportAware: true;
     readonly hashLookupCapable: true;

package/dist-lib/map/areaGraph.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Desktop's area graph (TAreaGraph.cpp): the areas of a map as a graph — a
+ * node per area, a link per pair of areas joined by at least one normal or
+ * special exit — and a 2D world position per area from a deterministic
+ * force-directed layout. Areas have no shared coordinates of their own, so
+ * this is what places them relative to each other in a world view.
+ *
+ * A position is where the centre of the area's room bounding box goes, in
+ * room units. Positions are kept in the map user data under
+ * {@link AREA_GRAPH_LAYOUT_KEY}, so they travel with the map file. Areas that
+ * already have one keep it when others are added, moving only to make way for
+ * an area that grew into them; setPosition() pins an area so it never moves.
+ *
+ * A port, step for step: the layout is part of the map file, so the same map
+ * has to come out the same way here as there. The randomness is desktop's own
+ * splitmix64 over the area ids (in BigInt, as it is 64-bit arithmetic), and
+ * every loop walks in the order desktop's does, since the order the pushes are
+ * applied in decides where areas end up.
+ */
+/** TAreaGraph::cLayoutUserDataKey. */
+export declare const AREA_GRAPH_LAYOUT_KEY = "system.areaGraphLayout";
+/** TAreaGraph::cMaxCoordinate: positions further out are refused, which keeps
+ *  the layout's grid cell arithmetic in range; computed ones are clamped. */
+export declare const AREA_GRAPH_MAX_COORDINATE = 1000000000000000;
+type Point = [number, number];
+export interface AreaGraphNode {
+    areaId: number;
+    name: string;
+    roomCount: number;
+    /** Half the diagonal of the room bounding box, at least 2: how much room the area needs. */
+    radius: number;
+    position: Point;
+    pinned: boolean;
+}
+export interface AreaGraphLink {
+    /** fromArea < toArea; an exit counts once in whichever direction it runs. */
+    fromArea: number;
+    toArea: number;
+    exitCount: number;
+}
+/** A room as the graph reads it: where it is, and where its exits lead. */
+export interface AreaGraphRoom {
+    area: number;
+    x: number;
+    y: number;
+    /** The twelve normal exits' targets, then the special exits' — ≤ 0 is none. */
+    exits(): Iterable<number>;
+}
+/** What the graph reads from the map it belongs to. */
+export interface AreaGraphSource {
+    /** Every area with a name, by id (setAreaName makes one with only a name). */
+    areaNames(): ReadonlyMap<number, string>;
+    /** Every area that exists as an area, with its rooms. */
+    areaRooms(): ReadonlyMap<number, readonly number[]>;
+    room(id: number): AreaGraphRoom | undefined;
+    rooms(): Iterable<AreaGraphRoom>;
+    getUserData(key: string): string | undefined;
+    /** Undefined removes the key. */
+    setUserData(key: string, value: string | undefined): void;
+}
+export declare class AreaGraph {
+    private readonly source;
+    private nodes;
+    private links;
+    private stored;
+    /** What the user data held when this last read or wrote it, to notice a
+     *  load or a script changing it. */
+    private storedLayoutText;
+    private storedDirty;
+    private storedLayoutRead;
+    private built;
+    constructor(source: AreaGraphSource);
+    /** TAreaGraph::radiusOf — in double, as the span of int room coordinates can overflow an int. */
+    static radiusOf(minX: number, maxX: number, minY: number, maxY: number): number;
+    /** The nodes in area id order, each with its position. Call {@link refresh} first. */
+    getNodes(): AreaGraphNode[];
+    /** Sorted by (fromArea, toArea). */
+    getLinks(): AreaGraphLink[];
+    /**
+     * TAreaGraph::refresh. Desktop skips the rebuild when the map's revision
+     * has not moved; Mudlet Web keeps no such counter, so the graph is rebuilt
+     * every time and laid out again only when, as there, an area came, went or
+     * changed size, or the stored layout changed under it.
+     */
+    refresh(): void;
+    /** Pins the area there. False if there is no such area or a coordinate
+     *  is not finite or beyond the limit. */
+    setPosition(areaId: number, position: Point): boolean;
+    /** Discards the stored positions (but the pinned ones, if asked) and lays everything out again. */
+    resetLayout(keepPinned: boolean): void;
+    /** Drops a deleted area's stored position, which a later area given the
+     *  same id would otherwise take. */
+    forgetArea(areaId: number): void;
+    /** True if an area was added or removed or changed size. */
+    private rebuildGraph;
+    private rebuildLinks;
+    private readStoredLayout;
+    private writeStoredLayout;
+    private radiusOfArea;
+    private nodeIds;
+    /** Places areas with no position, then pushes apart any that overlap. */
+    private layoutAreas;
+    private placeNewAreas;
+    /** Shelf-packs components laid out on their own into rows below what is already placed. */
+    private packComponents;
+    /**
+     * Fruchterman-Reingold in its grid form — areas repel only within twice
+     * their ideal distance, which keeps a step near linear in the number of
+     * areas — with each pair's ideal distance set by the two areas' sizes.
+     * Only areas not in `fixed` move.
+     */
+    private simulate;
+    /**
+     * Pushes apart overlapping areas. Of a pair, the one with the higher
+     * mobility moves, both move if equal, and neither if both are pinned; an
+     * area missing from `mobilityOf` is new.
+     */
+    private removeOverlaps;
+}
+export {};

package/dist-lib/map/environmentKit.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Desktop's environment kits (EnvironmentKit.cpp): the kind of ground an
+ * environment is, for the 3D map styles that draw rooms by it rather than by
+ * colour alone. A game names the kit for an environment with
+ * setMapEnvironmentKit; until it does, one is guessed from the colour the
+ * environment is drawn in. Mudlet Web draws no 3D map, but the names are map
+ * data — kept in the map's user data, so they travel with the map file — and
+ * the guess is what a script reads back, so both follow desktop exactly.
+ */
+/** The kits, in the order desktop's refusal lists them. */
+export declare const ENVIRONMENT_KITS: readonly ["plain", "water", "road", "forest", "building"];
+export type EnvironmentKit = typeof ENVIRONMENT_KITS[number];
+/** The map user data key the named kits are saved under, as a JSON object of
+ *  environment id to kit name. */
+export declare const ENVIRONMENT_KIT_USER_DATA_KEY = "system.mapStyle.environmentKits";
+export declare const isEnvironmentKit: (name: unknown) => name is EnvironmentKit;
+/**
+ * EnvironmentKit::guess: blue is water, green forest, grey, brown and tan
+ * road, anything else a building. Nearly black is a road and nearly white a
+ * building, as neither has a hue to go by. Worked in HSL, as QColor::toHsl.
+ */
+export declare function guessEnvironmentKit([r255, g255, b255]: readonly [number, number, number]): EnvironmentKit;
+/** EnvironmentKit::stored: the kits the map names. An entry that cannot be
+ *  read — a key that is not a number, a name that is not a kit — is left out,
+ *  as is everything when what is saved is not a JSON object. */
+export declare function storedEnvironmentKits(saved: string | undefined): Map<number, EnvironmentKit>;
+/**
+ * EnvironmentKit::store: set or, with no kit, clear one environment's kit,
+ * keeping every other entry as it was, even one that cannot be read. Answers
+ * the new saved value — undefined when nothing is left, which removes the key —
+ * or null, refusing, when what is saved is not a JSON object, rather than
+ * overwrite it.
+ */
+export declare function storeEnvironmentKit(saved: string | undefined, environmentId: number, kit: EnvironmentKit | null): {
+    value: string | undefined;
+} | null;

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

@@ -0,0 +1,90 @@
+import type { MudletMap } from 'mudlet-map-binary-reader';
+/**
+ * The image a text map label carries, drawn the way TMap::createMapLabel draws
+ * it. Desktop renders the label once, at creation, into a pixmap — background
+ * fill, a one-pixel outline made of four offset copies of the text when the
+ * outline colour differs from the foreground, then the text — crops it to the
+ * text's bounding rectangle, and stores that pixmap in the map file. Its 2D map
+ * paints labels from the pixmap alone, so a label saved without one opens blank
+ * on desktop.
+ */
+export interface LabelPixmapInput {
+    text: string;
+    /** Point size, as passed to createMapLabel. */
+    fontSize: number;
+    /** Font family; empty means the default face. */
+    fontName?: string;
+    fg: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    bg: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    outline: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+}
+export interface LabelPixmap {
+    /** The PNG, base64-encoded — how MapStore holds every label pixmap. */
+    base64: string;
+    /** The pixmap's size in pixels — desktop's label box before the zoom divide. */
+    width: number;
+    height: number;
+}
+/**
+ * Render a label's pixmap, or null when there is no canvas to draw with (a
+ * worker, a test DOM) — the label then keeps an empty pixmap, as before.
+ */
+export declare function renderLabelPixmap(input: LabelPixmapInput): LabelPixmap | null;
+/**
+ * The map with every label pixmap as raw bytes, which is what
+ * `writeMapToBuffer` needs. MapStore holds pixmaps as base64 strings (cheap to
+ * clone and to JSON); handed one, the writer emits the string's characters in
+ * place of the PNG and the file no longer reads back — in Mudlet or here.
+ * Labels are copied, never changed in place, so the store keeps its strings.
+ *
+ * A string that is not a base64 PNG (a pixmap from a map written before image
+ * labels carried their image, which kept the file's path there) is written as no image: decoded, it would be junk bytes the
+ * reader cannot find the end of, and every record after it would misparse.
+ */
+export declare function withLabelPixmapBytes(map: MudletMap): MudletMap;
+export declare const isPng: (b: Uint8Array) => boolean;
+/**
+ * The pixmap an image label is created with, the way TMap::createMapImageLabel
+ * makes it: a transparent `width * zoom` by `height * zoom` pixmap with the image
+ * painted over it, kept as a base64 PNG — so getMapLabel, the map file and
+ * saveJsonMap carry the picture and never the path.
+ *
+ * Built synchronously, since createMapImageLabel answers at once:
+ *  - a PNG file is that data already and is kept as it is;
+ *  - an XPM (text, so a script can write one) is read and scaled here;
+ *  - a missing or empty file is the bare transparent pixmap, as on desktop.
+ * Any other format needs the browser to decode it, which is asynchronous:
+ * `pending` then resolves to the finished pixmap (null where there is no canvas
+ * to draw with), and until it does the label holds the transparent one.
+ */
+export declare function imageLabelPixmap(bytes: Uint8Array | null, width: number, height: number, zoom: number): {
+    pixmap: string;
+    pending?: Promise<string | null>;
+};
+interface Rgba {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** An XPM (version 3) image as RGBA, or null when the bytes are not one. */
+export declare function readXpm(bytes: Uint8Array): Rgba | null;
+export declare function crc32(bytes: Uint8Array): number;
+/** RGBA pixels as a base64 PNG, encoded synchronously — what a pixmap has to
+ *  be before a label can hold it, without waiting on a canvas. */
+export declare function encodePngBase64(rgba: Uint8Array, width: number, height: number): string;
+export {};

package/dist-lib/map/mapImageExport.d.ts

@@ -1,10 +1,44 @@
 import type { Settings as MapRendererSettings } from 'mudlet-map-renderer';
 import type { MapStore } from './MapStore';
 import { type MapperSettings } from '../storage/schema';
+/**
+ * One profile-supplied font family as a CSS string literal, safe to concatenate
+ * into a `font-family` list.
+ *
+ * The backslash must be escaped *before* the quote, and escaping the quote
+ * alone is worse than not escaping at all. Take a family ending in a single
+ * backslash: quote-only escaping emits `'Foo\'`, whose closing quote is now
+ * itself escaped, so the literal never terminates and the rest of the
+ * declaration is swallowed as string content. Doubling the backslash first
+ * gives `'Foo\\'`, which closes properly around one literal backslash.
+ * (CodeQL alert 23 caught the original, which escaped only the quote.)
+ *
+ * Line terminators cannot appear in a CSS string at all, escaped or not, so
+ * they are dropped rather than encoded. The value reaches the renderer's canvas
+ * `font` shorthand today, where a malformed string merely fails to parse — but
+ * it is a profile field a package can set through the mapper settings, and the
+ * next consumer might be a stylesheet.
+ */
+export declare function cssFontFamilyLiteral(family: string): string;
+/** The bundled room-symbol font. Mudlet's default too, and the reason it has one:
+ *  a generic family picks a different glyph shape per operating system, so the
+ *  same map looks different on each machine. */
+export declare const BUNDLED_SYMBOL_FONT = "Bitstream Vera Sans Mono";
+/**
+ * The CSS `font-family` room symbols are drawn with — the profile's chosen font
+ * first, the bundled one behind it, so a family this device does not have still
+ * lands somewhere sensible.
+ *
+ * One function because three places have to agree on the answer: the renderer,
+ * the map image export that configures it, and the symbol-usage report, which
+ * would be lying if it drew a symbol in a different font from the map.
+ */
+export declare function mapSymbolFontStack(mapper: MapperSettings | undefined): string;
 /**
  * Copy user-set fields from MapperSettings onto a live renderer settings
- * object. Anything left undefined in `mapper` is intentionally not touched
- * so the renderer's own createSettings() defaults stay in effect.
+ * object. Most fields left undefined in `mapper` are intentionally not touched
+ * so the renderer's own createSettings() defaults stay in effect; room size and
+ * exit width are the exception (see below).
  */
 export declare function applyMapperSettings(target: MapRendererSettings, mapper: MapperSettings | undefined): void;
 /**

package/dist-lib/map/mapStyle.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The styles desktop's modern 3D mapper draws in (MapStyle::ids()), in the
+ * order its setConfig refusal names them. Mudlet Web has no 3D view to draw
+ * them with, but the choice is ordinary profile data: getConfig/setConfig
+ * read and write it, and the profile save carries it as `<Host mapStyle="…">`,
+ * so a profile moved to desktop opens in the style it was set to.
+ */
+export declare const MAP_STYLES: readonly string[];
+/** MapStyle::defaultId(): what a new profile, and a save that names none or an
+ *  unknown one, starts on. */
+export declare const DEFAULT_MAP_STYLE = "tiles";

package/dist-lib/map/mapVersion.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Mudlet map format-version gate.
+ *
+ * Mudlet's own reader checks the leading format-version int *before* it parses
+ * anything and tells the player, on the main console, exactly why a map file
+ * was refused (`TMap::readMap`, src/TMap.cpp:1531-1573). `mudlet-map-binary-reader`
+ * has no equivalent: it throws a bare `Error("Unsupported Mudlet map version
+ * N. Supported version(s): 16, 17, 18, 19, 20.")` that every map entry point
+ * used to swallow into a `console.warn`, leaving the player with a blank map
+ * window and nothing to act on.
+ *
+ * So the version is read here, on this side of the library, and classified into
+ * the same cases Mudlet reports — with Mudlet's wording, since the player is
+ * being told the same thing.
+ */
+/**
+ * Highest format version this build can read.
+ *
+ * Mudlet desktop's `mMaxVersion` (src/TMap.h:351) is also 20; here the ceiling
+ * comes from `mudlet-map-binary-reader`, which registers version models for
+ * 16-20 only (see its `getSupportedVersions`, not exported — hence the literal;
+ * `tests/map/mapVersionMessages.test.ts` pins these constants against the
+ * library's actual behaviour so a dependency bump cannot silently desync them).
+ */
+export declare const MAP_MAX_SUPPORTED_VERSION = 20;
+/**
+ * Lowest format version this build can read. Desktop Mudlet reads much older
+ * maps (down to version 1, warning from below 4 — src/TMap.cpp:1561), so a map
+ * we reject here is not necessarily lost: desktop can still open it and re-save
+ * it in the current format.
+ */
+export declare const MAP_MIN_SUPPORTED_VERSION = 16;
+/** Why a map buffer was refused, in the three shapes Mudlet distinguishes. */
+export type MapVersionFault = 'not-a-map' | 'too-new' | 'too-old';
+/**
+ * A map buffer whose format version this build cannot read.
+ *
+ * `messages` carries the console lines to post, already in Mudlet's
+ * `"[ PREFIX ] - body"` form (see `cTelnet::postMessage`, src/ctelnet.cpp:4436,
+ * which colours off that prefix); `summary` is the one-line version for UI that
+ * has a small error slot rather than a console.
+ */
+export declare class MapVersionError extends Error {
+    readonly fault: MapVersionFault;
+    readonly version: number;
+    readonly messages: string[];
+    readonly summary: string;
+    constructor(fault: MapVersionFault, version: number, messages: string[], summary: string);
+}
+/**
+ * The format version a Mudlet `.dat` buffer declares: the very first value in
+ * the stream, a Qt `qint32` written big-endian by `QDataStream`
+ * (`mudlet-map-binary-reader`'s own `readMapVersion` reads the same four bytes
+ * through `QInt.read`). Returns `NaN` when the buffer is too short to hold one.
+ */
+export declare function readMapFormatVersion(buf: ArrayBuffer): number;
+/**
+ * Throw {@link MapVersionError} when `buf` declares a format version this build
+ * cannot read, mirroring `TMap::readMap`'s pre-parse gate (src/TMap.cpp:1531-1573).
+ * Returns the version otherwise.
+ *
+ * `source` is the file name / origin to quote in the message, when the caller
+ * has one (Mudlet always does; here a buffer can come from IndexedDB or a
+ * download, in which case the clause is simply left off).
+ */
+export declare function assertReadableMapVersion(buf: ArrayBuffer, source?: string): number;

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

@@ -10,8 +10,8 @@ export interface ExitWeightFilterResult {
     weightOverride?: number;
 }
 /**
- * Called once per candidate exit while the graph is explored, with the room
- * being expanded and the exit's key — the short direction name ("e", "up") for
+ * Called once for every exit in the map before a search (see filterEveryExit),
+ * with the exit's source room and its key — the short direction name ("e", "up") for
  * stock exits, or the verbatim command for special exits. Mirrors Mudlet's
  * `applyExitWeightFilter(source, exitKey)` (TMap.cpp).
  */

package/dist-lib/mud/CharLoginController.d.ts

@@ -0,0 +1,230 @@
+/**
+ * GMCP `Char.Login` sign-in, versions 1 and 2, for one profile's session.
+ *
+ * Port of Mudlet's `GMCPAuthenticator` (development branch): it reads the
+ * game's `Char.Login.Default`, decides how to answer (see `charLoginFlow`),
+ * replays and stores password-less reconnect tokens, offers `Char.Login.URL`
+ * sign-in pages, and runs the client-driven OAuth flow (`oauthClientFlow`).
+ * React stays out of it — `ProfileSession` supplies the UI through
+ * {@link CharLoginUi} and forwards the session's events.
+ *
+ * Where it differs from desktop, and why:
+ *
+ * - **No browser launch.** Mudlet opens the system browser itself when it has
+ *   evidence the player wants to sign in. A browser blocks a tab opened outside
+ *   a user gesture, so every sign-in page becomes a button (and a console link)
+ *   the player clicks.
+ * - **Storage is the credential vault.** Mudlet writes tokens to the OS
+ *   keychain. Ours go into the vault, encrypted, and nowhere else: with no
+ *   vault, or a locked one, `token_storage` says false and an arriving token
+ *   is dropped, as the standard requires of a client that said so.
+ * - **One session per profile.** Mudlet's rotated-token retry and rejected-token
+ *   fingerprint exist because two desktop instances can share one keychain
+ *   entry. A profile here is held by one tab at a time (per-profile Web Locks),
+ *   so a rejected token is simply dead.
+ * - **A version 1 popup.** Mudlet Web raises `CharLoginModal` when a version 1
+ *   game rejects a saved password; Mudlet does not. Version 2 never opens it.
+ */
+import type { VaultSignIn } from '../vault/vaultRecord';
+import { type CharLoginCapabilities, type CharLoginResult, type CharLoginToken, type CharLoginUrl } from './protocol/charLoginFlow';
+import { OAuthClientFlow, type OAuthAuthorization, type OAuthClientFlowOptions } from './protocol/oauthClientFlow';
+/** A sign-in page waiting for the player to open it. */
+export interface SignInOffer {
+    url: string;
+    provider?: string;
+    /** `server`: a `Char.Login.URL` — the game finishes the sign-in itself.
+     *  `client`: our own OAuth flow, which is waiting for the redirect. */
+    flow: 'server' | 'client';
+}
+/** The session operations the controller drives (a `MudSession` satisfies it). */
+export interface CharLoginSession {
+    sendCharLoginCredentials(account?: string, password?: string, tokenStorage?: boolean): void;
+    sendCharLoginReconnect(account: string, token: string, secureOnly: boolean, tokenStorage?: boolean): boolean;
+    sendCharLoginResume(account: string, provider: string, tokenStorage?: boolean): void;
+    sendCharLoginAuthCode(auth: OAuthAuthorization, tokenStorage?: boolean): boolean;
+    readonly gameTransportSecure: boolean;
+    dontReconnect: boolean;
+    reconnect(): boolean;
+}
+/** Where saved sign-ins live — the credential vault, via `vaultAccess`. */
+export interface CharLoginVault {
+    /** A saved password or token for this profile sits in a locked vault. */
+    needsUnlock(): boolean;
+    /** The saved sign-in, when there is one and the vault is open. */
+    signIn(): VaultSignIn | undefined;
+    /** A vault exists and is locked. */
+    locked(): boolean;
+    /** No vault exists, but one could be set up here. False in a build that
+     *  ships no vault, which must not be pointed at one. */
+    missing(): boolean;
+    /** Whether the vault holds a token for this profile — answerable locked. */
+    hasSignIn(): boolean;
+    /** Whether a token handed to us now would be kept (`token_storage`). */
+    canStore(): boolean;
+    save(entry: VaultSignIn | null): Promise<boolean>;
+}
+/** What the controller needs from the UI. */
+export interface CharLoginUi {
+    /** Text auto-login (Mudlet's login timers) — GMCP takes the login over. */
+    cancelTextAutoLogin(): void;
+    /** Raise the version 1 credentials popup, keeping one already up. */
+    showPrompt(): void;
+    /** Show a rejected attempt's reason in the popup (raising it if needed). */
+    showPromptError(message: string): void;
+    closePrompt(): void;
+    /** Ask to unlock the vault; answer with {@link CharLoginController.vaultUnlockDone}. */
+    requestUnlock(reason: 'read' | 'store'): void;
+    /** Offer to set up a vault — once a visit, when none exists and the game
+     *  could have handed over a sign-in to keep. */
+    suggestVaultSetup(): void;
+    /** Show (or with null, withdraw) a sign-in page for the player to open. */
+    offerSignIn(offer: SignInOffer | null): void;
+    /** A console notice in Mudlet's house style. */
+    post(level: 'INFO' | 'WARN', text: string): void;
+}
+export interface CharLoginControllerOptions {
+    session: CharLoginSession;
+    vault: CharLoginVault;
+    ui: CharLoginUi;
+    /** The player's saved account + password (`utils/storedCredentials`). */
+    readStoredLogin(): {
+        account: string;
+        password: string;
+    };
+    /** The client-driven OAuth redirect URI, or null when this page cannot run
+     *  the flow at all (no WebCrypto, no BroadcastChannel). */
+    oauthRedirectUri(): string | null;
+    /** Seams for tests. */
+    createOAuthFlow?: (opts: OAuthClientFlowOptions) => Pick<OAuthClientFlow, 'start' | 'abort' | 'done'>;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** A server can pack many `Char.Login.Default` frames into one burst, and each
+ *  attempt reads the vault and may send a frame. One attempt a second, the
+ *  burst folded into one — Mudlet's `scmSignInAttemptInterval`. */
+export declare const SIGN_IN_ATTEMPT_INTERVAL_MS = 1000;
+/** How long a replayed token waits for the `Char.Login.Result` that answers it
+ *  before the game is treated as one that ignores `Char.Login.Reconnect` —
+ *  Mudlet's `scmReconnectResultTimeout`. */
+export declare const RECONNECT_RESULT_TIMEOUT_MS = 15000;
+export declare class CharLoginController {
+    private readonly opts;
+    /** Credentials have been sent once this connection. */
+    private attempted;
+    /** The player chose "Use text login". */
+    private declined;
+    /** The player dismissed the vault unlock prompt this connection. */
+    private vaultDeclined;
+    /** A Char.Login request is parked behind the vault unlock prompt. */
+    private vaultPending;
+    /** Why the parked request asked. */
+    private vaultPendingReason;
+    /** The player said "Not now" to opening the vault just to keep a new
+     *  sign-in. Lasts the visit, not the connection: the vault stays locked
+     *  across reconnects, and asking at every one would nag. */
+    private storeDeclined;
+    /** The "set up saved logins" hint went out. Once a visit. */
+    private noVaultHinted;
+    /** Credentials went out and the game has said nothing since. */
+    private unanswered;
+    /** Any `Char.Login.Default` this connection named a way to sign in. A token
+     *  arriving without one is ignored: nothing would replay it. */
+    private signInOffered;
+    private reconnectAttempted;
+    private resumeAttempted;
+    private oauthAttempted;
+    /** The last capabilities the game advertised, for re-deciding after an
+     *  unlock or a deadline. */
+    private caps;
+    /** The account the player last handed over, for the retry popup. */
+    lastLoginAttempt: {
+        account: string;
+        save: boolean;
+    } | null;
+    private awaitingReconnectResult;
+    /** This connection is running on a token it replayed, so a token arriving
+     *  now is a silent rotation rather than a first save worth announcing. */
+    private reconnectingWithToken;
+    /** The provider this account signs in with — from the stored entry or this
+     *  connection's `Char.Login.URL`. Saved with the token. */
+    private accountProvider;
+    private reconnectAccount;
+    /** A token was rejected: the next attempt reads the store but does not
+     *  replay. Consumed by that attempt. Mudlet's `mReconnectRejected`. */
+    private tokenRejected;
+    /** Bumped on every connect, disconnect and sign-in attempt, so async work
+     *  that started under an older one stops. */
+    private generation;
+    private announcedSaveFor;
+    private lastAttemptAt;
+    private pendingAttempt;
+    private reconnectDeadline;
+    private oauthFlow;
+    private offerShown;
+    private offerFlow;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    constructor(opts: CharLoginControllerOptions);
+    /** The game link came up: a fresh connection signs in from scratch. */
+    connected(): void;
+    /** The connection went. If credentials are still unanswered, this drop *is*
+     *  the game's answer — say so before the popup goes (measured on Achaea). */
+    disconnected(): void;
+    /** The player pressed Disconnect: hanging up on ourselves is not the game
+     *  refusing the login. */
+    userDisconnecting(): void;
+    /** Any server output: the game is still talking, so whatever happens later
+     *  is not a silent hang-up on the login. */
+    serverOutput(): void;
+    dispose(): void;
+    private resetSocket;
+    private resetAttempt;
+    request(caps: CharLoginCapabilities): void;
+    private scheduleAttempt;
+    private clearPendingAttempt;
+    private requestState;
+    /** Mudlet's `attemptReconnect` → `readStoredSignIn` → `selectAuthMethod`. */
+    private attempt;
+    private get tokenStorage();
+    private execute;
+    /** The vault unlock prompt closed. When a request was parked behind it,
+     *  answer it now — the game withholds its own prompt until we reply. */
+    vaultUnlockDone(result: 'created' | 'unlocked' | 'closed'): void;
+    /** The player submitted the credentials popup. */
+    promptSubmitted(account: string, password: string, save: boolean): void;
+    /** The player chose "Use text login". */
+    promptDeclined(): void;
+    result(result: CharLoginResult): void;
+    /** A replayed token was refused. Drop it — keeping the account and
+     *  provider as a resume hint so the next sign-in needs no provider menu —
+     *  and reconnect so the player signs in on a fresh, stable connection:
+     *  servers commonly hang up right after rejecting one. */
+    private tokenRejected_;
+    private armReconnectDeadline;
+    private clearReconnectDeadline;
+    url(link: CharLoginUrl | null): void;
+    private offer;
+    private withdrawOffer;
+    /** Close a `Char.Login.URL` offer once the game has moved past it. The
+     *  game only says the page is done by what it does next — a token, a
+     *  result, its next `Default` — and some (StickMUD, for a sign-in not yet
+     *  linked to a character) send nothing but text. Our own OAuth offer has
+     *  its own ending (captured / failed) and is left alone. */
+    private withdrawServerOffer;
+    /** The player sent a command. A game waiting on a browser sign-in takes
+     *  input as "cancel" or as the next answer, so its page is done with. */
+    playerInput(): void;
+    token(t: CharLoginToken): void;
+    private startOAuthFlow;
+    private sendAuthCode;
+    private oauthFailed;
+    /** The player chose the game's own sign-in over our browser flow. */
+    useGameSignIn(): void;
+    /** The player dismissed a server-driven sign-in offer. The console link
+     *  stays; nothing is sent. */
+    dismissOffer(): void;
+    private handOff;
+    private cancelOAuthFlow;
+}

package/dist-lib/mud/ItemIdSequence.d.ts

@@ -3,7 +3,7 @@
  *
  * Mudlet hands every trigger, alias, timer, key, button and script its id from
  * a single running number — temporary and permanent alike — so `tempAlias()`
- * followed by `permAlias()` followed by `tempAlias()` yields n, n+1, n+2. mudix
+ * followed by `permAlias()` followed by `tempAlias()` yields n, n+1, n+2. Mudlet Web
  * grew a counter per engine plus one for the permanent tree, which meant a
  * temporary item and a permanent one could be handed the *same* id: two
  * different things answering to one number, which `killAlias(id)` and