@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -0,0 +1,14 @@
+/**
+ * Replace every control character XML cannot represent with Mudlet's placeholder
+ * pair. Safe to run over any string bound for a document — text content and
+ * attribute values alike. Tab, LF and CR are legal in XML 1.0 and left alone.
+ *
+ * Divergence: desktop has no mapping for NUL (0x00) at all, and so still emits a
+ * document Qt rejects when a script holds one. We encode it as U+FFFC U+2400 — the
+ * glyph the Control Pictures block reserves for it. Desktop will not decode that
+ * back, leaving the placeholder visible in the script, but the file stays valid
+ * and everything around the NUL survives.
+ */
+export declare function sanitizeControlChars(s: string): string;
+/** Inverse of {@link sanitizeControlChars}. */
+export declare function desanitizeControlChars(s: string): string;

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

@@ -1,21 +1,29 @@
 import type { ProfileSettings } from '../storage/schema';
 import { type MudletImportResult } from './mudletXmlImport';
 import { type MudletVariablePackage } from './mudletVariables';
-/**
- * Map a `<Host>` element to a partial ProfileSettings. Only keys actually
- * present in the XML are set, so the result can be merged over existing/default
- * settings without clobbering anything Mudlet didn't specify.
- */
+import type { SavedStopwatch } from '../scripting/StopwatchManager';
 export declare function parseMudletHost(host: Element): Partial<ProfileSettings>;
 /** The connection identity a Mudlet `<Host>` carries: the profile name and the
- *  MUD address (`<url>` host + `<port>`). Used to seed a new mudix connection. */
+ *  MUD address (`<url>` host + `<port>`). Used to seed a new Mudlet Web connection. */
 export interface MudletProfileIdentity {
     name?: string;
     host?: string;
     port?: number;
+    /** `mSslTsl` — connect over TLS. The profile's `ssl_tsl` file, when it has
+     *  one, is fresher (see buildMudletProfileBundle). */
+    tls?: boolean;
+    sslIgnoreExpired?: boolean;
+    sslIgnoreSelfSigned?: boolean;
+    sslIgnoreAll?: boolean;
 }
-/** Read `<name>`/`<url>`/`<port>` (direct children of `<Host>`). */
+/** Read `<name>`/`<url>`/`<port>` (direct children of `<Host>`) and the TLS
+ *  attributes. */
 export declare function parseMudletHostIdentity(host: Element): MudletProfileIdentity;
+/** What Mudlet's own exporter puts above `<MudletPackage>`, reproduced so a file
+ *  written here is byte-shaped like one written there. Nothing reads it —
+ *  Mudlet's QXmlStreamReader ignores the doctype — but dropping it would make
+ *  Mudlet Web's saves gratuitously different. */
+export declare const MUDLET_XML_PROLOG = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!DOCTYPE MudletPackage>";
 /**
  * Write the modeled ProfileSettings back onto an existing `<Host>` element,
  * in place — only the fields present in `s` are touched, so unmodeled Host
@@ -25,12 +33,67 @@ export declare function parseMudletHostIdentity(host: Element): MudletProfileIde
  * the rest of the QFont spec is preserved.
  */
 export declare function applyProfileSettingsToHost(host: Element, s: Partial<ProfileSettings>): void;
+/** The identity a Mudlet `<Host>` carries for one profile: its name, the MUD
+ *  address, and the packages Mudlet should consider installed. */
+export interface MudletHostIdentity {
+    name: string;
+    url: string;
+    port: number;
+    installedPackages: string[];
+}
+/**
+ * Write the connection identity onto a `<Host>` in place. Unlike
+ * {@link applyProfileSettingsToHost} this always overwrites rather than only
+ * touching what's set: the live connection record and package set are
+ * authoritative, so a `<Host>` retained from an earlier import can't export the
+ * name, address or package list it had back then.
+ */
+export declare function applyHostIdentity(host: Element, identity: MudletHostIdentity): void;
+/**
+ * Replace `<Host><mInstalledPackages>` with `names`, creating it when absent.
+ * Desktop's `Host::saveProfile` always writes the live list, and a load takes
+ * the profile's package set from it — so a save that left it out (or kept a
+ * stale copy from the document it was based on) forgets every package on the
+ * next open.
+ */
+export declare function applyInstalledPackages(host: Element, names: string[]): void;
+/**
+ * Replace `<Host><stopwatches>` with the profile's persistent stopwatches,
+ * written as desktop's `XMLexport` writes them, so a save carries them as
+ * desktop's does rather than the copy the document was based on.
+ */
+export declare function applyStopwatches(host: Element, watches: SavedStopwatch[]): void;
+/**
+ * Reduce a full Mudlet profile save to a document holding just its
+ * `<HostPackage>`.
+ *
+ * Mudlet's `<Host>` is roughly 120 attributes, 26 child elements and 53 colour
+ * elements (`XMLimport.cpp:723-1305`); Mudlet Web models about a third of that. The
+ * rest — proxy and TLS configuration, logging setup, the spell dictionary,
+ * console buffer sizing, the map colours and sizes, `<stopwatches>`, `<MMCP>`,
+ * the `<experiment>` flags, the second-console palette — has no home in
+ * ProfileSettings, so it survives a round-trip only by being carried verbatim.
+ * Retaining this on import is what lets an export base its `<Host>` on the real
+ * one instead of a skeleton.
+ *
+ * Dropped on the way through:
+ * - the automation and variable packages, which are regenerated from live state
+ *   on every write; keeping a copy here would ship the same data twice, in two
+ *   formats, and let a stale one resurface.
+ * - `<mInstalledModules>`, because import re-registers each resolved module
+ *   against a copy of its XML inside the new profile. A surviving reference
+ *   would make Mudlet load it a second time from the absolute path it had on
+ *   the original machine.
+ *
+ * Returns null if `profileXml` doesn't parse or carries no `<HostPackage>`.
+ */
+export declare function extractHostPackageXml(profileXml: string): string | null;
 /** Names from `<Host><mInstalledPackages>` — the packages Mudlet considers
  *  installed for this profile. Mudlet tracks these so package managers (mpkg) and
- *  `getPackageInfo`/`getInstalledPackages` work; mudix registers a manifest per
+ *  `getPackageInfo`/`getInstalledPackages` work; Mudlet Web registers a manifest per
  *  entry on import. */
 export declare function parseInstalledPackages(host: Element): string[];
-/** Everything a full Mudlet profile XML carries that mudix can import. */
+/** Everything a full Mudlet profile XML carries that Mudlet Web can import. */
 export interface MudletProfileImport {
     /** From `<Host>` — the profile name + MUD address for the connection record. */
     connection: MudletProfileIdentity;
@@ -59,7 +122,7 @@ export interface MudletModuleRef {
 /** Parse the repeated `<mInstalledModules>` blocks under `<Host>`. */
 export declare function parseInstalledModules(host: Element): MudletModuleRef[];
 /**
- * Parse a complete Mudlet profile XML (a `current/*.xml`) into the things mudix
+ * Parse a complete Mudlet profile XML (a `current/*.xml`) into the things Mudlet Web
  * can apply: the connection identity, profile settings, automation trees, and
  * saved variables. `<VariablePackage>` variable names become the seed of the
  * profile's save-list when applied. Throws on malformed XML.

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

@@ -1,3 +1,5 @@
+import type { MudConnection } from '../storage/schema';
+import { type DesktopProfileFiles } from './mudletProfileImport';
 export interface VfsReader {
     exists(path: string): boolean;
     readdir(path: string): string[];
@@ -6,6 +8,11 @@ export interface VfsReader {
     } | null;
     readFile(path: string): string;
 }
+/** A {@link VfsReader} that also reads bytes — what a linked folder's
+ *  desktop profile-data files need (they are not text; see qtProfileData.ts). */
+export interface LinkedVfsReader extends VfsReader {
+    readBinaryFile(path: string): Uint8Array;
+}
 /** current/*.xml paths (relative to the profile root) ordered newest-first.
  *  Order is by mtime; when mtimes are unavailable (all zero) autosave.xml comes
  *  first, then the latest timestamp filename. Empty when not a Mudlet profile. */
@@ -14,6 +21,18 @@ export declare function listCurrentXmlsByRecency(vfs: VfsReader): string[];
 export declare function findNewestCurrentXml(vfs: VfsReader): string | null;
 /** Whether a mounted VFS looks like a linked Mudlet profile (has current/*.xml). */
 export declare function isMudletProfileVfs(vfs: VfsReader): boolean;
+/**
+ * Whether opening this profile loads it from its newest current/*.xml rather
+ * than `.mudlet/profile.json`: only a linked Mudlet folder, where desktop may
+ * have edited the save since. A Mudlet Web profile that called saveProfile()
+ * has a current/*.xml too, but nothing outside this app writes it and
+ * profile.json — flushed alongside it — is the fuller record (module
+ * manifests, install paths, …). Loading that one as a linked folder lost its
+ * installed packages and re-ran the default-package install (#259).
+ */
+export declare function opensAsLinkedProfile(connection: {
+    mudletLinked?: boolean;
+}, vfs: VfsReader): boolean;
 /**
  * The newest current/*.xml whose content actually parses as a Mudlet profile,
  * with its text. Skips a corrupt newest save (e.g. a truncated/garbage autosave
@@ -27,8 +46,40 @@ export declare function readNewestParseableXml(vfs: VfsReader): {
 } | null;
 /**
  * Hydrate the store for a Mudlet-linked profile from the newest current/*.xml,
- * layering the .mudix sidecar's mudix-only slices on top. Returns false if the
+ * layering the .mudlet sidecar's Mudlet Web-only slices on top. Returns false if the
  * VFS isn't a Mudlet profile (caller falls back to the normal profile.json load).
  * `installedAt` stamps the package manifests (pass an ISO timestamp).
  */
-export declare function loadMudletLinkedProfile(vfs: VfsReader, connectionId: string, installedAt: string): boolean;
+export declare function loadMudletLinkedProfile(vfs: LinkedVfsReader, connectionId: string, installedAt: string): boolean;
+/** {@link readDesktopProfileFiles} over a linked folder's root. */
+export declare function readLinkedDesktopFiles(vfs: LinkedVfsReader, saveTls?: boolean): DesktopProfileFiles;
+/** Where the last-merged `command_history_main` modification time is kept. */
+export declare function linkedHistoryMarkerKey(connectionId: string): string;
+/**
+ * Fold the folder's `command_history_main` into the command bar's history
+ * when the file has changed since it was last read: desktop's commands first
+ * (it was used since), then this client's own, one entry per command ignoring
+ * case. An unchanged file is skipped, so this client's history isn't
+ * reshuffled on every open.
+ */
+export declare function mergeLinkedCommandHistory(vfs: LinkedVfsReader, connectionId: string, saveSize?: number): void;
+/** Whether a connection-record change touches what a linked folder's
+ *  profile-data files mirror (TLS, the character name), so a save must write
+ *  them back. Nothing for a profile that is not a linked folder. */
+export declare function linkedConnectionFilesChanged(conn: Pick<MudConnection, 'mudletLinked' | 'mode' | 'tls' | 'charLoginAccount'> | undefined, prev: Pick<MudConnection, 'mudletLinked' | 'mode' | 'tls' | 'charLoginAccount'> | undefined): boolean;
+/** The settings a linked folder's profile-data files mirror. */
+export interface DesktopProfileFileValues {
+    serverEncoding?: string;
+    /** Undefined for a connection where TLS isn't the profile's to say (websocket). */
+    tls?: boolean;
+    login?: string;
+}
+/**
+ * The profile-data files to write so a linked folder says what `want` does, in
+ * desktop's format, keyed by name. Only files whose value differs are listed —
+ * an unchanged file is not rewritten under a desktop Mudlet that may be
+ * running on the same folder — and none is created to say what its absence
+ * already means (no encoding chosen, TLS off, no character name). Never the
+ * password.
+ */
+export declare function desktopProfileFileUpdates(vfs: LinkedVfsReader, want: DesktopProfileFileValues): Record<string, Uint8Array>;

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

@@ -4,9 +4,27 @@ import type { PersistedProfileData } from '../storage/profileVfsData';
  *  filename when no mtimes are available, so the stamp has to be sortable. */
 export declare function formatSaveStamp(date: Date): string;
 /** Connection fields Mudlet's `<Host>` can't express (websocket mode, the proxy
- *  override, auto-reconnect). Written beside the XML so a mudix→mudix round-trip
+ *  override, auto-reconnect). Written beside the XML so a Mudlet Web→Mudlet Web round-trip
  *  keeps them; desktop Mudlet ignores the dot-directory entirely. */
-export declare const CONNECTION_SIDECAR_PATH = ".mudix/connection.json";
+export declare const CONNECTION_SIDECAR_PATH = ".mudlet/connection.json";
+/** Where the sidecar lived in archives exported before the storage rename.
+ *  Those zips are out in the wild, so import still has to look here. */
+export declare const LEGACY_CONNECTION_SIDECAR_PATH = ".mudix/connection.json";
+/** Where a profile imported from Mudlet keeps its original `<HostPackage>`,
+ *  inside its own VFS. `extractHostPackageXml` produces it at import time; the
+ *  export and `saveProfile()` base their `<Host>` on it so the settings Mudlet Web
+ *  doesn't model don't revert to Mudlet's defaults. Dot-prefixed like the rest
+ *  of Mudlet Web's bookkeeping, so desktop Mudlet ignores it.
+ *
+ *  Absent for a profile created in Mudlet Web (nothing unmodeled to preserve), for a
+ *  linked folder (its own `current/*.xml` is the live original), and for
+ *  profiles imported before this file existed — their `<Host>` was already
+ *  dropped at import and can't be recovered. */
+export declare const RETAINED_HOST_PATH = ".mudlet/host.xml";
+/** Pre-rename location of the retained host XML. A profile whose VFS has not
+ *  been opened since the rename still keeps it here (see migrateLegacyDotDir),
+ *  as does any archive exported before it. */
+export declare const LEGACY_RETAINED_HOST_PATH = ".mudix/host.xml";
 export interface ConnectionSidecar {
     mode?: MudConnection['mode'];
     url?: string;
@@ -14,10 +32,21 @@ export interface ConnectionSidecar {
     port?: number;
     proxyUrl?: string;
     autoReconnect?: boolean;
+    reconnectOnDrop?: boolean;
 }
 export declare function buildConnectionSidecar(c: MudConnection): ConnectionSidecar;
+/**
+ * The base `buildLinkedWriteback` writes this profile's automation and settings
+ * onto. The connection identity and package list are stamped on either way: a
+ * retained `<Host>` holds the name, address and packages the profile had when it
+ * was imported, and the live connection record is what's authoritative now.
+ */
+export declare function buildHostBaseXml(connection: MudConnection, packageNames: string[], retained?: string): string;
 /** Serialize one profile's automation, variables and settings as Mudlet profile XML. */
-export declare function buildProfileXml(connection: MudConnection, data: PersistedProfileData): string;
+export declare function buildProfileXml(connection: MudConnection, data: PersistedProfileData, 
+/** The profile's retained `<HostPackage>` (or a full save to take it from),
+ *  so unmodeled Mudlet settings survive. See {@link RETAINED_HOST_PATH}. */
+hostBaseXml?: string): string;
 /** One exported session log: `name` becomes the filename under `logs/`. */
 export interface ExportLog {
     name: string;
@@ -25,11 +54,15 @@ export interface ExportLog {
 }
 export interface ProfileExportSource {
     connection: MudConnection;
-    /** Contents of `.mudix/profile.json`. */
+    /** Contents of `.mudlet/profile.json`. */
     data: PersistedProfileData;
     /** Loose VFS files (packages, fonts, sounds, …), keyed relative to the
-     *  profile root. `.mudix/` is expected to be filtered out by the collector. */
+     *  profile root. `.mudlet/` is expected to be filtered out by the collector. */
     files: Record<string, Uint8Array>;
+    /** The profile's retained Mudlet `<HostPackage>` — `.mudlet/host.xml`, or a
+     *  linked folder's own newest save. Undefined for a profile that was never
+     *  imported from Mudlet: it has no unmodeled Host settings to preserve. */
+    hostBaseXml?: string;
     mapBytes?: Uint8Array;
     logs?: ExportLog[];
 }

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

@@ -8,9 +8,15 @@ export interface MudletProfileBundle {
     port?: number;
     /** Parsed settings + automation + variables from the newest current/*.xml. */
     profile: MudletProfileImport;
+    /** That save's `<HostPackage>`, verbatim. `profile.settings` covers only the
+     *  Host fields Mudlet Web models; the other ~100 live here and nowhere else, so
+     *  this is retained in the new profile's VFS for an export to base on.
+     *  Undefined if the save carries no `<HostPackage>`. */
+    hostPackageXml?: string;
     /** Manifests for the profile's installed packages (from <mInstalledPackages>,
      *  metadata from each package's config.lua). Registered on import so
-     *  getPackageInfo / package managers see them as installed. */
+     *  getPackageInfo / package managers see them as installed. Folded-in
+     *  modules join them as `kind: 'module'` manifests (addModuleToBundle). */
     packages: PackageManifest[];
     /** Modules the profile loads from external local XML files — unresolvable in a
      *  browser; the import UI asks the user to upload or drop each. */
@@ -18,9 +24,52 @@ export interface MudletProfileBundle {
     /** Newest map/* binary, ready for mapStorage. Undefined if the profile has no map. */
     mapBytes?: Uint8Array;
     /** Remaining profile-root files to copy into the new VFS (packages, fonts,
-     *  sounds, …), keyed relative to the profile root. Excludes current/ and map/. */
+     *  sounds, …), keyed relative to the profile root. Excludes current/ and map/,
+     *  and the {@link CONSUMED_PROFILE_FILES} read into the fields below. */
     files: Record<string, Uint8Array>;
+    /** Connect over TLS: the profile's `ssl_tsl` file, else `<Host mSslTsl>`.
+     *  Undefined when neither says. */
+    tls?: boolean;
+    /** Desktop's saved character name — the profile's `login` file, which it
+     *  sends on its own two seconds after connecting. */
+    login?: string;
+    /** The saved password, from the profile's `password` file. Only there when
+     *  desktop was not keeping passwords in the system keychain. Never written
+     *  into the new profile's files: the caller hands it to the credential vault. */
+    password?: string;
+    /** The main command line's history (`command_history_main`), newest first,
+     *  de-duplicated the way Mudlet Web's own history is. */
+    commandHistory?: string[];
+    /**
+     * Everything about this profile that could not be carried over faithfully,
+     * in the order it was noticed. Seeded from the XML parse
+     * (`profile.automation.warnings`) and appended to as the import proceeds —
+     * by `addModuleToBundle` for each folded-in module, and by
+     * `importMudletProfile` for files that would not write and a map that would
+     * not save.
+     *
+     * The single place the import UI reads: a profile import used to succeed in
+     * silence even when it dropped things, which made every fidelity gap a
+     * surprise discovered weeks later (issue #45).
+     */
+    warnings: string[];
 }
+/**
+ * Profile-root files desktop keeps a connection detail in, one value per file
+ * (`MudletApp::readProfileData`). Each is read into the bundle — the connection
+ * record or the settings — rather than copied as a file: once imported, those
+ * are what's live, and a copy left in the profile would be stale the moment the
+ * setting changed (an export writes fresh ones, see buildProfileFolder). The
+ * password is kept out of the profile's files above all.
+ */
+export declare const CONSUMED_PROFILE_FILES: readonly ["encoding", "ssl_tsl", "login", "password"];
+/**
+ * Desktop's `command_history_main`: one command per line, newest first, often
+ * led by an empty line (TCommandLine::slot_saveHistory saves the line being
+ * typed too). Read into the shape Mudlet Web's history keeps — no blanks, one
+ * entry per command ignoring case, at most {@link MAX_HISTORY}.
+ */
+export declare function parseCommandHistory(text: string): string[];
 /**
  * Build a manifest per installed package, reading metadata from each package's
  * config.lua via `readConfig(name)` (returns the file text or undefined).
@@ -28,10 +77,38 @@ export interface MudletProfileBundle {
  * Reusable across the file-map import path and the linked-folder (VFS) path.
  */
 export declare function buildPackageManifests(names: string[], readConfig: (name: string) => string | undefined): PackageManifest[];
+/** Desktop's main command-line history file, beside the profile-data files. */
+export declare const DESKTOP_HISTORY_FILE = "command_history_main";
+/** What a desktop profile's own files say about its connection — see
+ *  {@link readDesktopProfileFiles}. */
+export interface DesktopProfileFiles {
+    /** The `encoding` file, in the listed spelling. Undefined when there is no
+     *  file, or it names an encoding Mudlet Web cannot decode (then warned). */
+    serverEncoding?: string;
+    /** `ssl_tsl`, else the save's `mSslTsl` passed in. */
+    tls?: boolean;
+    login?: string;
+    password?: string;
+    /** `command_history_main`, newest first (see {@link parseCommandHistory}). */
+    commandHistory?: string[];
+    warnings: string[];
+}
+/**
+ * Read the files desktop keeps a profile's connection details in — the
+ * {@link CONSUMED_PROFILE_FILES}, serialised QStrings (see qtProfileData.ts),
+ * and the plain-text {@link DESKTOP_HISTORY_FILE}. `read` returns a file's
+ * bytes by its name at the profile root, or undefined when it is absent.
+ * Shared by the import and by a linked folder, which reads the same files in
+ * place. `saveTls` is the save's `<Host mSslTsl>`, the fallback for TLS.
+ */
+export declare function readDesktopProfileFiles(read: (name: string) => Uint8Array | undefined, saveTls?: boolean): DesktopProfileFiles;
+/** An `ssl_tsl` file's decoded text as on/off, or undefined when it holds no
+ *  check state (missing, empty, or not a number). */
+export declare function parseSslTsl(text: string | undefined): boolean | undefined;
 /**
  * Every profile root in the tree — the prefix before each `current/` directory.
  *
- * A tree with profiles side by side (mudix's multi-profile export) yields one
+ * A tree with profiles side by side (Mudlet Web's multi-profile export) yields one
  * root each. Nesting is resolved by depth: a root at the top wins over anything
  * inside it, so a single profile that happens to contain another `current/*.xml`
  * deeper down still imports as one profile, matching the old shallowest-wins
@@ -42,11 +119,21 @@ export declare function buildMudletProfileBundle(files: Record<string, Uint8Arra
 /** Import this specific root (from {@link findProfileRoots}) instead of the
  *  shallowest one — used when one tree holds several profiles. */
 rootOverride?: string): MudletProfileBundle;
-/** Build a profile bundle from a `.zip` of a Mudlet profile directory. (Zip
- *  entry mtimes aren't surfaced, so newest-save uses the autosave/timestamp
- *  fallback.) */
+/**
+ * Each entry's modification time (ms), keyed by name exactly as `unzipSync`
+ * keys it, read from the archive's central directory — fflate doesn't surface
+ * them. Uses the Info-ZIP extended-timestamp field (0x5455, true UTC to the
+ * second) when every entry has one, else the DOS date/time all entries carry
+ * (local time, two-second resolution). Either way the values only have to
+ * order entries of the same archive, so a DOS time is read as if it were UTC.
+ * Entries with no usable time are left out. Never throws: an archive this
+ * can't read just yields no times, and the import falls back to names.
+ */
+export declare function zipEntryMtimes(bytes: Uint8Array): Record<string, number>;
+/** Build a profile bundle from a `.zip` of a Mudlet profile directory, picking
+ *  the newest save and map by the entries' modification times. */
 export declare function extractMudletProfileZip(bytes: Uint8Array, fallbackName?: string): MudletProfileBundle;
-/** One bundle per profile in the tree — a mudix multi-profile export, or a
+/** One bundle per profile in the tree — a Mudlet Web multi-profile export, or a
  *  single Mudlet profile (in which case this is a one-element list). */
 export declare function buildAllMudletProfileBundles(files: Record<string, Uint8Array>, fallbackName?: string, mtimes?: Record<string, number>): MudletProfileBundle[];
 /** Every profile in a `.zip`, in folder order. */
@@ -54,6 +141,8 @@ export declare function extractMudletProfileZipAll(bytes: Uint8Array, fallbackNa
 export interface ResolvedModule {
     ref: MudletModuleRef;
     xmlBytes: Uint8Array;
+    /** Where the file was found, as a `bundle.files` key. */
+    path: string;
 }
 /** Split a bundle's modules into those whose XML was found in the imported tree
  *  (by filename) and those still missing. */
@@ -63,9 +152,18 @@ export declare function resolveModulesFromTree(bundle: MudletProfileBundle): {
 };
 /**
  * Fold a resolved/uploaded module's XML into the bundle: its triggers/aliases/…
- * are parsed (grouped + tagged under the module key, so it's a removable unit)
- * and appended to the automation, and a manifest is registered. Mutates and
- * returns the bundle. Treated as a package — the live-sync-to-disk behaviour
- * doesn't apply in a browser.
+ * are parsed (tagged under the module key) and appended to the automation, and
+ * a MODULE manifest is registered — `kind: 'module'`, the `<globalSave>` flag
+ * as `sync`, its `<priority>` — so getModules/getModulePriority/getModulePath
+ * see it the way desktop does, and getPackages does not (issue #279).
+ *
+ * The XML has to exist as a file for the module to reload from: `treePath` is
+ * where the import tree already holds it (see resolveModulesFromTree); an
+ * uploaded file is added to `bundle.files` under `<key>/<its filename>`. The
+ * manifest's `xmlVfsPath` is that path relative to the profile root until
+ * bundleToConnectionData anchors it in the new profile's VFS.
+ *
+ * `module` may be the bare key, in which case the rest of its entry is looked
+ * up in `bundle.modules`. Mutates and returns the bundle.
  */
-export declare function addModuleToBundle(bundle: MudletProfileBundle, key: string, xmlBytes: Uint8Array): MudletProfileBundle;
+export declare function addModuleToBundle(bundle: MudletProfileBundle, module: MudletModuleRef | string, xmlBytes: Uint8Array, treePath?: string): MudletProfileBundle;

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

@@ -2,9 +2,10 @@ export declare const LUA_TBOOLEAN = 1;
 export declare const LUA_TNUMBER = 3;
 export declare const LUA_TSTRING = 4;
 export declare const LUA_TTABLE = 5;
-/** How a variable's key is typed in its parent table. Lua only distinguishes
- *  string vs number keys here (Mudlet never saves other key types). */
-export type VarKeyKind = 'string' | 'number';
+/** How a variable's key is typed in its parent table. Mudlet saves string,
+ *  number and boolean keys (a boolean key's <name> is "true"/"false"); other
+ *  key types are never saved. */
+export type VarKeyKind = 'string' | 'number' | 'boolean';
 /** Scalar value types we round-trip. Tables are represented by `children`. */
 export type VarValueType = 'boolean' | 'number' | 'string' | 'table';
 /**

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

@@ -1,12 +1,26 @@
 import type { ProfileSettings } from '../storage/schema';
 import { type SerializeInput } from './mudletXmlExport';
 import { type MudletVariablePackage } from './mudletVariables';
+import type { SavedStopwatch } from '../scripting/StopwatchManager';
 /**
  * Produce the updated profile XML: the base save with its automation + variable
  * packages replaced by `trees` / `variables`, the modeled `<Host>` settings
  * updated in place from `settings`, and HostPackage's unmodeled fields (plus any
  * unknown element) carried over verbatim. Throws if the base XML is malformed.
  */
-export declare function buildLinkedWriteback(baseXml: string, trees: SerializeInput, variables: MudletVariablePackage, settings?: Partial<ProfileSettings>): string;
+export declare function buildLinkedWriteback(baseXml: string, trees: SerializeInput, variables: MudletVariablePackage, settings?: Partial<ProfileSettings>, 
+/** Leave the profile's own settings out, as Mudlet's "save as" does —
+ *  Host::saveProfileAs goes through writeGenericPackage, which writes the
+ *  seven item packages and nothing else. A document meant to be handed to
+ *  someone else should not carry the sender's preferences. */
+omitHostSettings?: boolean, 
+/** The profile's live package list, written into `<mInstalledPackages>`
+ *  as desktop's `Host::saveProfile` does. Left out, the base's own list
+ *  stands — right for an export whose base was already stamped, wrong for a
+ *  save based on an older one, whose list predates any install since. */
+installedPackages?: string[], 
+/** The profile's persistent stopwatches, written into `<stopwatches>` as
+ *  desktop's save does. Left out, the base's own copy stands. */
+stopwatches?: SavedStopwatch[]): string;
 /** Mudlet's profile-save filename stamp for `date`: `YYYY-MM-DD#HH-mm-ss`. */
 export declare function mudletTimestamp(date: Date): string;

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

@@ -1,4 +1,5 @@
 import type { AliasNode, ButtonNode, KeyNode, ScriptNode, TimerNode, TriggerNode } from '../storage/schema';
+import { type MudletVariable } from './mudletVariables';
 export interface MudletImportResult {
     scripts: ScriptNode[];
     aliases: AliasNode[];
@@ -7,6 +8,44 @@ export interface MudletImportResult {
     keys: KeyNode[];
     buttons: ButtonNode[];
     warnings: string[];
+    /**
+     * The globals a `<VariablePackage>` carries, if any. A package may be
+     * nothing BUT these — a module of variables, fonts, images or a map loads
+     * completely and still leaves every one of the six item units empty — so an
+     * install that only looked at the units took such a package for one that had
+     * installed nothing at all.
+     */
+    variables?: MudletVariable[];
+    /**
+     * Why the document could not be read, when it could not. Set only for a
+     * caller that asked to be TOLD rather than thrown at — an install carries on
+     * with whatever loaded and reports the failure, because the package is
+     * listed either way and a silent one is a package the player cannot account
+     * for.
+     */
+    parseError?: string;
+    /**
+     * Set alongside {@link parseError} when the fault left nothing at all read
+     * out of the document — no item and no variable — because it broke before
+     * the first one, was not XML at all, or came from a later Mudlet and was
+     * refused whole (`'newer'`). A package made only of such documents is
+     * refused rather than listed empty; one that read anything, or one read
+     * through without a fault, empty or not, is the package.
+     */
+    nothingRead?: 'unreadable' | 'newer';
+    /**
+     * Why the document stopped being read, in the words desktop's streaming
+     * reader (QXmlStreamReader::errorString) gives — what Host::installPackage
+     * hands back for it, "<package>[/<file>]: <this>". Set alongside
+     * {@link parseError} for a malformed document.
+     */
+    xmlError?: string;
+    /**
+     * The install's "load errors": one "<package>[/<file>]: <xmlError>" per
+     * document of the package that could not be read whole, in the order they
+     * were read. Filled in by the package installer, which knows the files.
+     */
+    loadErrors?: string[];
 }
 export interface ParseOptions {
     /**
@@ -17,5 +56,12 @@ export interface ParseOptions {
      * cleanly removable by tag.
      */
     packageName?: string;
+    /**
+     * Report a malformed document instead of throwing on it. An install wants
+     * this: Mudlet's reader keeps whatever it read before the break and leaves
+     * the package listed, so throwing here would refuse an install Mudlet
+     * completes.
+     */
+    reportParseError?: boolean;
 }
 export declare function parseMudletXml(xml: string, opts?: ParseOptions): MudletImportResult;

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

@@ -0,0 +1,33 @@
+import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
+import type { PackageManifest } from '../storage/schema';
+export interface PackageFontResult {
+    /** Families successfully registered, in the order they were found. */
+    registered: string[];
+    /** One line per font that could not be registered, for the error log. */
+    warnings: string[];
+}
+/**
+ * Register every font shipped inside one installed package.
+ *
+ * Every font found is in `document.fonts` by the time this returns its promise
+ * (see `loadFontFromVfs`); the promise settles when they have all loaded.
+ *
+ * Best-effort per file: a font that will not parse or will not load must not
+ * stop the ones beside it, and must not fail the install that is calling this —
+ * desktop's `loadFont` likewise reports and carries on. What it must not do is
+ * stay silent, which is the whole of issue #103, so each failure comes back as
+ * a warning for the caller to surface.
+ *
+ * Idempotent, because `refreshPackageFonts` re-runs it over packages whose
+ * fonts may already be registered: `loadFontFromVfs` keys what it has loaded by
+ * profile + path + family and returns early on a repeat.
+ */
+export declare function installPackageFonts(manifest: PackageManifest, vfs: ProfileVFS): Promise<PackageFontResult>;
+/**
+ * Re-register the fonts of every installed package — desktop's
+ * `Host::refreshPackageFonts`, called on profile open.
+ *
+ * Without it a package's font works until the tab is closed and then silently
+ * stops, which is a worse bug than never having worked.
+ */
+export declare function refreshPackageFonts(manifests: readonly PackageManifest[], vfs: ProfileVFS): Promise<PackageFontResult>;