@mudlet/mudlet-web 0.5.0 → 1.0.1

package/dist-lib/db/sqliteClient.d.ts

@@ -7,19 +7,207 @@ type ExecResult = {
     kind: 'changes';
     changes: number;
 };
+/** A cell as LuaSQL hands it to Lua: a number (INTEGER and REAL alike — Lua 5.1
+ *  has only doubles, and desktop converts an int64 with a plain C cast), the raw
+ *  bytes of a TEXT or BLOB, or null. */
+export type LuasqlCell = number | Uint8Array | null;
+export type LuasqlExecResult = 
+/** A statement with result columns: a cursor's shape. Its rows are read by
+ *  {@link SqliteClient.cursorFetch}, one step per fetch as LuaSQL reads them. */
+{
+    kind: 'cursor';
+    cursorId: number;
+    columns: Uint8Array[];
+    declTypes: (Uint8Array | null)[];
+    wrote: boolean;
+} | {
+    kind: 'changes';
+    changes: number;
+} | {
+    kind: 'error';
+    message: Uint8Array;
+};
+export type LuasqlFetchResult = {
+    kind: 'row';
+    row: LuasqlCell[];
+}
+/** The rows ran out; the statement is finalized and the cursor gone. */
+ | {
+    kind: 'done';
+}
+/** The step failed, as sqlite3_errmsg reports it; the cursor is gone. */
+ | {
+    kind: 'error';
+    message: Uint8Array;
+};
+/** Where databases a statement opens by name (ATTACH, VACUUM INTO) live. */
+export interface FileHost {
+    /** The absolute path a database name stands for (relative names are
+     *  relative to the Lua working directory). */
+    resolve(name: string): string;
+    /** The file at `abs`: its bytes, null when there is none but one can be
+     *  created there, or false when it cannot be opened (no such directory, or
+     *  a directory). */
+    read(abs: string): Uint8Array | null | false;
+    /** Write `abs`'s committed bytes to its durable home. */
+    persist(abs: string, bytes: Uint8Array): void;
+}
+export interface OpenOptions {
+    readOnly?: boolean;
+    /** Writes the store's committed bytes to its durable home. */
+    persist?: (bytes: Uint8Array) => void;
+}
+/** How long a committed write waits to be written out once writes stop.
+ *  Writing out is a whole-database export plus a rewrite of the whole file, so
+ *  a script that writes a row per incoming line (a chat or loot logger) paid
+ *  that on every line — 50-280 ms per write on a 12-48 MB database (#443).
+ *  Writes now coalesce: each one pushes the export back by this much, up to
+ *  {@link SNAPSHOT_MAX_WAIT_MS} after the first. Nothing that reads the file
+ *  waits on it — the VFS read barrier flushes before any read of the file, and
+ *  the page hiding or unloading, saveProfile(), the last connection closing
+ *  and the runtime going (profile switch, closeMudlet) all flush at once. */
+export declare const SNAPSHOT_DELAY_MS = 1000;
+/** The longest a write stream may hold its database back from being written
+ *  out, so a crash mid-stream loses at most this much. */
+export declare const SNAPSHOT_MAX_WAIT_MS = 3000;
+/**
+ * round(X, Y) as the SQLite desktop Mudlet links (3.37) computes it: Y=0 adds
+ * a half and truncates; otherwise the value goes through its printf("%.*f"),
+ * which adds the half-unit rounder plus a 3e-16 relative fudge and then
+ * truncates to at most 16 significant digits. That fudge is why round(1.005, 2)
+ * is 1.01 and round(2.675, 2) is 2.68 there, where 3.53's exact decimal
+ * rounding gives 1.0 and 2.67. (3.37's printf sums in long double; the sum here
+ * is a double, which only matters within an ulp of a rounding boundary.)
+ */
+export declare function round337(r: number, n: number): number;
 export declare const sqliteReady: Promise<void>;
 export declare class SqliteClient {
-    private readonly dbs;
-    private readonly idByPath;
-    private readonly pathById;
+    private readonly handles;
+    private readonly stores;
+    private readonly cursors;
     private nextId;
-    liveId(path: string): number | undefined;
+    private nextCursorId;
+    private nextFile;
+    private flushing;
+    private unlinkFn;
+    private host;
+    /** The connection whose statement is running, so a database it opens by
+     *  name is counted as open by it. */
+    private active;
+    private vfsName;
+    private roundPtr;
+    private readonly clientId;
     private get s();
-    open(path: string, preload?: Uint8Array): number;
+    private get x();
+    private get raw();
+    /** Why sqlite cannot be used (its wasm failed to load), or null when it
+     *  can. Callers that run during startup check this rather than touching
+     *  the module, so a failed load costs only the database API. */
+    unavailable(): string | null;
+    /** The SQLite library version, or null when sqlite failed to load. */
+    version(): string | null;
+    /** Where databases opened by name from SQL live; null leaves such names to
+     *  the wasm filesystem. */
+    setFileHost(host: FileHost | null): void;
+    /** Clear `host`, unless another has replaced it since. */
+    releaseFileHost(host: FileHost): void;
+    /** Whether a connection to `path` is open, i.e. its live state is here and
+     *  not (only) in its durable home. */
+    isLive(path: string): boolean;
+    /**
+     * Open a new connection to the database at `path`. Every call is its own
+     * handle. `preload` seeds the database only when no connection to it is
+     * open; an open one is authoritative.
+     */
+    open(path: string, preload?: Uint8Array, options?: OpenOptions): number;
+    /** A private in-memory database (LuaSQL's ":memory:"). Through the shim
+     *  all the same, so a database it ATTACHes by name is a profile file. */
+    openMemory(): number;
+    private createStore;
+    private register;
+    /** round() with desktop's arithmetic ({@link round337}); an application
+     *  function of a built-in's name takes its place. */
+    private installRound;
+    /** The name of the unix-VFS shim connections open through, registered on
+     *  first use. */
+    private shimVfs;
+    /** The in-memory file (as a C string) standing for `path`, a live store's
+     *  database or one of its journals; 0 for a name no store has. */
+    private mapName;
+    private cname;
+    private handle;
+    /** Run every statement in `sql` (the file browser's read-only queries). */
     exec(dbId: number, sql: string): ExecResult;
-    exportFile(dbId: number): Uint8Array;
+    /** NUL-terminated C string at `ptr`, as raw bytes. */
+    private cstrBytes;
+    private errmsg;
+    /**
+     * LuaSQL's conn:execute (ls_sqlite3.c conn_execute): prepare the FIRST
+     * statement in `sql` — anything after it is ignored, as sqlite3_prepare's
+     * tail is — and step it once. A statement with result columns becomes a
+     * cursor (reset, to be run by cursorFetch); otherwise the result is
+     * sqlite3_changes(). `sql` is bytes, so text that is not UTF-8 reaches
+     * sqlite unchanged.
+     */
+    luasqlExec(dbId: number, sql: Uint8Array): LuasqlExecResult;
+    private luasqlExecOn;
+    /**
+     * LuaSQL's cur:fetch: step the cursor's statement once and hand back that
+     * row. One row per call, as desktop's cursor reads them, so whatever the
+     * connection writes between two fetches — deleting a row the cursor has not
+     * reached yet, updating one, inserting one — shows in what the cursor goes
+     * on to return; and the statement, mid-step, holds the read lock until its
+     * rows run out. The step that finds none finalizes it.
+     */
+    cursorFetch(cursorId: number): LuasqlFetchResult;
+    /** The cursor is closed: finalize its statement, letting its lock go. */
+    cursorClose(cursorId: number): void;
+    private dropCursor;
+    /** sqlite3_exec of fixed transaction-control SQL; the error text as raw
+     *  bytes, or null on success. */
+    script(dbId: number, sql: string): Uint8Array | null;
+    lastInsertRowid(dbId: number): number;
+    /** Note that `dbId` may have changed its database, or one it has attached;
+     *  they are written out once its writes settle, or sooner by flush(). */
+    markDirty(dbId: number): void;
+    /** Debounced: every write moves the export back to {@link SNAPSHOT_DELAY_MS}
+     *  from now, but never past {@link SNAPSHOT_MAX_WAIT_MS} from the first
+     *  write it is waiting for. A retry passes its own fixed delay. */
+    private schedule;
+    /** Write `path`'s committed state out now if it has changed. Cheap when it
+     *  has not, so it can sit in front of every read of the file. */
+    flush(path: string): void;
+    flushAll(): void;
+    private flushStore;
+    /**
+     * Bytes were written over `path` from outside sqlite (io, a restore, the
+     * file browser). An open database takes them as its file's new contents,
+     * written into the same in-memory file so every connection on it sees them
+     * from its next statement, and what it had not yet written out is dropped:
+     * the file is what was just written.
+     */
+    fileReplaced(path: string, read: () => Uint8Array): void;
+    /**
+     * sqlite tells that another writer changed a file by its header: a
+     * connection keeps its cached pages while the change counter matches, and
+     * its parsed schema while the schema cookie does. Bytes copied over a
+     * database can carry the same values as the file they replace (a backup
+     * taken after as many commits), so where they match, the copy the
+     * connections read gets them one higher than the file's current ones.
+     */
+    private markChanged;
+    /**
+     * `path` (or a directory holding it) was removed or renamed away. Every
+     * database there leaves its connections on the unlinked file, as a disk
+     * file's do: they read what it held, sqlite refuses their writes, nothing
+     * is written back, and the next connection to the path starts afresh.
+     */
+    fileRemoved(path: string): void;
+    /** Close one connection: sqlite3_close, which rolls back whatever it never
+     *  committed. The last connection to a database writes it out first. */
     close(dbId: number): void;
-    escape(s: string): string;
+    private teardown;
+    private unlink;
 }
 export declare function getSqliteClient(): SqliteClient;
 export {};

package/dist-lib/hooks/useAutoReconnect.d.ts

@@ -0,0 +1,61 @@
+import type { MudSession } from '../mud/MudSession';
+/**
+ * Mudlet's "Reconnect automatically" profile option, ported from `cTelnet`.
+ *
+ * It covers two different endings, and treats them differently:
+ *
+ * **A connection that was made and then lost** — the end of
+ * `slot_socketDisconnected`:
+ *
+ * ```cpp
+ * if (mAutoReconnect && !mDontReconnect && timeOffset >= 5000) {
+ *     connectIt(mHostUrl, mHostPort);
+ * }
+ * mDontReconnect = false;
+ * ```
+ *
+ * **One** redial, immediately, with nothing printed — a session that ran for an
+ * hour and blipped should come back without narrating it. A drop inside five
+ * seconds (`timeOffset < 5000`) is the server turning the login away, and is
+ * left alone.
+ *
+ * **An attempt that never reached the game** — refused, unknown host, the
+ * proxy unreachable — `handleFailedConnection`: "Trying again in N seconds...",
+ * after 5 s, doubling with each failure in a row up to 60 s
+ * (`FAILED_CONNECTION_RETRY_DELAY` / `_MAX_DELAY`). The wait and its timer live
+ * on {@link MudSession.scheduleFailedConnectionRetry}, so that Connect,
+ * Disconnect and closing the profile all call a pending retry off.
+ *
+ * Common to both:
+ *
+ * - **`mAutoReconnect`** is the profile's own `autoreconnect` flag — here
+ *   `MudConnection.reconnectOnDrop`, a *different* option from the badly-named
+ *   `autoReconnect`, which is Mudlet's `autologin` and only decides whether
+ *   opening the profile dials.
+ * - **`!mDontReconnect`** — a disconnect the player asked for is never undone.
+ *   {@link MudSession.dontReconnect} is that flag: raised by `disconnect()`, so
+ *   it covers the toolbar button, Lua `disconnect()` and closing the profile
+ *   alike, and raised again by a rejected certificate and a failed GMCP login
+ *   exactly as Mudlet does (ctelnet.cpp:819, GMCPAuthenticator.cpp:613) —
+ *   neither of those gets better by being retried.
+ *
+ * `timeOffset` is `mConnectionTimer`, started when the *game* socket connects —
+ * here `client.established`, never the WebSocket to the proxy opening, which
+ * happens for a game that is down too (issue #130).
+ */
+/** Mudlet's `timeOffset >= 5000`: how long the game link has to have been up
+ *  for its loss to count as a drop worth redialing rather than an attempt that
+ *  never really got anywhere. Shares its value, and its reasoning, with
+ *  MudSession's `CONNECTION_REJECTED_WINDOW_MS`. */
+export declare const SETTLED_SESSION_MS = 5000;
+interface Options {
+    session: MudSession;
+    /** The profile's `reconnectOnDrop`. */
+    enabled: boolean;
+    /** Dial again, from the connection as it stands in the store — Mudlet
+     *  redials `mHostUrl`/`mHostPort`, i.e. the address as last dialled, which
+     *  after a TLS upgrade is not the one the profile started with. */
+    redial: () => void;
+}
+export declare function useAutoReconnect({ session, enabled, redial }: Options): void;
+export {};

package/dist-lib/hooks/useDocumentFullscreen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Real fullscreen — the browser's own, over the whole screen.
+ *
+ * This used to be a profile setting that hid the top toolbar and called that
+ * "fullscreen mode". It was never fullscreen: the browser's chrome, tab strip
+ * and the operating system's own furniture all stayed put, and what the player
+ * actually got back was 44 pixels. Hiding the client's own bars is now what the
+ * menu-bar and toolbar settings are for, and this is the Fullscreen API.
+ *
+ * Deliberately not persisted. Requesting fullscreen needs a user gesture, so a
+ * profile that stored "fullscreen: true" could not honour it on load anyway —
+ * it would come back as a setting that is on and visibly not in effect.
+ */
+export interface DocumentFullscreen {
+    /** Whether the document is in fullscreen right now. */
+    active: boolean;
+    /** Whether the browser will allow it at all — false inside an iframe that
+     *  was not given `allow="fullscreen"`, which is how this client is embedded
+     *  in someone else's page. */
+    available: boolean;
+    toggle: () => void;
+}
+export declare function useDocumentFullscreen(): DocumentFullscreen;

package/dist-lib/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Dispatching the client's own keyboard shortcuts, and any a package placed
+ * with `addCommand`.
+ *
+ * Two things make this more than a switch on `event.key`:
+ *
+ *  - **It must fire while the player is typing.** The command line is a
+ *    textarea and has the keyboard essentially all the time; a handler that
+ *    bailed out on text-entry targets would be a shortcut system that never
+ *    ran. So the guard is on the shortcut instead: a combination with a
+ *    modifier is dispatched wherever focus is, a bare key only outside text
+ *    entry — nobody should lose the letter E because a command is bound to it.
+ *
+ *  - **Qt sequences can have up to four steps** ("Ctrl+Alt+F1, Ctrl+Alt+F2"),
+ *    and `addCommand` accepts them, so a keypress can be the start of something
+ *    rather than the whole of it. Steps matched so far are held until one
+ *    sequence completes, nothing can still match, or the player pauses.
+ */
+export interface ShortcutBinding {
+    /** The Qt-style sequence, as written by a default or by the player. */
+    shortcut: string;
+    run: () => void;
+}
+/**
+ * Whether one of the client's shortcuts (or an `addCommand` one) would take
+ * this press: it completes or continues a sequence. Desktop resolves a
+ * QAction's shortcut before the focused widget sees the key, so a key binding
+ * on Alt+K does not run while the Mute action holds it (mudlet-web#340).
+ */
+export declare function claimedByAppShortcut(e: KeyboardEvent): boolean;
+/**
+ * Hold keys for a client action that is not a ShortcutBinding — the buffer
+ * search's F3 while `f3SearchEnabled` is on — so the Lua keybinding listener
+ * yields them the way it yields a menu accelerator's. Returns the release.
+ */
+export declare function claimShortcutKeys(claims: (e: KeyboardEvent) => boolean): () => void;
+export declare function useKeyboardShortcuts(bindings: readonly ShortcutBinding[], enabled?: boolean): void;

package/dist-lib/hooks/useRecordLastPlayed.d.ts

@@ -0,0 +1,10 @@
+import type { MudSession } from '../mud/MudSession';
+/**
+ * Stamp `lastConnectedAt` on the profile each time its session reaches the
+ * game, so the launcher can lead with the profile played most recently.
+ *
+ * `client.established`, not `client.connect`: the latter fires when the
+ * WebSocket to the proxy opens, before the proxy has reached the game — a
+ * profile whose server is down would still jump to the front of the list.
+ */
+export declare function useRecordLastPlayed(session: MudSession | null, connectionId: string): void;

package/dist-lib/import/applyMudletProfile.d.ts

@@ -3,7 +3,7 @@ import type { MudConnection } from '../storage/schema';
 /** The per-connection store slices a bundle maps to. Pure — no side effects, so
  *  it's unit-testable; `importMudletProfile` applies it. Automation is imported
  *  profile-owned (as authored in Mudlet), not package-tagged. */
-export declare function bundleToConnectionData(bundle: MudletProfileBundle, installedAt: string): {
+export declare function bundleToConnectionData(bundle: MudletProfileBundle, installedAt: string, profilePath?: string): {
     scripts: import("../storage/schema").ScriptNode[];
     aliases: import("../storage/schema").AliasNode[];
     triggers: import("..").TriggerNode[];
@@ -11,26 +11,39 @@ export declare function bundleToConnectionData(bundle: MudletProfileBundle, inst
     keybindings: import("../storage/schema").KeyNode[];
     buttons: import("../storage/schema").ButtonNode[];
     packages: import("../storage/schema").PackageManifest[];
-    profile: Partial<import("../storage").ProfileSettings>;
+    profile: Partial<import("..").ProfileSettings>;
     variables: {
         saveList: string[];
         values: import("./mudletVariables").MudletVariable[];
+        hidden: string[];
     };
 };
 /**
  * The connection record for an imported bundle.
  *
  * A Mudlet `<Host>` only models a telnet host/port, so that's the default. A
- * profile exported *from mudix* also carries `.mudix/connection.json`, which
+ * profile exported from Mudlet Web also carries `.mudlet/connection.json`, which
  * restores what Mudlet can't express — websocket mode and its ws(s):// URL, the
  * per-profile proxy override, auto-reconnect. Unknown/aliased sidecar values are
  * ignored field by field, so a hand-edited file can't produce a broken profile.
  */
 export declare function bundleToConnectionRecord(bundle: MudletProfileBundle): Omit<MudConnection, 'id'>;
 /**
- * Create a new mudix profile from a Mudlet profile bundle. Returns the new
+ * Seed a new profile's command-bar history from the bundle's
+ * `command_history_main`, so Up arrow recalls what it did on desktop. Capped at
+ * the profile's own `commandLineHistorySaveSize` when it has one, as every
+ * later save of that history is.
+ */
+export declare function seedCommandHistory(connectionId: string, bundle: MudletProfileBundle): void;
+/**
+ * Create a new Mudlet Web profile from a Mudlet profile bundle. Returns the new
  * connection id. The profile opens offline like any other; its data is durable
- * in the new VFS (`.mudix/profile.json`) and map store before this resolves.
+ * in the new VFS (`.mudlet/profile.json`) and map store before this resolves.
+ *
+ * Anything that could not be carried over is appended to `bundle.warnings` for
+ * the caller to show — a copy that quietly loses a package's files or the map
+ * still "succeeds", so the console warnings below are not a surface any user
+ * ever looks at (issue #45).
  */
 export declare function importMudletProfile(bundle: MudletProfileBundle): Promise<string>;
 /** Recursively read a picked directory into {path -> bytes} + {path -> mtime}
@@ -47,11 +60,24 @@ export declare function bundleFromDirectory(dir: FileSystemDirectoryHandle): Pro
  *  handling — callers that need the upload/remove flow should use bundleFromDirectory
  *  + resolveModulesFromTree first). */
 export declare function importMudletProfileFromDirectory(dir: FileSystemDirectoryHandle): Promise<string>;
+/** What {@link linkMudletFolder} made, and what it leaves to the caller. */
+export interface LinkedFolderResult {
+    connectionId: string;
+    /** Desktop's saved password (the folder's `password` file), for the
+     *  caller to hand to the credential vault. The folder's copy is left
+     *  where it is: desktop still reads it. */
+    password?: string;
+    /** What could not be carried over, for the import UI to show. */
+    warnings: string[];
+}
 /**
- * Link a Mudlet profile *directory* as a new mudix profile (Link mode): the
+ * Link a Mudlet profile *directory* as a new Mudlet Web profile (Link mode): the
  * folder stays the source of truth — its `current/*.xml` is re-read on every
  * open — rather than being copied in. Reads the connection identity from the
- * newest save, registers the connection, persists the folder handle so the VFS
- * mounts it, and copies the current map. Returns the new connection id.
+ * newest save, and TLS and the character name from desktop's own files for
+ * them, as an import does (#450); registers the connection, persists the
+ * folder handle so the VFS mounts it, and copies the current map. The server
+ * encoding and command history are read when the profile opens
+ * (loadMudletLinkedProfile), every time, so desktop's later changes arrive too.
  */
-export declare function linkMudletFolder(dir: FileSystemDirectoryHandle): Promise<string>;
+export declare function linkMudletFolder(dir: FileSystemDirectoryHandle): Promise<LinkedFolderResult>;

package/dist-lib/import/backupImport.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Importing a whole-origin backup taken from a previous Mudlet Web address.
+ *
+ * Browser storage is keyed per address. When the client moved from
+ * `mudlet-web.mudlet.org` to `web.mudlet.org` every profile, script, package
+ * and map stayed behind on the old origin, reachable by nothing — the app that
+ * could read them was no longer served there. The holding page left at the old
+ * address (Mudlet/mudlet-web-moved) writes all of it to one `mudlet-web-backup`
+ * JSON file; this module is the other half, and reads that file back in.
+ *
+ * The file is a verbatim dump of the old origin's storage, so nothing here has
+ * to understand the *meaning* of a profile's data. What it does have to do is
+ * re-address it:
+ *
+ *   - Every profile is created through {@link AppSchema.addConnection}, so it
+ *     gets a fresh id and a non-clashing name from the store rather than being
+ *     forced in under the old one. Importing into a browser that already has
+ *     profiles is therefore additive: nothing existing is overwritten, and
+ *     importing the same file twice yields "Achaea" and "Achaea (2)" rather
+ *     than a silent clobber.
+ *   - Everything keyed by the *old* connection id is rewritten to the new one:
+ *     the profile's ZenFS database, its map, its logs, its command history and
+ *     its stopwatches. `profileStorage.ts` holds the same inventory from the
+ *     deletion side; the two must stay in step.
+ *
+ * A profile's ZenFS database is restored by copying its records verbatim into a
+ * database named for the new id. The store is keyed by inode number and holds
+ * no reference to its own name, so the copy is the same filesystem — verified
+ * in a browser against the real ProfileVFS before this was written. Everything
+ * per-profile that is not the connection row itself (settings, layout, and the
+ * automation trees in `.mudix/profile.json`) rides along inside it.
+ */
+/** The `format` string every backup file carries. */
+export declare const BACKUP_FORMAT = "mudlet-web-backup";
+/** The highest `version` this importer understands. */
+export declare const BACKUP_MAX_VERSION = 1;
+interface BackupRecord {
+    key: unknown;
+    value: unknown;
+}
+interface BackupStore {
+    keyPath: string | string[] | null;
+    autoIncrement: boolean;
+    records: BackupRecord[];
+}
+interface BackupDatabase {
+    version: number;
+    stores: Record<string, BackupStore>;
+}
+export interface MudletWebBackup {
+    format: string;
+    version: number;
+    createdAt?: string;
+    origin?: string;
+    localStorage: Record<string, string>;
+    indexedDB: Record<string, BackupDatabase>;
+    skipped?: {
+        where: string;
+        why: string;
+    }[];
+}
+/** What a file holds, for the confirmation the user sees before committing. */
+export interface BackupSummary {
+    createdAt: string | null;
+    origin: string | null;
+    /** Profiles in the file, in the order they will be created. */
+    profiles: {
+        id: string;
+        name: string;
+    }[];
+    /** How many of those profiles have a stored map. */
+    maps: number;
+    logSessions: number;
+    /** Notes worth showing up front — things that will not come across. */
+    warnings: string[];
+}
+export interface BackupImportResult {
+    /** Profiles created, under the names they actually got. */
+    imported: {
+        id: string;
+        name: string;
+    }[];
+    warnings: string[];
+}
+/**
+ * Undo the exporter's tagging. Plain JSON passes through untouched; anything
+ * structured clone can hold that JSON cannot arrives as a `$`-tagged object.
+ *
+ * A value the exporter could not carry at all (`$: 'unsupported'`) decodes to
+ * `undefined` rather than throwing: one unreadable field in one log row must
+ * not cost the user the profile it belongs to.
+ */
+export declare function decodeBackupValue(value: unknown): unknown;
+/**
+ * Read and check a backup file.
+ *
+ * Deliberately strict about the envelope and forgiving about the contents: a
+ * file that is not a backup at all should say so plainly, while a backup with
+ * one unreadable section is still worth most of what it holds.
+ */
+export declare function parseBackup(text: string): MudletWebBackup;
+/**
+ * What the file holds, without changing anything.
+ *
+ * Profiles come from the store blob first; a VFS database with no row left in
+ * that blob is still offered, under a placeholder name, because the data in it
+ * is the part worth rescuing and a truncated store blob should not bury it.
+ */
+export declare function summariseBackup(backup: MudletWebBackup): BackupSummary;
+/**
+ * Import everything in a backup file.
+ *
+ * Additive by construction: every profile is created fresh through the store,
+ * so an import can be run into a browser that is already in use, and can be run
+ * twice, without losing anything that was already here.
+ */
+export declare function importBackup(backup: MudletWebBackup): Promise<BackupImportResult>;
+export {};

package/dist-lib/import/collectProfileExport.d.ts

@@ -1,5 +1,36 @@
+import { ProfileVFS } from '../scripting/vfs/ProfileVFS';
 import type { MudConnection } from '../storage/schema';
-import type { ProfileExportSource } from './mudletProfileExport';
+import { type ProfileExportSource } from './mudletProfileExport';
+import { type VfsReader } from './mudletLink';
+/** The part of ProfileVFS the walk needs, so it's testable over any ZenFS. */
+export type WalkableVfs = Pick<ProfileVFS, 'profilePath' | 'readdir' | 'stat' | 'readBinaryFile'>;
+/**
+ * Every user file in the profile folder, keyed by its path relative to the
+ * profile root — packages, modules, and whatever scripts wrote with `io.*` /
+ * `table.save`, i.e. what desktop Mudlet's profile folder holds.
+ *
+ * Paths are resolved against `profilePath`, never passed bare: ProfileVFS reads
+ * a leading `/` as the ZenFS root, and a relative path resolves against the Lua
+ * working directory, which `lfs.chdir` can move (issue #261).
+ */
+export declare function collectVfsFiles(vfs: WalkableVfs): Record<string, Uint8Array>;
+/**
+ * The `<Host>` this profile's export should base on, so the ~100 Mudlet settings
+ * Mudlet Web doesn't model don't revert to Mudlet's defaults on the way out.
+ *
+ * The retained copy comes first. A profile that has one was imported from
+ * Mudlet, and any `current/*.xml` in its VFS is a save Mudlet Web itself wrote via
+ * `saveProfile()` — basing on that would just re-read our own output. A linked
+ * folder has no retained copy and its `current/*.xml` *is* the live original,
+ * kept current by write-back, so it's the right base there.
+ *
+ * Undefined for a profile born in Mudlet Web: nothing beyond the modeled settings to
+ * preserve, and the export falls back to the empty skeleton as before.
+ *
+ * Takes the same minimal reader surface as the link-mode loader, so it's
+ * testable without a mounted ZenFS.
+ */
+export declare function readHostBase(vfs: VfsReader): string | undefined;
 export interface CollectOptions {
     /** Session logs aren't part of the Mudlet format; they ride along under
      *  `logs/` so a migrating user doesn't leave history behind. */
@@ -8,7 +39,7 @@ export interface CollectOptions {
 /**
  * Read one profile out of storage, ready for export.
  *
- * The profile's `.mudix/profile.json` is the source of truth — not the Zustand
+ * The profile's `.mudlet/profile.json` is the source of truth — not the Zustand
  * store, which only holds slices for the *open* profile. A profile open in
  * another tab may therefore be up to one save-debounce stale; exporting from the
  * connection screen (where nothing is open) always sees the committed state.