@mudlet/mudlet-web 0.3.0

package/dist-lib/ui/windows/panels/HtmlPanel.d.ts

@@ -0,0 +1,27 @@
+import type { WindowManager } from '../WindowManager';
+import type { LabelManager } from '../../labels/LabelManager';
+import type { CommandLineManager } from '../../cmdline/CommandLineManager';
+import type { ScrollBoxManager } from '../../scrollbox/ScrollBoxManager';
+interface HtmlPanelProps {
+    id: string;
+    manager: WindowManager;
+    labels?: LabelManager;
+    cmdLines?: CommandLineManager;
+    scrollBoxes?: ScrollBoxManager;
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    backgroundImage?: {
+        url: string;
+        mode: number;
+    };
+    cmdLineEnabled?: boolean;
+    cmdLineStyleSheet?: string;
+    cmdLineValue?: string;
+    cmdLineValueSeq?: number;
+}
+export declare function HtmlPanel({ id, manager, labels, cmdLines, scrollBoxes, backgroundColor, backgroundImage, cmdLineEnabled, cmdLineStyleSheet, cmdLineValue, cmdLineValueSeq }: HtmlPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/LuaEditor.d.ts

@@ -0,0 +1,14 @@
+interface Props {
+    value: string;
+    onChange: (value: string) => void;
+    /** Invoked when the user hits Ctrl/Cmd+S or Ctrl/Cmd+Enter inside the editor. */
+    onSave?: () => void;
+    /** Jump request from the parent (e.g. error log click). Bump `revision` to
+     *  re-trigger a jump even when `line` is unchanged. */
+    gotoLine?: {
+        line: number;
+        revision: number;
+    } | null;
+}
+export declare function LuaEditor({ value, onChange, onSave, gotoLine }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/MapPanel.d.ts

@@ -0,0 +1,8 @@
+import type { WindowManager } from '../WindowManager';
+interface MapPanelProps {
+    id: string;
+    manager: WindowManager;
+    connectionId: string;
+}
+export declare function MapPanel({ id, manager, connectionId }: MapPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/PackageRepositoryModal.d.ts

@@ -0,0 +1,18 @@
+import { type PackageRepoEntry } from '../../../import/packageRepository';
+interface Props {
+    /** Names of packages already installed on this profile — used to flag matching entries. */
+    installedNames: Set<string>;
+    /** Active proxy URL, used to retry catalog/download fetches when a direct fetch fails CORS. */
+    proxyUrl?: string;
+    onClose: () => void;
+    /**
+     * Called after the user clicks Install on an entry. The caller fetches/installs/commits
+     * to the store — keeping that flow in ScriptEditorPanel means we don't need to plumb the
+     * VFS, scripting engine, or store mutators through the modal.
+     *
+     * Must throw on failure so the modal can surface the error inline.
+     */
+    onInstall: (entry: PackageRepoEntry, bytes: Uint8Array) => Promise<void>;
+}
+export declare function PackageRepositoryModal({ installedNames, proxyUrl, onClose, onInstall }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/ScriptEditorPanel.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import type { MudSession } from '../../../mud/MudSession';
+import type { ProfileVFS } from '../../../scripting/vfs/ProfileVFS';
+import type { ScriptingEngine } from '../../../scripting/ScriptingEngine';
+import './ScriptEditorPanel.css';
+type Category = 'scripts' | 'aliases' | 'triggers' | 'timers' | 'keys' | 'buttons' | 'packages' | 'errors' | 'variables';
+type EditCategory = Exclude<Category, 'errors' | 'packages' | 'variables'>;
+interface ScriptEditorPanelProps {
+    connectionId: string;
+    session: MudSession;
+    vfs: ProfileVFS | null;
+    scriptingEngineRef?: React.RefObject<ScriptingEngine | null>;
+    initialListWidth?: number;
+    onSplitsChange?: (listWidth: number) => void;
+    onOpenVfsFile?: (path: string, line?: number) => void;
+}
+/** Imperative API exposed to the title-bar search box. */
+export interface ScriptEditorPanelHandle {
+    /** Switch to the item's category, expand its ancestors, select it, and —
+     *  when a line is given — move the editor cursor there. */
+    navigateToItem: (category: EditCategory, id: string, line?: number) => void;
+}
+export declare const ScriptEditorPanel: React.ForwardRefExoticComponent<ScriptEditorPanelProps & React.RefAttributes<ScriptEditorPanelHandle>>;
+export {};

package/dist-lib/ui/windows/panels/ScriptSearch.d.ts

@@ -0,0 +1,12 @@
+import './ScriptSearch.css';
+export type EditCategory = 'scripts' | 'aliases' | 'triggers' | 'timers' | 'keys' | 'buttons';
+interface ScriptSearchProps {
+    connectionId: string;
+    /** Navigate the editor to a matched item (and optionally a code line). */
+    onNavigate: (category: EditCategory, id: string, line?: number) => void;
+}
+/** Global search for the Scripts editor — lives in the modal title bar and
+ *  drops a VS Code-style results overlay (rendered through a portal so it
+ *  escapes the modal's `overflow: hidden`). */
+export declare function ScriptSearch({ connectionId, onNavigate }: ScriptSearchProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/TextPanel.d.ts

@@ -0,0 +1,35 @@
+import type { WindowManager } from '../WindowManager';
+import type { LabelManager } from '../../labels/LabelManager';
+import type { CommandLineManager } from '../../cmdline/CommandLineManager';
+import type { ScrollBoxManager } from '../../scrollbox/ScrollBoxManager';
+interface TextPanelProps {
+    id: string;
+    /** Human-readable window title (defaults to the id), used as the accessible
+     *  name so a screen reader can identify and navigate to this user window. */
+    title?: string;
+    manager: WindowManager;
+    labels?: LabelManager;
+    cmdLines?: CommandLineManager;
+    scrollBoxes?: ScrollBoxManager;
+    fontSize?: number;
+    fontFamily?: string;
+    wrapAt?: number;
+    wrapIndent?: number;
+    wrapHangingIndent?: number;
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    backgroundImage?: {
+        url: string;
+        mode: number;
+    };
+    cmdLineEnabled?: boolean;
+    cmdLineStyleSheet?: string;
+    cmdLineValue?: string;
+    cmdLineValueSeq?: number;
+}
+export declare function TextPanel({ id, title, manager, labels, cmdLines, scrollBoxes, fontSize, fontFamily, wrapAt, wrapIndent, wrapHangingIndent, backgroundColor, backgroundImage, cmdLineEnabled, cmdLineStyleSheet, cmdLineValue, cmdLineValueSeq }: TextPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/VariablesView.d.ts

@@ -0,0 +1,21 @@
+import type { ScriptingEngine } from '../../../scripting/ScriptingEngine';
+interface VariablesViewProps {
+    connectionId: string;
+    scriptingEngineRef?: React.RefObject<ScriptingEngine | null>;
+}
+/**
+ * Mudlet's Variables view: the live `_G` tree with a checkbox per top-level
+ * entry that toggles whether it persists across sessions (the profile's
+ * save-list / Mudlet `<VariablePackage>`). Built-in globals — the default Lua +
+ * Mudlet API namespace present at runtime boot — are hidden by default (toggle
+ * to show), so only your own variables appear. Tables expand to browse their
+ * contents (fetched eagerly, so expansion is instant). Functions/userdata are
+ * shown but not flaggable. Save flagging is top-level granularity (checking a
+ * table persists all of it); per-key flagging is a follow-up.
+ *
+ * Enumerating `_G` runs synchronously on the Lua/main thread, so we defer it a
+ * tick behind a loader: the spinner paints first, then the walk runs, keeping
+ * opening the tab responsive even for a large namespace.
+ */
+export declare function VariablesView({ connectionId, scriptingEngineRef }: VariablesViewProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/VfsModulePickerModal.d.ts

@@ -0,0 +1,8 @@
+import type { ProfileVFS } from '../../../scripting/vfs/ProfileVFS';
+interface Props {
+    vfs: ProfileVFS;
+    onClose: () => void;
+    onPick: (absolutePath: string) => void;
+}
+export declare function VfsModulePickerModal({ vfs, onClose, onPick }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/WindowCmdLine.d.ts

@@ -0,0 +1,23 @@
+import type { WindowManager } from '../WindowManager';
+interface WindowCmdLineProps {
+    id: string;
+    manager: WindowManager;
+    styleSheet?: string;
+    /** Latest script-pushed value (clearCmdLine, printCmdLine, appendCmdLine).
+     *  Applied to the input one-shot whenever `seedSeq` changes. */
+    seedValue?: string;
+    seedSeq?: number;
+}
+/**
+ * Per-userwindow command line `<input>`. Backs Mudlet's enableCommandLine /
+ * setCmdLineAction / setCmdLineStyleSheet on a userwindow. The component owns
+ * the typed value as React state (so script-side seeds via printCmdLine /
+ * clearCmdLine can drive it through the seedSeq bump) and registers a probe
+ * with WindowManager so getCmdLine([name]) can read the live text.
+ *
+ * Enter dispatches to the bound Lua callback (setCmdLineAction). When no
+ * callback is bound, Enter is a no-op — userwindow command lines don't
+ * automatically send to the MUD the way the main command bar does.
+ */
+export declare function WindowCmdLine({ id, manager, styleSheet, seedValue, seedSeq }: WindowCmdLineProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/types.d.ts

@@ -0,0 +1,145 @@
+export type PanelKind = 'output' | 'text' | 'html' | 'map';
+export type DockSide = 'left' | 'right' | 'top' | 'bottom';
+export interface DragState {
+    panelId: string;
+    potentialDock: DockSide | null;
+    insertSlotIndex: number | null;
+    /** Center zone drop — creates/joins a tab group. */
+    stackTargetId?: string;
+    /** Cross-axis edge drop — creates/joins a split group (vertical stack in horizontal dock). */
+    splitTargetId?: string;
+    /** true = insert before target in cross-axis; false = after. */
+    splitBefore?: boolean;
+}
+export interface WindowOpenOptions {
+    title?: string;
+    kind?: 'text' | 'html' | 'map';
+    position?: 'right' | 'left' | 'above' | 'below';
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    activate?: boolean;
+    autoOpen?: boolean;
+    docked?: DockSide;
+    dockOrder?: number;
+    dockFlex?: number;
+    dockGroup?: string;
+    tabOrder?: number;
+    isActiveTab?: boolean;
+    splitGroup?: string;
+    splitOrder?: number;
+    splitFlex?: number;
+    /** If true, window is restored in hidden state. */
+    hidden?: boolean;
+    /** If false, skip restoring the saved hint (Mudlet restoreLayout=false). */
+    ignoreHint?: boolean;
+    /** If false, force floating regardless of dockingArea (Mudlet autoDock=false). */
+    autoDock?: boolean;
+    /** If true, the user cannot drag this window into a dock slot. Set
+     *  automatically when openUserWindow(name, _, autoDock=false) is called,
+     *  mirroring Mudlet's "autoDock=false locks the window floating" behaviour. */
+    lockFloating?: boolean;
+    /** Dock side to use when no saved hint exists (Mudlet dockingArea). "main" = floating. */
+    dockingArea?: string;
+    /** Output font size in pixels (Mudlet setFontSize). */
+    fontSize?: number;
+    /** Output font family override (Mudlet setFont). */
+    fontFamily?: string;
+    /** Character-column wrap width (Mudlet setWindowWrap). 0/undefined disables. */
+    wrapAt?: number;
+    /** Indent (in characters) of newline-started lines (Mudlet setWindowWrapIndent). */
+    wrapIndent?: number;
+    /** Indent (in characters) of wrapped continuation lines (Mudlet setWindowWrapHangingIndent). */
+    wrapHangingIndent?: number;
+    /** Window background fill (Mudlet setBackgroundColor). rgba 0..255. */
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /** Mudlet setBackgroundImage. `url` is a resolved href for modes 1-3 or the
+     *  raw stylesheet body for mode 4 (style). `mode` mirrors `mudlet.BgImageMode`:
+     *  1=border (stretched), 2=center, 3=tile, 4=style. */
+    backgroundImage?: {
+        url: string;
+        mode: number;
+    };
+    /** For miniconsoles, the parent userwindow id ('main' or another userwindow's
+     *  name). When set to a non-main parent, the miniconsole is rendered inside
+     *  that parent's viewport at parent-relative (x, y) coordinates. */
+    parent?: string;
+}
+export interface WindowHandle {
+    readonly id: string;
+    readonly kind: PanelKind;
+    readonly element: HTMLElement;
+    write(text: string): void;
+    clear(): void;
+    setTitle(title: string): void;
+    focus(): void;
+    close(): void;
+}
+export interface ScriptWindowRenderData {
+    id: string;
+    title: string;
+    kind: 'text' | 'html' | 'map';
+    visible: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    zIndex: number;
+    docked?: DockSide;
+    dockOrder?: number;
+    dockFlex?: number;
+    dockGroup?: string;
+    tabOrder?: number;
+    isActiveTab?: boolean;
+    splitGroup?: string;
+    splitOrder?: number;
+    splitFlex?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    wrapAt?: number;
+    wrapIndent?: number;
+    wrapHangingIndent?: number;
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    backgroundImage?: {
+        url: string;
+        mode: number;
+    };
+    /** For miniconsoles created with a parent userwindow — see WindowOpenOptions.parent. */
+    parent?: string;
+    /** When true, drag-to-dock is disabled for this floating window. See
+     *  WindowOpenOptions.lockFloating. */
+    lockFloating?: boolean;
+    /** When true, the panel is detached into a separate browser window. Its
+     *  portal-target div is appended into that window's document instead of a
+     *  dock slot / floating frame; the component never unmounts (scrollback and
+     *  live registrations survive). Closing the popout window pops it back in.
+     *  This is transient runtime state — it is not persisted to the saved hint,
+     *  so a reload restores the panel to its prior docked/floating position
+     *  (re-opening a popup without a user gesture would be blocked anyway). */
+    poppedOut?: boolean;
+    /** Mudlet enableCommandLine(name) — when true, the panel renders a single-line
+     *  input below the output area. Enter fires the registered cmd-line action;
+     *  if none, the text is sent to the MUD via the main connection. */
+    cmdLineEnabled?: boolean;
+    /** Mudlet setCmdLineStyleSheet(name, qss) — Qt QSS for the per-window input.
+     *  Translated through cmdLineQssToScopedCss at render time. */
+    cmdLineStyleSheet?: string;
+    /** Mudlet clearCmdLine / printCmdLine seed value. Drives the input's value
+     *  one-shot on change so React stays in sync with script writes. */
+    cmdLineValue?: string;
+    /** Bumped each time cmdLineValue is written by script, so identical writes
+     *  still trigger React's seed effect (otherwise printCmdLine('x') after a
+     *  user types 'x' would do nothing). */
+    cmdLineValueSeq?: number;
+}

package/dist-lib/utils/documentTitle.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Single owner of `document.title`.
+ *
+ * The tab title is composed from two parts that used to fight over it: a leading
+ * connection-status dot (🟢/🟡/🔴, set from React) and the profile label. On top
+ * of that sit transient flashes — Mudlet's `alert()` and the "notify on new
+ * data" feature. Everything goes through here so there's exactly one blink
+ * interval and one set of focus/visibility listeners for the whole app.
+ *
+ * The flash reuses the *same* status dot rather than adding a second one: while
+ * flashing, the leading dot blinks to white `⚪` and back. Both frames are emoji
+ * so they share an advance width and the title text never shifts as it blinks.
+ * If there's no status dot (connection indicator off) the flash falls back to a
+ * standalone 🟢 ↔ ⚪ dot so the notification is still visible.
+ *
+ * - `setBaseTitle()` updates the status dot + label; an active flash is preserved.
+ * - `flashTitle()` starts the blink, until the user returns to the tab (and,
+ *   optionally, no longer than `maxSeconds` — Mudlet's `alert(seconds)`).
+ * - A flash is a no-op while the tab is already focused, matching Mudlet.
+ */
+/**
+ * Set the steady-state title: a leading status `dot` (pass '' for none) and the
+ * profile `text`. Any active flash keeps running on top of it.
+ */
+export declare function setBaseTitle(text: string, dot?: string): void;
+/**
+ * Flash the title until the user returns to the tab. If `maxSeconds` is given it
+ * also caps the duration. No-op while the tab is focused. Calling again while a
+ * flash is active just refreshes the deadline (the blink keeps its phase).
+ */
+export declare function flashTitle(maxSeconds?: number): void;
+/** Stop any active flash immediately. Does not change the base title. */
+export declare function clearTitleFlash(): void;

package/dist-lib/utils/fontLoader.d.ts

@@ -0,0 +1,52 @@
+import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
+import type { OutputFontSource } from '../storage';
+/** Synchronous detection. May false-negative on a system font whose face the
+ *  browser hasn't materialized yet — use {@link ensureFontAvailable} when an
+ *  await is acceptable. */
+export declare function isFontAvailable(family: string): boolean;
+/** Async variant: nudges the browser via document.fonts.load() first (this
+ *  causes Chrome to materialize an installed system face into the FontFaceSet
+ *  so subsequent measurements can see it), then measures via the DOM probe. */
+export declare function ensureFontAvailable(family: string): Promise<boolean>;
+export interface FontProbeRow {
+    fallback: string;
+    baselineWidth: number;
+    candidateWidth: number;
+    diverges: boolean;
+}
+export interface FontProbeReport {
+    family: string;
+    text: string;
+    fontSizePx: number;
+    rows: FontProbeRow[];
+    available: boolean;
+    fontsCheckSays: boolean;
+    fontsLoadFaces: number;
+    fontFamiliesInSet: number;
+}
+/** Run the probe and return raw measurements for debugging the detector. */
+export declare function diagnoseFontProbe(family: string): Promise<FontProbeReport>;
+export interface LocalFontEntry {
+    family: string;
+    fullName: string;
+    postscriptName: string;
+    style?: string;
+}
+export declare function isLocalFontApiSupported(): boolean;
+export declare function queryLocalFonts(): Promise<LocalFontEntry[]>;
+export declare function getUniversalDefaultFonts(): readonly string[];
+export declare function getCachedLocalFonts(): string[];
+export declare function setLocalFontsCache(families: Iterable<string>): void;
+/** Fire-and-forget. If Local Font Access is supported AND permission was
+ *  previously granted, query installed fonts and cache the family list.
+ *  Never prompts the user. Idempotent: subsequent calls before the first
+ *  resolves piggy-back on the in-flight promise. */
+export declare function primeLocalFontsCache(): Promise<void>;
+/** Families currently registered in document.fonts — URL stylesheets and
+ *  FontFace-API uploads (the kind loaded by loadFontFromUrl / loadFontFromVfs)
+ *  show up here once the browser has materialized the face. Quoted-string
+ *  forms ("Family Name") are unwrapped to plain names. */
+export declare function getRegisteredFontFamilies(): string[];
+export declare function loadFontFromUrl(family: string, url: string): Promise<void>;
+export declare function loadFontFromVfs(family: string, path: string, vfs: ProfileVFS): Promise<void>;
+export declare function applyOutputFont(font: OutputFontSource | undefined, vfs: ProfileVFS | null): Promise<void>;

package/dist-lib/utils/profileLock.d.ts

@@ -0,0 +1,26 @@
+/** Shared prefix for every per-profile Web Lock name. */
+export declare const PROFILE_LOCK_PREFIX = "mudix:profile:";
+/** Web Lock name for a profile. */
+export declare const profileLockName: (connectionId: string) => string;
+/** Inverse of {@link profileLockName}: the connectionId encoded in a lock name,
+ *  or null when the name isn't a profile lock. Used to enumerate which profiles
+ *  are open across tabs from `navigator.locks.query()`. */
+export declare const connectionIdFromLockName: (name: string) => string | null;
+/** Best-effort check whether some tab currently holds the profile's lock. Used
+ *  only to pick the initial "waiting for the other tab" message; the actual
+ *  hand-off is the queued request in {@link acquireProfileLock}. */
+export declare function isProfileLockHeld(connectionId: string): Promise<boolean>;
+export interface ProfileLockHandle {
+    /** Resolves once this tab owns the profile — immediately when the lock is
+     *  free, or later when the owning tab releases it. Rejects with AbortError
+     *  if the signal fires before ownership is granted. */
+    readonly acquired: Promise<void>;
+    /** Release ownership. Idempotent; safe to call before `acquired` resolves
+     *  (it then cancels the pending request via the same signal path). */
+    release(): void;
+}
+/** Acquire the profile's exclusive lock, queuing behind another tab if one
+ *  already holds it. Pass an AbortSignal to stop waiting (e.g. the user backs
+ *  out to the connection screen). Degrades to a no-op guard when the Web Locks
+ *  API is unavailable (legacy browser or insecure context). */
+export declare function acquireProfileLock(connectionId: string, signal: AbortSignal): ProfileLockHandle;

package/dist-lib/utils/sessionCredentials.d.ts

@@ -0,0 +1,16 @@
+/**
+ * In-memory login credentials, keyed by connection id. Used by branded builds,
+ * where credentials are **never persisted**: the login screen deposits them
+ * here and the auto-login paths (GMCP Char.Login, text-login prompts) read
+ * them with priority over the connection record's stored fields. Lifetime is
+ * the page — a reload starts back at the login form.
+ */
+export interface SessionCredentials {
+    account: string;
+    password: string;
+}
+export declare function setSessionCredentials(connectionId: string, creds: SessionCredentials | null): void;
+export declare function getSessionCredentials(connectionId: string): SessionCredentials | undefined;
+/** The most recently entered credentials this page, regardless of profile —
+ *  prefills the branded login form after closing a profile. */
+export declare function getLastSessionCredentials(): SessionCredentials | undefined;

package/dist-lib/version.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The client's own identity on the wire — one source of truth for every
+ * protocol that asks who we are: TTYPE/MTTS (`TelnetNegotiator`), MNES and
+ * NEW-ENVIRON (`protocol/mnes`), GMCP `Core.Hello` (`MudClient`), and the MXP
+ * `<VERSION>` reply (`protocol/mxp`). These four used to carry three different
+ * spellings and two different version numbers; keep them going through here.
+ *
+ * This is *our* version, not the Mudlet API level we implement. Scripts
+ * feature-gate on `getMudletVersion()` (Bridge.lua), which reports the Mudlet
+ * release whose Lua API this client targets and moves independently of the
+ * client's own release number — a script asking `mudletOlderThan(4, 10, 0)`
+ * wants to know which APIs exist, not which build of Mudlet Web it runs on.
+ *
+ * `CLIENT_VERSION` comes straight from package.json, substituted at build time
+ * by Vite `define` (see buildInfo.ts) — `src/` can't import package.json
+ * itself because tsconfig.lib.json pins `rootDir: "src"`.
+ */
+/** Client name reported to servers. Uppercase, hyphenated: TTYPE values are
+ *  conventionally uppercase tokens (Mudlet sends `MUDLET`), and the MNES and
+ *  GMCP slots reuse the same token so a server sees one consistent identity.
+ *
+ *  Deliberately distinct from desktop Mudlet's `MUDLET`: server authors
+ *  feature-detect off this, and Mudlet Web is not feature-identical to the
+ *  desktop client. Claiming to be `MUDLET` would invite traffic we can't
+ *  honour. */
+export declare const CLIENT_NAME = "MUDLET-WEB";
+/** Client version, reported alongside `CLIENT_NAME`. Always package.json's
+ *  `version` — there is nothing to keep in sync by hand. */
+export declare const CLIENT_VERSION: string;
+/** Short git hash of the build, or '' when git wasn't available at build time.
+ *  Shown in the About dialog next to the version: releases between version
+ *  bumps are otherwise indistinguishable in a bug report. */
+export declare const GIT_COMMIT: string;
+/** Terminal type reported via TTYPE and MNES `TERMINAL_TYPE`. "ANSI-TRUECOLOR"
+ *  (matching Mudlet) describes the real capability — ANSI with 24-bit colour —
+ *  better than an xterm emulation claim; 256-colour/truecolour support is also
+ *  signalled via MTTS and the 256_COLORS/TRUECOLOR vars, so capability
+ *  detection doesn't rest on this name. */
+export declare const TERMINAL_TYPE = "ANSI-TRUECOLOR";

package/dist-lib/vfs-sw.js

@@ -0,0 +1,131 @@
+// Service worker that serves ProfileVFS-backed assets at /__vfs/<connectionId>/<path>.
+// The page is the source of truth for VFS contents (the SW can't share folder
+// handles or always-open the same IDB store), so each request round-trips to
+// the client via MessageChannel.
+
+const CACHE_NAME = 'mudix-vfs-v1';
+// Scope path always ends with '/'. On a root-served deploy this is '/'; on
+// GitHub Pages or any subpath deploy it's '/<repo>/'. The intercept prefix is
+// '<scope>__vfs/' so SW-controlled URLs stay inside scope.
+const SCOPE_PATH = new URL(self.registration.scope).pathname;
+const PREFIX = `${SCOPE_PATH}__vfs/`;
+const READ_TIMEOUT_MS = 5000;
+
+self.addEventListener('install', () => self.skipWaiting());
+self.addEventListener('activate', (e) => e.waitUntil(self.clients.claim()));
+
+self.addEventListener('fetch', (event) => {
+    const url = new URL(event.request.url);
+    if (url.origin !== self.location.origin) return;
+    if (!url.pathname.startsWith(PREFIX)) return;
+    event.respondWith(handle(event, url));
+});
+
+async function handle(event, url) {
+    const rest = url.pathname.slice(PREFIX.length).split('/').filter(Boolean);
+    if (rest.length < 2) return new Response('Bad request', { status: 400 });
+    const connectionId = decodeURIComponent(rest[0]);
+    const filePath = '/' + rest.slice(1).map(decodeURIComponent).join('/');
+
+    const cache = await caches.open(CACHE_NAME);
+    const cached = await cache.match(event.request);
+    if (cached) return cached;
+
+    const client = await pickClient(event);
+    if (!client) {
+        // Either there's no app tab loaded (direct URL hit in fresh tab) or
+        // the only candidate is the tab currently navigating to this URL.
+        return new Response('No app tab loaded; open mudix first', { status: 503 });
+    }
+
+    const reply = await ask(client, { type: 'vfs:read', connectionId, path: filePath });
+    if (!reply || !reply.ok) {
+        return new Response(reply?.error ?? 'Not found', { status: 404 });
+    }
+
+    const headers = new Headers();
+    headers.set('Content-Type', reply.contentType || 'application/octet-stream');
+    // no-store keeps this response out of the browser's own HTTP cache, which
+    // has no validator to revalidate against (we set none) and would otherwise
+    // race our explicit Cache Storage entry above — that race is what produced
+    // stale 304-with-no-body responses for cached images. The Cache Storage
+    // entry (invalidated on writes via postMessage) is the only cache that
+    // should own this decision.
+    headers.set('Cache-Control', 'no-store');
+    const response = new Response(reply.bytes, { headers });
+    cache.put(event.request, response.clone()).catch(() => {});
+    return response;
+}
+
+async function pickClient(event) {
+    // Prefer the client that issued this request — for sub-resource fetches
+    // that's the loaded app page, which can reply immediately.
+    const requestingId = event.clientId || event.resultingClientId || '';
+    if (requestingId) {
+        const c = await self.clients.get(requestingId);
+        if (c && isUsable(c)) return c;
+    }
+    const all = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
+    const usable = all.filter(isUsable);
+    return usable.find((c) => c.focused) ?? usable[0] ?? null;
+}
+
+// Skip clients that are themselves navigating to a /__vfs/ URL — those are
+// fresh tabs in the middle of loading the SW response; they have no JS running
+// and can't reply, so picking one guarantees a timeout.
+function isUsable(client) {
+    try {
+        return !new URL(client.url).pathname.startsWith(PREFIX);
+    } catch {
+        return false;
+    }
+}
+
+function ask(client, message) {
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        const timer = setTimeout(() => {
+            channel.port1.close();
+            resolve({ ok: false, error: 'timeout' });
+        }, READ_TIMEOUT_MS);
+        channel.port1.onmessage = (e) => {
+            clearTimeout(timer);
+            channel.port1.close();
+            resolve(e.data);
+        };
+        client.postMessage(message, [channel.port2]);
+    });
+}
+
+self.addEventListener('message', (event) => {
+    const data = event.data;
+    if (!data) return;
+    if (data.type === 'vfs:invalidate') {
+        event.waitUntil(invalidate(data));
+    }
+});
+
+async function invalidate({ connectionId, path }) {
+    if (!connectionId) {
+        await caches.delete(CACHE_NAME);
+        return;
+    }
+    const cache = await caches.open(CACHE_NAME);
+    const connPrefix = `${PREFIX}${encodeURIComponent(connectionId)}/`;
+    const keys = await cache.keys();
+    if (path) {
+        const segs = path.split('/').filter(Boolean).map(encodeURIComponent).join('/');
+        const target = `${connPrefix}${segs}`;
+        await Promise.all(
+            keys
+                .filter((req) => new URL(req.url).pathname === target)
+                .map((req) => cache.delete(req)),
+        );
+        return;
+    }
+    await Promise.all(
+        keys
+            .filter((req) => new URL(req.url).pathname.startsWith(connPrefix))
+            .map((req) => cache.delete(req)),
+    );
+}

package/dist-lib/vite.d.ts

@@ -0,0 +1,2 @@
+import type { PluginOption } from 'vite';
+export default function mudix(): PluginOption[];