@songsid/agend 2.2.0-beta.1 → 2.2.0-beta.3

package/dist/web-host-guard.d.ts

@@ -64,17 +64,9 @@ export declare function isHostAllowed(hostHeader: string | string[] | undefined,
  */
 export declare function applyWebSecurityHeaders(res: ServerResponse): void;
 /**
- * The one remote image source a panel may load: Discord's custom-emoji CDN, which the status-emoji editor shows
- * (status-emojis.ts emojiImageUrl). Path-scoped — a source ending in "/" admits only what is under it, so the rest of
- * cdn.discordapp.com (attachments, avatars) stays refused, and a redirect elsewhere is refused too. It is an image
- * source only: script still cannot connect or post anywhere but this origin. What it gives up is that Discord sees the
- * viewer's address when the editor is open (the request carries no referrer — EmojiImg sets no-referrer).
- */
-export declare const DISCORD_EMOJI_IMG_SRC = "https://cdn.discordapp.com/emojis/";
-/**
- * The panel policy for one response: WEB_CONTENT_SECURITY_POLICY with this response's nonce for scripts and styles,
- * Discord's emoji CDN for images (DISCORD_EMOJI_IMG_SRC),
- * and — for /ui only, when a preview origin was chosen for this load (#1306) — `frame-src <preview origin>/frame`:
+ * The panel policy for one response: WEB_CONTENT_SECURITY_POLICY with this response's nonce for scripts and styles —
+ * images stay 'self' (#1630: Discord's emoji pictures come from the dashboard's own /ui/img/emoji/, so no remote image
+ * source is admitted any more, and Discord never sees a viewer's address) — and — for /ui only, when a preview origin was chosen for this load (#1306) — `frame-src <preview origin>/frame`:
  * path-scoped, so nothing else of that origin can be framed or navigated to. Without it, frames fall back to
  * default-src 'self'.
  */

package/dist/web-host-guard.js

@@ -103,24 +103,15 @@ export function applyWebSecurityHeaders(res) {
     res.setHeader("Cache-Control", "no-store");
 }
 /**
- * The one remote image source a panel may load: Discord's custom-emoji CDN, which the status-emoji editor shows
- * (status-emojis.ts emojiImageUrl). Path-scoped — a source ending in "/" admits only what is under it, so the rest of
- * cdn.discordapp.com (attachments, avatars) stays refused, and a redirect elsewhere is refused too. It is an image
- * source only: script still cannot connect or post anywhere but this origin. What it gives up is that Discord sees the
- * viewer's address when the editor is open (the request carries no referrer — EmojiImg sets no-referrer).
- */
-export const DISCORD_EMOJI_IMG_SRC = "https://cdn.discordapp.com/emojis/";
-/**
- * The panel policy for one response: WEB_CONTENT_SECURITY_POLICY with this response's nonce for scripts and styles,
- * Discord's emoji CDN for images (DISCORD_EMOJI_IMG_SRC),
- * and — for /ui only, when a preview origin was chosen for this load (#1306) — `frame-src <preview origin>/frame`:
+ * The panel policy for one response: WEB_CONTENT_SECURITY_POLICY with this response's nonce for scripts and styles —
+ * images stay 'self' (#1630: Discord's emoji pictures come from the dashboard's own /ui/img/emoji/, so no remote image
+ * source is admitted any more, and Discord never sees a viewer's address) — and — for /ui only, when a preview origin was chosen for this load (#1306) — `frame-src <preview origin>/frame`:
  * path-scoped, so nothing else of that origin can be framed or navigated to. Without it, frames fall back to
  * default-src 'self'.
  */
 export function panelContentSecurityPolicy(nonce, opts = {}) {
     let policy = rewriteDirective(WEB_CONTENT_SECURITY_POLICY, "script-src 'self'", `script-src 'self' 'nonce-${nonce}'`);
     policy = rewriteDirective(policy, "style-src 'self'", `style-src 'self' 'nonce-${nonce}'`);
-    policy = rewriteDirective(policy, "img-src 'self' data: blob:", `img-src 'self' data: blob: ${DISCORD_EMOJI_IMG_SRC}`);
     if (opts.frameSrc)
         policy = `${policy}; frame-src ${opts.frameSrc}`;
     // #1589: the app shell's audio/video — exactly <dashboard origin>/ui/file/ (or 'none'); without it media falls back

package/dist/web-host-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-host-guard.js","sourceRoot":"","sources":["../src/web-host-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"web-host-guard.js","sourceRoot":"","sources":["../src/web-host-guard.ts"],"names":[],"mappings":"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"}

package/dist/web-images.d.ts

@@ -0,0 +1,47 @@
+import type { StickerPreview } from "./channel/types.js";
+export declare const WEB_IMAGE_MAX_AGE_MS: number;
+export declare const WEB_IMAGE_RETRY_MS: number;
+/** Files not refreshed for this long (an emoji no longer used, a removed connection) are deleted on the next write. */
+export declare const WEB_IMAGE_PRUNE_MS: number;
+export declare const WEB_IMAGE_MAX_BYTES: number;
+/** The picture type of an uploaded file by its extension (View's profile avatars), or null for anything else. */
+export declare function imageMimeForFile(name: string): string | null;
+export interface CachedImage {
+    readonly bytes: Buffer;
+    readonly mime: string;
+    readonly version: string;
+}
+/** What a fetch found: the picture, or null when there is none (the bot has no avatar). Throws when it failed. */
+export type ImageLoader = () => Promise<StickerPreview | null>;
+export declare class WebImageCache {
+    private readonly opts;
+    private readonly inflight;
+    /** key → when it may be asked again (monotonic ms), after a failure or a "none". */
+    private readonly quietUntil;
+    constructor(opts: {
+        dir: string;
+        now?: () => number;
+        mono?: () => number;
+        maxAgeMs?: number;
+        retryMs?: number;
+        onError?: (key: string, err: unknown) => void;
+    });
+    private get now();
+    private get mono();
+    private base;
+    private find;
+    private stale;
+    /** What is on disk now (fresh or stale), as a version for the page's URL; a stale or missing one is refreshed in the background. */
+    peek(key: string, loader: ImageLoader): {
+        version: string;
+    } | null;
+    /** The bytes on disk, or null. Never fetches. */
+    read(key: string): CachedImage | null;
+    /** The bytes, fetching first when nothing is on disk yet (a stale file is served and refreshed behind). */
+    get(key: string, loader: ImageLoader): Promise<CachedImage | null>;
+    /** One fetch per key at a time; none while the key is quiet (after a failure or a "none"). Never throws. */
+    refresh(key: string, loader: ImageLoader): Promise<void>;
+    private write;
+    private remove;
+    private prune;
+}

package/dist/web-images.js

@@ -0,0 +1,169 @@
+/**
+ * #1630: images the web app shows that come from a chat platform — a bot's own avatar, a Discord server's custom
+ * emoji — fetched on the host with the token the adapter already holds, kept on disk, and served same-origin (the page
+ * never loads cdn.discordapp.com or a Telegram file URL, and CSP img-src stays 'self').
+ *
+ * - On disk under `<AGEND_HOME>/cache/<kind>/`, one file per key, named by a hash of the key (a key never becomes a
+ *   path), written to a temp file and renamed.
+ * - Refreshed at most once a day: the file's age is wall-clock (mtime — it must survive a restart). A stale file is
+ *   still served while the refresh runs in the background.
+ * - A failed fetch keeps the file it had; the key is then not retried for an hour. A fetch that says there is no image
+ *   (a bot with no avatar) removes the file, and is not asked again for a day. Those two waits are in-memory durations:
+ *   monotonic clock.
+ * - Never more than one fetch per key at a time. Nothing here blocks a caller: `peek` starts a refresh and returns
+ *   what is on disk now; only `get` (a first request for an emoji nobody has fetched yet) waits for one.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+export const WEB_IMAGE_MAX_AGE_MS = 24 * 60 * 60_000;
+export const WEB_IMAGE_RETRY_MS = 60 * 60_000;
+/** Files not refreshed for this long (an emoji no longer used, a removed connection) are deleted on the next write. */
+export const WEB_IMAGE_PRUNE_MS = 30 * WEB_IMAGE_MAX_AGE_MS;
+export const WEB_IMAGE_MAX_BYTES = 256 * 1024;
+const MIME = { png: "image/png", jpg: "image/jpeg", webp: "image/webp", gif: "image/gif" };
+const EXTS = Object.keys(MIME);
+/** The picture type of an uploaded file by its extension (View's profile avatars), or null for anything else. */
+export function imageMimeForFile(name) {
+    const ext = /\.([a-z]+)$/i.exec(name)?.[1]?.toLowerCase();
+    return ext === "jpeg" ? MIME.jpg : ext && Object.hasOwn(MIME, ext) ? MIME[ext] : null;
+}
+export class WebImageCache {
+    opts;
+    inflight = new Map();
+    /** key → when it may be asked again (monotonic ms), after a failure or a "none". */
+    quietUntil = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get now() { return (this.opts.now ?? Date.now)(); }
+    get mono() { return (this.opts.mono ?? (() => performance.now()))(); }
+    base(key) { return createHash("sha256").update(key).digest("hex").slice(0, 32); }
+    find(key) {
+        const base = this.base(key);
+        for (const ext of EXTS) {
+            const path = join(this.opts.dir, `${base}.${ext}`);
+            try {
+                if (existsSync(path))
+                    return { path, ext, mtimeMs: statSync(path).mtimeMs };
+            }
+            catch { /* raced with a refresh */ }
+        }
+        return null;
+    }
+    stale(mtimeMs) { return this.now - mtimeMs >= (this.opts.maxAgeMs ?? WEB_IMAGE_MAX_AGE_MS); }
+    /** What is on disk now (fresh or stale), as a version for the page's URL; a stale or missing one is refreshed in the background. */
+    peek(key, loader) {
+        const found = this.find(key);
+        if (!found || this.stale(found.mtimeMs))
+            void this.refresh(key, loader);
+        return found ? { version: Math.floor(found.mtimeMs).toString(36) } : null;
+    }
+    /** The bytes on disk, or null. Never fetches. */
+    read(key) {
+        const found = this.find(key);
+        if (!found)
+            return null;
+        try {
+            return { bytes: readFileSync(found.path), mime: MIME[found.ext], version: Math.floor(found.mtimeMs).toString(36) };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The bytes, fetching first when nothing is on disk yet (a stale file is served and refreshed behind). */
+    async get(key, loader) {
+        const found = this.find(key);
+        if (!found)
+            await this.refresh(key, loader);
+        else if (this.stale(found.mtimeMs))
+            void this.refresh(key, loader);
+        return this.read(key);
+    }
+    /** One fetch per key at a time; none while the key is quiet (after a failure or a "none"). Never throws. */
+    refresh(key, loader) {
+        const running = this.inflight.get(key);
+        if (running)
+            return running;
+        const quiet = this.quietUntil.get(key);
+        if (quiet !== undefined && this.mono < quiet)
+            return Promise.resolve();
+        // Started on a later tick, after it is registered: a loader that throws at once must still release the key.
+        const run = Promise.resolve().then(async () => {
+            try {
+                const got = await loader();
+                if (!got) {
+                    this.remove(key);
+                    this.quietUntil.set(key, this.mono + (this.opts.maxAgeMs ?? WEB_IMAGE_MAX_AGE_MS));
+                    return;
+                }
+                if (!MIME[got.ext] || got.bytes.length === 0 || got.bytes.length > WEB_IMAGE_MAX_BYTES)
+                    throw new Error("not a usable image");
+                this.write(key, got);
+                this.quietUntil.delete(key);
+            }
+            catch (err) {
+                this.quietUntil.set(key, this.mono + (this.opts.retryMs ?? WEB_IMAGE_RETRY_MS));
+                this.opts.onError?.(key, err);
+            }
+            finally {
+                if (this.inflight.get(key) === run)
+                    this.inflight.delete(key);
+            }
+        });
+        this.inflight.set(key, run);
+        return run;
+    }
+    write(key, image) {
+        mkdirSync(this.opts.dir, { recursive: true, mode: 0o700 });
+        const base = this.base(key), path = join(this.opts.dir, `${base}.${image.ext}`);
+        const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        try {
+            writeFileSync(tmp, image.bytes, { mode: 0o600 });
+            renameSync(tmp, path);
+        }
+        catch (err) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* never created */ }
+            throw err;
+        }
+        for (const ext of EXTS)
+            if (ext !== image.ext) {
+                try {
+                    unlinkSync(join(this.opts.dir, `${base}.${ext}`));
+                }
+                catch { /* none */ }
+            }
+        this.prune();
+    }
+    remove(key) {
+        const base = this.base(key);
+        for (const ext of EXTS) {
+            try {
+                unlinkSync(join(this.opts.dir, `${base}.${ext}`));
+            }
+            catch { /* none */ }
+        }
+    }
+    prune() {
+        let names;
+        try {
+            names = readdirSync(this.opts.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(this.opts.dir, name);
+            try {
+                if (this.now - statSync(path).mtimeMs > WEB_IMAGE_PRUNE_MS)
+                    unlinkSync(path);
+            }
+            catch { /* raced */ }
+        }
+    }
+}
+//# sourceMappingURL=web-images.js.map

package/dist/web-images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-images.js","sourceRoot":"","sources":["../src/web-images.ts"],"names":[],"mappings":"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"}

package/dist/web-prefs.d.ts

@@ -0,0 +1,63 @@
+export declare const WEB_PREFS_FILE = "web-prefs.json";
+export declare const OPERATOR = "operator";
+/** #1664: at most this many favorites. */
+export declare const MAX_FAVORITES = 50;
+export declare const WEB_PREF_KEYS: readonly string[];
+export declare function isWebPrefKey(key: string): boolean;
+export interface WebPrefsView {
+    /** Every key that is set, and its value (a key not set has its default: the page's own). */
+    readonly values: Record<string, unknown>;
+    readonly rev: number;
+    /** The file could not be read: these are the defaults, and writes are refused until it is fixed. */
+    readonly unreadable?: true;
+}
+export type WebPrefsWrite = {
+    ok: true;
+    view: WebPrefsView;
+    changed: string[];
+} | {
+    ok: false;
+    status: 400 | 503;
+    error: string;
+};
+/**
+ * A request's `set`: own keys only, each known, each valid — or the first reason it is not. All or nothing.
+ * `exists`: whether an instance of that name is in the fleet now (#1664: a favorite must be one).
+ */
+export declare function parseWebPrefsPatch(set: unknown, exists?: (name: string) => boolean): {
+    ok: true;
+    patch: Map<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class WebPrefsStore {
+    private readonly dir;
+    private readonly opts;
+    private state;
+    /**
+     * `exists` (#1664): whether an instance of that name is in the fleet now — a favorite that is not is never served,
+     * and is never accepted.
+     */
+    constructor(dir: string, opts?: {
+        now?: () => number;
+        write?: (path: string, data: string) => void;
+        exists?: (name: string) => boolean;
+    });
+    /** parseWebPrefsPatch against this fleet. */
+    parsePatch(set: unknown): ReturnType<typeof parseWebPrefsPatch>;
+    get path(): string;
+    private load;
+    read(identity?: string): WebPrefsView;
+    rev(): number;
+    /** #1664: an instance was removed — drop it from every favorites list (a write, and a new rev, only if one had it). */
+    forgetInstance(name: string): void;
+    private viewOf;
+    /**
+     * Set (or, with null, clear) the patch's keys. `onlyIfUnset`: a device's first upload of what it had locally — only
+     * the keys the host does not have yet are taken, so the first device to arrive wins and the host wins from then on.
+     */
+    write(identity: string, patch: Map<string, unknown>, opts?: {
+        onlyIfUnset?: boolean;
+    }): WebPrefsWrite;
+}

package/dist/web-prefs.js

@@ -0,0 +1,263 @@
+/**
+ * #1665: the web preferences that follow the person from device to device (theme, language, the sidebar's arrangement,
+ * the HTML-preview opt-in), kept on the host — design: the comment on #1665.
+ *
+ * - The tour and the first-run card stay per device (the user's call on #1665): they are not keys here.
+ * - One bucket per web identity. There is one today: every web session is the operator's (SessionRecord has no
+ *   owner), so the file is keyed by identity and holds "operator" only; a per-owner key can come later unmigrated.
+ * - A fixed registry of keys, each with its own validator. Anything else is refused — "__proto__" and "constructor"
+ *   are just unknown keys: every lookup is a Map, never an object's prototype chain.
+ * - The file (<home>/web-prefs.json, 0600) is replaced atomically. One that cannot be read or parsed is never
+ *   overwritten: reads give the defaults, writes are refused, until a person looks at it.
+ * - `rev` rises with every change; the status frame carries it, so another device re-reads at its next poll.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "./atomic-write.js";
+export const WEB_PREFS_FILE = "web-prefs.json";
+export const OPERATOR = "operator";
+const bad = (invalid) => ({ invalid });
+const isInvalid = (v) => !!v && typeof v === "object" && Object.hasOwn(v, "invalid") && Object.keys(v).length === 1;
+const plain = (v) => !!v && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+const shortText = (v, max) => typeof v === "string" && v.length <= max;
+const name = (v) => typeof v === "string" && v.length >= 1 && v.length <= 128 && !/[\u0000-\u001f\u007f]/.test(v);
+/** Only the listed fields, each present: an extra field is a value this version does not understand. */
+function exactly(v, fields) {
+    const keys = Object.keys(v);
+    return keys.length === fields.length && fields.every((f) => Object.hasOwn(v, f));
+}
+function uniqueStrings(v, max, each, what) {
+    if (!Array.isArray(v) || v.length > max)
+        return bad(`${what}: a list of at most ${max}`);
+    if (!v.every(each))
+        return bad(`${what}: each a name of 1–128 characters`);
+    if (new Set(v).size !== v.length)
+        return bad(`${what}: no repeats`);
+    return v;
+}
+/** #1664: at most this many favorites. */
+export const MAX_FAVORITES = 50;
+const FAVORITES = "nav.favorites";
+/** The status chips of the sidebar filter (src/ui/shared/instance-nav.js STATUS_FACETS). */
+const STATUS_FACETS = new Set(["working", "needs", "idle", "stopped", "crashed"]);
+/** Each key's validator: the value to store, or why it is refused. `null` (clear) never reaches one. */
+const REGISTRY = new Map([
+    ["theme", (v) => (v === "light" || v === "dark" || v === "system" ? v : bad("theme: light, dark or system"))],
+    ["lang", (v) => (v === "en" || v === "zh-TW" ? v : bad("lang: en or zh-TW"))],
+    // The sidebar's drag order: the rows instance-nav.js keeps (group rows have no group_name).
+    ["nav.order", (v) => {
+            if (!Array.isArray(v) || v.length > 1000)
+                return bad("nav.order: a list of at most 1000 rows");
+            for (const row of v) {
+                if (!plain(row) || !exactly(row, ["item_type", "item_name", "sort_index", "group_name"]))
+                    return bad("nav.order: rows of item_type, item_name, sort_index, group_name");
+                const groupRow = row.item_type === "group";
+                if (!groupRow && row.item_type !== "instance")
+                    return bad("nav.order: item_type group or instance");
+                if (!name(row.item_name))
+                    return bad("nav.order: item_name of 1–128 characters");
+                if (!Number.isSafeInteger(row.sort_index) || row.sort_index < 0)
+                    return bad("nav.order: sort_index a whole number from 0");
+                if (groupRow ? row.group_name !== null : !name(row.group_name))
+                    return bad("nav.order: group_name null for a group, the group's name for an instance");
+            }
+            return v;
+        }],
+    ["nav.collapsed", (v) => uniqueStrings(v, 200, name, "nav.collapsed")],
+    ["nav.filter", (v) => {
+            if (!plain(v) || !exactly(v, ["q", "status", "cli"]))
+                return bad("nav.filter: { q, status, cli }");
+            if (!shortText(v.q, 200))
+                return bad("nav.filter: q at most 200 characters");
+            const status = uniqueStrings(v.status, STATUS_FACETS.size, (s) => typeof s === "string" && STATUS_FACETS.has(s), "nav.filter.status");
+            if (isInvalid(status))
+                return status;
+            const cli = uniqueStrings(v.cli, 32, (s) => typeof s === "string" && /^[a-z0-9][a-z0-9_-]{0,31}$/.test(s), "nav.filter.cli");
+            if (isInvalid(cli))
+                return cli;
+            return { q: v.q, status, cli };
+        }],
+    // #1664: the starred instances, in the order they were starred (or moved). Whether each one exists is checked where
+    // the fleet is known (parseWebPrefsPatch's `exists`); a deleted one is dropped on read and when it is removed.
+    [FAVORITES, (v) => uniqueStrings(v, MAX_FAVORITES, name, FAVORITES)],
+    // HTML previews allowed. Who may write it at all is the route's business (a signed-in session, never the public link).
+    ["preview.optIn", (v) => (typeof v === "boolean" ? v : bad("preview.optIn: true or false"))],
+]);
+export const WEB_PREF_KEYS = [...REGISTRY.keys()];
+export function isWebPrefKey(key) { return REGISTRY.has(key); }
+/**
+ * A request's `set`: own keys only, each known, each valid — or the first reason it is not. All or nothing.
+ * `exists`: whether an instance of that name is in the fleet now (#1664: a favorite must be one).
+ */
+export function parseWebPrefsPatch(set, exists) {
+    if (!plain(set))
+        return { ok: false, error: "set: an object of preference keys" };
+    const patch = new Map();
+    const keys = Object.keys(set);
+    if (!keys.length)
+        return { ok: false, error: "set: at least one preference" };
+    for (const key of keys) {
+        const validate = REGISTRY.get(key);
+        if (!validate)
+            return { ok: false, error: `unknown_pref: ${key.slice(0, 64)}` };
+        const raw = set[key];
+        if (raw === null) {
+            patch.set(key, null);
+            continue;
+        }
+        const value = validate(raw);
+        if (isInvalid(value))
+            return { ok: false, error: value.invalid };
+        if (key === FAVORITES) {
+            const unknown = value.find((n) => !exists || !exists(n));
+            if (unknown !== undefined)
+                return { ok: false, error: `unknown_instance: ${unknown.slice(0, 64)}` };
+        }
+        patch.set(key, value);
+    }
+    return { ok: true, patch };
+}
+export class WebPrefsStore {
+    dir;
+    opts;
+    state = null;
+    /**
+     * `exists` (#1664): whether an instance of that name is in the fleet now — a favorite that is not is never served,
+     * and is never accepted.
+     */
+    constructor(dir, opts = {}) {
+        this.dir = dir;
+        this.opts = opts;
+    }
+    /** parseWebPrefsPatch against this fleet. */
+    parsePatch(set) { return parseWebPrefsPatch(set, this.opts.exists); }
+    get path() { return join(this.dir, WEB_PREFS_FILE); }
+    load() {
+        // A store that could not read its file tries again next time (a permission put back, a disk that recovered); one
+        // that did keeps what it read.
+        if (this.state && this.state !== "unreadable")
+            return this.state;
+        const empty = { buckets: new Map(), rev: 0 };
+        // Only a file that is definitely not there (ENOENT) is a new, empty store. Anything else — a read refused (EACCES),
+        // an I/O error, no place for the file at all, content of another shape — is "unreadable": the defaults are served
+        // and nothing is written, so the file is never replaced and a page or status frame never fails because of it.
+        try {
+            let raw;
+            try {
+                raw = readFileSync(this.path, "utf8");
+            }
+            catch (err) {
+                if (err?.code === "ENOENT")
+                    return (this.state = empty);
+                return (this.state = "unreadable");
+            }
+            const doc = JSON.parse(raw);
+            if (!plain(doc) || doc.version !== 1 || !plain(doc.identities) || !Number.isSafeInteger(doc.rev))
+                return (this.state = "unreadable");
+            const buckets = new Map();
+            for (const id of Object.keys(doc.identities)) {
+                const raw = doc.identities[id];
+                if (!plain(raw) || !plain(raw.values) || !plain(raw.updated))
+                    return (this.state = "unreadable");
+                const bucket = { values: new Map(), updated: new Map() };
+                // A key this version no longer knows, or a value it would refuse now, is left out (never served).
+                for (const key of Object.keys(raw.values)) {
+                    const validate = REGISTRY.get(key);
+                    if (!validate)
+                        continue;
+                    const value = validate(raw.values[key]);
+                    if (isInvalid(value))
+                        continue;
+                    bucket.values.set(key, value);
+                    const at = raw.updated[key];
+                    bucket.updated.set(key, typeof at === "number" && Number.isFinite(at) ? at : 0);
+                }
+                buckets.set(id, bucket);
+            }
+            return (this.state = { buckets, rev: doc.rev });
+        }
+        catch {
+            return (this.state = "unreadable");
+        }
+    }
+    read(identity = OPERATOR) {
+        const state = this.load();
+        if (state === "unreadable")
+            return { values: {}, rev: 0, unreadable: true };
+        return this.viewOf(state, identity);
+    }
+    rev() { const s = this.load(); return s === "unreadable" ? 0 : s.rev; }
+    /** #1664: an instance was removed — drop it from every favorites list (a write, and a new rev, only if one had it). */
+    forgetInstance(name) {
+        const state = this.load();
+        if (state === "unreadable")
+            return;
+        for (const [identity, bucket] of state.buckets) {
+            const list = bucket.values.get(FAVORITES);
+            if (list && list.includes(name))
+                this.write(identity, new Map([[FAVORITES, list.filter((n) => n !== name)]]));
+        }
+    }
+    viewOf(state, identity) {
+        const values = Object.create(null);
+        const bucket = state.buckets.get(identity);
+        if (bucket)
+            for (const [k, v] of bucket.values)
+                values[k] = v;
+        // #1664: a favorite whose instance was deleted is dropped (paused or stopped ones are still instances: kept).
+        if (Object.hasOwn(values, FAVORITES)) {
+            const exists = this.opts.exists;
+            values[FAVORITES] = values[FAVORITES].filter((n) => !!exists && exists(n));
+        }
+        return { values: { ...values }, rev: state.rev };
+    }
+    /**
+     * Set (or, with null, clear) the patch's keys. `onlyIfUnset`: a device's first upload of what it had locally — only
+     * the keys the host does not have yet are taken, so the first device to arrive wins and the host wins from then on.
+     */
+    write(identity, patch, opts = {}) {
+        const state = this.load();
+        if (state === "unreadable")
+            return { ok: false, status: 503, error: "prefs_unreadable" };
+        const prior = state.buckets.get(identity);
+        const next = { values: new Map(prior?.values), updated: new Map(prior?.updated) };
+        const at = (this.opts.now ?? Date.now)();
+        const changed = [];
+        for (const [key, value] of patch) {
+            if (opts.onlyIfUnset && next.values.has(key))
+                continue;
+            if (value === null) {
+                if (!next.values.has(key))
+                    continue;
+                next.values.delete(key);
+                next.updated.delete(key);
+            }
+            else {
+                if (next.values.has(key) && JSON.stringify(next.values.get(key)) === JSON.stringify(value))
+                    continue;
+                next.values.set(key, value);
+                next.updated.set(key, at);
+            }
+            changed.push(key);
+        }
+        if (!changed.length)
+            return { ok: true, view: this.viewOf(state, identity), changed };
+        const buckets = new Map(state.buckets);
+        buckets.set(identity, next);
+        const candidate = { buckets, rev: state.rev + 1 };
+        (this.opts.write ?? ((path, data) => atomicWriteFileSync(path, data, { mode: 0o600 })))(this.path, serialize(candidate));
+        // Only once it is on disk: a failed write leaves memory as the file is.
+        this.state = candidate;
+        return { ok: true, view: this.viewOf(candidate, identity), changed };
+    }
+}
+function serialize(state) {
+    const identities = {};
+    for (const [id, b] of state.buckets) {
+        identities[id] = { values: Object.fromEntries(b.values), updated: Object.fromEntries(b.updated) };
+    }
+    // Object.fromEntries with a "__proto__" entry defines an own property, but no such key ever gets in: ids are ours, keys
+    // are the registry's.
+    return JSON.stringify({ version: 1, rev: state.rev, identities }, null, 2) + "\n";
+}
+//# sourceMappingURL=web-prefs.js.map