@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -49,7 +49,7 @@ export interface BindingContext {
      */
     channel(v: unknown): number | null;
     /**
-     * Invoke a Lua callback previously registered through `__mudix_register_cb`.
+     * Invoke a Lua callback previously registered through `__mudlet_register_cb`.
      * `what` names the call site and is used only to attribute errors.
      */
     dispatchCb(id: number, what: string): void;
@@ -57,12 +57,27 @@ export interface BindingContext {
     releaseCb(id: number): void;
     /** Raise a Mudlet event on the Lua side (deferred if a dispatch is live). */
     emitEvent(name: string, args: unknown[]): void;
+    /** Park the dispatch state (`command`, `matches`, …) the calling script is
+     *  holding before running an alias pass of its own, and hand it back at the
+     *  depth the push answered with. See LuaRuntime.pushNestedDispatchState. */
+    pushNestedDispatchState(parkCommand?: boolean): number;
+    /** Whether an alias or trigger pass is running a script now — the
+     *  nesting desktop's feedTriggers parks the caller's captures for. */
+    inDispatchPass(): boolean;
+    popNestedDispatchState(depth: number): void;
+    /** Whether `matches`/`multimatches` are being built — see
+     *  LuaRuntime.buildingCaptureTables. */
+    buildingCaptureTables(): boolean;
     /** This profile's virtual filesystem, or null before one is mounted.
      *  Never reassigned after the runtime is constructed, so a plain reference
      *  is safe here. */
     readonly vfs: ProfileVFS | null;
+    /** The bytes behind a path in the read-only `/lua/` namespace (the bundled
+     *  Lua, and in busted builds the spec corpus and its fixtures), or null
+     *  for any other path. See LuaRuntime.readBuiltinBytes. */
+    readBuiltinBytes(path: string): Uint8Array | null;
     /** Drop a Lua-side callback registration by id (the registry slot behind
-     *  `__mudix_register_cb`). Distinct from {@link releaseCb}, which goes
+     *  `__mudlet_register_cb`). Distinct from {@link releaseCb}, which goes
      *  through Lua; this is the direct JS-side removal. */
     unregisterCb(cbId: number): void;
     /** Marshal a JS value onto the Lua stack. Used by the raw lua_CFunction
@@ -78,6 +93,9 @@ export interface BindingContext {
      *  leaking it. Mutated in place and never reassigned, so a reference is
      *  enough. */
     readonly overlayCmdLineActionCbIds: Map<string, number>;
+    /** The same for a miniconsole's or user window's own command line, keyed
+     *  by the window's name. */
+    readonly windowCmdLineActionCbIds: Map<string, number>;
     /** Run a registerMapInfo callback and read back what it produced. */
     evaluateMapInfo(cbId: number, roomId: number | null, selectionSize: number, areaId: number, displayedAreaId: number): MapInfoEvaluation | null;
     /** Run a `setExitWeightFilter` callback for one candidate exit and read

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

@@ -6,4 +6,4 @@ import type { BindingContext } from './context';
  * than with the console: raising a script error the editor can attribute, and
  * expanding an alias without executing it.
  */
-export declare function installDiagnosticsBindings({ lua, api }: BindingContext): void;
+export declare function installDiagnosticsBindings({ lua, api, pushNestedDispatchState, popNestedDispatchState, buildingCaptureTables }: BindingContext): void;

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

@@ -1,2 +1,2 @@
 import type { BindingContext } from './context';
-export declare function installMapBindings({ lua, api, vfs, channel, emitEvent, unregisterCb, pushJsValue, registerRawGlobal, evaluateMapInfo, evaluateExitWeightFilter, }: BindingContext): void;
+export declare function installMapBindings({ lua, api, vfs, readBuiltinBytes, channel, emitEvent, unregisterCb, pushJsValue, registerRawGlobal, evaluateMapInfo, evaluateExitWeightFilter, }: BindingContext): void;

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

@@ -4,11 +4,11 @@ import type { BindingContext } from './context';
  * Mudlet playSoundFile / playMusicFile / stopSounds / stopMusic and friends.
  * Web Audio backend lives on session.sounds.
  */
-export declare function installSoundBindings({ lua, api }: BindingContext): void;
+export declare function installSoundBindings(ctx: BindingContext): void;
 /**
  * Mudlet playVideoFile / pauseVideos / stopVideos.
  * Same VFS-or-URL loader as sounds; videos mount on the main viewport.
- * playVideoFile(path [, volume, loops]) | playVideoFile{name=..., ...}.
+ * playVideoFile{name=..., ...} (table form only, as in Mudlet).
  */
 export declare function installVideoBindings({ lua, api }: BindingContext): void;
 /**

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

@@ -7,4 +7,4 @@ import type { BindingContext } from './context';
  * Colour channels are validated through the shared 0..255 coercion; Mudlet
  * silently no-ops on an out-of-range channel rather than raising.
  */
-export declare function installOutputBindings({ lua, api }: BindingContext): void;
+export declare function installOutputBindings({ lua, api, pushNestedDispatchState, popNestedDispatchState, inDispatchPass }: BindingContext): void;

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

@@ -3,7 +3,7 @@ import type { BindingContext } from './context';
 /**
  * Session-level introspection and event raising: stopwatches, the console
  * width, connection info, desktop notifications, screen-reader announcements,
- * the clock, and raiseEvent / raiseGlobalEvent.
+ * the clock, and raiseGlobalEvent (raiseEvent lives in Bridge.lua).
  *
  * These share no subsystem - what groups them is that each answers a question
  * about (or acts on) the session as a whole rather than a specific window,
@@ -13,4 +13,4 @@ import type { BindingContext } from './context';
  * and passed in: it needs the runtime's event emitter and the live profile
  * name, neither of which belongs in this module.
  */
-export declare function installSessionBindings({ lua, api, emitEvent }: BindingContext, globalEvents: GlobalEventChannel): void;
+export declare function installSessionBindings({ lua, api, registerRawGlobal }: BindingContext, globalEvents: GlobalEventChannel): void;

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

@@ -6,4 +6,4 @@ import type { BindingContext } from './context';
  * Backed by TextEditManager, which is a pure data-model registry; the React
  * overlay renders whatever the model holds.
  */
-export declare function installTextEditBindings({ lua, api, channel }: BindingContext): void;
+export declare function installTextEditBindings({ lua, api, channel, emitEvent }: BindingContext): void;

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

@@ -8,4 +8,4 @@ import type { BindingContext } from './context';
  * Lua-side callback slots the widget had bound before dropping it, or the
  * registry entry leaks for the lifetime of the runtime.
  */
-export declare function installUserWindowBindings({ lua, api, emitEvent, unregisterCb, overlayCmdLineActionCbIds, }: BindingContext): void;
+export declare function installUserWindowBindings({ lua, api, emitEvent, unregisterCb, overlayCmdLineActionCbIds, windowCmdLineActionCbIds, vfs, }: BindingContext): void;

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

@@ -0,0 +1,36 @@
+/**
+ * Binary armoring across the wasmoon bridge.
+ *
+ * wasmoon marshals strings between Lua and JS with emscripten's UTF8ToString /
+ * stringToUTF8: Lua→JS stops at the first NUL byte and UTF-8-*decodes* the
+ * rest, JS→Lua re-encodes chars >= 0x80 as multi-byte UTF-8. That is fine for
+ * text and silently destructive for bytes — `feedTelnet("\229\254\13")` does
+ * not deliver 0xE5 0xFE 0x0D, it delivers U+5F8D, because those three bytes
+ * happen to look like one three-byte sequence to the decoder. A replay file's
+ * int32 headers lost every \0 the same way.
+ *
+ * So every binding that carries game *bytes* rather than text crosses armored
+ * as pure ASCII: a marker char (\2 = raw, \1 = encoded) followed by the payload
+ * with NUL, '%' and 0x80–0xFF written as %XX escapes. `__mudlet_armor` /
+ * `__mudlet_unarmor` in Bridge.lua are the Lua half of the same scheme, and
+ * VFS.lua takes them as locals for its hot paths.
+ *
+ * A payload is a *byte-string*: one JS char per byte, 0x00–0xFF, which is what
+ * the socket layer produces and what every telnet/encoding path downstream
+ * expects.
+ */
+/** Byte-string → armored ASCII, for a value on its way into Lua. */
+export declare function armor(s: string): string;
+/** Armored ASCII → byte-string, for a value that has just come out of Lua. */
+export declare function unarmor(s: string): string;
+/**
+ * An event argument that is bytes rather than text — desktop's
+ * ARGUMENT_TYPE_BYTES (sysTelnetEvent's payload). Handed to
+ * `LuaRuntime.emitEvent` in place of a string, it crosses armored and reaches
+ * the handlers as a Lua string of exactly those bytes, NULs and 0x80–0xFF
+ * included, where a plain string argument would be UTF-8-encoded on the way.
+ */
+export declare class LuaBytes {
+    readonly bytes: string;
+    constructor(bytes: string);
+}

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

@@ -2,3 +2,10 @@ export declare function parseImageSize(b: Uint8Array): {
     width: number;
     height: number;
 } | null;
+/**
+ * Whether `bytes` hold something a QPixmap or QSvgRenderer would load, judged
+ * by content the way Qt's image readers are: a recognised raster header, an
+ * ICO/CUR or TIFF signature, or an SVG candidate (markup or gzip). A missing
+ * file, a text file, or an empty one is not an image.
+ */
+export declare function looksLikeImage(b: Uint8Array): boolean;

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

@@ -1,3 +1,5 @@
 import type { Lua } from 'wasmoon-lua5.1';
-/** Register __rex_* JS helpers and put rex_pcre2 into package.loaded. */
-export declare function setupRex(lua: Lua): Promise<void>;
+/** Register the __rex_* JS helpers and build the module. `run` executes the
+ *  module's Lua source — LuaRuntime compiles it as its own ("=[C]") code, since
+ *  desktop's rex is the lrexlib C library. */
+export declare function setupRex(lua: Lua, run?: (code: string) => void): Promise<void>;

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

@@ -1 +1,6 @@
-export declare function encodeRowsToLuaSource(rows: unknown[][]): string;
+/** Raw bytes as a Lua string literal: printable ASCII as itself, everything
+ *  else as a `\DDD` escape. The source is pure ASCII, so it crosses the wasmoon
+ *  bridge without being UTF-8 re-encoded — the bytes Lua gets are the bytes. */
+export declare function encodeLuaBytes(buf: Uint8Array): string;
+/** One row as a Lua array literal: `{...}`. */
+export declare function encodeRowToLuaSource(row: unknown[]): string;

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

@@ -0,0 +1 @@
+export declare function utf8CaseMap(): string;

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

@@ -3,7 +3,7 @@
  * 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
+ * library, so Mudlet Web 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:
  *
@@ -57,3 +57,23 @@ export type LuaFindResult =
  * 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;
+/**
+ * `utf8.gsub` / `utf8.gmatch` walk the subject in BYTES, as luautf8 does, so
+ * their native search reports bytes: the first match at or after the 1-based
+ * byte position `initByte` (a character boundary), as `[first byte, byte after
+ * the match, capture…]`. Null when the pattern needs the Lua matcher, and for
+ * a subject or pattern holding U+FFFD — which is also what invalid UTF-8
+ * becomes on its way over the bridge, and luautf8 raises on that.
+ */
+export declare function findLuaPatternBytes(subject: string, pattern: string, initByte: number): {
+    start: number;
+    end: number;
+    captures: string[];
+} | false | null;
+/**
+ * Whether codepoint `cp` is in Lua class `%<cl>` (lowercase: the class itself),
+ * by the same Unicode tables the native matcher uses — for luautf8's own
+ * matcher in utf8.lua, which takes the patterns a regex cannot express. `%t`
+ * is luautf8's "compose" class, the combining marks.
+ */
+export declare function luaClassMatches(cl: string, cp: number): boolean;

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

@@ -0,0 +1,40 @@
+/**
+ * Unpaired UTF-16 surrogates on their way into Lua.
+ *
+ * A buffer edit by column can split a surrogate pair — selectSection() over
+ * half an emoji, insertText() between its halves — and leave a lone surrogate
+ * in the line, exactly as it does in Mudlet's QString buffer. What differs is
+ * the trip into Lua. Mudlet converts with QString::toUtf8(), whose encoder
+ * drops a lone surrogate outright (its error handler writes a '?' through a
+ * copy of the output pointer, so the next character overwrites it). wasmoon
+ * converts with emscripten's stringToUTF8, which assumes every high surrogate
+ * is followed by a low one: it fuses a lone high surrogate with whatever comes
+ * next, swallowing that character into a bogus astral code point, and turns a
+ * lone low surrogate into a four-byte sequence too. So `getSelection()` over
+ * the first half of 😀 answered U+1F400 🐀 instead of desktop's "".
+ *
+ * Every JS string wasmoon hands to Lua goes through `lua_pushstring`, so that
+ * one entry point drops lone surrogates the way toUtf8() does.
+ */
+/** `s` without its unpaired surrogates, as QString::toUtf8() would encode it. */
+export declare function dropLoneSurrogates(s: string): string;
+interface PushStringApi {
+    lua_pushstring: (L: number, s: string | null) => void;
+}
+/** Make `api.lua_pushstring` drop lone surrogates from the strings it pushes. */
+export declare function installWellFormedPush(api: PushStringApi): void;
+interface ToLStringApi {
+    lua_tolstring: (L: number, index: number, size: number | null) => string;
+    module: {
+        _lua_tolstring: (L: number, index: number, size: number) => number;
+        HEAPU8: Uint8Array;
+    };
+}
+/** QString::fromUtf8 over bytes that are not valid UTF-8: every byte that does
+ *  not start a whole, valid sequence is one U+FFFD. Exported for tests. */
+export declare function decodeUtf8LikeQt(bytes: Uint8Array): string;
+/** Make `api.lua_tolstring` decode the way QString::fromUtf8 does. It still
+ *  stops at the first NUL, as UTF8ToString did, so nothing that relied on
+ *  that changes. */
+export declare function installDesktopUtf8Read(api: ToLStringApi): void;
+export {};

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

@@ -1,11 +1,49 @@
-import type { Lua } from 'wasmoon-lua5.1';
-export type LuaValueTransform = (v: unknown) => unknown;
+import { type Lua } from 'wasmoon-lua5.1';
+type LuaApi = Lua['global']['luaApi'];
+type LuaState = Lua['global']['address'];
+/**
+ * Stands for JSON null in a JS value about to be pushed to Lua; the raw pusher
+ * swaps it for the registry's `yajl.null` userdata. The GMCP/MSDP bridge never
+ * hands wasmoon the sentinel itself: wasmoon reads a userdata's first word as
+ * one of its own JS references, which is why the userdata built here is
+ * zero-filled (reference 0 is unused, so wasmoon sees `undefined`).
+ */
+export declare const YAJL_NULL: unique symbol;
+/**
+ * The deepest container nesting lua_yajl's to_value accepts: one more and
+ * lua_checkstack fails (see the header). Measured from the C, not guessed —
+ * 3 base slots + 3 per open level + the 4 it asks for must stay ≤ 8000.
+ */
+export declare const MAX_DECODE_DEPTH = 2665;
+/** The error lua_yajl raises past MAX_DECODE_DEPTH (luaL_error from a C frame: no position). */
+export declare const DECODE_DEPTH_ERROR = "lua stack overflow";
 /**
  * Serialise a JSON-decoded value as a Lua chunk returning it. The chunk takes
  * the null sentinel as its vararg so nulls survive without a global lookup.
  * Returns null when the value nests too deeply to express as source.
  */
 export declare function luaChunkForValue(v: unknown): string | null;
-export declare function setupYajl(lua: Lua): {
-    transform: LuaValueTransform;
-};
+/** Container nesting depth of a JSON value (a scalar is 0, `[]` is 1), without recursing. */
+export declare function jsonDepth(root: unknown): number;
+/**
+ * Push a JSON-shaped value (plain arrays/objects/scalars, `null` or YAJL_NULL
+ * for JSON null) onto `L` with the raw lua_* API, the way lua_yajl's to_value
+ * builds it: arrays 1-indexed, nulls as the registry `yajl.null`.
+ *
+ * Iterative, so neither the JS nor the C stack grows with the document's depth
+ * — wasmoon's own pushValue recursed and wrote past the Lua stack, which is the
+ * "memory access out of bounds" that used to kill the VM on a deep document.
+ * Returns false, having pushed nothing, when the value is nested deeper than
+ * lua_yajl accepts (MAX_DECODE_DEPTH) or the Lua stack can't take it.
+ */
+export declare function pushJsonValue(api: LuaApi, L: LuaState, root: unknown): boolean;
+export interface YajlBridge {
+    /**
+     * Push a JSON-decoded value (JSON.parse output) onto `L` exactly as
+     * yajl.to_value would build it. False, with nothing pushed, if it is too
+     * deep for lua_yajl (see pushJsonValue).
+     */
+    pushValue(L: LuaState, value: unknown): boolean;
+}
+export declare function setupYajl(lua: Lua, registerRawGlobal: (name: string, fn: (L: LuaState) => number) => void): YajlBridge;
+export {};

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

@@ -1,10 +1,10 @@
 /**
  * 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
+ * Mudlet's `getProfiles()`. Mudlet Web 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
+ *    Lock named `mudlet: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
@@ -20,6 +20,13 @@
  * 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.
+ *
+ * The same channel carries `closeProfile(name)` for a profile open in another
+ * tab: the caller broadcasts `close` with the target's id and the tab owning it
+ * closes itself through {@link onCloseRequested}. `setActiveProfile(name)` for
+ * a profile open in another tab sends `attention` the same way: a page cannot
+ * bring another tab forward, so the owning tab flags itself instead
+ * ({@link onAttentionRequested}).
  */
 export declare class ProfilesPresence {
     private readonly ownId;
@@ -31,6 +38,11 @@ export declare class ProfilesPresence {
     private loaded;
     /** Last-announced connected state of OTHER tabs' profiles. */
     private readonly remoteConnected;
+    /** Called when another tab asks this profile to close (`closeProfile`). */
+    onCloseRequested: (() => void) | null;
+    /** Called when another tab asks this profile to come to the front
+     *  (`setActiveProfile`). */
+    onAttentionRequested: (() => void) | null;
     constructor(ownId: string, 
     /** This tab's live connected state, read whenever we announce. */
     localConnected: () => boolean, refreshMs?: number);
@@ -40,6 +52,12 @@ export declare class ProfilesPresence {
     /** Connection ids of all loaded profiles (best-effort snapshot, always
      *  including this profile's own id). */
     loadedIds(): string[];
+    /** Ask the tab that has profile `id` open to close it. False when there is
+     *  no channel to carry the request (the other tab cannot be reached). */
+    requestClose(id: string): boolean;
+    /** Ask the tab that has profile `id` open to draw the user's attention to
+     *  itself. False when there is no channel to carry the request. */
+    requestAttention(id: string): boolean;
     /** 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. */

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

@@ -1,4 +1,30 @@
 export type VFSSource = 'folder' | 'idb';
+/** How long an appended tail waits in memory before it is written out. */
+export declare const APPEND_FLUSH_MS = 500;
+/** A tail that has grown this large is written out at once. */
+export declare const APPEND_FLUSH_BYTES: number;
+/** {@link ProfileVFS.lstat}: a stat that can also be about a symbolic link. */
+export type VfsLstat = Omit<VfsStat, 'type'> & {
+    type: VfsStat['type'] | 'link';
+};
+export interface VfsStat {
+    type: 'file' | 'dir';
+    size: number;
+    mtime: Date;
+    atime: Date;
+    /** Inode change time — what `lfs.attributes` reports as `change`. */
+    ctime: Date;
+    /** The full `st_mode`: file type bits and permission bits. */
+    mode: number;
+    dev: number;
+    ino: number;
+    nlink: number;
+    uid: number;
+    gid: number;
+    rdev: number;
+    blocks: number;
+    blksize: number;
+}
 export declare class ProfileVFS {
     readonly connectionId: string;
     readonly profilePath: string;
@@ -7,16 +33,57 @@ export declare class ProfileVFS {
     private _handle?;
     readonly source: VFSSource;
     readonly folderName?: string;
+    private readBarrier;
+    private writeObserver;
+    /** See {@link writeGeneration}. Bumped in afterWrite, the one place every
+     *  write, removal and rename already reports through. */
+    private readonly writeGenerations;
+    /** See {@link appendBinaryFile}. Keyed by absolute path. */
+    private readonly pendingAppends;
+    private appendFlushTimer;
     private constructor();
     static mount(connectionId: string): Promise<ProfileVFS>;
     private static doMount;
     get cwd(): string;
+    /**
+     * Run `barrier` with a file's absolute path before anything reads it.
+     * The sql bridge uses it to write a database's pending changes out first,
+     * so a file a script (or the file browser, or an upload) reads right after
+     * a db:add holds that row, as desktop's database file would. Null removes it.
+     */
+    setReadBarrier(barrier: ((absPath: string) => void) | null): void;
+    /**
+     * Install (or clear, with null) a hook told after a file has been written
+     * ('write') or removed, renamed away or replaced by a rename, or had its
+     * directory removed ('remove'). The sql bridge uses it so a database file
+     * changed underneath an open connection is changed for that connection
+     * too, as a file on disk is.
+     */
+    setWriteObserver(observer: ((absPath: string, kind: 'write' | 'remove') => void) | null): void;
+    private afterWrite;
+    private beforeRead;
     resolvePath(path: string): string;
+    /** Whether a component of `path` is longer than NAME_MAX — for a caller
+     *  that must refuse such a name before it writes (io.open, as fopen does). */
+    nameTooLong(path: string): boolean;
     exists(path: string): boolean;
     readFile(path: string): string;
     readBinaryFile(path: string): Uint8Array;
+    /**
+     * A count that moves whenever the file at `path` is written, removed or
+     * renamed through this VFS, and never otherwise. For a reader that holds a
+     * file's bytes and must notice when they have gone stale, without reading
+     * the whole file again to find out — a replay being played comes back to
+     * its file once a chunk. A stat cannot stand in for it: mtime is in
+     * milliseconds, and a rewrite in place keeps the size.
+     */
+    writeGeneration(path: string): number;
     writeFile(path: string, content: string): void;
-    writeBinaryFile(path: string, data: Uint8Array): void;
+    /** `createParents: false` writes only into a directory that already exists,
+     *  throwing as open(2) would otherwise — what a download's QFile does. */
+    writeBinaryFile(path: string, data: Uint8Array, { createParents }?: {
+        createParents?: boolean;
+    }): void;
     /**
      * The linked-folder (WebAccess / FileSystemDirectoryHandle) backend overwrites
      * a file from offset 0 but does NOT shrink it, so writing shorter content over
@@ -27,17 +94,104 @@ export declare class ProfileVFS {
      */
     private clearForOverwrite;
     appendFile(path: string, content: string): void;
+    /**
+     * Add `data` to the end of a file, creating it when missing — what Lua's
+     * io.open(f, "a") writes through. The read barrier runs first so the bytes
+     * land after anything a database still has pending for that file.
+     *
+     * ZenFS keeps a file as one value in its store, and an append reads that
+     * value, copies it one longer and puts the whole of it back, so every
+     * append cost the size of the file: a chat log EMCO appends a line to
+     * per message took 30 ms a line at 5 MB (#457), where desktop's write is
+     * the line's bytes. So the bytes appended to a file already in the store
+     * are held here and written out together — after APPEND_FLUSH_MS, once
+     * they reach APPEND_FLUSH_BYTES, or as soon as anything reads, stats,
+     * rewrites, moves or removes the file (every such path goes through
+     * {@link settle}), and when the page is hidden or goes away. One write per
+     * window instead of one per line, and nothing can see the file without
+     * the tail: {@link stat} counts it into the size and {@link exists} knows
+     * the file is there.
+     *
+     * A file that is not there yet, a link, or an append while the page is
+     * going away is written straight through, as before.
+     */
+    appendBinaryFile(path: string, data: Uint8Array): void;
+    /** A regular file in the store with only this one name — the only kind
+     *  whose appends can be held: a held tail is found again by its path. */
+    private isPlainFile;
+    private scheduleAppendFlush;
+    /**
+     * Write out the appended bytes held for `scope` — that file, or every
+     * file under it when it is a directory — or for every file when omitted.
+     * Returns `scope`, so a path can be settled on its way into a call.
+     */
+    flushAppends(scope?: string): string | undefined;
+    /** {@link flushAppends} for one absolute path, returned for chaining. */
+    private settle;
     deleteFile(path: string): void;
-    rename(oldPath: string, newPath: string): void;
-    mkdir(path: string): void;
-    rmdir(path: string): void;
+    /**
+     * Move a file or directory. By default a missing parent of the target is
+     * created, which the app's own callers rely on. `{ posix: true }` is
+     * `rename(2)`, what Lua's `os.rename` is on desktop: the target's directory
+     * must already exist (ENOENT, or ENOTDIR under a file), a directory may
+     * replace only an empty directory (ENOTEMPTY otherwise, ENOTDIR for a
+     * file) and never move into itself (EINVAL), and a file never replaces a
+     * directory (EISDIR).
+     */
+    rename(oldPath: string, newPath: string, { posix }?: {
+        posix?: boolean;
+    }): void;
+    /**
+     * Create a directory. By default the whole chain is created and an existing
+     * directory is not an error, which is what the app's own callers want.
+     * `{ recursive: false }` is POSIX `mkdir(2)` — what LuaFileSystem's
+     * `lfs.mkdir` does on desktop: a missing parent is ENOENT, a parent that is
+     * a file is ENOTDIR, and an existing path is EEXIST.
+     */
+    mkdir(path: string, { recursive }?: {
+        recursive?: boolean;
+    }): void;
+    /**
+     * Remove a directory. By default it goes with everything in it — the app's
+     * own callers (the file browser, package reinstalls) mean exactly that.
+     * `{ recursive: false }` is POSIX `rmdir(2)`, what `lfs.rmdir` does on
+     * desktop: only an empty directory is removed, and a non-empty directory
+     * (ENOTEMPTY), a plain file (ENOTDIR) or a missing path (ENOENT) is left
+     * alone and reported. A script must never be able to wipe a folder of
+     * saved data with a call that desktop refuses.
+     */
+    rmdir(path: string, { recursive }?: {
+        recursive?: boolean;
+    }): void;
+    /**
+     * C's `remove(3)`, which Lua's `os.remove` is: a file is unlinked and an
+     * empty directory is removed, as `rmdir(2)` would.
+     */
+    remove(path: string): void;
+    /**
+     * The parts of the kernel's path walk that `resolvePath`'s normalising
+     * would hide: an empty path names nothing (ENOENT), a plain file can't
+     * have anything under it (ENOTDIR), and a path ending in "." or ".." is
+     * refused with `dotErrno` — the profile root is not what `os.remove(".")`
+     * means.
+     */
+    private checkPosixPath;
+    /**
+     * Set a path's access and modification times (`utime(2)`), which is all
+     * `lfs.touch` does — it never creates a file.
+     */
+    touch(path: string, atime: Date, mtime: Date): void;
     readdir(path: string): string[];
-    stat(path: string): {
-        type: 'file' | 'dir';
-        size: number;
-        mtime: Date;
-        atime: Date;
-    } | null;
+    stat(path: string): VfsStat | null;
+    /** `lstat(2)`: like {@link stat}, but about a symbolic link itself, which
+     *  reports as type `link`. Throws the filesystem's error (ENOENT …). */
+    lstat(path: string): VfsLstat;
+    /** `readlink(2)`: a symbolic link's target, as stored. */
+    readlink(path: string): string;
+    /** `link(2)` / `symlink(2)` — what `lfs.link` makes. A symbolic link's
+     *  target is stored as given (it may be relative, or dangle); a hard link's
+     *  must exist. Throws the filesystem's error (EEXIST, ENOENT, ENOTSUP …). */
+    link(target: string, path: string, symbolic: boolean): void;
     chdir(path: string): string | null;
     /**
      * Drain queued async writes to the underlying backend. For folder-backed

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

@@ -0,0 +1,28 @@
+/**
+ * Filesystem errors in the shape C's `strerror`/`errno` give them, so the Lua
+ * `io`/`os`/`lfs` bindings can report failures the way stock Lua and
+ * LuaFileSystem do on desktop Mudlet: `nil, "<message>", <errno>`.
+ *
+ * ZenFS already throws errors carrying Linux errno numbers and codes, but its
+ * messages are its own ("EISDIR: File is a directory, open '/a'"), and scripts
+ * that match on the text — or show it to the player — expect glibc's wording.
+ */
+/** Linux errno numbers, for errors raised here rather than by ZenFS. */
+declare const ERRNO: Record<string, number>;
+export type FsErrorCode = keyof typeof ERRNO & string;
+/** An error thrown by ProfileVFS's own checks, shaped like ZenFS's. */
+export declare class FsError extends Error {
+    readonly code: FsErrorCode;
+    readonly path?: string | undefined;
+    readonly errno: number;
+    constructor(code: FsErrorCode, path?: string | undefined);
+}
+export interface FsErrorDescription {
+    /** The `strerror` text, or the error's own message when it has no errno code. */
+    message: string;
+    /** The errno number, when the error carries one. */
+    errno?: number;
+}
+/** Reduce anything thrown by the VFS to `strerror` text and an errno. */
+export declare function describeFsError(e: unknown): FsErrorDescription;
+export {};

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

@@ -0,0 +1,20 @@
+import type { FileSystem } from '@zenfs/core';
+/**
+ * Make every synchronous write to an IndexedDB-backed StoreFS commit its
+ * IndexedDB transaction there and then (#438).
+ *
+ * ZenFS issues a sync write's put/delete requests at once, but never calls
+ * `IDBTransaction.commit()` — its `commitSync()` only marks the wrapper done
+ * — so the transaction is left to auto-commit. Chromium auto-commits from the
+ * page: once the requests' success events have been delivered back to it. A
+ * write made while the page is going away (sysExitEvent on pagehide, where
+ * Geyser's Adjustable.Container saves its layout) never gets those events, so
+ * the transaction is aborted with the page and the file is lost. An explicit
+ * commit hands the decision to the database itself, which finishes the
+ * transaction whether or not the page is still there to hear about it.
+ *
+ * Only the sync path is touched: async operations await their requests
+ * across tasks, and nothing here is in a hurry. A transaction that already
+ * finished (it had nothing to do) refuses `commit()`; that is not an error.
+ */
+export declare function commitSyncWritesImmediately(fs: FileSystem): void;