@mudlet/mudlet-web 0.3.0

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

@@ -0,0 +1,67 @@
+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.
+ */
+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. */
+export interface MudletProfileIdentity {
+    name?: string;
+    host?: string;
+    port?: number;
+}
+/** Read `<name>`/`<url>`/`<port>` (direct children of `<Host>`). */
+export declare function parseMudletHostIdentity(host: Element): MudletProfileIdentity;
+/**
+ * Write the modeled ProfileSettings back onto an existing `<Host>` element,
+ * in place — only the fields present in `s` are touched, so unmodeled Host
+ * fields (and the whole rest of the profile) are preserved. The inverse of
+ * {@link parseMudletHost}. The display-font family is only written for a *system*
+ * font (Mudlet can't resolve a url/vfs font name); the size is always synced, and
+ * the rest of the QFont spec is preserved.
+ */
+export declare function applyProfileSettingsToHost(host: Element, s: Partial<ProfileSettings>): void;
+/** 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
+ *  entry on import. */
+export declare function parseInstalledPackages(host: Element): string[];
+/** Everything a full Mudlet profile XML carries that mudix can import. */
+export interface MudletProfileImport {
+    /** From `<Host>` — the profile name + MUD address for the connection record. */
+    connection: MudletProfileIdentity;
+    /** From `<HostPackage><Host>` — partial so it merges over defaults. */
+    settings: Partial<ProfileSettings>;
+    /** From the Trigger/Alias/Script/Timer/Key/Action packages. */
+    automation: MudletImportResult;
+    /** From `<VariablePackage>` — the saved-variables tree + hidden list. */
+    variables: MudletVariablePackage;
+    /** Names from `<mInstalledPackages>` — registered as package manifests on import. */
+    installedPackages: string[];
+    /** From `<mInstalledModules>` — modules reference an XML file at an absolute
+     *  local path *outside* the profile, which a browser can't read. The import
+     *  flow surfaces these for the user to upload or drop. */
+    modules: MudletModuleRef[];
+}
+/** One `<mInstalledModules>` entry: a module the profile loads from an external
+ *  XML file on the user's disk. */
+export interface MudletModuleRef {
+    key: string;
+    filepath: string;
+    /** Mudlet `globalSave` flag — sync the module back on save. */
+    globalSave: boolean;
+    priority: number;
+}
+/** 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
+ * 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.
+ */
+export declare function parseMudletProfile(xml: string): MudletProfileImport;

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

@@ -0,0 +1,34 @@
+export interface VfsReader {
+    exists(path: string): boolean;
+    readdir(path: string): string[];
+    stat(path: string): {
+        mtime: Date;
+    } | null;
+    readFile(path: string): string;
+}
+/** 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. */
+export declare function listCurrentXmlsByRecency(vfs: VfsReader): string[];
+/** Path of the newest profile save in current/, or null if not a Mudlet profile. */
+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;
+/**
+ * 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
+ * from the write bug) and falls back to older saves — so a linked profile still
+ * opens, and write-back can re-heal the bad file from a good base. Null if none
+ * parse.
+ */
+export declare function readNewestParseableXml(vfs: VfsReader): {
+    path: string;
+    xml: string;
+} | 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
+ * 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;

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

@@ -0,0 +1,49 @@
+import type { MudConnection } from '../storage/schema';
+import type { PersistedProfileData } from '../storage/profileVfsData';
+/** Mudlet names its saves `YYYY-MM-DD#HH-mm-ss.xml`; the importer sorts by that
+ *  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
+ *  keeps them; desktop Mudlet ignores the dot-directory entirely. */
+export declare const CONNECTION_SIDECAR_PATH = ".mudix/connection.json";
+export interface ConnectionSidecar {
+    mode?: MudConnection['mode'];
+    url?: string;
+    host?: string;
+    port?: number;
+    proxyUrl?: string;
+    autoReconnect?: boolean;
+}
+export declare function buildConnectionSidecar(c: MudConnection): ConnectionSidecar;
+/** Serialize one profile's automation, variables and settings as Mudlet profile XML. */
+export declare function buildProfileXml(connection: MudConnection, data: PersistedProfileData): string;
+/** One exported session log: `name` becomes the filename under `logs/`. */
+export interface ExportLog {
+    name: string;
+    html: string;
+}
+export interface ProfileExportSource {
+    connection: MudConnection;
+    /** Contents of `.mudix/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. */
+    files: Record<string, Uint8Array>;
+    mapBytes?: Uint8Array;
+    logs?: ExportLog[];
+}
+/** Strip characters that are illegal in zip entry / filesystem names, so a
+ *  profile called `Arkadia: main` can't produce an unextractable archive. */
+export declare function sanitizeFolderName(name: string, fallback: string): string;
+/**
+ * Build one profile's folder as `{path -> bytes}`, keyed *relative to the
+ * profile root* (no folder prefix). Pure — the caller supplies everything.
+ */
+export declare function buildProfileFolder(src: ProfileExportSource, stamp: string): Record<string, Uint8Array>;
+/**
+ * Build the downloadable archive: one folder per profile, so a single zip can
+ * carry every profile a user has. Duplicate profile names are suffixed rather
+ * than merged — two folders that collide would silently lose one profile.
+ */
+export declare function buildProfilesZip(sources: ProfileExportSource[], now: Date): Uint8Array;

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

@@ -0,0 +1,71 @@
+import type { PackageManifest } from '../storage/schema';
+import { type MudletProfileImport, type MudletModuleRef } from './mudletHost';
+export interface MudletProfileBundle {
+    /** Profile name — `<Host><name>`, else the profile folder name, else fallback. */
+    name: string;
+    /** MUD address from `<Host>` (`<url>`/`<port>`), if present. */
+    host?: string;
+    port?: number;
+    /** Parsed settings + automation + variables from the newest current/*.xml. */
+    profile: MudletProfileImport;
+    /** 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. */
+    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. */
+    modules: MudletModuleRef[];
+    /** 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/. */
+    files: Record<string, Uint8Array>;
+}
+/**
+ * Build a manifest per installed package, reading metadata from each package's
+ * config.lua via `readConfig(name)` (returns the file text or undefined).
+ * `installedAt` is left empty for the caller to stamp (keeps this deterministic).
+ * 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[];
+/**
+ * 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
+ * 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
+ * behavior. Returned sorted, so import order is deterministic.
+ */
+export declare function findProfileRoots(files: Record<string, Uint8Array>): string[];
+export declare function buildMudletProfileBundle(files: Record<string, Uint8Array>, fallbackName?: string, mtimes?: Record<string, number>, 
+/** 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.) */
+export declare function extractMudletProfileZip(bytes: Uint8Array, fallbackName?: string): MudletProfileBundle;
+/** One bundle per profile in the tree — a mudix 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. */
+export declare function extractMudletProfileZipAll(bytes: Uint8Array, fallbackName?: string): MudletProfileBundle[];
+export interface ResolvedModule {
+    ref: MudletModuleRef;
+    xmlBytes: Uint8Array;
+}
+/** Split a bundle's modules into those whose XML was found in the imported tree
+ *  (by filename) and those still missing. */
+export declare function resolveModulesFromTree(bundle: MudletProfileBundle): {
+    resolved: ResolvedModule[];
+    unresolved: MudletModuleRef[];
+};
+/**
+ * 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.
+ */
+export declare function addModuleToBundle(bundle: MudletProfileBundle, key: string, xmlBytes: Uint8Array): MudletProfileBundle;

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

@@ -0,0 +1,49 @@
+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';
+/** Scalar value types we round-trip. Tables are represented by `children`. */
+export type VarValueType = 'boolean' | 'number' | 'string' | 'table';
+/**
+ * One saved variable (or table entry). `name` is the key as written in <name>
+ * — for a numeric key it's the number stringified ("7"). `value` is Mudlet's
+ * string form of the scalar ("true"/"42"/"3.5"/raw string); it is '' and unused
+ * for tables, whose entries live in `children`.
+ */
+export interface MudletVariable {
+    name: string;
+    keyKind: VarKeyKind;
+    valueType: VarValueType;
+    value: string;
+    children?: MudletVariable[];
+}
+export interface MudletVariablePackage {
+    /** <HiddenVariables> names. Round-tripped verbatim; the populated inner
+     *  format is unverified (only ever observed empty) so we preserve whatever
+     *  <name> entries are present without interpreting them. */
+    hidden: string[];
+    variables: MudletVariable[];
+}
+/** Parse a `<VariablePackage>` element. */
+export declare function parseVariablePackage(pkg: Element): MudletVariablePackage;
+/** Parse the first `<VariablePackage>` out of a full Mudlet profile XML string.
+ *  Returns an empty package when there is none. */
+export declare function parseVariablePackageXml(xml: string): MudletVariablePackage;
+/**
+ * Coerce a loosely-typed variable tree (e.g. the result of `JSON.parse` on a
+ * `yajl.to_string` capture from the Lua side) into well-formed `MudletVariable`s.
+ * Notably, yajl can't tell an empty Lua table from an empty array, so an empty
+ * `children`/root arrives as `{}` rather than `[]`; this normalises those back to
+ * arrays and drops anything that isn't a recognisable node.
+ */
+export declare function normalizeVariableTree(raw: unknown): MudletVariable[];
+/**
+ * Serialize a `<VariablePackage>` to Mudlet's exact textual format (tab indent).
+ * `indent` is the leading indent of the `<VariablePackage>` line itself (one tab
+ * inside `<MudletPackage>` in a real profile). Top-level variables and table
+ * children are emitted name-sorted to match Mudlet and keep output stable.
+ */
+export declare function serializeVariablePackage(pkg: MudletVariablePackage, indent?: string): string;

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

@@ -0,0 +1,12 @@
+import type { ProfileSettings } from '../storage/schema';
+import { type SerializeInput } from './mudletXmlExport';
+import { type MudletVariablePackage } from './mudletVariables';
+/**
+ * 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;
+/** 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/mudletXmlExport.d.ts

@@ -0,0 +1,16 @@
+import type { AliasNode, ButtonNode, KeyNode, ScriptNode, TimerNode, TriggerNode } from '../storage/schema';
+export interface SerializeInput {
+    scripts: ScriptNode[];
+    aliases: AliasNode[];
+    triggers: TriggerNode[];
+    timers: TimerNode[];
+    keys: KeyNode[];
+    buttons: ButtonNode[];
+}
+/**
+ * Serialize a Mudlet-package node set back to XML. When `packageName` is supplied,
+ * a top-level wrapper group of that name (the one that `applyPackageTagging`
+ * inserts on import) is unwrapped — its children become package-level roots —
+ * so the document round-trips back to the same structure on re-import.
+ */
+export declare function serializeMudletXml(input: SerializeInput, packageName?: string): string;

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

@@ -0,0 +1,21 @@
+import type { AliasNode, ButtonNode, KeyNode, ScriptNode, TimerNode, TriggerNode } from '../storage/schema';
+export interface MudletImportResult {
+    scripts: ScriptNode[];
+    aliases: AliasNode[];
+    triggers: TriggerNode[];
+    timers: TimerNode[];
+    keys: KeyNode[];
+    buttons: ButtonNode[];
+    warnings: string[];
+}
+export interface ParseOptions {
+    /**
+     * When set, every parsed node is tagged with this packageName, and a
+     * top-level group of the same name is prepended to each non-empty
+     * category as a parent for the imported tree. This mirrors Mudlet's
+     * .mpackage import behaviour: items are organisationally grouped and
+     * cleanly removable by tag.
+     */
+    packageName?: string;
+}
+export declare function parseMudletXml(xml: string, opts?: ParseOptions): MudletImportResult;

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

@@ -0,0 +1,72 @@
+import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
+import type { PackageKind, PackageManifest } from '../storage/schema';
+import { type MudletImportResult } from './mudletXmlImport';
+export interface InstallResult {
+    manifest: PackageManifest;
+    data: MudletImportResult;
+}
+export interface InstallOptions {
+    /**
+     * 'package' (default) — plain XML imports skip VFS storage; only zips are kept on disk.
+     * 'module'            — XML on disk is the source of truth: even plain XML is written to the
+     *                       VFS so it can be re-parsed on the next profile open and synced to.
+     */
+    kind?: PackageKind;
+    /**
+     * Absolute VFS path the bytes were read from, when known. If it lives inside the
+     * derived pkgDir, the install skips the pkgDir wipe — otherwise an installer-style
+     * "unzip into <pkgDir>/ then installPackage(<pkgDir>/foo.xml)" pattern would delete
+     * the resources the script just staged.
+     */
+    sourcePath?: string;
+}
+/**
+ * Install a Mudlet package from in-memory bytes. Synchronous — the caller is
+ * expected to flush the VFS afterwards (or let the next idle flush handle it).
+ *
+ * Behaviour by kind:
+ * - .mpackage / .zip : always unzipped into <profilePath>/<packageName>/. The full payload
+ *                      is preserved so resources (images, sounds, lua modules) remain
+ *                      available to scripts via the VFS, regardless of `kind`.
+ * - .xml as 'package': parse only — no files written. Nodes live in the app store.
+ * - .xml as 'module' : the XML is also written to <profilePath>/<packageName>/<filename>;
+ *                      the on-disk file is treated as the source of truth, so it must exist
+ *                      to be re-parsed on profile open.
+ *
+ * The XML is parsed in package-mode, which wraps each category in a top-level
+ * group and tags every node with the package name, making uninstall a tag-based cascade.
+ */
+export declare function installPackageFromBytes(filename: string, buf: Uint8Array, vfs: ProfileVFS, opts?: InstallOptions): InstallResult;
+/** Async wrapper that reads from a File and flushes the VFS to disk on success. */
+export declare function installPackageFromFile(file: File, vfs: ProfileVFS, opts?: InstallOptions): Promise<InstallResult>;
+/**
+ * Remove a package's on-disk files. The store handles tag-based node removal
+ * separately. Modules are exempt: they unlink only — the underlying XML (and any
+ * unzipped resources) survive uninstall so the user's source files aren't
+ * silently destroyed when they remove the module from the app.
+ */
+export declare function uninstallPackageFiles(manifest: PackageManifest, vfs: ProfileVFS): Promise<void>;
+/**
+ * Resolve the absolute VFS path of a module's XML file. Honors `xmlVfsPath` (in-place
+ * modules) first, then falls back to the managed `<profilePath>/<name>/<xmlPath>` layout.
+ * Returns null if neither is set.
+ */
+export declare function moduleXmlAbsolutePath(manifest: PackageManifest, vfs: ProfileVFS): string | null;
+/**
+ * Re-read a module's XML from the VFS and return the parsed result.
+ * Throws if the on-disk file is missing — modules require their XML to be present.
+ */
+export declare function reloadModuleFromVfs(manifest: PackageManifest, vfs: ProfileVFS): MudletImportResult;
+/**
+ * Install a module from a path that already lives inside the profile's VFS.
+ *
+ * - Plain XML : referenced in place. The manifest stores `xmlVfsPath` and no pkgDir is
+ *               created. Reload and sync read/write the user-chosen path verbatim, so
+ *               external tools (a synced folder, an editor) can keep editing it.
+ * - .mpackage / .zip : same flow as a normal module install — extracted into a fresh
+ *               pkgDir so resources are accessible. The original archive on disk is
+ *               left untouched but is no longer referenced by the module.
+ *
+ * Throws on read/parse failures.
+ */
+export declare function installModuleFromVfsPath(absolutePath: string, vfs: ProfileVFS): InstallResult;

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

@@ -0,0 +1,54 @@
+/**
+ * Browse and install packages from Mudlet's official package repository.
+ *
+ * The repository is published as a static site backed by the
+ * github.com/Mudlet/mudlet-package-repository git repo. A reindex script
+ * regenerates `packages/mpkg.packages.json` after every commit, so the JSON
+ * catalog is authoritative — we don't try to scrape the all-packages.html page.
+ *
+ * Catalog shape (top-level object):
+ *   { name, updated, packages: PackageRepoEntry[] }
+ *
+ * URLs are constructed from the repo's GitHub Pages base. Icon paths inside
+ * each entry are already relative to the repo root (e.g. "packages/icons/Foo.png"),
+ * so they're joined to REPO_BASE_URL verbatim.
+ */
+/**
+ * Public-facing repository site (used for "view in browser" links).
+ * NOT used for fetching the catalog — the GitHub Pages mirror lags weeks behind
+ * the main branch. Mudlet's own package manager dialog hits raw.githubusercontent.com
+ * for the same reason; we mirror that choice.
+ */
+export declare const REPO_SITE_URL = "https://mudlet.github.io/mudlet-package-repository";
+/** Base for fetching individual .mpackage files and icons (always-current `main` branch). */
+export declare const REPO_RAW_BASE = "https://raw.githubusercontent.com/Mudlet/mudlet-package-repository/refs/heads/main";
+export declare const CATALOG_URL = "https://raw.githubusercontent.com/Mudlet/mudlet-package-repository/refs/heads/main/packages/mpkg.packages.json";
+export interface PackageRepoEntry {
+    /** Internal identifier (matches manifest.name produced by installPackageFromBytes). */
+    mpackage: string;
+    /** Filename inside the repo's packages/ directory, e.g. "Foo.mpackage". */
+    filename: string;
+    title?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    /** ISO-8601 author-declared creation date. */
+    created?: string;
+    /** Unix timestamp the package was last uploaded to the repo. */
+    uploaded?: number;
+    /** Repo-relative icon path, e.g. "packages/icons/Foo.png". Optional. */
+    icon?: string;
+}
+export interface PackageRepoCatalog {
+    name: string;
+    updated: string;
+    packages: PackageRepoEntry[];
+}
+/** Absolute URL of the .mpackage zip for `entry`. */
+export declare function packageDownloadUrl(entry: PackageRepoEntry): string;
+/** Absolute URL of the icon image for `entry`, or null when none. */
+export declare function packageIconUrl(entry: PackageRepoEntry): string | null;
+/** Fetch and parse the package catalog. Throws on network or JSON errors. */
+export declare function fetchPackageCatalog(proxyUrl?: string): Promise<PackageRepoCatalog>;
+/** Download a single package's bytes. The caller is expected to pass it to installPackageFromBytes. */
+export declare function downloadPackageBytes(entry: PackageRepoEntry, proxyUrl?: string): Promise<Uint8Array>;

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

@@ -0,0 +1,52 @@
+/**
+ * Fetch a package file from a remote URL, falling back through the configured
+ * proxy on CORS / network failures. Mirrors the proxy logic in HttpService and
+ * packageRepository — duplicated rather than imported to keep this module
+ * focused on the small concern of "download bytes for a package install".
+ */
+import type { PackageManifest } from '../storage/schema';
+export declare function downloadFromUrl(url: string, proxyUrlRaw?: string): Promise<Uint8Array>;
+/** Pull the trailing path segment out of a URL, falling back when the URL is malformed. */
+export declare function filenameFromUrl(url: string): string;
+export interface ClientGuiPayload {
+    url: string;
+    version?: string;
+}
+/**
+ * Decide whether a `Client.GUI` request is a re-delivery of a package already
+ * installed from the same URL — i.e. whether the install can be skipped.
+ *
+ * The comparison is against `sourceVersion` (the server's own delivery
+ * revision, see PackageManifest.sourceVersion), never against the package's
+ * own `version`: those are the two fields that must stay apart.
+ *
+ * When the server declares no version — either the message carries none, or it
+ * carries a non-string one that `parseClientGuiPayload` drops — nothing
+ * signals that anything changed, so a URL match alone is the whole answer.
+ * Falling back to the package's own `version` here would re-conflate the two
+ * fields, and would still reinstall on every connect for a package whose
+ * author shipped no version at all.
+ *
+ * A manifest from before `sourceVersion` existed has none recorded, so a
+ * versioned request reinstalls it once — that pass is what replaces the
+ * server's value in `version` with the author's.
+ */
+export declare function isClientGuiRedelivery(existing: PackageManifest | undefined, version: string | undefined): boolean;
+/**
+ * Decode a `Client.Map` GMCP payload (the MMP map-location announcement).
+ * Mudlet (Host::setMmpMapLocation) only accepts a JSON object with a valid
+ * `url`; anything else is silently ignored. Returns null on that same basis.
+ */
+export declare function parseClientMapPayload(value: unknown): string | null;
+/**
+ * Decode a `Client.GUI` GMCP payload. Mudlet supports two shapes
+ * (cTelnet::setGMCPVariables):
+ *   - a `{ url, version }` JSON object (current MMP-style format)
+ *   - a string `"<version>\n<url>"` (legacy raw telnet) — version first, which
+ *     is the opposite of what this parser assumed before
+ * Returns null when neither shape applies or the URL is empty. Mudlet also
+ * requires both fields in the legacy shape and drops the message otherwise, so
+ * a lone line is only accepted as a bare URL from the JSON-ish path, never as a
+ * half-decoded legacy pair.
+ */
+export declare function parseClientGuiPayload(value: unknown): ClientGuiPayload | null;

package/dist-lib/index.d.ts

@@ -0,0 +1,30 @@
+import './styles.css';
+export { MudletWebApp } from "./MudletWebApp";
+export { getBrand, isBrandedMode, isPackageRemovable, getThemeChoices, isLightTheme, DEFAULT_BRAND, STOCK_THEMES, type BrandConfig, type BrandMudTarget, type BrandPackage, type BrandTheme, type BrandToolbarButton, type BrandToolbarConfig, type BrandToolbarContext, type StockToolbarButton, type LandingProps, } from "./branding";
+export { BrandLoginScreen } from "./ui/BrandLoginScreen";
+export { useBrandLogin, type UseBrandLoginResult } from "./ui/useBrandLogin";
+export { BrandLoginFields, type BrandLoginFieldsProps } from "./ui/BrandLoginFields";
+export { setSessionCredentials, getSessionCredentials, getLastSessionCredentials, type SessionCredentials } from "./utils/sessionCredentials";
+export type { MudConnection, ConnectionMode } from "./storage/schema";
+export { EventBus } from "./core/EventBus";
+export { ScriptingAPI } from "./scripting/ScriptingAPI";
+export { MudSession } from "./mud/MudSession";
+export type { MudSessionOptions } from "./mud/MudSession";
+export type { SessionStatus, MudClientEvents, MudEvents } from "./mud/events";
+export { TELNET_OPTION_REGEX, GMCP_COMMAND_CODE, GMCP_WILL, GMCP_DO, ECHO_WILL, ECHO_WONT, ECHO_DO, ECHO_DONT, MCCP2_OPTION, } from "./mud/protocol/constants";
+export { MccpHandler } from "./mud/protocol/mccp";
+export { EchoHandler } from "./mud/protocol/echo";
+export { createTelnetOptionParser, stripTelnetSequences, createGmcpStream, encodeGmcp, encodeGmcpRaw, } from "./mud/protocol/gmcp";
+export type { GmcpEnvelope, TelnetOptionHandler, GmcpStreamOptions } from "./mud/protocol/gmcp";
+export { AnsiAwareBuffer, cloneFormatState, formatStatesEqual, } from "./mud/text/FormatState";
+export type { FormatStateSnapshot, FormatColor, IndexedColor, RgbColor, HexColor, FormatHyperlink, DimEffect, DimEasing, BufferSegment, TextRange, } from "./mud/text/FormatState";
+export { colorCodes } from "./mud/text/colors";
+export { setupOutputRenderer } from "./ui/output/OutputRenderer";
+export type { OutputRendererControls } from "./ui/output/OutputRenderer";
+export { MudClient } from "./mud/connection/MudClient";
+export type { MudClientOptions } from "./mud/connection/MudClient";
+export { PingTracker } from "./mud/connection/PingTracker";
+export { createPassthroughProcessor } from "./mud/triggers/ChunkProcessor";
+export type { ChunkProcessor } from "./mud/triggers/ChunkProcessor";
+export { TriggerEngine } from "./mud/triggers/TriggerEngine";
+export type { TriggerNode } from "./mud/triggers/TriggerEngine";