@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -3,11 +3,16 @@ export interface StopwatchStore {
     load(): string | null;
     save(data: string): void;
 }
+/** localStorage key holding one profile's stopwatches. Shared with the
+ *  profile-deletion sweep (storage/profileStorage) so the two can't drift. */
+export declare function stopwatchStorageKey(connectionId: string): string;
 /** Build a localStorage-backed store scoped to a connection, or undefined when
  *  localStorage is unavailable (tests / SSR) — in which case persistence is a
  *  no-op and watches behave as memory-only. */
 export declare function localStorageStopwatchStore(connectionId: string): StopwatchStore | undefined;
-/** Broken-down elapsed time, mirroring Mudlet's generateElapsedTimeTable. */
+/** Broken-down elapsed time, mirroring Mudlet's generateElapsedTimeTable —
+ *  what getStopWatchBrokenDownTime answers, which calls it with
+ *  includeDecimalSeconds false. */
 export interface BrokenDownTime {
     negative: boolean;
     days: number;
@@ -15,6 +20,10 @@ export interface BrokenDownTime {
     minutes: number;
     seconds: number;
     milliSeconds: number;
+}
+/** The elapsedTime getStopWatches reports per watch: the same table with
+ *  generateElapsedTimeTable's includeDecimalSeconds on. */
+export interface ElapsedTime extends BrokenDownTime {
     /** Signed total seconds (matches Mudlet's elapsedMilliSeconds / 1000). */
     decimalSeconds: number;
 }
@@ -23,72 +32,124 @@ export interface StopwatchSummary {
     name: string;
     isRunning: boolean;
     isPersistent: boolean;
-    elapsedTime: BrokenDownTime;
+    elapsedTime: ElapsedTime;
 }
+/** A persistent stopwatch as a profile save holds it. */
+export type SavedStopwatch = {
+    id: number;
+    name: string;
+} & ({
+    running: true;
+    effectiveStartEpochMs: number;
+} | {
+    running: false;
+    elapsedMs: number;
+});
+/**
+ * How a stopwatch was asked for: a number is an ID, a string is a name — only
+ * a Lua number is an ID, so "5" names a stopwatch called 5 (Mudlet tests the
+ * argument with `lua_type(L, 1) == LUA_TNUMBER`). The empty name stands for the
+ * first (lowest ID) unnamed stopwatch.
+ */
+export type StopwatchSubject = number | string;
+/**
+ * A refusal, in the words Mudlet's `Host` and `TLuaInterpreter` use for it —
+ * the binding hands it to Lua as the second value after nil.
+ */
+export type StopwatchRefusal = {
+    refused: string;
+};
+export declare const isRefusal: (v: unknown) => v is StopwatchRefusal;
 export declare class StopwatchManager {
     private readonly storage?;
     private readonly watches;
-    private nextId;
     constructor(storage?: StopwatchStore | undefined);
     private now;
     private elapsedMs;
+    /** Watches in ascending ID order — Mudlet's std::map, which is what makes
+     *  "the first unnamed stopwatch" the lowest-numbered one. */
+    private ordered;
+    /** Host::findStopWatchId — the first watch with this name, '' finding the
+     *  first unnamed one. */
+    private findByName;
     /**
-     * Resolve a watchID-or-name argument. Numbers (and numeric strings, which
-     * Mudlet's lua_isnumber treats as ids) look up by id; other strings look up
-     * by name. An empty string returns the first unnamed watch — Mudlet's
-     * findStopWatchId("") behaviour.
+     * Look a subject up, or answer the refusal for one that is not there.
+     * `idWord` is the one place the family disagrees with itself: the
+     * functions that go through `TLuaInterpreter::csmInvalidStopWatchID` say
+     * "ID", the ones whose message comes from `Host` say "id".
      */
-    private resolve;
+    private lookup;
+    /** The refusal looking `subject` up gives where TLuaInterpreter's own
+     *  csmInvalidStopWatchID words it ("ID"), or null when the watch exists. */
+    missing(subject: StopwatchSubject): StopwatchRefusal | null;
+    /** How Host names a watch in an "already" refusal: the way it was asked for. */
+    private describe;
     /** Rehydrate persistent watches from the backing store (called once on construction). */
     private restore;
+    /** The persistent watches as desktop's profile save writes them
+     *  (XMLexport's `<stopwatches>`): a running one by the moment it would have
+     *  started to reach its elapsed time, a stopped one by that time. */
+    savedForProfile(now?: number): SavedStopwatch[];
     /** Write the current set of persistent watches to the backing store. */
     private persist;
+    private touched;
+    private startWatch;
+    private stopWatch;
+    /** A stopped watch goes back to never-started; a running one restarts
+     *  from zero and keeps running. One never started has nothing to reset. */
+    private resetWatch;
     /**
-     * Mudlet createStopWatch([name], [autostart]). Returns the new id, or null
-     * when `name` is given and already in use (Mudlet rejects duplicate names).
+     * Mudlet createStopWatch([name], [autostart]). Returns the new id, or the
+     * refusal when `name` is already in use (Mudlet rejects duplicate names).
      */
-    create(name: string, autoStart: boolean): number | null;
+    create(name: string, autoStart: boolean): number | StopwatchRefusal;
     /**
      * Mudlet startStopWatch. `resetAndRestart` replicates the legacy behaviour
-     * for a numeric id called bare: reset to zero and run from there. Otherwise
-     * a stopped watch resumes and a running one is left untouched. Returns false
-     * for an unknown watch.
+     * for a numeric id called bare: reset to zero and run from there, which
+     * always succeeds. Asked to keep the elapsed time instead, starting one
+     * that is already running is refused.
      */
-    start(arg: number | string, resetAndRestart: boolean): boolean;
+    start(subject: StopwatchSubject, resetAndRestart: boolean): true | StopwatchRefusal;
     /**
      * Mudlet stopStopWatch. Pauses the watch and returns the elapsed seconds
-     * once (legacy behaviour preserved by Mudlet). null for an unknown watch.
+     * once (legacy behaviour preserved by Mudlet). Stopping one that is
+     * already stopped — including one that was never started — is refused.
      */
-    stop(arg: number | string): number | null;
+    stop(subject: StopwatchSubject): number | StopwatchRefusal;
     /** Mudlet getStopWatchTime — elapsed seconds without stopping. */
-    getTime(arg: number | string): number | null;
+    getTime(subject: StopwatchSubject): number | StopwatchRefusal;
     /** Mudlet getStopWatchBrokenDownTime — elapsed time as a day/hour/minute/
-     *  second/millisecond table. null for an unknown watch. */
-    getBrokenDownTime(arg: number | string): BrokenDownTime | null;
+     *  second/millisecond table. */
+    getBrokenDownTime(subject: StopwatchSubject): BrokenDownTime | StopwatchRefusal;
     /**
-     * Mudlet setStopWatchName(watchID|currentName, newName). Assigns or renames
-     * a watch. Returns false for an unknown watch, an empty new name, or when
-     * another watch already uses the new name (Mudlet rejects duplicate names).
+     * Mudlet `setStopWatchName(id|name, newName)` — Host::setStopWatchName.
+     * Refuses a name another stopwatch already carries, naming that one; the
+     * empty new name takes a watch's name away again.
      */
+    setName(subject: StopwatchSubject, newName: string): true | StopwatchRefusal;
+    /** Mudlet resetStopWatch — zero the elapsed time; a running watch keeps running. */
+    reset(subject: StopwatchSubject): true | StopwatchRefusal;
     /**
-     * Mudlet `setStopWatchName(id|name, newName)`. Refuses a name another
-     * stopwatch already carries, naming that one — the reason has to reach the
-     * caller, so this returns the message (null on success) rather than a bare
-     * boolean the binding would have to guess a reason for.
+     * Mudlet `adjustStopWatch` — add `seconds` (may be negative) to the elapsed
+     * time. Time that accumulates past the end of the range stops there; an
+     * adjustment asking for more than the whole range is refused with the
+     * reason, as every other out-of-range stopwatch argument is.
+     *
+     * It is the MILLISECONDS the adjustment rounds to that are bounded, since
+     * that is what a stopwatch keeps its time in, and the comparison is written
+     * so that a NaN or an infinity fails it too.
      */
-    setName(arg: number | string, newName: string): boolean | string;
-    /** Mudlet resetStopWatch — zero the elapsed time; a running watch keeps running. */
-    reset(arg: number | string): boolean;
-    /** Mudlet adjustStopWatch — add `seconds` (may be negative) to the elapsed time. */
-    adjust(arg: number | string, seconds: number): boolean;
+    adjust(subject: StopwatchSubject, seconds: number): true | StopwatchRefusal;
     /** Mudlet deleteStopWatch. */
-    delete(arg: number | string): boolean;
+    delete(subject: StopwatchSubject): true | StopwatchRefusal;
+    /** Host::removeAllNonPersistentStopWatches, which resetProfile() runs:
+     *  every watch not flagged persistent goes, freeing its ID. */
+    removeNonPersistent(): void;
     /**
      * Mudlet setStopWatchPersistence(id|name, state). Marks whether the watch is
-     * saved to (and restored from) the backing store across reloads. Returns
-     * false for an unknown watch.
+     * saved to (and restored from) the backing store across reloads.
      */
-    setPersistence(arg: number | string, state: boolean): boolean;
+    setPersistence(subject: StopwatchSubject, state: boolean): true | StopwatchRefusal;
     /** Mudlet getStopWatches — record keyed by stringified id (Bridge.lua re-keys to ints). */
     getAll(): Record<string, StopwatchSummary>;
 }

package/dist-lib/scripting/http/HttpService.d.ts

@@ -15,6 +15,7 @@ export declare class HttpService {
      *  bundled path resolves the same way Lua's io.open resolves it. */
     private readonly localReader;
     private readonly proxiedOrigins;
+    private readonly directOrigins;
     /**
      * The response record Mudlet hands to every HTTP event as its last argument:
      * `{ headers = {...}, cookies = {...} }`. Scripts read it to branch on what
@@ -31,12 +32,13 @@ export declare class HttpService {
     /** Consulted before the profile VFS when serving a `file:` URL, so a
      *  bundled path resolves the same way Lua's io.open resolves it. */
     localReader?: LocalReader);
-    downloadFile(saveTo: string, url: string): void;
+    downloadFile(saveTo: string, rawUrl: string): void;
     getHTTP(url: string, headers?: Record<string, string>): void;
     postHTTP(data: string | null, url: string, headers?: Record<string, string>, file?: string): void;
     putHTTP(data: string | null, url: string, headers?: Record<string, string>, file?: string): void;
     deleteHTTP(url: string, headers?: Record<string, string>): void;
     customHTTP(method: string, data: string | null, url: string, headers?: Record<string, string>, file?: string): void;
+    private upload;
     /**
      * Serve a `file:` URL out of the VFS, reporting through the same
      * sysDownloadDone/sysDownloadError a network download would.
@@ -66,8 +68,14 @@ export declare class HttpService {
      * its timer queue instead.
      */
     private emitLater;
+    /** Raise `event` unless it is '' — the "no event" a HEAD finishes with. */
+    private emitNamed;
     private bodyForUpload;
     private runRequest;
     private fetchWithFallback;
+    private fetchViaProxy;
+    private checkProxyReply;
+    private isProxied;
+    private answersCors;
 }
 export {};

package/dist-lib/scripting/http/userUrl.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Read a url the way Mudlet does before it issues any request: through
+ * `QUrl::fromUserInput`. Scripts pass bare `example.com/x` or `127.0.0.1:8080/x`
+ * and Mudlet means http by them. fetch() would instead resolve such a string
+ * *relative to the page* — fetching the web app's own index.html and reporting
+ * success — so every url is put through this before it goes anywhere.
+ *
+ * The rules, as fromUserInput has them:
+ *  - an absolute local path (`/x/y`) is a `file:` url;
+ *  - an explicit scheme is kept, unless what looks like one is really a host
+ *    followed by a port (`localhost:8080/x`), which gets http prepended;
+ *  - anything else gets http prepended.
+ *
+ * The result is the string the request goes to, the string the HTTP functions
+ * return, and the string their events report.
+ */
+export declare function normalizeUserUrl(raw: string): string;
+/** Why `raw` is not a usable url, or null when it is. */
+export declare function userUrlInvalidReason(raw: string): string | null;
+/**
+ * A `file:` url's host and fully decoded path, read the way QUrl reads them,
+ * or null when `url` is not a file url. Not the WHATWG parser: that one drops a
+ * `localhost` host and folds a path that starts `//` into the host, both of
+ * which the checks below need to see.
+ */
+export declare function fileUrlParts(url: string): {
+    host: string;
+    path: string;
+} | null;
+/**
+ * Why Mudlet refuses `raw` before issuing a request, as the whole reason that
+ * follows "url is invalid, reason: " (TLuaInterpreter::getHTTP and friends), or
+ * null when it may be used.
+ *
+ * Only http and https may be fetched: file:, qrc:, data: and the like would hand
+ * local or bundled content back as though it had been downloaded. downloadFile()
+ * alone also takes a local file — it copies to a path the script chose rather
+ * than handing the content back — but only one on this machine: a file url
+ * naming another host, or a path naming a share, is a network path on Windows.
+ */
+export declare function userUrlRefusal(raw: string, allowLocalFile: boolean): string | null;