@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -1,9 +1,56 @@
 import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
-import type { PackageKind, PackageManifest } from '../storage/schema';
+import type { PackageKind, PackageManifest, ProfileSettings } from '../storage/schema';
 import { type MudletImportResult } from './mudletXmlImport';
 export interface InstallResult {
     manifest: PackageManifest;
     data: MudletImportResult;
+    /**
+     * Why the archive's `config.lua` gave up nothing, when it did. The install
+     * still goes ahead — under the archive's own name, with no details filed —
+     * and the caller says so, because the silence is what costs: a name-based
+     * uninstall, a repository update and anything depending on the package all
+     * stop matching, with nothing to go on.
+     */
+    configProblem?: string;
+    /**
+     * The name config.lua asked for, when a folder is already sitting at it.
+     *
+     * Reported rather than refused here because the ORDER matters: a name that
+     * is already installed is refused for that first, and only a folder standing
+     * on its own is this. The caller knows what is installed; this module only
+     * knows what is on disk.
+     */
+    occupiedFolder?: string;
+    /**
+     * Set when the archive cannot be moved into a folder of its name that is
+     * already in the profile: one of its files would land where that folder
+     * has a folder, or one of its folders where it has a file. Desktop moves
+     * an archive into such a folder entry by entry, keeping everything else
+     * in it, and is refused by a clash; the reason is this.
+     */
+    moveClash?: string;
+    /**
+     * The profile settings a package XML's `<HostPackage>` carries. Desktop's
+     * XMLimport reads a package's HostPackage into the profile as it reads a
+     * profile's own, so a package exported from a profile brings its settings.
+     */
+    hostSettings?: Partial<ProfileSettings>;
+}
+/**
+ * An install that has been validated and unpacked in memory but has not touched
+ * the profile's files yet: `commit()` is the only step that writes. A caller
+ * that decides to refuse — the name is already installed, the user cancelled —
+ * drops the prepared install and the profile is left exactly as it was.
+ *
+ * Desktop Mudlet takes the same order (`Host::installPackage` refuses an
+ * already-installed name before it unpacks anything). Wiping first meant every
+ * later refusal destroyed the files of the very install it declined to replace,
+ * leaving a package that was listed, had items in the store, and had nothing
+ * behind it on disk.
+ */
+export interface PreparedInstall extends InstallResult {
+    /** Write the package's files into the VFS. Nothing on disk changes before this. */
+    commit(): void;
 }
 export interface InstallOptions {
     /**
@@ -19,10 +66,30 @@ export interface InstallOptions {
      * the resources the script just staged.
      */
     sourcePath?: string;
+    /**
+     * Runs a package's `config.lua` and reports what it set, or why it never
+     * finished. Supplied by the caller that owns a Lua runtime — this module
+     * stays free of one — and when it is absent the manifest is read by pattern
+     * instead, which is enough for a well-formed config.lua and cannot tell a
+     * manifest that would RAISE from one that would not.
+     */
+    readConfig?: (source: string) => {
+        ok: true;
+        info: Record<string, string>;
+    } | {
+        ok: false;
+        reason: string;
+    };
 }
+export declare function profileKeepsItsOwnDataIn(name: string): boolean;
+/** The XML files an archive's package is read from: those at its root, by name
+ *  ignoring case (QDir's default listing order), else the first at any depth. */
+export declare function archiveXmlEntries(paths: string[]): 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).
+ * Validate and unpack a Mudlet package from in-memory bytes without writing
+ * anything — the returned `commit()` performs every filesystem change.
+ * 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
@@ -36,9 +103,33 @@ export interface InstallOptions {
  * 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 preparePackageInstall(filename: string, buf: Uint8Array, vfs: ProfileVFS, opts?: InstallOptions): PreparedInstall;
+/**
+ * Prepare and immediately commit — equivalent to `preparePackageInstall(...)`
+ * followed by `commit()`, for callers with nothing to decide in between.
+ */
 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>;
+/**
+ * {@link preparePackageInstall} over a `File`, for a caller that has to decide
+ * whether to go through with the install *after* seeing the name it would land
+ * under — which `config.lua` can rename to anything, so the file's own name
+ * settles nothing. Nothing is written until `commit()`; flushing the VFS
+ * afterwards is the caller's, as with every other prepare.
+ */
+export declare function preparePackageInstallFromFile(file: File, vfs: ProfileVFS, opts?: InstallOptions): Promise<PreparedInstall>;
+/**
+ * The pattern pass over a config.lua's text: every `key = <string literal>`
+ * assignment, mapped onto the manifest's own fields and kept verbatim (keys
+ * lower-cased) as `declaredInfo`, which is what getPackageInfo answers with.
+ * Not a Lua eval — see {@link readConfigLua} for when one is used instead.
+ *
+ * Shared with the Mudlet profile import, which registers the packages a
+ * profile already has from the config.lua files left in its folder: a
+ * manifest built there without `declaredInfo` reported no info at all.
+ */
+export declare function parseConfigLuaText(text: string): Partial<PackageManifest>;
 /**
  * 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
@@ -56,9 +147,15 @@ export declare function moduleXmlAbsolutePath(manifest: PackageManifest, vfs: Pr
  * 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;
+export declare function reloadModuleFromVfs(manifest: PackageManifest, vfs: ProfileVFS, readConfig?: InstallOptions['readConfig'], 
+/** Filled in with the manifest an archive's config.lua now gives, which
+ *  may name the module differently than it was installed as. */
+out?: {
+    manifest?: PackageManifest;
+}): MudletImportResult;
 /**
- * Install a module from a path that already lives inside the profile's VFS.
+ * Prepare a module install from a path that already lives inside the profile's
+ * VFS. Nothing is written until the returned `commit()` runs.
  *
  * - 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
@@ -69,7 +166,14 @@ export declare function reloadModuleFromVfs(manifest: PackageManifest, vfs: Prof
  *
  * Throws on read/parse failures.
  */
-export declare function installModuleFromVfsPath(absolutePath: string, vfs: ProfileVFS, 
+export declare function prepareModuleInstallFromVfsPath(absolutePath: string, vfs: ProfileVFS, 
 /** Consulted first, so a module under the read-only /lua/ namespace installs
  *  as readily as one in the profile — see LuaRuntime.readBuiltinBytes. */
-readBuiltin?: (path: string) => Uint8Array | null): InstallResult;
+readBuiltin?: (path: string) => Uint8Array | null, 
+/** The same manifest reader the package path takes; see InstallOptions. */
+readConfig?: InstallOptions['readConfig']): PreparedInstall;
+/**
+ * Prepare and immediately commit — equivalent to
+ * `prepareModuleInstallFromVfsPath(...)` followed by `commit()`.
+ */
+export declare function installModuleFromVfsPath(absolutePath: string, vfs: ProfileVFS, readBuiltin?: (path: string) => Uint8Array | null): InstallResult;

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

@@ -0,0 +1,10 @@
+/**
+ * The string a desktop profile-data file holds. Bytes that are not a whole
+ * serialised `QString` are read as UTF-8 text instead, so a file written by
+ * hand (or by an older Mudlet Web export) still reads; such text cannot pass
+ * as the binary form, whose first byte is always 0x00 or 0xFF for any length
+ * a file this small can carry.
+ */
+export declare function decodeProfileData(bytes: Uint8Array): string;
+/** `text` as desktop's `writeProfileData` writes it, so desktop reads it back. */
+export declare function encodeProfileData(text: string): Uint8Array;

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

@@ -8,9 +8,17 @@ 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;
+/**
+ * The name desktop gives a `Client.GUI` package (cTelnet's
+ * handleGUIPackageInstallationAndUpgrade): the URL's last segment with the
+ * package extensions and every dot, slash and backslash taken out. It is what desktop
+ * looks for among the installed packages to tell a first install from an
+ * upgrade — so a package the player installed by hand counts as installed.
+ */
+export declare function clientGuiPackageName(url: string): string;
 export interface ClientGuiPayload {
     url: string;
-    version?: string;
+    version: string;
 }
 /**
  * Decide whether a `Client.GUI` request is a re-delivery of a package already
@@ -42,11 +50,19 @@ 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.
+ *   - a string `"<version>\n<url>"` (legacy raw telnet) — version first
+ * Mudlet acts on an offer only when it carries both a version and a URL
+ * (handleGUIPackageInstallationAndUpgrade returns on either being empty), in
+ * either shape, so neither a bare URL nor a half pair is salvaged: the version
+ * is what tells a re-delivery from an upgrade, and without it there is nothing
+ * to record against the install.
  */
 export declare function parseClientGuiPayload(value: unknown): ClientGuiPayload | null;
+/**
+ * Whether a `Client.GUI` payload declines the built-in starter UI —
+ * `{"baseui": false}`, which Mudlet (cTelnet::parseGUIBaseUiDeclinedFromJSON)
+ * also takes spelled as the string "false", trimmed and in any case, since some
+ * games' GMCP serializers can only write strings. Only the JSON object form can
+ * decline: the raw telnet form carries a version and a URL and nothing else.
+ */
+export declare function clientGuiDeclinesBaseUi(value: unknown): boolean;

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

@@ -0,0 +1,45 @@
+import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
+/**
+ * A zip archive read entry by entry, the way libzip hands it to brimworks'
+ * lua-zip (what desktop's `zip` global is).
+ *
+ * fflate's `unzipSync` is all or nothing: one entry that will not inflate and
+ * the whole archive throws, it never checks a CRC, and it keys entries by name,
+ * so two with the same name collapse into one. Desktop's `unzip()` reports each
+ * entry it cannot read and carries on with the rest, so it needs an archive it
+ * can walk by index and read one entry of at a time.
+ */
+export interface ZipEntry {
+    /** The name as stored (Latin-1 unless the entry flags UTF-8, as fflate reads it). */
+    name: string;
+    /** The uncompressed size the archive records. */
+    size: number;
+    /** The entry's bytes, or throws with the reason they cannot be had. */
+    read(): Uint8Array;
+}
+/** The archive's entries in central-directory order, or null when the bytes
+ *  are not a zip this can read. */
+export declare function readZipEntries(bytes: Uint8Array): ZipEntry[] | null;
+/**
+ * An entry name's path components inside the folder it unpacks into, with "."
+ * and ".." resolved, or null when the name is absolute or climbs out of it.
+ * Both separators count, as on Windows, which honours either: desktop's own
+ * `unzip()` reads names the same way, so an archive is judged identically
+ * whichever platform made it.
+ */
+export declare function zipEntryComponents(name: string): string[] | null;
+/** `path` with any symbolic links standing at it followed to what they name,
+ *  so a folder reached through a link can be written into. Left as it is when
+ *  it is not a link, or the chain is too long to be anything but a loop. */
+export declare function resolveLinkedDirectory(vfs: ProfileVFS, path: string): string;
+/**
+ * Why the archive's entries cannot all be unpacked into `destDir`, or null when
+ * they can. Checked over every entry before anything is written, so a refused
+ * archive leaves nothing of itself behind:
+ *  - a name that resolves outside `destDir`;
+ *  - a symbolic link already inside `destDir` that an entry would pass through
+ *    or write over, which would carry it outside.
+ * `destDir` itself may be reached through a link: that is where the caller
+ * asked for the files to go.
+ */
+export declare function zipExtractionProblem(vfs: ProfileVFS, destDir: string, names: string[]): string | null;

package/dist-lib/index.d.ts

@@ -1,11 +1,16 @@
 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 { getBrand, isBrandedMode, getThemeChoices, isLightTheme, DEFAULT_BRAND, STOCK_THEMES, type BrandConfig, type BrandMudTarget, type BrandPackage, type BrandTheme, type BrandCommand, type BrandToolbarButton, type BrandToolbarConfig, type BrandToolbarContext, type StockToolbarButton, type LandingProps, } from "./branding";
+export { hostCommands as commands } from "./ui/commands/hostCommands";
+export type { HostCommand, HostCommandRequest } from "./ui/commands/hostCommands";
+export type { MenuAction, MenuNode, MenuSeparator, MenuSubmenu, PlacedCommand, TopMenu, } from "./ui/menu/menuModel";
+export type { ToolbarButtonItem, ToolbarCustomItem, ToolbarItem, ToolbarSplitItem, } from "./ui/menu/toolbarModel";
+export { isPackageRemovable } from "./import/defaultPackages";
 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 type { MudConnection, ConnectionMode, ProfileSettings } from "./storage/schema";
 export { EventBus } from "./core/EventBus";
 export { ScriptingAPI } from "./scripting/ScriptingAPI";
 export { MudSession } from "./mud/MudSession";
@@ -23,7 +28,6 @@ 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";