@mudlet/mudlet-web 0.3.0

package/dist-lib/scripting/profilesPresence.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cross-tab view of which profiles are open and which are connected — backs
+ * Mudlet's `getProfiles()`. mudix runs one profile per browser tab, so two
+ * cross-tab signals are combined:
+ *
+ *  - **loaded** (open & editable): every open profile holds an exclusive Web
+ *    Lock named `mudix:profile:<id>` (see profileLock.ts). `navigator.locks
+ *    .query()` lists held locks across all same-origin tabs, so the held
+ *    profile locks ARE the loaded set. Authoritative and crash-safe (the browser
+ *    auto-releases a lock when its tab closes/crashes). Polled on a slow interval
+ *    since the query is async but `getProfiles()` is a synchronous Lua call.
+ *
+ *  - **connected** (playing): not observable through Web Locks, so each tab
+ *    announces its own live connection state over a `BroadcastChannel`. A tab
+ *    announces on connect/disconnect and answers a `query` from a newly-opened
+ *    tab; `bye` on teardown clears it eagerly (a crash is caught by the loaded
+ *    set dropping). The owning tab's own state is always read live.
+ *
+ * Degrades gracefully where the platform lacks these APIs (legacy browser,
+ * insecure context, or the Node test environment): no Web Locks → loaded is just
+ * this profile; no BroadcastChannel → connected is just this profile's live
+ * state. That matches the old single-profile `getProfiles()` behaviour.
+ */
+export declare class ProfilesPresence {
+    private readonly ownId;
+    /** This tab's live connected state, read whenever we announce. */
+    private readonly localConnected;
+    private channel;
+    private lockTimer;
+    /** Loaded profile ids from Web Locks (authoritative; always includes self). */
+    private loaded;
+    /** Last-announced connected state of OTHER tabs' profiles. */
+    private readonly remoteConnected;
+    constructor(ownId: string, 
+    /** This tab's live connected state, read whenever we announce. */
+    localConnected: () => boolean, refreshMs?: number);
+    /** Broadcast this tab's current connected state to peers. Call on connect/
+     *  disconnect. No-op without a channel. */
+    announce(): void;
+    /** Connection ids of all loaded profiles (best-effort snapshot, always
+     *  including this profile's own id). */
+    loadedIds(): string[];
+    /** Connected state for a profile id: own → live, others → last announced
+     *  (false when never announced). Callers gate this on `loaded` so a crashed
+     *  tab's stale "connected" can't outlive its lock. */
+    isConnected(id: string): boolean;
+    private onMessage;
+    private refreshLoaded;
+    destroy(): void;
+}

package/dist-lib/scripting/vfs/ProfileVFS.d.ts

@@ -0,0 +1,62 @@
+export type VFSSource = 'folder' | 'idb';
+export declare class ProfileVFS {
+    readonly connectionId: string;
+    readonly profilePath: string;
+    private _cwd;
+    private _fs;
+    private _handle?;
+    readonly source: VFSSource;
+    readonly folderName?: string;
+    private constructor();
+    static mount(connectionId: string): Promise<ProfileVFS>;
+    private static doMount;
+    get cwd(): string;
+    resolvePath(path: string): string;
+    exists(path: string): boolean;
+    readFile(path: string): string;
+    readBinaryFile(path: string): Uint8Array;
+    writeFile(path: string, content: string): void;
+    writeBinaryFile(path: string, data: Uint8Array): void;
+    /**
+     * The linked-folder (WebAccess / FileSystemDirectoryHandle) backend overwrites
+     * a file from offset 0 but does NOT shrink it, so writing shorter content over
+     * longer leaves stale tail bytes — silently corrupting Lua `table.save` data,
+     * JSON, and the profile XML. Removing the file first forces a fresh,
+     * correctly-sized write. IndexedDB truncates on the `w` flag correctly, so it's
+     * left untouched (no extra op per save).
+     */
+    private clearForOverwrite;
+    appendFile(path: string, content: string): void;
+    deleteFile(path: string): void;
+    rename(oldPath: string, newPath: string): void;
+    mkdir(path: string): void;
+    rmdir(path: string): void;
+    readdir(path: string): string[];
+    stat(path: string): {
+        type: 'file' | 'dir';
+        size: number;
+        mtime: Date;
+        atime: Date;
+    } | null;
+    chdir(path: string): string | null;
+    /**
+     * Drain queued async writes to the underlying backend. For folder-backed
+     * mounts this writes RAM-cached changes through to disk; for IDB mounts
+     * it persists to IndexedDB. Safe to call on any source.
+     */
+    flush(): Promise<void>;
+    /**
+     * Re-walk the linked directory and rebuild the in-memory cache. Use after
+     * external edits (file added/changed in the OS file manager). No-op for
+     * IDB-backed profiles since their state is owned by the browser.
+     *
+     * Any Lua file handles opened before resync become invalid: ZenFS replaces
+     * the underlying FS instance, so subsequent reads on those handles will
+     * error. New `io.open` calls work normally.
+     */
+    resync(): Promise<void>;
+    /** Tell the VFS service worker to drop its cached copy of a file, keyed
+     *  by its path relative to the profile root (matches vfsUrlFor's scheme). */
+    private invalidate;
+    unmount(): void;
+}

package/dist-lib/scripting/vfs/cssRewrite.d.ts

@@ -0,0 +1,21 @@
+import type { ProfileVFS } from './ProfileVFS';
+/**
+ * Map one asset reference onto the URL the service worker serves, or return
+ * null when it must be left alone (empty, or already an absolute http/data/
+ * blob/__vfs URL). Paths are resolved through the VFS (honouring its cwd and
+ * profile root) and rebased onto the profile root.
+ *
+ * Shared by the stylesheet rewriter and the label-HTML rewriter so `url(...)`
+ * in a stylesheet and `<img src>` in label rich text resolve identically.
+ */
+export declare function vfsRefToUrl(ref: string, connectionId: string, vfs: ProfileVFS): string | null;
+/**
+ * Rewrite `url(<local-path>)` references in a Qt/CSS stylesheet to
+ * `url(/__vfs/<connectionId>/<path>)` so the registered service worker can
+ * serve the bytes from the connection's ProfileVFS. Already-absolute http/data/
+ * blob/__vfs URLs pass through untouched.
+ *
+ * Paths are resolved through the VFS (which honours its cwd and profile root)
+ * and rebased onto the profile root before being put into the URL.
+ */
+export declare function rewriteVfsUrlsInCss(css: string, connectionId: string, vfs: ProfileVFS): string;

package/dist-lib/scripting/vfs/folderHandleStore.d.ts

@@ -0,0 +1,16 @@
+interface ShowDirectoryPickerOptions {
+    mode?: 'read' | 'readwrite';
+}
+declare global {
+    interface Window {
+        showDirectoryPicker?: (options?: ShowDirectoryPickerOptions) => Promise<FileSystemDirectoryHandle>;
+    }
+}
+export type FolderPermissionState = 'granted' | 'prompt' | 'denied' | 'unsupported';
+export declare function isFolderLinkSupported(): boolean;
+export declare function saveFolderHandle(connectionId: string, handle: FileSystemDirectoryHandle): Promise<void>;
+export declare function loadFolderHandle(connectionId: string): Promise<FileSystemDirectoryHandle | null>;
+export declare function clearFolderHandle(connectionId: string): Promise<void>;
+export declare function checkFolderPermission(handle: FileSystemDirectoryHandle): Promise<FolderPermissionState>;
+export declare function requestFolderPermission(handle: FileSystemDirectoryHandle): Promise<FolderPermissionState>;
+export {};

package/dist-lib/scripting/vfs/folderSync.d.ts

@@ -0,0 +1,59 @@
+import { readFileSync, statSync } from '@zenfs/core';
+import type { ProfileVFS } from './ProfileVFS';
+export type SideKind = 'local' | 'folder';
+export interface FileEntry {
+    /** Relative path from the profile root, e.g. "scripts/foo.lua". No leading slash. */
+    path: string;
+    size: number;
+    mtimeMs: number;
+}
+export interface DiffResult {
+    /** Files present only in the local (IDB) side. */
+    onlyLocal: FileEntry[];
+    /** Files present only in the linked folder. */
+    onlyFolder: FileEntry[];
+    /** Files at the same path on both sides (need user resolution). */
+    conflicts: {
+        path: string;
+        local: FileEntry;
+        folder: FileEntry;
+    }[];
+}
+export declare function walkFolderHandle(root: FileSystemDirectoryHandle): Promise<FileEntry[]>;
+/** Walk every file under the mounted profile, returning paths relative to the profile root. */
+export declare function walkVfsTree(vfs: ProfileVFS): FileEntry[];
+/**
+ * A file is considered "conflicting" if it exists at the same relative path on
+ * both sides, regardless of whether the bytes match. Comparing mtime/size is
+ * unreliable across filesystems (folder-backed mtime comes from disk,
+ * IDB-backed mtime comes from the inode index), so we let the user resolve.
+ */
+export declare function diffSides(local: FileEntry[], folder: FileEntry[]): DiffResult;
+/**
+ * Copy the listed relative paths from the mounted profile into the linked
+ * folder. Used on link to materialize IDB-only files (and "use local"
+ * resolutions) before the next mount picks up the folder as the source.
+ */
+export declare function copyVfsToFolder(vfs: ProfileVFS, handle: FileSystemDirectoryHandle, relPaths: string[]): Promise<{
+    copied: number;
+    failed: {
+        path: string;
+        reason: string;
+    }[];
+}>;
+/**
+ * Side-mount a fresh IDB backend for the given connection at a temporary
+ * profile path, copy every file from the linked folder into it, then unmount.
+ * Used on unlink so the user's next mount (now IDB-backed because the handle
+ * is cleared) sees the folder's content. Idempotent: any prior data in the
+ * IDB store gets overwritten when paths collide.
+ */
+export declare function copyFolderToIdb(handle: FileSystemDirectoryHandle, connectionId: string): Promise<{
+    copied: number;
+    failed: {
+        path: string;
+        reason: string;
+    }[];
+}>;
+export declare function hasAnyFile(entries: FileEntry[]): boolean;
+export { readFileSync, statSync };

package/dist-lib/scripting/vfs/htmlRewrite.d.ts

@@ -0,0 +1,26 @@
+import type { ProfileVFS } from './ProfileVFS';
+/**
+ * Rewrite profile-local asset references in Lua-supplied HTML to the
+ * `/__vfs/<connectionId>/<path>` URLs the service worker serves.
+ *
+ * Mudlet renders `echo(labelName, html)` as Qt rich text, where
+ * `<img src="/home/user/.config/mudlet/profiles/X/pkg/icon.png">` loads straight
+ * off the local filesystem. In the browser there is no such filesystem — the
+ * bytes live in the profile's ProfileVFS, reachable only through the service
+ * worker — so those paths have to be rebased or the images silently 404 (on a
+ * dev server they resolve to the SPA fallback `index.html`, which decodes as a
+ * broken image).
+ *
+ * Two kinds of reference are rewritten:
+ *   - `src` attributes (`<img>`, and anything else Qt resolves as a resource)
+ *   - `url(...)` refs inside an inline `style` attribute, via the same
+ *     stylesheet rewriter used for setLabelStyleSheet
+ *
+ * `href` is deliberately left alone: label links are navigation targets
+ * (openUrl / setLinkStyle), not embedded resources, and rewriting them would
+ * turn an anchor into a VFS fetch.
+ *
+ * Absolute http(s)/data:/blob:/already-`__vfs` references pass through
+ * untouched, as do paths when no VFS is mounted.
+ */
+export declare function rewriteVfsUrlsInHtml(html: string, connectionId: string, vfs: ProfileVFS): string;

package/dist-lib/scripting/vfs/vfsBridge.d.ts

@@ -0,0 +1,16 @@
+import type { ProfileVFS } from './ProfileVFS';
+export declare function vfsUrlPrefix(): string;
+/** Register a mounted profile so the service worker can read its files. */
+export declare function registerVfs(connectionId: string, vfs: ProfileVFS): void;
+/** Drop the mapping and clear cached responses for this connection. */
+export declare function unregisterVfs(connectionId: string): void;
+/** Tell the SW to drop one cached file (call after writes). */
+export declare function invalidateVfsPath(connectionId: string, path: string): void;
+/** Build a URL the SW will resolve to bytes from `vfs.readBinaryFile(path)`. */
+export declare function vfsUrlFor(connectionId: string, path: string): string;
+/**
+ * Register the service worker and wait until it controls this page. Safe to
+ * call multiple times; resolves to false if the browser doesn't support SWs
+ * or registration failed.
+ */
+export declare function registerVfsServiceWorker(): Promise<boolean>;

package/dist-lib/services/cloudflare.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal Cloudflare API client for the proxy-deploy wizard.
+ *
+ * The wizard uses the user's API token to:
+ *   1. List accounts the token has access to (verifyToken / listAccounts)
+ *   2. Upload the proxy worker script (deployWorker)
+ *   3. Enable the *.workers.dev route on it (enableWorkersDevRoute)
+ *   4. Look up the account's workers.dev subdomain (getWorkersSubdomain)
+ *
+ * Cloudflare's API rejects cross-origin browser requests, so every call is
+ * tunneled through a relay Worker's HTTP-forward mode (`?url=<target>`). The
+ * relay adds CORS headers and strips Origin/Referer/Cookie before forwarding;
+ * the Authorization header is preserved.
+ *
+ * The token never leaves component state — it's consumed once per deploy and
+ * never persisted.
+ */
+export interface CloudflareAccount {
+    id: string;
+    name: string;
+}
+export declare class CloudflareApiError extends Error {
+    readonly status: number;
+    readonly cfErrors?: {
+        code: number;
+        message: string;
+    }[];
+    constructor(message: string, status: number, cfErrors?: {
+        code: number;
+        message: string;
+    }[]);
+}
+/**
+ * Lists accounts visible to the token. Doubles as a token-validity check:
+ * an invalid token returns a Cloudflare error envelope which we surface.
+ */
+export declare function listAccounts(token: string, proxyBase?: string): Promise<CloudflareAccount[]>;
+/**
+ * Uploads a Worker script via the multipart "modules" format. The script is
+ * sent as an ES module so `import { connect } from 'cloudflare:sockets'` works.
+ */
+export declare function deployWorker(token: string, accountId: string, scriptName: string, scriptSource: string, proxyBase?: string): Promise<void>;
+/**
+ * Enables (or disables) the auto-assigned *.workers.dev route for a script.
+ * Without this the script is uploaded but not reachable.
+ */
+export declare function enableWorkersDevRoute(token: string, accountId: string, scriptName: string, proxyBase?: string): Promise<void>;
+/**
+ * Returns the account's workers.dev subdomain (e.g. "yourname" → "*.yourname.workers.dev").
+ * If the user has never created one, the API returns an empty string and the
+ * wizard surfaces a friendlier error.
+ */
+export declare function getWorkersSubdomain(token: string, accountId: string, proxyBase?: string): Promise<string>;
+export declare function buildWorkerWssUrl(scriptName: string, subdomain: string): string;

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

@@ -0,0 +1,132 @@
+import { type AppSchema, type MudConnection, type AliasNode, type ButtonNode, type KeyNode, type TimerNode, type TriggerNode, type ScriptNode, type ScriptEditorBounds, type ModalBounds, type ClientSettings, type ProfileSettings, type PackageManifest, type WindowLayoutSnapshot, type ProfileVariables } from './schema';
+import type { MudletVariable } from '../import/mudletVariables';
+import type { MudletImportResult } from '../import/mudletXmlImport';
+import type { WindowOpenOptions } from '../ui/windows/types';
+interface AppStore extends AppSchema {
+    /** Adds a connection and returns its newly generated id (so callers can
+     *  immediately attach per-profile data like saved login credentials). */
+    addConnection: (data: Omit<MudConnection, 'id'>) => string;
+    updateConnection: (id: string, data: Omit<MudConnection, 'id'>) => void;
+    /** Partial update preserving fields the patch doesn't mention. Used for
+     *  surgical edits (icon, login creds) that must not wipe the rest of the
+     *  connection record. Keys set to `undefined` are removed. */
+    patchConnection: (id: string, patch: Partial<Omit<MudConnection, 'id'>>) => void;
+    removeConnection: (id: string) => void;
+    /** Reorder the profile list to match `orderedIds`. Ids not present in the
+     *  list are ignored; any existing connection missing from `orderedIds` is
+     *  appended in its current relative order (so a stale list can't drop
+     *  profiles). Backs drag-to-rearrange on the connection screen. */
+    reorderConnections: (orderedIds: string[]) => void;
+    patchClient: (patch: Partial<ClientSettings>) => void;
+    patchConnectionProfile: (connectionId: string, patch: Partial<ProfileSettings>) => void;
+    saveWindowHint: (connectionId: string, panelId: string, hint: WindowOpenOptions) => void;
+    clearWindowHints: (connectionId: string) => void;
+    saveDockExtents: (connectionId: string, extents: Record<string, number>) => void;
+    saveLayoutSnapshot: (connectionId: string, snapshot: WindowLayoutSnapshot) => void;
+    /** Replace the set of global names flagged to persist (Mudlet save-list).
+     *  Edited from the Variables view; triggers a profile-data save. */
+    setVariableSaveList: (connectionId: string, saveList: string[]) => void;
+    /** Replace the captured variable values without disturbing the save-list
+     *  reference — so the engine can refresh them on save without re-triggering
+     *  the save subscription (which keys on the save-list, not values). */
+    setVariableValues: (connectionId: string, values: MudletVariable[]) => void;
+    addScript: (connectionId: string, data: Omit<ScriptNode, 'id'>) => string;
+    updateScript: (connectionId: string, id: string, patch: Partial<Omit<ScriptNode, 'id'>>) => void;
+    removeScript: (connectionId: string, id: string) => void;
+    addAlias: (connectionId: string, data: Omit<AliasNode, 'id'>) => string;
+    updateAlias: (connectionId: string, id: string, patch: Partial<Omit<AliasNode, 'id'>>) => void;
+    updateAliases: (connectionId: string, patches: ReadonlyArray<{
+        id: string;
+        patch: Partial<Omit<AliasNode, 'id'>>;
+    }>) => void;
+    removeAlias: (connectionId: string, id: string) => void;
+    addTrigger: (connectionId: string, data: Omit<TriggerNode, 'id'>) => string;
+    updateTrigger: (connectionId: string, id: string, patch: Partial<Omit<TriggerNode, 'id'>>) => void;
+    /** Bulk apply enabled/disabled (or any partial) to many triggers in one set(). */
+    updateTriggers: (connectionId: string, patches: ReadonlyArray<{
+        id: string;
+        patch: Partial<Omit<TriggerNode, 'id'>>;
+    }>) => void;
+    removeTrigger: (connectionId: string, id: string) => void;
+    removeTriggers: (connectionId: string, ids: ReadonlyArray<string>) => void;
+    addTimer: (connectionId: string, data: Omit<TimerNode, 'id'>) => string;
+    updateTimer: (connectionId: string, id: string, patch: Partial<Omit<TimerNode, 'id'>>) => void;
+    updateTimers: (connectionId: string, patches: ReadonlyArray<{
+        id: string;
+        patch: Partial<Omit<TimerNode, 'id'>>;
+    }>) => void;
+    removeTimer: (connectionId: string, id: string) => void;
+    removeTimers: (connectionId: string, ids: ReadonlyArray<string>) => void;
+    removeAliases: (connectionId: string, ids: ReadonlyArray<string>) => void;
+    addKeybinding: (connectionId: string, data: Omit<KeyNode, 'id'>) => string;
+    updateKeybinding: (connectionId: string, id: string, patch: Partial<Omit<KeyNode, 'id'>>) => void;
+    removeKeybinding: (connectionId: string, id: string) => void;
+    removeKeybindings: (connectionId: string, ids: ReadonlyArray<string>) => void;
+    addButton: (connectionId: string, data: Omit<ButtonNode, 'id'>) => string;
+    updateButton: (connectionId: string, id: string, patch: Partial<Omit<ButtonNode, 'id'>>) => void;
+    removeButton: (connectionId: string, id: string) => void;
+    moveScript: (connectionId: string, id: string, newParentId: string | null, insertBeforeId: string | null) => void;
+    moveAlias: (connectionId: string, id: string, newParentId: string | null, insertBeforeId: string | null) => void;
+    moveTrigger: (connectionId: string, id: string, newParentId: string | null, insertBeforeId: string | null) => void;
+    moveTimer: (connectionId: string, id: string, newParentId: string | null, insertBeforeId: string | null) => void;
+    moveKeybinding: (connectionId: string, id: string, newParentId: string | null, insertBeforeId: string | null) => void;
+    moveButton: (connectionId: string, id: string, newParentId: string | null, insertBeforeId: string | null) => void;
+    saveScriptEditorBounds: (connectionId: string, bounds: ScriptEditorBounds) => void;
+    saveModalBounds: (connectionId: string, key: string, bounds: ModalBounds) => void;
+    installPackage: (connectionId: string, manifest: PackageManifest, data: MudletImportResult) => void;
+    uninstallPackage: (connectionId: string, packageName: string) => void;
+    updatePackageManifest: (connectionId: string, packageName: string, patch: Partial<Omit<PackageManifest, 'name'>>) => void;
+    /** Replace the VFS-persisted automation slices for one connection in a single
+     *  set(). Called once on profile open, after its VFS mounts, to seed the
+     *  store from `.mudix/profile.json`. Missing keys reset to empty arrays. */
+    hydrateConnectionData: (connectionId: string, data: PersistedConnectionData) => void;
+}
+/** The per-connection slices persisted in the profile VFS (see profileVfsData.ts). */
+interface PersistedConnectionData {
+    scripts?: ScriptNode[];
+    aliases?: AliasNode[];
+    triggers?: TriggerNode[];
+    timers?: TimerNode[];
+    keybindings?: KeyNode[];
+    buttons?: ButtonNode[];
+    packages?: PackageManifest[];
+    profile?: Partial<ProfileSettings>;
+    windowHints?: Record<string, WindowOpenOptions>;
+    dockExtents?: Record<string, number>;
+    scriptEditorBounds?: ScriptEditorBounds;
+    modalBounds?: Record<string, ModalBounds>;
+    layoutSnapshot?: WindowLayoutSnapshot;
+    variables?: ProfileVariables;
+}
+/** localStorage key + schema version for the persisted store. Exported so the
+ *  cross-tab sync (crossTabSync.ts) can match `storage` events to this store and
+ *  reject writes from a different schema version. */
+export declare const MUDIX_STORE_NAME = "mudix_v1";
+export declare const MUDIX_STORE_VERSION = 21;
+/** One-time localStorage key holding pre-v21 per-profile UI/layout/settings
+ *  slices, stashed by the v21 migration so they can be moved into each profile's
+ *  VFS (.mudix/profile.json) the first time it's opened. Kept separate from the
+ *  persisted store blob so editing the connections list (which rewrites the
+ *  blob) can't drop un-migrated profiles' data. Consumed per-profile by
+ *  loadProfileData, then removed when empty. */
+export declare const MIGRATION_BACKUP_KEY = "mudix_profile_migration_v21";
+export declare const useAppStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<AppStore>, "setState" | "persist"> & {
+    setState(partial: AppStore | Partial<AppStore> | ((state: AppStore) => AppStore | Partial<AppStore>), replace?: false | undefined): unknown;
+    setState(state: AppStore | ((state: AppStore) => AppStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<AppStore, {
+            connections: MudConnection[];
+            client: ClientSettings;
+        }, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: AppStore) => void) => () => void;
+        onFinishHydration: (fn: (state: AppStore) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<AppStore, {
+            connections: MudConnection[];
+            client: ClientSettings;
+        }, unknown>>;
+    };
+}>;
+export {};

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

@@ -0,0 +1,3 @@
+/** Begin listening for other tabs' persisted-store writes and merging them in.
+ *  Idempotent; safe to call more than once (e.g. across HMR reloads). */
+export declare function initCrossTabSync(): void;

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

@@ -0,0 +1,18 @@
+import type { PersistStorage } from 'zustand/middleware';
+/**
+ * Zustand PersistStorage adapter that coalesces rapid mutations into a single
+ * write — *including* the JSON serialization step.
+ *
+ * Using `createJSONStorage` over a debounced Web-Storage wrapper only collapses
+ * the localStorage.setItem call; zustand still runs `JSON.stringify(state)`
+ * before each setItem, so N mutations cost N full serializations of the
+ * persisted blob (scripts, triggers, packages, …). Implementing PersistStorage
+ * directly lets us hold the unserialized object and stringify exactly once,
+ * at flush time.
+ *
+ * The latest pending value is flushed synchronously on `pagehide`,
+ * `visibilitychange→hidden`, and `beforeunload` so a tab close right after a
+ * mutation doesn't lose state. `getItem` honours an in-flight pending value so
+ * the adapter is internally consistent even mid-debounce.
+ */
+export declare function createDebouncedJsonStorage<S>(delayMs: number): PersistStorage<S>;

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

@@ -0,0 +1,17 @@
+import { type ClientSettings, type ProfileSettings, type Theme } from './schema';
+/**
+ * Active profile id, provided by ProfileSession. `null` outside a profile
+ * (e.g. on the connection screen) — settings consumers fall through to
+ * PROFILE_DEFAULTS in that case.
+ */
+export declare const ConnectionIdContext: import("react").Context<string | null>;
+export declare function useConnectionId(): string | null;
+/** Read one ProfileSettings field for the active profile (from context). */
+export declare function useProfileField<K extends keyof ProfileSettings>(key: K): ProfileSettings[K];
+/** Read one ClientSettings field. */
+export declare function useClientField<K extends keyof ClientSettings>(key: K): ClientSettings[K];
+/** The theme actually in effect: the active profile's override if it has one,
+ *  else the launcher theme. Use anywhere a profile-scoped component needs the
+ *  current theme (e.g. CodeMirror editors). Outside a profile (no context) it
+ *  resolves to the launcher theme. */
+export declare function useEffectiveTheme(): Theme;

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

@@ -0,0 +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 { useAppStore } from './appStore';
+export { initCrossTabSync } from './crossTabSync';
+export { ConnectionIdContext, useConnectionId, useProfileField, useClientField, useEffectiveTheme } from './hooks';

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

@@ -0,0 +1,32 @@
+import { type LogEntry, type LogSession } from './logStorage';
+/** `YYYY-MM-DD HH-MM-SS`, safe for filenames. */
+export declare function formatSessionFileStamp(ts: number): string;
+/** `HH:MM:SS` for per-line timestamps. */
+export declare function formatTime(ts: number): string;
+/** `YYYY-MM-DD HH:MM:SS` for session labels. */
+export declare function formatDateTime(ts: number): string;
+/** A standalone, self-contained HTML document for one session. */
+export declare function buildSessionHtml(session: LogSession, entries: LogEntry[]): string;
+/** Trigger a browser download for an in-memory blob. */
+export declare function downloadBlob(filename: string, blob: Blob): void;
+/** Download one session as a standalone `.html` file. */
+export declare function exportSessionHtml(session: LogSession): Promise<void>;
+/** Bundle several sessions into one `.zip`, one HTML file per session. */
+export declare function exportSessionsZip(sessions: LogSession[]): Promise<void>;
+/** Shape of the JSON export/import payload. */
+export interface LogExportJson {
+    version: 1;
+    exportedAt: number;
+    sessions: Array<{
+        session: LogSession;
+        entries: LogEntry[];
+    }>;
+}
+/** Export sessions (with their entries) to a `.json` file. */
+export declare function exportSessionsJson(sessions: LogSession[]): Promise<void>;
+/**
+ * Import a previously exported JSON payload. Each session is re-keyed with a
+ * fresh id so re-importing never clobbers an existing session, and entry rows
+ * drop their old auto-increment ids. Returns the number of sessions imported.
+ */
+export declare function importSessionsJson(text: string): Promise<number>;

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

@@ -0,0 +1,45 @@
+/** One recorded gameplay session (a single profile open). */
+export interface LogSession {
+    /** UUID; also the foreign key on every {@link LogEntry}. */
+    id: string;
+    connectionId: string;
+    /** Display name captured at record time, so the browser can label the
+     *  session even after the connection is renamed or deleted. */
+    connectionName: string;
+    startedAt: number;
+    /** Updated on every flush; the wall-clock time of the last logged line. */
+    endedAt: number;
+    entryCount: number;
+}
+/** One captured output line. `html` is the styled, HTML-escaped render
+ *  (snapshotted at emit time); `plain` is the unstyled text used for search. */
+export interface LogEntry {
+    /** Auto-increment key, assigned by IndexedDB on insert. */
+    id?: number;
+    sessionId: string;
+    /** Monotonic ordering within the session (guards against equal timestamps). */
+    seq: number;
+    timestamp: number;
+    /** Mirrors the `message` event type: 'mud' | 'echo' | 'script' | 'info' | … */
+    type: string;
+    html: string;
+    plain: string;
+}
+/** Insert a session record (call once, on the first flush that has entries). */
+export declare function createSession(session: LogSession): Promise<void>;
+/** Merge a partial update into an existing session record (endedAt/entryCount). */
+export declare function updateSession(id: string, patch: Partial<LogSession>): Promise<void>;
+/** Append a batch of entries in a single transaction. */
+export declare function appendEntries(entries: LogEntry[]): Promise<void>;
+/** All sessions, newest first. Optionally filtered to one connection. */
+export declare function listSessions(connectionId?: string): Promise<LogSession[]>;
+/** All entries for a session, in capture order. */
+export declare function getSessionEntries(sessionId: string): Promise<LogEntry[]>;
+/** Delete a session and every entry that belongs to it. */
+export declare function deleteSession(id: string): Promise<void>;
+/** Delete several sessions (and their entries). */
+export declare function deleteSessions(ids: string[]): Promise<void>;
+/** Remove every log for a connection — called when the connection is deleted. */
+export declare function deleteSessionsForConnection(connectionId: string): Promise<void>;
+/** Wipe all recorded logs across every connection. */
+export declare function clearAllLogs(): Promise<void>;

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

@@ -0,0 +1,2 @@
+export declare function saveMap(connectionId: string, data: ArrayBuffer): Promise<void>;
+export declare function loadMap(connectionId: string): Promise<ArrayBuffer | null>;

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

@@ -0,0 +1,47 @@
+import type { ScriptNode, AliasNode, TriggerNode, TimerNode, KeyNode, ButtonNode, PackageManifest, ProfileSettings, ScriptEditorBounds, ModalBounds, WindowLayoutSnapshot, ProfileVariables } from './schema';
+import type { WindowOpenOptions } from '../ui/windows/types';
+import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
+/**
+ * Per-profile data is stored inside that profile's own VFS rather than the
+ * shared localStorage blob — see the design notes in CLAUDE.md / the storage
+ * layer. One JSON file per profile holds the bulky tree data (scripts, aliases,
+ * triggers, …) AND the per-profile UI/settings/layout slices, so the only
+ * per-profile state left in localStorage is the connection record itself. That
+ * makes each profile single-writer (one tab owns it via the cross-tab lock),
+ * eliminating the multi-tab clobber the shared blob suffered.
+ *
+ * The file is dot-prefixed so it stays out of the way in the user-browsable
+ * file area. `ProfileVFS.writeFile` creates the `.mudix/` parent dir for us.
+ */
+export declare const PROFILE_DATA_PATH = ".mudix/profile.json";
+export interface PersistedProfileData {
+    version: number;
+    scripts: ScriptNode[];
+    aliases: AliasNode[];
+    triggers: TriggerNode[];
+    timers: TimerNode[];
+    keybindings: KeyNode[];
+    buttons: ButtonNode[];
+    packages: PackageManifest[];
+    /** Mudlet saved-variables: the save-list + last captured values. Optional so
+     *  older files (no variables) still parse. */
+    variables?: ProfileVariables;
+    profile?: Partial<ProfileSettings>;
+    windowHints?: Record<string, WindowOpenOptions>;
+    dockExtents?: Record<string, number>;
+    scriptEditorBounds?: ScriptEditorBounds;
+    modalBounds?: Record<string, ModalBounds>;
+    layoutSnapshot?: WindowLayoutSnapshot;
+}
+/**
+ * Read `.mudix/profile.json` from the profile VFS and push it into the store
+ * for `connectionId`. Also completes the one-time v21 migration: if this
+ * profile's UI/settings/layout slices haven't moved into the VFS yet, they're
+ * pulled from the migration backup, hydrated, written to the VFS, and dropped
+ * from the backup. No-op for a fresh profile with nothing to load.
+ */
+export declare function loadProfileData(vfs: ProfileVFS, connectionId: string): void;
+/** Serialize a profile's automation + UI slices for `connectionId` from the store. */
+export declare function serializeProfileData(connectionId: string): string;
+/** Write the current store state for `connectionId` to the profile VFS. */
+export declare function saveProfileData(vfs: ProfileVFS, connectionId: string): void;