@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -1,10 +1,20 @@
 import React from 'react';
+import type { TriggerPatternType } from '../../../storage/schema';
 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'>;
+/** The `text` a pattern row should carry after its type changes.
+ *
+ *  `colorTrigger` stores `"fg,bg"` and `lineSpacer` stores a line count, so
+ *  neither can inherit a regex left over from the previous type — and a regex
+ *  must not inherit `"-1,-1"` or `"2"` either. Mudlet gets this for free by
+ *  giving each type its own widget (`dlgTriggerEditor.cpp:7196-7239`); here one
+ *  `text` field is shared, so it is reset explicitly whenever the type crosses
+ *  into or out of one of the two structured kinds. */
+export declare function retypePatternText(text: string, from: TriggerPatternType, to: TriggerPatternType): string;
 interface ScriptEditorPanelProps {
     connectionId: string;
     session: MudSession;
@@ -19,6 +29,10 @@ 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;
+    /** Show the Variables tab with its filter set to the named top-level global.
+     *  Desktop selects the row in its variables tree; filtering is the same job
+     *  in a view that has no persistent selection. */
+    navigateToVariable: (name: string) => void;
 }
 export declare const ScriptEditorPanel: React.ForwardRefExoticComponent<ScriptEditorPanelProps & React.RefAttributes<ScriptEditorPanelHandle>>;
 export {};

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

@@ -1,12 +1,17 @@
+import React from 'react';
+import type { ScriptingEngine } from '../../../scripting/ScriptingEngine';
 import './ScriptSearch.css';
 export type EditCategory = 'scripts' | 'aliases' | 'triggers' | 'timers' | 'keys' | 'buttons';
 interface ScriptSearchProps {
     connectionId: string;
+    scriptingEngineRef?: React.RefObject<ScriptingEngine | null>;
     /** Navigate the editor to a matched item (and optionally a code line). */
     onNavigate: (category: EditCategory, id: string, line?: number) => void;
+    /** Show the Variables tab filtered to the named top-level global. */
+    onNavigateVariable?: (name: string) => 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 declare function ScriptSearch({ connectionId, scriptingEngineRef, onNavigate, onNavigateVariable }: ScriptSearchProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -2,6 +2,7 @@ import type { WindowManager } from '../WindowManager';
 import type { LabelManager } from '../../labels/LabelManager';
 import type { CommandLineManager } from '../../cmdline/CommandLineManager';
 import type { ScrollBoxManager } from '../../scrollbox/ScrollBoxManager';
+import { type MouseEventRegistry } from '../../MouseEventRegistry';
 interface TextPanelProps {
     id: string;
     /** Human-readable window title (defaults to the id), used as the accessible
@@ -11,6 +12,8 @@ interface TextPanelProps {
     labels?: LabelManager;
     cmdLines?: CommandLineManager;
     scrollBoxes?: ScrollBoxManager;
+    /** addMouseEvent entries, which desktop puts in every console's menu. */
+    mouseEvents?: MouseEventRegistry;
     fontSize?: number;
     fontFamily?: string;
     /** Rendered row height in px (MXP frames). See WindowManager.setLineHeight. */
@@ -33,5 +36,5 @@ interface TextPanelProps {
     cmdLineValue?: string;
     cmdLineValueSeq?: number;
 }
-export declare function TextPanel({ id, title, manager, labels, cmdLines, scrollBoxes, fontSize, fontFamily, lineHeight, wrapAt, wrapIndent, wrapHangingIndent, backgroundColor, backgroundImage, cmdLineEnabled, cmdLineStyleSheet, cmdLineValue, cmdLineValueSeq }: TextPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function TextPanel({ id, title, manager, labels, cmdLines, scrollBoxes, mouseEvents, fontSize, fontFamily, lineHeight, 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

@@ -2,20 +2,50 @@ import type { ScriptingEngine } from '../../../scripting/ScriptingEngine';
 interface VariablesViewProps {
     connectionId: string;
     scriptingEngineRef?: React.RefObject<ScriptingEngine | null>;
+    /** A search result asking for this top-level global to be brought into view.
+     *  `revision` makes a repeat jump to the same name re-apply the filter. */
+    focus?: {
+        name: string;
+        revision: number;
+    } | null;
+    /** Called once `focus` has been applied. The request lives in the parent,
+     *  which outlives this view — without clearing it, leaving the tab and
+     *  coming back would silently re-type the old name into the filter. */
+    onFocusConsumed?: () => void;
 }
+/**
+ * Re-point every hidden path that lived at `from` (or underneath it) at `to`,
+ * for a rename. Returns null when nothing referred to the old path, so the
+ * caller can skip a no-op store write.
+ *
+ * A descendant is spelled `from` followed by `.` or `[`, which are the only two
+ * separators {@link pathKey} emits — so `myTable` never captures `myTableTwo`.
+ */
+export declare function renameHiddenPaths(hidden: readonly string[], from: string, to: string): string[] | null;
+/** Drop every hidden path at `at` or underneath it, for a delete. Returns null
+ *  when none matched, so the caller can skip a no-op store write. */
+export declare function dropHiddenPaths(hidden: readonly string[], at: string): string[] | 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.
+ * save-list / Mudlet `<VariablePackage>`), and the create/rename/retype/edit/
+ * hide/delete controls desktop puts in `vars_main_area.ui` — name
+ * (`lineEdit_var_name:73`), key type (`comboBox_variable_key_type:105`), hidden
+ * (`checkBox_variable_hidden:142`), value type
+ * (`comboBox_variable_value_type:165`), plus `dlgTriggerEditor::addVar`
+ * (:5211). Edits go straight into the running `_G`, so a script sees them
+ * immediately.
+ *
+ * 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 neither flaggable nor editable.
+ * 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 declare function VariablesView({ connectionId, scriptingEngineRef, focus, onFocusConsumed }: VariablesViewProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -16,8 +16,10 @@ interface WindowCmdLineProps {
  * 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.
+ * callback is bound, the text is sent to the game as typed input, the way
+ * Mudlet's TCommandLine::enterCommand falls back to Host::send. History, Tab
+ * completion, Shift+Enter, Escape and what Enter leaves behind follow desktop's
+ * TCommandLine (see useSubCommandLineKeys).
  */
 export declare function WindowCmdLine({ id, manager, styleSheet, seedValue, seedSeq }: WindowCmdLineProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -0,0 +1,24 @@
+/**
+ * Edit-time detection of the alias that feeds itself: a pattern that matches
+ * its own substitution, so sending the command re-triggers the alias.
+ *
+ * Desktop refuses the save outright — `if (aliasSubstitutionLoops(regex,
+ * substitution)) { showAliasLoopWarning(...); return; }`
+ * (dlgTriggerEditor.cpp:6174-6178, :15054, :15090), implemented at :6269 as an
+ * unanchored match of the pattern against the substitution.
+ *
+ * Here it only warns. Mudlet Web already stops the damage at runtime — send()
+ * refuses past `MAX_SEND_DEPTH` with a message naming the alias — and that
+ * guard catches indirect loops (A → B → A) this one cannot see. Refusing the
+ * save on top of it would block the direct case while still letting the
+ * indirect one through, so the warning is what the runtime guard is missing:
+ * feedback before the 25 junk lines rather than after them.
+ *
+ * The match runs through JS `RegExp`, not PCRE — near enough for a warning, and
+ * a pattern that does not compile here produces none, mirroring desktop's
+ * `if (!rx.isValid()) return false`.
+ */
+export declare function aliasSubstitutionLoops(pattern: string, substitution: string): boolean;
+/** The warning shown beside a looping alias, worded as desktop words it
+ *  (`showAliasLoopWarning`, dlgTriggerEditor.cpp:6364-6369) minus the refusal. */
+export declare function aliasLoopWarning(name: string): string;

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

@@ -0,0 +1,45 @@
+/**
+ * Copy / paste / duplicate for editor items.
+ *
+ * Mudlet round-trips the item and its subtree through XML — `slot_copyXml`
+ * (dlgTriggerEditor.cpp:11777) exports it to `mpHost->mpEditorDialog`'s
+ * clipboard buffer and `slot_pasteXml` (:11913) imports it back, which is why
+ * the paste mints fresh ids there too. Mudlet Web's nodes are plain objects, so the
+ * same job is a structured clone with remapped ids; the clipboard is an
+ * in-memory snapshot rather than XML text, which keeps it exact (no lossy
+ * element set) at the cost of not surviving a page reload — Mudlet's doesn't
+ * outlive its editor either.
+ */
+import type { EditorItemCategory, EditorItemNode } from './editorUndo';
+export interface EditorClipboard {
+    category: EditorItemCategory;
+    /** The copied item followed by its descendants, in tree order. */
+    nodes: EditorItemNode[];
+    /** What the context menu says it will paste, e.g. `trigger "qa-sub"`. */
+    label: string;
+}
+/**
+ * The item plus every descendant, root first and the rest in `items` order.
+ *
+ * Root-first matters because {@link cloneSubtree} and the paste placement both
+ * treat the first element as the item the user picked. Every producer happens
+ * to keep parents ahead of children today, but the walk below explicitly does
+ * not rely on that — so neither does this.
+ */
+export declare function collectSubtree<T extends {
+    id: string;
+    parentId: string | null;
+}>(items: readonly T[], rootId: string): T[];
+/**
+ * Copy `nodes` (a subtree, root first) under `newParentId` with fresh ids.
+ *
+ * `packageName` is dropped: uninstalling a package removes every item carrying
+ * its name, so a copy that kept the tag would be deleted along with the
+ * original the next time that package went away — and the package's own
+ * manifest never listed the copy in the first place.
+ *
+ * `existingNames` are the names already in use among the new siblings; a
+ * collision gets a " (copy)" suffix so the paste is visible in the tree rather
+ * than looking like nothing happened.
+ */
+export declare function cloneSubtree<T extends EditorItemNode>(nodes: readonly T[], newParentId: string | null, existingNames: ReadonlySet<string>, newId?: () => string): T[];

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

@@ -0,0 +1,79 @@
+/**
+ * The script editor's item-level undo stack.
+ *
+ * Mudlet's editor deletes immediately and never asks; what makes that safe is
+ * that every delete path builds an `EditorDeleteItemCommand` and pushes it onto
+ * the editor's own `EditorUndoStack` (dlgTriggerEditor.cpp:3714 for triggers,
+ * and the same at :3089 aliases, :3237 buttons, :3441 scripts, :3575 keys,
+ * :3848 timers), reachable from Ctrl+Z. This is that stack, minus the parts
+ * Mudlet only needs because of how it stores items:
+ *
+ *  * Mudlet snapshots each deleted item to XML and re-imports it on undo, which
+ *    mints fresh ids — hence the id remapping, the `remapItemID` plumbing and
+ *    the child-id fix-up loops all over `EditorDeleteItemCommand::undo()`.
+ *    Mudlet Web's nodes are plain objects with stable string ids, so the very same
+ *    objects go back and none of that is needed.
+ *  * Mudlet restores parents before children (a topological sort) because a
+ *    child needs a live parent pointer. Here the tree is a flat array plus
+ *    `parentId`, so restoring the whole subtree at its recorded indices
+ *    reproduces it in one step, in any order.
+ */
+import type { AliasNode, ButtonNode, KeyNode, ScriptNode, TimerNode, TriggerNode } from '../../../storage/schema';
+import type { RestoredNode } from '../../../storage/appStore';
+/** The six editor views that hold deletable items. Mirrors Mudlet's
+ *  EditorViewType minus the varUnit view, which has no delete command. */
+export type EditorItemCategory = 'scripts' | 'aliases' | 'triggers' | 'timers' | 'keys' | 'buttons';
+export type EditorItemNode = ScriptNode | AliasNode | TriggerNode | TimerNode | KeyNode | ButtonNode;
+/** Mudlet caps the editor stack at 50 commands (`setUndoLimit(50)`,
+ *  dlgTriggerEditor.cpp:457). */
+export declare const EDITOR_UNDO_LIMIT = 50;
+/**
+ * One reversible edit to the item tree.
+ *
+ * `delete` and `insert` are the same record read in opposite directions: both
+ * hold every node involved plus the index it occupied, so undoing one is
+ * redoing the other. Mudlet only ever pushes deletions here, but a paste that
+ * cannot be undone makes Ctrl+Z do something unrelated to what the user just
+ * did — so pastes and duplicates go on the same stack.
+ */
+export interface EditorItemCommand {
+    kind: 'delete' | 'insert';
+    category: EditorItemCategory;
+    /** Every node the command covers — the item and its whole subtree — each
+     *  with the index it occupied in the category's flat list. */
+    entries: ReadonlyArray<RestoredNode<EditorItemNode>>;
+    /** Undo-menu wording, e.g. `delete trigger "qa-sub"`. Mirrors
+     *  `EditorDeleteItemCommand::generateText`. */
+    label: string;
+}
+/**
+ * The item plus every descendant, paired with the index each occupies in
+ * `items` — exactly the set the store's `removeX` actions drop (they take the
+ * same `id` + `getDescendantIds` closure), so the capture and the removal can
+ * never disagree.
+ *
+ * Mudlet's `captureTriggerAndChildren` lambda (dlgTriggerEditor.cpp:3616) does
+ * the same walk, recording `positionInParent` because its tree is real
+ * parent/child widgets. Here sibling order lives in the flat array, so the flat
+ * index is the position worth keeping.
+ */
+export declare function captureDeletion<T extends {
+    id: string;
+    parentId: string | null;
+}>(items: readonly T[], id: string): RestoredNode<T>[];
+/** `delete trigger "qa-sub"` / `delete 4 triggers`, following
+ *  `EditorDeleteItemCommand::generateText` — including its choice to count the
+ *  captured descendants, not just the item the user picked. */
+export declare function describeDeletion(category: EditorItemCategory, entries: ReadonlyArray<{
+    node: {
+        name: string;
+    };
+}>): string;
+/** The same wording for the other direction — `paste trigger "qa-sub"`. */
+export declare function describeInsertion(category: EditorItemCategory, entries: ReadonlyArray<{
+    node: {
+        name: string;
+    };
+}>): string;
+/** Push onto a stack held at Mudlet's 50-command limit, dropping the oldest. */
+export declare function pushBounded<T>(stack: readonly T[], command: T): T[];

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

@@ -0,0 +1,10 @@
+/**
+ * The `sysMapAreaChanged(newAreaID, prevAreaID)` a centerview raises, or null
+ * when it raises none.
+ *
+ * Moving into another area raises it, as does the first centerview since the
+ * map widget opened (or its map was replaced) even when the room lies in the
+ * area already on show: that area is only the view restored from last time,
+ * and desktop reports the first centerview with -2 as the previous area.
+ */
+export declare function centerviewAreaChange(first: boolean, prevArea: number | null, areaId: number): [number, number] | null;

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

@@ -0,0 +1,25 @@
+/**
+ * Whether this build wants its shell cached at all.
+ *
+ * Only a built app does. A dev server has no content-hashed assets to cache
+ * anyway, and the caching it *could* do — the icons, the manifest, the WASM the
+ * plugin serves at the root — is pure cost there: a second copy written on every
+ * boot, and a hot-reload hazard for the one file that isn't content-addressed.
+ * It is measurable cost, too. The busted corpus boots the whole app 41 times in
+ * parallel contexts, and on a four-core CI runner the extra work per boot was
+ * enough to push readiness past its 90s timeout.
+ *
+ * Read at the two edges rather than inside the functions below, so the worker's
+ * registration URL and the page's decision to speak to it can't disagree.
+ */
+export declare const appShellCacheEnabled: boolean;
+/**
+ * Hand the active worker this build's resource list, once the page has settled.
+ * Safe to call when there is no worker, no support, or nothing loaded — it is a
+ * best-effort optimisation of a cache the worker also fills on its own.
+ */
+export declare function primeAppShellCache(): Promise<void>;
+/** How long after load to let stragglers arrive before taking the snapshot.
+ *  A flat wait rather than an idle callback: the browser counts as idle while a
+ *  WASM download is still in flight, which is exactly the case this is for. */
+export declare const SETTLE_MS = 5000;

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

@@ -0,0 +1,13 @@
+/**
+ * The family name a font file declares, or null when the bytes are not a font
+ * this can read.
+ *
+ * Null is a normal answer, not an error: a package may ship a font in a format
+ * with no sfnt wrapper, and the caller's job is then to say so rather than to
+ * register the file under a name nothing would ask for.
+ */
+export declare function fontFamilyName(bytes: Uint8Array): string | null;
+/** File extensions desktop's `Host::installPackageFonts` picks up
+ *  (Host.cpp:3513). */
+export declare const FONT_EXTENSIONS: readonly [".otf", ".ttf", ".ttc", ".otc"];
+export declare function isFontPath(path: string): boolean;

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

@@ -1,5 +1,9 @@
 import type { ProfileVFS } from '../scripting/vfs/ProfileVFS';
 import type { OutputFontSource } from '../storage';
+/** Cache-key component for anything that memoises a font measurement. */
+export declare function getFontGeneration(): number;
+/** Note that a family became usable — see `getFontGeneration`. */
+export declare function bumpFontGeneration(): void;
 /** 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. */
@@ -53,5 +57,32 @@ export declare function primeLocalFontsCache(): Promise<void>;
  *  forms ("Family Name") are unwrapped to plain names. */
 export declare function getRegisteredFontFamilies(): string[];
 export declare function loadFontFromUrl(family: string, url: string): Promise<void>;
+/**
+ * Register a font file from the profile VFS under `family`.
+ *
+ * The face goes into `document.fonts` before this returns — synchronously —
+ * and the returned promise settles once the browser has parsed it. That order
+ * is what lets a package use its own font in the events its install raises
+ * straight after (#438): `getAvailableFonts()` reads `document.fonts`, and
+ * desktop's font database has the family the moment `loadFont` returns, so a
+ * `setFont` in sysInstallPackage or sysLoadEvent must find it. Text already
+ * asking for the family re-renders in it once the face has loaded, as with any
+ * web font. A file that will not load is taken out again and the promise
+ * rejects.
+ */
 export declare function loadFontFromVfs(family: string, path: string, vfs: ProfileVFS): Promise<void>;
+/**
+ * Make a font source drawable, without saying where it is to be drawn.
+ *
+ * A `system` source is whatever the machine already has, so there is nothing to
+ * do; the other two have to be fetched or read out of the profile before the
+ * family name means anything. Both underlying loaders are idempotent, so calling
+ * this again for a font already registered costs nothing — which is what lets it
+ * sit in an effect keyed on the setting.
+ *
+ * Separate from {@link applyOutputFont} because the map's room-symbol font needs
+ * the registration half and not the CSS-variable half: it is handed to a canvas
+ * by the renderer, not inherited through the document.
+ */
+export declare function registerFontSource(font: OutputFontSource | undefined, vfs: ProfileVFS | null): Promise<void>;
 export declare function applyOutputFont(font: OutputFontSource | undefined, vfs: ProfileVFS | null): Promise<void>;

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

@@ -0,0 +1,4 @@
+/** Byte count for a person: "912 B", "48 KB", "3.4 MB". Rounded hard on
+ *  purpose — these appear next to a control, where the order of magnitude is
+ *  the whole message and a second decimal place is noise. */
+export declare function formatBytes(n: number): string;

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

@@ -0,0 +1,9 @@
+/**
+ * The refusal Mudlet gives a value outside a fixed set of words, in the one
+ * wording its API settled on: `<what> must be "a", "b" or "c", got "x"` — no
+ * function-name prefix, double quotes, no comma before the "or".
+ *
+ * The Lua twin is `__mudlet_must_be_one_of` in `src/scripting/lua/Bridge.lua`;
+ * keep the two in step.
+ */
+export declare function mustBeOneOf(what: string, values: readonly string[], got: unknown): string;

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

@@ -1,5 +1,5 @@
 /** Shared prefix for every per-profile Web Lock name. */
-export declare const PROFILE_LOCK_PREFIX = "mudix:profile:";
+export declare const PROFILE_LOCK_PREFIX = "mudlet: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,

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

@@ -0,0 +1,24 @@
+import type { Theme } from '../storage/schema';
+/** The stored value meaning "whatever the OS is set to". Never reaches
+ *  `data-theme`; {@link resolveTheme} turns it into a real palette first. */
+export declare const SYSTEM_THEME = "system";
+/** Whether the OS is asking for a dark UI right now. Defaults to dark when
+ *  nothing can be asked, which is this app's own default. */
+export declare function prefersDark(): boolean;
+/**
+ * The concrete palette to render: `theme` itself, unless it is the system
+ * sentinel. Safe to call with any stored value, including one from a brand.
+ */
+export declare function resolveTheme(theme: Theme | undefined): Theme;
+/** `isLightTheme` through {@link resolveTheme}, for callers holding a stored
+ *  value rather than a resolved one (the editor's syntax palette). */
+export declare function isLightResolvedTheme(theme: Theme | undefined): boolean;
+/**
+ * Call `onChange` whenever the OS preference flips, so a theme left on "System
+ * setting" repaints without a reload. Returns an unsubscribe.
+ *
+ * Subscribed unconditionally rather than only while `system` is selected: the
+ * listener is one boolean check, and gating it on the current value would mean
+ * re-subscribing every time the theme changes for no saving worth having.
+ */
+export declare function onSystemThemeChange(onChange: () => void): () => void;

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

@@ -0,0 +1,10 @@
+/** Short zone name in effect at `date` ("UTC", "EST", "CET") — what glibc's
+ *  `%Z` and Qt's `t` format token print. A zone tzdata gives no letters gets
+ *  its numeric abbreviation ("+03", "+0545"); a time before the zone adopted
+ *  standard time is its local mean time, "LMT". `timeZone` is an IANA id; the
+ *  local zone when omitted. */
+export declare function timeZoneAbbreviation(date: Date, timeZone?: string): string;
+export declare function timeZoneLongName(date: Date): string;
+/** The local zone's offset from UTC at `date` as "+hhmm", or "+hh:mm" with
+ *  `colon` — Qt's `tt` and `ttt`. */
+export declare function timeZoneOffset(date: Date, colon?: boolean): string;

package/dist-lib/vault/CredentialVault.d.ts

@@ -21,12 +21,15 @@
  * sync, another user on the machine, an extension trawling localStorage. It does
  * not defend against script running in the page *while the vault is unlocked* —
  * no in-page vault can, and neither can a password manager with an open vault.
- * The unlocked state is per page load and lives only in memory.
+ * The unlocked state is per page load and lives only in memory — unless the
+ * player opts into keeping it unlocked on this device (see `deviceUnlock`).
  *
  * State changes notify `subscribe` listeners so React can render off
  * `getSnapshot` through `useSyncExternalStore`.
  */
-import { type VaultRecord, type VaultUnlocker } from './vaultRecord';
+import { type DeviceUnlockStore } from './deviceUnlock';
+import { type VaultRecord, type VaultSignIn, type VaultUnlocker } from './vaultRecord';
+export type { VaultSignIn } from './vaultRecord';
 /** What a listener needs to render. Immutable; identity changes on every
  *  mutation so `useSyncExternalStore` re-renders exactly when something did. */
 export interface VaultSnapshot {
@@ -36,6 +39,8 @@ export interface VaultSnapshot {
     locked: boolean;
     /** Profiles with a stored password — readable while locked. */
     entryIds: readonly string[];
+    /** Profiles with a saved GMCP sign-in token — readable while locked. */
+    signInIds: readonly string[];
     /** Unlock methods, without their key material. */
     unlockers: readonly {
         id: string;
@@ -43,6 +48,9 @@ export interface VaultSnapshot {
         label: string;
         createdAt: string;
     }[];
+    /** Epoch ms until which this device opens the vault by itself, when the
+     *  player chose that. Known only once the vault is open. */
+    rememberedUntil: number | null;
 }
 /** Failure modes worth telling apart in the UI. */
 export type VaultErrorCode = 'unavailable' | 'no-vault' | 'locked' | 'no-prf' | 'no-passkey' | 'last-unlocker';
@@ -56,14 +64,19 @@ interface VaultIO {
 }
 export declare class CredentialVault {
     private io;
+    private device;
     private record;
     /** Recovered at unlock, dropped at lock. Never persisted. */
     private masterKey;
     /** Decrypted secrets while unlocked, keyed by connection id. */
     private secrets;
+    /** Decrypted GMCP sign-ins while unlocked, keyed by connection id. */
+    private signIns;
     private listeners;
     private snapshot;
-    constructor(io?: VaultIO);
+    /** See {@link VaultSnapshot.rememberedUntil}. */
+    private rememberedUntil;
+    constructor(io?: VaultIO, device?: DeviceUnlockStore | null);
     subscribe: (listener: () => void) => (() => void);
     getSnapshot: () => VaultSnapshot;
     /** Whether this browser can do vault crypto at all (secure context). */
@@ -78,6 +91,18 @@ export declare class CredentialVault {
     /** The stored password, or `undefined` when there is none *or* the vault is
      *  locked. Callers treat both the same way: fall back to asking the user. */
     getPassword(connectionId: string): string | undefined;
+    /** True when this profile has a saved sign-in *token* — answerable while
+     *  locked. A token-less resume hint does not count: it is not worth asking
+     *  the player to unlock for. */
+    hasSignIn(connectionId: string): boolean;
+    /** The saved GMCP sign-in (a copy), or `undefined` when there is none or
+     *  the vault is locked. */
+    getSignIn(connectionId: string): VaultSignIn | undefined;
+    /** Whether this browser can keep the vault unlocked between visits. */
+    get canRemember(): boolean;
+    /** Whether a secret written now would actually be kept: a vault exists and
+     *  is open. What the GMCP `token_storage` field reports. */
+    get canStore(): boolean;
     /**
      * Create a vault whose first unlocker is a passphrase.
      *
@@ -101,8 +126,23 @@ export declare class CredentialVault {
     /** Open the vault with a registered passkey. Throws on cancel (WebAuthn's
      *  own error) or when no passkey unlocker exists. */
     unlockWithPasskey(): Promise<boolean>;
-    /** Drop the master key and every decrypted secret. The record stays. */
+    /** Drop the master key and every decrypted secret. The record stays. A
+     *  vault kept unlocked on this device stops being so: "Lock" means locked
+     *  on the next visit too. */
     lock(): void;
+    /**
+     * Open the vault from a remembered unlock, if this device has one for it.
+     * Called once at startup, before anything reads a password. A stale entry —
+     * expired, for a vault since replaced, or one that will not decrypt — is
+     * dropped. Never throws: the worst case is the usual unlock prompt.
+     */
+    restoreOnThisDevice(): Promise<boolean>;
+    /** Keep the open vault unlocked on this device until the expiry. Asking
+     *  again renews it. Requires unlocked. */
+    rememberOnThisDevice(): Promise<void>;
+    /** Stop keeping the vault unlocked on this device. It stays open for the
+     *  rest of this visit. */
+    forgetOnThisDevice(): Promise<void>;
     /** Remove the vault and everything in it, irreversibly. */
     deleteVault(): void;
     /** Store (or, with `null`, forget) one profile's password. Requires unlocked. */
@@ -116,6 +156,13 @@ export declare class CredentialVault {
      * password is unreachable.
      */
     forgetConnection(connectionId: string): Promise<boolean>;
+    /**
+     * Store (or, with `null`, forget) one profile's GMCP sign-in. Requires
+     * unlocked: whether a token can be kept at all is decided from
+     * {@link canStore} *before* the game is told (`token_storage`), so a locked
+     * vault here is a race for the caller to report, not a silent drop.
+     */
+    setSignIn(connectionId: string, entry: VaultSignIn | null): Promise<void>;
     /** Drop stored passwords for profiles that no longer exist. No-op while
      *  locked; the caller runs it right after an unlock. */
     pruneMissing(existingConnectionIds: Iterable<string>): Promise<void>;
@@ -148,4 +195,3 @@ export declare class CredentialVault {
  *  across profiles, so opening a second game after unlocking the first asks for
  *  nothing. */
 export declare const credentialVault: CredentialVault;
-export {};

package/dist-lib/vault/deviceUnlock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * "Keep unlocked on this device": the vault opens by itself on later visits.
+ *
+ * The master key is wrapped under a *device key* — an AES-GCM key created with
+ * `extractable: false` and kept in IndexedDB, which stores a `CryptoKey` by
+ * structured clone. Script on this origin can ask the browser to use it but can
+ * never read its bytes, so the wrapped copy is useless anywhere but this
+ * browser profile: not in a backup, not on another machine, not to an extension
+ * that copies localStorage (where the vault record lives).
+ *
+ * What it gives up, and what the player is told: anyone who can use this
+ * browser profile can open the vault, as with the browser's own saved
+ * passwords. Script in the page could already use an unlocked vault, so that
+ * exposure is unchanged. Someone copying the profile directory off the disk may
+ * recover the key, since browsers do not all encrypt IndexedDB at rest. Hence
+ * opt-in, and an expiry ({@link REMEMBER_UNLOCK_DAYS}) that re-asking renews.
+ *
+ * Kept in its own database so dropping it never touches anything else, and so
+ * no backup or storage sweep that names the app's other databases picks it up.
+ */
+import { type Ciphertext } from './vaultCrypto';
+/** How long a remembered unlock lasts before the vault asks again. */
+export declare const REMEMBER_UNLOCK_DAYS = 30;
+/** One remembered unlock — at most one per browser profile, like the vault. */
+export interface RememberedUnlock {
+    /** Non-extractable; never leaves IndexedDB as bytes. */
+    deviceKey: CryptoKey;
+    /** The vault master key, encrypted under `deviceKey`. */
+    wrapped: Ciphertext;
+    /** Which vault this opens — its `prfSalt`, random per vault. A vault
+     *  deleted and set up again must not be "opened" by a stale entry. */
+    vaultTag: string;
+    /** Epoch ms after which it is discarded unused. */
+    expiresAt: number;
+}
+export interface DeviceUnlockStore {
+    load(): Promise<RememberedUnlock | null>;
+    save(entry: RememberedUnlock): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Wrap `master` under a fresh device key. */
+export declare function rememberMasterKey(master: CryptoKey, vaultTag: string, now?: number): Promise<RememberedUnlock>;
+/** The master key back, or `null` when the entry is for another vault, has
+ *  expired, or will not decrypt. */
+export declare function recallMasterKey(entry: RememberedUnlock, vaultTag: string, now?: number): Promise<CryptoKey | null>;
+/** The IndexedDB-backed store, or `null` where there is no IndexedDB. */
+export declare function idbDeviceUnlockStore(): DeviceUnlockStore | null;