@mudlet/mudlet-web 0.3.1 → 0.4.0

package/README.md

@@ -78,6 +78,12 @@ yarn start    # listens on ws://localhost:3001 by default
 
 Then choose **MUD (host:port)** mode when creating a connection. Servers that expose a native WebSocket endpoint don't need the proxy — use **WebSocket** mode and point it straight at the `ws(s)://` URL.
 
+### Already play in desktop Mudlet?
+
+Your existing profile comes across whole — triggers, aliases, scripts, keybindings, buttons, saved variables, installed packages, your map, and your colours and fonts. **[docs/help/migrating.md](docs/help/migrating.md)** walks through it: where the profile folder lives on each platform, the three ways in (copy a folder, import a `.zip`, or link the folder and keep using both), what doesn't come across, and how to export back to desktop Mudlet.
+
+The same guide — plus [connecting](docs/help/connecting.md), [storage and backups](docs/help/storage.md), and [browsers and limits](docs/help/browsers.md) — is built into the app behind the **Help** button, on the start screen and in the toolbar.
+
 ## 🛠️ Development
 
 ```bash
@@ -145,6 +151,8 @@ Lua scripts and packages that Mudlet Web merely *runs* (your profile scripts, in
 
 Mudlet Web also bundles **Bitstream Vera Sans Mono** (`src/assets/fonts/bitstream-vera-sans-mono/`) as the default console output and command-line font, matching Mudlet's own default console typeface. It's under the separate, permissive [Bitstream Vera license](src/assets/fonts/bitstream-vera-sans-mono/COPYRIGHT.TXT) (free redistribution and embedding; just don't sell the font standalone or rename a modified copy while keeping "Bitstream"/"Vera" in the name).
 
+**Ubuntu** and **Ubuntu Mono** (`src/assets/fonts/ubuntu/`, regular/bold/italic/bold-italic each) are bundled for the same reason: Mudlet registers both families into Qt's font database at startup, so packages written for Mudlet — including the bundled `mudlet-base-ui` — ask for them by name for labels, headers, and miniconsole stylesheets. They're under the [Ubuntu Font Licence 1.0](src/assets/fonts/ubuntu/LICENCE.txt) (free redistribution and embedding; modified copies must be renamed).
+
 <div align="center">
 <sub>Built with React, TypeScript, and a lot of WebAssembly. Happy MUDding. 🐉</sub>
 </div>

package/dist-lib/assets/qt-resources/index.d.ts

@@ -0,0 +1,16 @@
+/** Whether `path` uses Qt's resource syntax. Mudlet also accepts the `qrc:///`
+ *  URL form for the same bundle. */
+export declare function isQtResourcePath(path: string): boolean;
+/**
+ * A `:/…` path as a URL usable anywhere a browser wants one — an `<img>` src, a
+ * CSS `url(...)`, a background image. Null when the resource isn't vendored.
+ */
+export declare function qtResourceUrl(path: string): string | null;
+/**
+ * The bytes behind a `:/…` path, decoded synchronously. Null when the resource
+ * isn't vendored, or the entry isn't a base64 data URI (which would mean the
+ * bundler emitted it as a file instead of inlining it).
+ */
+export declare function qtResourceBytes(path: string): Uint8Array | null;
+/** Every vendored resource path, in Qt form. For diagnostics and tests. */
+export declare function qtResourcePaths(): string[];

package/dist-lib/branding.d.ts

@@ -70,7 +70,7 @@ export declare const STOCK_THEMES: {
 /** Ids of the stock toolbar buttons, for `BrandToolbarConfig.hide`.
  *  `connection` is the Reconnect/Disconnect pair; `close` closes the profile;
  *  `record` toggles Mudlet-format replay recording. */
-export type StockToolbarButton = 'scripts' | 'files' | 'map' | 'logs' | 'docs' | 'reportBug' | 'settings' | 'record' | 'connection' | 'close';
+export type StockToolbarButton = 'scripts' | 'files' | 'map' | 'logs' | 'docs' | 'help' | 'reportBug' | 'settings' | 'record' | 'connection' | 'close';
 /** What a brand toolbar button can do when clicked. */
 export interface BrandToolbarContext {
     connectionId: string;

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

@@ -6,5 +6,5 @@ export declare function useMudSession(options?: MudSessionOptions): {
     passwordMode: boolean;
     connect: (url: string) => void;
     disconnect: () => void;
-    send: (text: string, echo?: boolean) => void;
+    send: (text: string, echo?: boolean, isGameCommand?: boolean) => void;
 };

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

@@ -5,6 +5,8 @@ export interface UseStickyOutputOptions {
     maxElements?: number;
     splitViewThreshold?: number;
     showTimestamps?: boolean;
+    /** See OutputHandlerOptions.followTail. Omit for a normal scrollback. */
+    followTail?: () => boolean;
 }
 export interface UseStickyOutputResult {
     outputRef: React.RefObject<HTMLDivElement | null>;
@@ -14,4 +16,4 @@ export interface UseStickyOutputResult {
     scrollToBottom: () => void;
     controls: OutputRendererControls | null;
 }
-export declare function useStickyOutput(source: MessageSource | null, { stickyLines, maxElements, splitViewThreshold, showTimestamps, }?: UseStickyOutputOptions): UseStickyOutputResult;
+export declare function useStickyOutput(source: MessageSource | null, { stickyLines, maxElements, splitViewThreshold, showTimestamps, followTail, }?: UseStickyOutputOptions): UseStickyOutputResult;

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

@@ -15,6 +15,13 @@ interface DefaultPackage {
  * `mudlet-mapper.xml` row of `defaultScripts` in mudlet.cpp.
  */
 export declare const IRE_MAPPER_GAMES: string[];
+/**
+ * Games whose own bundled loader installs a full interface, so the starter UI is
+ * not preinstalled for them — it would only fight the game's GUI for the same
+ * screen space. Mirrors the `providesOwnUi` entries of `TGameDetails.h`'s
+ * `scmDefaultGames`, including each game's `alternateHostUrls`.
+ */
+export declare const GAMES_WITH_OWN_UI: string[];
 /** Every bundled default, whatever the host — for tests and tooling. */
 export declare const ALL_DEFAULTS: DefaultPackage[];
 /**
@@ -29,8 +36,32 @@ export declare const ALL_DEFAULTS: DefaultPackage[];
  * Exactly one mapper, always. `centerview()` is the only thing that moves the
  * map view and only a mapper calls it, so a profile with no mapper never follows
  * the player — and two mappers would both fire on the same movement.
+ *
+ * The starter UI is the one conditional pick: Mudlet skips it for players who
+ * aren't new (`experiencedMudletPlayer()` — any profile folder older than six
+ * months) because "veterans will have their own layouts already", and for games
+ * whose own loader installs a full interface. mudix has no profile-age signal to
+ * mirror the first, so `createdAt` stands in for it — see {@link isNewProfile}.
+ */
+export declare function stockDefaults(host?: string, conn?: {
+    createdAt?: string;
+}): DefaultPackage[];
+/**
+ * Whether a profile is new enough to be offered the starter UI.
+ *
+ * `addConnection` stamps `createdAt` on every profile it creates, so a profile
+ * without one was made before the field existed — i.e. someone has already been
+ * using it, quite possibly with a layout of their own. That's mudix's stand-in
+ * for Mudlet's "no profile folder older than six months" check: it errs the safe
+ * way, since dropping a dock, gauges and a chat window onto an established
+ * profile is far more disruptive than withholding them from a new one.
+ *
+ * No profile at all (tooling, a preview, `stockDefaults()` with no argument)
+ * counts as new — nothing established is at risk.
  */
-export declare function stockDefaults(host?: string): DefaultPackage[];
+export declare function isNewProfile(conn?: {
+    createdAt?: string;
+}): boolean;
 /** A default or brand package as the install loop sees it. */
 export type InstallablePackage = DefaultPackage & {
     removable?: boolean;
@@ -42,7 +73,9 @@ export type InstallablePackage = DefaultPackage & {
  * them — `[]` preinstalls nothing, and a brand shipping its own mapper simply
  * doesn't list ours. Unset means no opinion: the stock defaults for this game.
  */
-export declare function resolveDefaultPackages(brandPackages: InstallablePackage[] | undefined, host?: string): InstallablePackage[];
+export declare function resolveDefaultPackages(brandPackages: InstallablePackage[] | undefined, host?: string, conn?: {
+    createdAt?: string;
+}): InstallablePackage[];
 /** Hostname `stockDefaults` matches its game lists against, lowercased. */
 export declare function connectionHost(conn: {
     mode?: string;

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

@@ -0,0 +1,71 @@
+import { type SerializeInput } from './mudletXmlExport';
+export interface PackageExportMeta {
+    /** Package identity — also the XML filename and the install directory name. */
+    name: string;
+    author?: string;
+    title?: string;
+    description?: string;
+    version?: string;
+    helpURL?: string;
+    dependencies?: string[];
+    /** Icon filename as stored under `.mudlet/Icon/`; empty when there's no icon. */
+    icon?: string;
+    /** ISO-8601 creation stamp. Passed in rather than read from the clock so the
+     *  builders stay pure and testable. */
+    created: string;
+}
+/** Strip characters that are illegal in zip entry / filesystem names. */
+export declare function sanitizePackageName(raw: string, fallback?: string): string;
+/**
+ * Mudlet's `config.lua`: every key is written even when empty, in the order
+ * dlgPackageExporter emits them, with `created` as a plain quoted string.
+ */
+export declare function buildConfigLua(meta: PackageExportMeta): string;
+interface TreeNode {
+    id: string;
+    parentId: string | null;
+    isGroup: boolean;
+}
+/** Every descendant id of `rootId`, excluding the root itself. */
+export declare function descendantIds<T extends TreeNode>(nodes: T[], rootId: string): string[];
+/**
+ * Reduce a category's nodes to the selected ones, re-parenting any node whose
+ * parent wasn't selected to the top level.
+ *
+ * Mudlet drops such a node instead: its exporter walks from the roots and never
+ * reaches a selected child under an unselected group, so checking one trigger
+ * inside a folder exports nothing. Re-rooting keeps the item and makes the
+ * selection mean what it looks like; a fully-checked subtree serializes
+ * identically either way.
+ */
+export declare function selectExportNodes<T extends TreeNode>(nodes: T[], selected: ReadonlySet<string>): T[];
+/** Ids of every category, as the modal tracks them. */
+export interface PackageSelection {
+    scripts: ReadonlySet<string>;
+    aliases: ReadonlySet<string>;
+    triggers: ReadonlySet<string>;
+    timers: ReadonlySet<string>;
+    keys: ReadonlySet<string>;
+    buttons: ReadonlySet<string>;
+}
+/** Apply a selection across all six categories at once. */
+export declare function selectExportInput(all: SerializeInput, selection: PackageSelection): SerializeInput;
+export declare function countSelected(input: SerializeInput): number;
+export interface PackageExportInput {
+    meta: PackageExportMeta;
+    /** Already filtered through `selectExportInput`. */
+    nodes: SerializeInput;
+    /** Extra files to carry, keyed by path relative to the package root. */
+    assets?: Record<string, Uint8Array>;
+    /** Icon bytes; stored at `.mudlet/Icon/<meta.icon>` when `meta.icon` is set. */
+    iconBytes?: Uint8Array;
+}
+/**
+ * Build the package's file map. `config.lua` and `<name>.xml` are written last
+ * and always win: an asset list harvested from an installed package directory
+ * contains the *previous* pair, and letting those through would ship stale
+ * metadata alongside the freshly serialized items.
+ */
+export declare function buildPackageEntries(input: PackageExportInput): Record<string, Uint8Array>;
+export declare function buildPackageZip(input: PackageExportInput): Uint8Array;
+export {};

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

@@ -69,4 +69,7 @@ export declare function reloadModuleFromVfs(manifest: PackageManifest, vfs: Prof
  *
  * Throws on read/parse failures.
  */
-export declare function installModuleFromVfsPath(absolutePath: string, vfs: ProfileVFS): InstallResult;
+export declare function installModuleFromVfsPath(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;