@mudlet/mudlet-web 0.3.0 → 0.4.0

package/dist-lib/scripting/lua/bindings/map.d.ts

@@ -1,14 +1,2 @@
 import type { BindingContext } from './context';
-/**
- * Mudlet's map API: the 2D view, room and area CRUD, exits, doors, custom
- * lines, labels, highlights, selection, per-room styling, user data, and the
- * mapInfo / context-menu extension points.
- *
- * This is by far the widest binding surface in the runtime — it mirrors
- * Mudlet's map Lua API essentially one-for-one — so it lives in its own
- * module. The heavy lifting is all in MapStore behind `api.map`; the code
- * here is argument coercion and Mudlet's return-shape conventions (notably
- * alse where Mudlet returns nil, which Bridge.lua unpacks into the
- * documented (nil, errMsg) multi-returns).
- */
 export declare function installMapBindings({ lua, api, vfs, channel, emitEvent, unregisterCb, pushJsValue, registerRawGlobal, evaluateMapInfo, evaluateExitWeightFilter, }: BindingContext): void;

package/dist-lib/scripting/lua/utf8Patterns.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Lua patterns compiled to JavaScript regular expressions, for the `utf8`
+ * module's find/match/gmatch/gsub.
+ *
+ * Mudlet links the C `luautf8` (starwing) for `utf8`; the browser has no such
+ * library, so mudix bundles Stepets' pure-Lua `utf8.lua`. That shim is correct
+ * enough for the sub/len/char half of the module but not for the pattern half,
+ * in two ways that both matter:
+ *
+ *   * **Its character classes are ASCII.** `classMatchGenerator` writes `%a` as
+ *     the two ranges A-Z and a-z, so `caf%a` does not match `café` — while
+ *     luautf8 decides every class from Unicode tables. A pattern class is
+ *     supposed to be the one part of `utf8.*` that is not byte-wise.
+ *   * **It is slow enough to be a hazard.** One `find` over a 35-character line
+ *     costs ~35,000 Lua VM instructions — it walks the subject a character at a
+ *     time through a generated closure chain. `replaceAll` calls it once per
+ *     replacement, on trigger output.
+ *
+ * So the pattern is translated to a JS `RegExp` and matched natively, with the
+ * Lua implementation kept as the fallback for the constructs that have no
+ * regex equivalent (`%b`, `%f`, position captures, back-references — see
+ * `compileLuaPattern` returning null). Nothing gets worse for those; everything
+ * else gets Unicode classes and native speed.
+ *
+ * Positions cross the boundary as Lua sees them: 1-based, inclusive, and
+ * counted in CODE POINTS. JS regex indices are UTF-16 code units, so a subject
+ * holding anything outside the BMP needs the map `codePointOffsets` builds.
+ */
+export type CompiledLuaPattern = {
+    re: RegExp;
+    /** `^` at the start of a Lua pattern anchors at `init`, not at the start of
+     *  the subject — which is a sticky regex, not a `^`. */
+    anchored: boolean;
+    captures: number;
+};
+/** Compile a Lua pattern, or null when it uses something a regex cannot express
+ *  (`%b`, `%f`, a position capture, a back-reference) and the caller should fall
+ *  back to the Lua implementation. */
+export declare function compileLuaPattern(pattern: string): CompiledLuaPattern | null;
+export type LuaFindResult = 
+/** The pattern needs a construct a regex cannot express — use the Lua one. */
+{
+    kind: 'unsupported';
+} | {
+    kind: 'nomatch';
+}
+/** `start`/`end` are Lua positions: 1-based, inclusive, in code points. An
+ *  empty match reports `end === start - 1`, as `string.find` does. */
+ | {
+    kind: 'match';
+    start: number;
+    end: number;
+    captures: string[];
+};
+/**
+ * `string.find` over UTF-8, natively. `init` follows Lua: 1-based, negative
+ * counts from the end, and past the end of the subject there is no match.
+ */
+export declare function findLuaPattern(subject: string, pattern: string, init: number, plain: boolean): LuaFindResult;

package/dist-lib/storage/index.d.ts

@@ -1,4 +1,4 @@
-export { type AppSchema, type MudConnection, type ConnectionMode, type ClientSettings, type ProfileSettings, type MapperSettings, type MapInfoBgColor, type ProtocolSettings, type BooleanProtocolKey, type Theme, type OutputFontSource, APP_DEFAULTS, PROFILE_DEFAULTS, MAPPER_DEFAULTS, MAP_INFO_BG_DEFAULT, PROTOCOL_DEFAULTS, WS_SUBPROTOCOL_CHOICES, DEFAULT_PROXY_URL, connectionUrl, connectionDisplayAddr, connectionSecureTransport, selectProfileField } from './schema';
+export { type AppSchema, type MudConnection, type ConnectionMode, type ClientSettings, type ProfileSettings, type MapperSettings, type PlayerMarkerSettings, type MapInfoBgColor, type ProtocolSettings, type BooleanProtocolKey, type Theme, type OutputFontSource, APP_DEFAULTS, PROFILE_DEFAULTS, MAPPER_DEFAULTS, PLAYER_MARKER_DEFAULTS, MAP_INFO_BG_DEFAULT, PROTOCOL_DEFAULTS, WS_SUBPROTOCOL_CHOICES, DEFAULT_PROXY_URL, connectionUrl, connectionDisplayAddr, connectionSecureTransport, connectionNameTaken, uniqueConnectionName, effectiveProxyUrl, proxyCanInspectCertificates, selectProfileField } from './schema';
 export { useAppStore } from './appStore';
 export { initCrossTabSync } from './crossTabSync';
 export { ConnectionIdContext, useConnectionId, useProfileField, useClientField, useEffectiveTheme } from './hooks';

package/dist-lib/storage/persistentStorage.d.ts

@@ -0,0 +1,10 @@
+/** Whether this browser can be asked at all. */
+export declare function persistenceSupported(): boolean;
+/** Whether the origin's storage is already exempt from eviction. Never throws. */
+export declare function isPersisted(): Promise<boolean>;
+/** Ask the browser to exempt this origin's storage from eviction, at most once
+ *  per page session. Resolves to whether storage is persistent afterwards —
+ *  `false` on refusal or on a browser without the API. Never throws. */
+export declare function ensurePersistentStorage(): Promise<boolean>;
+/** Test seam: forget the one-per-session attempt. */
+export declare function resetPersistenceRequest(): void;

package/dist-lib/storage/schema.d.ts

@@ -44,6 +44,35 @@ export interface MudConnection {
      *  already ship them — Mudlet installs those only into brand-new profiles, so
      *  their absence in an imported profile is a real choice, not a gap to fill. */
     mudletImported?: boolean;
+    /** ISO timestamp stamped by `addConnection` when the profile is created.
+     *  **Absent means the profile predates this field**, which is exactly what
+     *  it's for: it stands in for Mudlet's `experiencedMudletPlayer()` (any
+     *  profile folder older than 6 months) so the starter UI only reaches
+     *  profiles created after it shipped, and never lands on top of a layout
+     *  someone already built. See `stockDefaults`. */
+    createdAt?: string;
+    /** Connect to the game over TLS — Mudlet's `mSslTsl` / the connection
+     *  dialog's "secure connection" checkbox. Meaningful in `mud` (proxy) mode
+     *  only: the browser cannot wrap a raw socket itself, so the proxy performs
+     *  the handshake on our behalf (`&tls=1`). In `websocket` mode the URL
+     *  scheme already decides it, so this flag is ignored there. */
+    tls?: boolean;
+    /** Tolerate an expired peer certificate (Mudlet's `mSslIgnoreExpired`). */
+    sslIgnoreExpired?: boolean;
+    /** Tolerate a self-signed peer certificate (Mudlet's `mSslIgnoreSelfSigned`). */
+    sslIgnoreSelfSigned?: boolean;
+    /** Tolerate *every* certificate fault, hostname mismatch included — this
+     *  gives up the authentication half of TLS and leaves only encryption
+     *  (Mudlet's `mSslIgnoreAll`, labelled "unsecure" in its UI).
+     *
+     *  ⚠ All three are honoured only by the Node proxy. The Cloudflare Worker
+     *  runtime's `connect()` exposes no way to inspect or override certificate
+     *  validation, so a worker-backed profile silently ignores them. */
+    sslIgnoreAll?: boolean;
+    /** The plaintext port in use before an MSSP-advertised TLS upgrade, kept so
+     *  a failed upgrade can be reverted in one click. Cleared once a secure
+     *  connection has actually worked. */
+    preTlsPort?: number;
     /** Free-text profile description (Mudlet's profile "description" field, read/
      *  written by getProfileInformation / setProfileInformation /
      *  clearProfileInformation). Lives on the connection record — not the VFS-
@@ -105,6 +134,22 @@ export interface ProfileSettings {
      *  installed automatically). Disable to ignore those requests. Per-profile
      *  so each MUD is trusted independently. */
     allowMudPackageInstall?: boolean;
+    /** When true (default — treat `undefined` as true), MUDs may drive playback
+     *  through the GMCP `Client.Media` messages (MCMP): files named by the
+     *  server are downloaded into the profile's `media/` folder and played.
+     *  Disable to ignore those messages outright — nothing is fetched and
+     *  nothing plays, which is what separates this from `muteMediaGame` (that
+     *  one still downloads and plays, just silently). Mudlet's
+     *  `mAcceptServerMedia` / "Allow server to download and play media", and
+     *  like Mudlet it gates GMCP only — MSP has its own switch in
+     *  `protocols.msp`. Per-profile, so each MUD is trusted independently. */
+    allowServerMedia?: boolean;
+    /** When true (default), a server that advertises a TLS port via MSSP prompts
+     *  once to switch to it. Declining sets this false so the offer never
+     *  reappears for this profile. Mudlet calls it `mAskTlsAvailable`
+     *  ("Allow secure connection reminder"), settable from Lua via
+     *  `setProfileConfig("askTlsAvailable", …)`. */
+    askTlsAvailable?: boolean;
     showTimestamps: boolean;
     fontSize: number;
     outputBackground: string;
@@ -354,6 +399,11 @@ export interface MapperSettings {
     backgroundColor?: string;
     /** renderer.settings.lineColor — exit color, hex (#rrggbb). */
     lineColor?: string;
+    /** Mudlet `TMap::mShowDefaultArea` — whether the unnamed catch-all area
+     *  rooms land in before they are filed anywhere is offered in the area
+     *  list. Set from Lua by `setDefaultAreaVisible`; read by MapPanel's area
+     *  dropdown. Visible unless turned off. */
+    showDefaultArea?: boolean;
     /** renderer.settings.gridEnabled — background grid overlay. */
     gridEnabled?: boolean;
     /** renderer.settings.lodEnabled — level-of-detail for very dense planes.
@@ -375,12 +425,50 @@ export interface MapperSettings {
      *  until you zoom in further. Measured against what the current viewport
      *  materialises, not the whole level. */
     lodHitTestBudget?: number;
+    /** renderer.settings.playerMarker — styling for the ring drawn on the
+     *  player's room. */
+    playerMarker?: PlayerMarkerSettings;
+}
+/** Styling for the player-position marker — the ring the renderer draws on
+ *  whichever room `updatePositionMarker()` was last given.
+ *
+ *  Mirrors the renderer's `PlayerMarkerStyle` one field at a time, except for
+ *  the dash pattern: the renderer takes a `number[]`, but a pair of scalars
+ *  patches independently and survives the JSON round-trip more simply, so
+ *  {@link dashLength}/{@link dashGap} are recombined into `[len, gap]` in
+ *  applyMapperSettings. Every field is optional — unset ones fall through to
+ *  the renderer's own createSettings() defaults. */
+export interface PlayerMarkerSettings {
+    /** Outline colour, hex (#rrggbb). */
+    strokeColor?: string;
+    /** Outline opacity, 0..1. */
+    strokeAlpha?: number;
+    /** Fill colour, hex (#rrggbb). Only visible when {@link fillAlpha} > 0. */
+    fillColor?: string;
+    /** Fill opacity, 0..1. 0 leaves the marker a hollow ring. */
+    fillAlpha?: number;
+    /** Outline thickness in map units (roughly 0.01–0.3). */
+    strokeWidth?: number;
+    /** Multiplier on `roomSize`. 1.0 makes the marker exactly room-sized;
+     *  the renderer's default (1.7) rings the room from outside. */
+    sizeFactor?: number;
+    /** Dash length in map units — only drawn when {@link dashEnabled}. */
+    dashLength?: number;
+    /** Gap between dashes in map units — only drawn when {@link dashEnabled}. */
+    dashGap?: number;
+    /** Dash the outline instead of drawing it solid. */
+    dashEnabled?: boolean;
+    /** Follow {@link MapperSettings.roomShape} instead of always drawing a
+     *  circle. Rectangle/rounded-rectangle rooms only; a circle room is
+     *  already a circle. */
+    matchRoomShape?: boolean;
 }
 /** Mirrors the renderer's createSettings() defaults so the Settings modal can
  *  show meaningful placeholder/fallback values when a field is still
  *  undefined. MapPanel itself does NOT use these — it only forwards fields
  *  that the user has actually set, so the renderer's own defaults stay in
  *  charge for anything untouched. */
+export declare const PLAYER_MARKER_DEFAULTS: Required<PlayerMarkerSettings>;
 export declare const MAPPER_DEFAULTS: Required<MapperSettings>;
 /** RGBA channels (0..255) for the map-info widget background. Stored in the
  *  profile `config` bag under `mapInfoColor` (Mudlet's `setConfig` key) and
@@ -427,6 +515,23 @@ export interface PackageManifest {
     xmlVfsPath?: string;
     /** Source filename (e.g. "GenericMapper.mpackage"), useful for display. */
     sourceFile?: string;
+    /** Absolute VFS path the install was given, when it came from one. This is
+     *  what `getModulePath` answers with: the file the user picked, not whatever
+     *  was unpacked out of it — a script uses it to reinstall, or to point the
+     *  user back at their own file, and neither works with an internal path. */
+    sourcePath?: string;
+    /**
+     * Exactly what the package's `config.lua` declared, keys lower-cased,
+     * unmapped and unaugmented.
+     *
+     * This is what `getPackageInfo`/`getModuleInfo` answer with, so it has to
+     * stay the package author's own set: Mudlet reports what the manifest said
+     * and nothing more, which means a package that shipped no config.lua has no
+     * info at all rather than a table of things mudix worked out for itself
+     * (the derived name, the install timestamp). Absent when there was no
+     * config.lua to read.
+     */
+    declaredInfo?: Record<string, string>;
     /** When the package was installed via a remote URL (e.g. a `Client.GUI`
      *  GMCP message), records the originating URL so subsequent install
      *  requests for the same URL can be deduplicated against this manifest
@@ -484,6 +589,19 @@ export interface TriggerNode extends BaseNode {
     multiline: boolean;
     delta: number;
     isFilter: boolean;
+    /**
+     * Session-scoped: created by `tempComplexRegexTrigger`, which needs a real
+     * trigger node rather than the flat temp-trigger primitive because it can
+     * ask for multiline-AND, a filter chain, a fire length, a line delta — all
+     * of them properties of a node in the tree — and can be named as another
+     * trigger's parent.
+     *
+     * Not persisted (see serializeProfileData), and neither is anything hanging
+     * under it: a permanent trigger parented to a temporary one goes when its
+     * parent does, so saving it would restore a child pointing at a parent that
+     * no longer exists.
+     */
+    temporary?: boolean;
     highlight?: {
         fg?: string;
         bg?: string;
@@ -626,13 +744,57 @@ export declare const APP_DEFAULTS: AppSchema;
  */
 export declare function selectProfileField<K extends keyof ProfileSettings>(s: Pick<AppSchema, 'connectionProfile'>, connectionId: string | null, key: K): ProfileSettings[K];
 export declare function connectionUrl(c: MudConnection, userProxyUrl?: string): string;
+/** The proxy a `mud`-mode connection will actually dial, applying the same
+ *  precedence as {@link connectionUrl}: per-connection > user's own > brand >
+ *  built-in default. */
+export declare function effectiveProxyUrl(c: MudConnection, userProxyUrl?: string): string;
+/**
+ * Whether a proxy can inspect the game's certificate — and therefore whether
+ * the "accept expired / self-signed / all" options mean anything.
+ *
+ * Only the Node proxy can: it uses `tls.connect` and reads the peer certificate.
+ * A Cloudflare Worker cannot, because `cloudflare:sockets` `connect()` exposes
+ * no certificate and no way to waive a validation failure — the options would be
+ * silently ignored, so the UI disables them instead of pretending.
+ *
+ * Recognised by the `workers.dev` hostname, which covers the built-in default
+ * proxy and anything deployed from `worker/`. A Worker on a custom domain can't
+ * be told apart from a Node proxy up front; that case is corrected at runtime by
+ * the `certInspection: false` flag the proxy reports on `tls.established`.
+ */
+export declare function proxyCanInspectCertificates(proxyUrl: string): boolean;
 export declare function connectionDisplayAddr(c: MudConnection): string;
 /** Whether the connection's link to the *game server* is TLS-encrypted — the
  *  signal reported as the NEW-ENVIRON `TLS` variable. In `websocket` mode the
  *  browser connects straight to the game, so a `wss://` URL is end-to-end TLS.
- *  In `mud` (proxy) mode the browser↔proxy hop may be `wss://`, but the proxy
- *  reaches the MUD over a raw TCP telnet socket (`net.connect`, no upstream
- *  TLS) — so the server's inbound connection is always plaintext and this is
- *  false regardless of the proxy URL scheme. */
+ *  In `mud` (proxy) mode the browser↔proxy hop being `wss://` says nothing about
+ *  the proxy↔game hop: that leg is a plaintext telnet socket unless `tls` is set,
+ *  which makes the proxy perform a TLS handshake with the game instead. */
 export declare function connectionSecureTransport(c: MudConnection): boolean;
+/**
+ * Whether `name` is already some other profile's, ignoring case.
+ *
+ * Case-insensitively, because that is how the scripting API resolves a profile
+ * name (`getProfileInformation("ACHAEA")` finds the Achaea profile — Mudlet
+ * looks the name up as a folder and the platforms it runs on mostly have
+ * case-insensitive ones). Two profiles differing only in case would make those
+ * calls pick between them arbitrarily.
+ *
+ * `exceptId` is the profile being edited, so renaming one to its own name is
+ * not a clash.
+ */
+export declare function connectionNameTaken(name: string, connections: MudConnection[], exceptId?: string): boolean;
+/**
+ * `name` if no other profile has it, otherwise the first free `name (2)`,
+ * `name (3)`, … — the same shape Mudlet gives a profile copied over an existing
+ * one.
+ *
+ * A last line of defence for the paths that create a profile without a form to
+ * validate: importing a Mudlet folder or zip, seeding a brand's profile, or
+ * starting a bundled game. Those must not fail on a name clash, but they must
+ * not produce two profiles sharing a name either — `getProfiles()` is keyed by
+ * name and would silently return only one of them, and every name-addressed
+ * script API would resolve to whichever came first.
+ */
+export declare function uniqueConnectionName(name: string, connections: MudConnection[], exceptId?: string): string;
 export {};