1681-engine 0.5.9 → 0.5.10

package/dist/assets/Prepainter.js

@@ -0,0 +1,61 @@
+function d({ w: o, h: t, pixels: e }) {
+  if (typeof document > "u") return null;
+  const s = document.createElement("canvas");
+  s.width = o, s.height = t;
+  const n = s.getContext("2d");
+  return n ? (n.putImageData(new ImageData(new Uint8ClampedArray(e), o, t), 0, 0), s) : null;
+}
+class h {
+  constructor(t) {
+    this.options = t, this.key = t.key ?? ((e) => e);
+  }
+  options;
+  pending = /* @__PURE__ */ new Set();
+  /** Ids whose painting is held as a texture: the current one and its neighbours. */
+  held = /* @__PURE__ */ new Set();
+  key;
+  destroyed = !1;
+  /**
+   * Stands on `current`: its texture (painted by the caller on arrival, or ahead) and its neighbours' are kept, every
+   * other one this prepainter held is freed, and the neighbours not yet painted are started.
+   */
+  enter(t, e) {
+    const s = this.options.id, n = s(t), r = /* @__PURE__ */ new Set([n, ...e.map(s)]);
+    for (const i of this.held)
+      r.has(i) || (this.options.textures.remove(this.key(i)), this.held.delete(i));
+    this.held.add(n);
+    for (const i of e) this.prepare(i);
+  }
+  /** Whether `id` is being painted right now (so a caller may wait for it a moment rather than paint it again). */
+  painting(t) {
+    return this.pending.has(t);
+  }
+  /** Ids held as textures now. */
+  get holding() {
+    return this.held;
+  }
+  /** Starts painting `item` unless it is painted or under way. */
+  prepare(t) {
+    const e = this.options.id(t), s = this.options.textures.exists(this.key(e));
+    s && this.held.add(e);
+    const n = this.options.painter;
+    s || this.pending.has(e) || !n || this.destroyed || (this.pending.add(e), n.paint(t, e).then(
+      (r) => this.receive(e, r),
+      () => this.pending.delete(e)
+    ));
+  }
+  /** Stops painting; textures already made are left to the registry. */
+  destroy() {
+    this.destroyed = !0, this.options.painter?.dispose?.(), this.pending.clear();
+  }
+  receive(t, e) {
+    if (this.pending.delete(t), this.destroyed) return;
+    const s = this.key(t);
+    if (this.options.textures.exists(s)) return;
+    const n = (this.options.canvas ?? d)(e);
+    n && (this.options.textures.addCanvas(s, n), this.held.add(t), this.options.onPainted?.(t));
+  }
+}
+export {
+  h as Prepainter
+};

package/dist/assets/workerPainter.js

@@ -0,0 +1,39 @@
+function w(i) {
+  let n;
+  const o = /* @__PURE__ */ new Map(), c = (r) => {
+    n?.terminate(), n = null;
+    for (const t of o.values()) for (const e of t) e.reject(new Error(r));
+    o.clear();
+  }, f = () => {
+    if (n !== void 0) return n;
+    try {
+      const r = i.create();
+      r.onmessage = (t) => {
+        const e = t.data, s = o.get(e.id);
+        if (s) {
+          o.delete(e.id);
+          for (const a of s)
+            "error" in e ? a.reject(new Error(e.error)) : a.resolve(e);
+        }
+      }, r.onerror = () => c("the painter worker failed"), n = r;
+    } catch {
+      n = null;
+    }
+    return n;
+  };
+  return {
+    paint(r, t) {
+      const e = f();
+      return e ? new Promise((s, a) => {
+        const l = o.get(t);
+        l ? l.push({ resolve: s, reject: a }) : (o.set(t, [{ resolve: s, reject: a }]), e.postMessage(i.message ? i.message(r, t) : { id: t, item: r }));
+      }) : Promise.reject(new Error("no painter worker"));
+    },
+    dispose() {
+      c("disposed");
+    }
+  };
+}
+export {
+  w as workerPainter
+};

package/dist/cjs/electron/electronLike.d.ts

@@ -0,0 +1,55 @@
+/** `electron.safeStorage`. */
+export interface SafeStorageLike {
+    isEncryptionAvailable(): boolean;
+    /** Linux only: `basic_text` means a hard-coded key, which is no encryption at all. */
+    getSelectedStorageBackend?(): string;
+    encryptString(plainText: string): Uint8Array;
+    decryptString(encrypted: Buffer): string;
+}
+/** `electron.ipcMain`. */
+export interface IpcMainLike {
+    handle(channel: string, listener: (event: any, ...args: any[]) => unknown): void;
+    removeHandler?(channel: string): void;
+}
+/** `electron.shell`. */
+export interface ShellLike {
+    openExternal(url: string): Promise<void>;
+}
+/** What `before-input-event` hands a listener (`Electron.Input`). */
+export interface InputLike {
+    type: string;
+    key: string;
+    control: boolean;
+    meta: boolean;
+    shift: boolean;
+    alt: boolean;
+}
+/** An event a listener may cancel. */
+export interface PreventableLike {
+    preventDefault(): void;
+}
+/** `electron.Session`, for the permission handlers. */
+export interface SessionLike {
+    setPermissionRequestHandler(handler: ((webContents: any, permission: any, callback: (granted: boolean) => void, details: any) => void) | null): void;
+    setPermissionCheckHandler(handler: ((webContents: any, permission: any, requestingOrigin: string, details: any) => boolean) | null): void;
+}
+/** `electron.WebContents`. */
+export interface WebContentsLike {
+    setWindowOpenHandler(handler: (details: {
+        url: string;
+    }) => any): void;
+    on(event: any, listener: (...args: any[]) => void): unknown;
+    toggleDevTools(): void;
+    session?: SessionLike;
+}
+/** `electron.BrowserWindow`, as far as a lockdown needs it. */
+export interface WindowLike {
+    webContents: WebContentsLike;
+}
+/** `electron.app`, as far as the debugger refusal needs it. */
+export interface AppLike {
+    isPackaged: boolean;
+    commandLine: {
+        hasSwitch(name: string): boolean;
+    };
+}

package/dist/cjs/electron/electronLike.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * The few parts of Electron's main-process API this module touches, written as structural types so the engine never
+ * imports or depends on `electron`: a game passes its own `app`, `safeStorage`, `ipcMain`, `shell` and windows, and
+ * a test passes fakes. Each is a subset of Electron's own type, so Electron's objects fit them as they are.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/electron/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `1681-engine/electron`: the main-process side of a desktop build on Electron — file-by-file web patching from a
+ * release store, the shell's identity, an OS-encrypted session store and a window lockdown. Electron is an optional
+ * peer: nothing here imports it, the game hands in its own `app`, `safeStorage`, `ipcMain`, `shell` and windows. Runs
+ * in the main process only (it uses Node's `fs` and `crypto`); the pure rules it shares with browsers and phones are
+ * `1681-engine/updates`. Importable from ESM (`import`) and from a CommonJS main process (`require`).
+ */
+export type { SafeStorageLike, IpcMainLike, ShellLike, InputLike, PreventableLike, SessionLike, WebContentsLike, WindowLike, AppLike } from './electronLike';
+export { shellId, type ShellIdOptions } from './shellId';
+export { WebPatcher, type WebPatcherOptions } from './webPatcher';
+export type { WebPointer, PointerName } from './webPointers';
+export { SessionStore, registerSessionStore, type SessionStoreOptions } from './sessionStore';
+export { isAllowedExternal, isAllowedNavigation, isDevToolsKey, debuggerRequested, DEBUG_SWITCHES, type ExternalPolicy } from './lockdownRules';
+export { lockDownWindow, denyPermissions, refuseDebugLaunch, type LockdownOptions } from './lockdown';

package/dist/cjs/electron/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refuseDebugLaunch = exports.denyPermissions = exports.lockDownWindow = exports.DEBUG_SWITCHES = exports.debuggerRequested = exports.isDevToolsKey = exports.isAllowedNavigation = exports.isAllowedExternal = exports.registerSessionStore = exports.SessionStore = exports.WebPatcher = exports.shellId = void 0;
+var shellId_1 = require("./shellId");
+Object.defineProperty(exports, "shellId", { enumerable: true, get: function () { return shellId_1.shellId; } });
+var webPatcher_1 = require("./webPatcher");
+Object.defineProperty(exports, "WebPatcher", { enumerable: true, get: function () { return webPatcher_1.WebPatcher; } });
+var sessionStore_1 = require("./sessionStore");
+Object.defineProperty(exports, "SessionStore", { enumerable: true, get: function () { return sessionStore_1.SessionStore; } });
+Object.defineProperty(exports, "registerSessionStore", { enumerable: true, get: function () { return sessionStore_1.registerSessionStore; } });
+var lockdownRules_1 = require("./lockdownRules");
+Object.defineProperty(exports, "isAllowedExternal", { enumerable: true, get: function () { return lockdownRules_1.isAllowedExternal; } });
+Object.defineProperty(exports, "isAllowedNavigation", { enumerable: true, get: function () { return lockdownRules_1.isAllowedNavigation; } });
+Object.defineProperty(exports, "isDevToolsKey", { enumerable: true, get: function () { return lockdownRules_1.isDevToolsKey; } });
+Object.defineProperty(exports, "debuggerRequested", { enumerable: true, get: function () { return lockdownRules_1.debuggerRequested; } });
+Object.defineProperty(exports, "DEBUG_SWITCHES", { enumerable: true, get: function () { return lockdownRules_1.DEBUG_SWITCHES; } });
+var lockdown_1 = require("./lockdown");
+Object.defineProperty(exports, "lockDownWindow", { enumerable: true, get: function () { return lockdown_1.lockDownWindow; } });
+Object.defineProperty(exports, "denyPermissions", { enumerable: true, get: function () { return lockdown_1.denyPermissions; } });
+Object.defineProperty(exports, "refuseDebugLaunch", { enumerable: true, get: function () { return lockdown_1.refuseDebugLaunch; } });

package/dist/cjs/electron/lockdown.d.ts

@@ -0,0 +1,33 @@
+import type { AppLike, SessionLike, ShellLike, WindowLike } from './electronLike';
+import { type ExternalPolicy } from './lockdownRules';
+/** How {@link lockDownWindow} treats a window. */
+export interface LockdownOptions {
+    /** `electron.shell`, which opens an allowed link in the system browser. */
+    shell: ShellLike;
+    /** The links that may leave for the system browser. */
+    external: ExternalPolicy;
+    /** `app.isPackaged`: a packaged build refuses the DevTools keys. */
+    packaged: boolean;
+    /** A dev run's page origin, allowed for navigation; leave unset in a packaged build whatever the environment says. */
+    devServerUrl?: string;
+    /** In a dev run, this key toggles DevTools. Default `F12`; null for none. */
+    devToolsKey?: string | null;
+    /** Where refusals are reported. Default `console.log`. */
+    log?: (...args: unknown[]) => void;
+}
+/**
+ * Keeps a window on the game: a new window is never opened (an allowed link goes to the system browser instead, any
+ * other is refused), the window never navigates or redirects away from the game's own page, and a packaged build
+ * refuses the DevTools keys (set `webPreferences.devTools: !app.isPackaged` too: the keys are only the visible way in).
+ */
+export declare function lockDownWindow(win: WindowLike, o: LockdownOptions): void;
+/**
+ * Answers every permission request and check on `session` (camera, microphone, notifications, geolocation…) with no,
+ * but those in `allow`. Chromium's default in Electron is yes to almost everything, which a game never needs.
+ */
+export declare function denyPermissions(session: SessionLike, allow?: readonly string[]): void;
+/**
+ * A packaged app started with a debugger switch quits before it opens a window. Call it first thing in the main
+ * process; `exit` defaults to `process.exit` — not `app.exit`, so nothing after the call may run.
+ */
+export declare function refuseDebugLaunch(app: AppLike, argv?: readonly string[], exit?: (code: number) => void): boolean;

package/dist/cjs/electron/lockdown.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lockDownWindow = lockDownWindow;
+exports.denyPermissions = denyPermissions;
+exports.refuseDebugLaunch = refuseDebugLaunch;
+const lockdownRules_1 = require("./lockdownRules");
+/**
+ * Keeps a window on the game: a new window is never opened (an allowed link goes to the system browser instead, any
+ * other is refused), the window never navigates or redirects away from the game's own page, and a packaged build
+ * refuses the DevTools keys (set `webPreferences.devTools: !app.isPackaged` too: the keys are only the visible way in).
+ */
+function lockDownWindow(win, o) {
+    const log = o.log ?? ((...a) => console.log(...a));
+    const wc = win.webContents;
+    const openOut = (url, what) => {
+        if ((0, lockdownRules_1.isAllowedExternal)(url, o.external))
+            void o.shell.openExternal(url).catch((err) => log('could not open', url, err));
+        else
+            log(`refused ${what}:`, url);
+    };
+    wc.setWindowOpenHandler(({ url }) => {
+        openOut(url, 'external link');
+        return { action: 'deny' };
+    });
+    wc.on('will-navigate', (event, url) => {
+        if ((0, lockdownRules_1.isAllowedNavigation)(url, o.devServerUrl))
+            return;
+        event.preventDefault();
+        openOut(url, 'navigation');
+    });
+    wc.on('will-redirect', (event, url) => {
+        if (!(0, lockdownRules_1.isAllowedNavigation)(url, o.devServerUrl))
+            event.preventDefault();
+    });
+    const devKey = o.devToolsKey === undefined ? 'F12' : o.devToolsKey;
+    wc.on('before-input-event', (event, input) => {
+        if (o.packaged) {
+            if ((0, lockdownRules_1.isDevToolsKey)(input))
+                event.preventDefault();
+            return;
+        }
+        if (devKey && input.type === 'keyDown' && input.key === devKey) {
+            wc.toggleDevTools();
+            event.preventDefault();
+        }
+    });
+}
+/**
+ * Answers every permission request and check on `session` (camera, microphone, notifications, geolocation…) with no,
+ * but those in `allow`. Chromium's default in Electron is yes to almost everything, which a game never needs.
+ */
+function denyPermissions(session, allow = []) {
+    const allowed = new Set(allow);
+    session.setPermissionRequestHandler((_wc, permission, callback) => callback(allowed.has(permission)));
+    session.setPermissionCheckHandler((_wc, permission) => allowed.has(permission));
+}
+/**
+ * A packaged app started with a debugger switch quits before it opens a window. Call it first thing in the main
+ * process; `exit` defaults to `process.exit` — not `app.exit`, so nothing after the call may run.
+ */
+function refuseDebugLaunch(app, argv = process.argv, exit = (c) => process.exit(c)) {
+    if (!app.isPackaged)
+        return false;
+    if (!(0, lockdownRules_1.debuggerRequested)(argv, (s) => app.commandLine.hasSwitch(s)))
+        return false;
+    console.error('[main] refusing to run with a debugger attached');
+    exit(1);
+    return true;
+}

package/dist/cjs/electron/lockdownRules.d.ts

@@ -0,0 +1,28 @@
+import type { InputLike } from './electronLike';
+/**
+ * The links a locked-down window may open in the system browser: https only, no credentials in the URL, to one of
+ * `hosts` or a subdomain of it — or, for a host where anyone can publish a page (a code host), only under one of its
+ * `paths`.
+ */
+export interface ExternalPolicy {
+    /** Hosts allowed whole, each with its subdomains (`example.com` allows `www.example.com`). */
+    hosts: readonly string[];
+    /** Hosts allowed only under a path prefix (exact host, prefix compared case-insensitively), e.g. one owner's repositories. */
+    paths?: readonly {
+        host: string;
+        prefix: string;
+    }[];
+}
+/** Whether `url` is a link {@link ExternalPolicy} lets out to the system browser. */
+export declare function isAllowedExternal(url: string, policy: ExternalPolicy): boolean;
+/**
+ * The game's own page: the bundled `file://` build, or the dev server's origin in a dev run. Anything else followed
+ * inside the window would replace the game with a web page that has the shell's preload API.
+ */
+export declare function isAllowedNavigation(url: string, devServerUrl?: string): boolean;
+/** The keys that open DevTools (F12, Ctrl/Cmd+Shift/Alt+I/J/C), refused in a packaged build. */
+export declare function isDevToolsKey(input: InputLike): boolean;
+/** Chromium and Node switches that attach a debugger to a running app. */
+export declare const DEBUG_SWITCHES: readonly string[];
+/** Whether the command line (`argv`, or a switch Chromium parsed: `hasSwitch`) asks for a debugger. */
+export declare function debuggerRequested(argv: readonly string[], hasSwitch?: (name: string) => boolean): boolean;

package/dist/cjs/electron/lockdownRules.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEBUG_SWITCHES = void 0;
+exports.isAllowedExternal = isAllowedExternal;
+exports.isAllowedNavigation = isAllowedNavigation;
+exports.isDevToolsKey = isDevToolsKey;
+exports.debuggerRequested = debuggerRequested;
+function parse(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `url` is a link {@link ExternalPolicy} lets out to the system browser. */
+function isAllowedExternal(url, policy) {
+    const u = parse(url);
+    if (!u || u.protocol !== 'https:' || u.username || u.password)
+        return false;
+    const host = u.hostname.toLowerCase();
+    const scoped = (policy.paths ?? []).filter((p) => p.host.toLowerCase() === host);
+    if (scoped.length)
+        return scoped.some((p) => u.pathname.toLowerCase().startsWith(p.prefix.toLowerCase()));
+    return policy.hosts.some((h) => {
+        const want = h.toLowerCase();
+        return host === want || host.endsWith(`.${want}`);
+    });
+}
+/**
+ * The game's own page: the bundled `file://` build, or the dev server's origin in a dev run. Anything else followed
+ * inside the window would replace the game with a web page that has the shell's preload API.
+ */
+function isAllowedNavigation(url, devServerUrl) {
+    const u = parse(url);
+    if (!u)
+        return false;
+    if (devServerUrl) {
+        const dev = parse(devServerUrl);
+        return !!dev && u.origin === dev.origin;
+    }
+    return u.protocol === 'file:';
+}
+/** The keys that open DevTools (F12, Ctrl/Cmd+Shift/Alt+I/J/C), refused in a packaged build. */
+function isDevToolsKey(input) {
+    if (input.type !== 'keyDown')
+        return false;
+    if (input.key === 'F12')
+        return true;
+    const key = input.key.toLowerCase();
+    const mod = input.control || input.meta;
+    return mod && (input.shift || input.alt) && (key === 'i' || key === 'j' || key === 'c');
+}
+/** Chromium and Node switches that attach a debugger to a running app. */
+exports.DEBUG_SWITCHES = ['--inspect', '--remote-debugging-port', '--remote-debugging-pipe', '--remote-debugging-address'];
+const DEBUG_SWITCH_NAMES = ['remote-debugging-port', 'remote-debugging-pipe', 'inspect', 'inspect-brk'];
+/** Whether the command line (`argv`, or a switch Chromium parsed: `hasSwitch`) asks for a debugger. */
+function debuggerRequested(argv, hasSwitch = () => false) {
+    const flagged = argv.some((arg) => exports.DEBUG_SWITCHES.some((s) => arg === s || arg.startsWith(`${s}=`) || arg.startsWith(`${s}-`)));
+    return flagged || DEBUG_SWITCH_NAMES.some((s) => hasSwitch(s));
+}

package/dist/cjs/electron/sessionStore.d.ts

@@ -0,0 +1,40 @@
+import type { IpcMainLike, SafeStorageLike } from './electronLike';
+/** Where and how a {@link SessionStore} keeps its one secret. */
+export interface SessionStoreOptions {
+    /** `electron.safeStorage`. */
+    safeStorage: SafeStorageLike;
+    /** The folder, e.g. `app.getPath('userData')` — a second app (a test build) with its own user data keeps its own. */
+    dir: string;
+    /** Default `session.bin`. */
+    fileName?: string;
+    /** Longest value accepted, in characters. Default 4096: a saved login is a token and a name, never a blob. */
+    maxLength?: number;
+    /** Default `process.platform`. */
+    platform?: string;
+}
+/**
+ * One small secret (a refresh token and username, as a JSON string) kept for "stay logged in", encrypted by the OS —
+ * `safeStorage`: DPAPI for the Windows user, the Keychain on the Mac. Where the OS offers no real encryption (Linux
+ * without a keyring: `basic_text`, a key written into Chromium) nothing is written and the player logs in again after
+ * closing; a token on disk in the clear is worse than that. Never `localStorage`: any script in the page could read it.
+ */
+export declare class SessionStore {
+    private readonly o;
+    private readonly file;
+    private readonly maxLength;
+    private readonly platform;
+    constructor(o: SessionStoreOptions);
+    /** Whether the OS can encrypt for real here. */
+    canEncrypt(): boolean;
+    /** The saved value, or null when there is none, it cannot be decrypted (another OS user, a reinstall) or nothing may be. */
+    get(): Promise<string | null>;
+    /** Saves `value`; false when it is not a string, too long, or the OS cannot encrypt it. */
+    set(value: unknown): Promise<boolean>;
+    clear(): Promise<void>;
+}
+/**
+ * Answers a renderer's `<prefix>:get`, `<prefix>:set` (one string) and `<prefix>:clear` from `store`, so the page only
+ * ever sees the plain value, and only its own. Expose them in the preload with `ipcRenderer.invoke`. Returns a function
+ * that removes the handlers.
+ */
+export declare function registerSessionStore(ipcMain: IpcMainLike, store: SessionStore, prefix?: string): () => void;

package/dist/cjs/electron/sessionStore.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+exports.registerSessionStore = registerSessionStore;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * One small secret (a refresh token and username, as a JSON string) kept for "stay logged in", encrypted by the OS —
+ * `safeStorage`: DPAPI for the Windows user, the Keychain on the Mac. Where the OS offers no real encryption (Linux
+ * without a keyring: `basic_text`, a key written into Chromium) nothing is written and the player logs in again after
+ * closing; a token on disk in the clear is worse than that. Never `localStorage`: any script in the page could read it.
+ */
+class SessionStore {
+    o;
+    file;
+    maxLength;
+    platform;
+    constructor(o) {
+        this.o = o;
+        this.file = (0, node_path_1.join)(o.dir, o.fileName ?? 'session.bin');
+        this.maxLength = o.maxLength ?? 4096;
+        this.platform = o.platform ?? process.platform;
+    }
+    /** Whether the OS can encrypt for real here. */
+    canEncrypt() {
+        const s = this.o.safeStorage;
+        if (!s.isEncryptionAvailable())
+            return false;
+        return this.platform !== 'linux' || s.getSelectedStorageBackend?.() !== 'basic_text';
+    }
+    /** The saved value, or null when there is none, it cannot be decrypted (another OS user, a reinstall) or nothing may be. */
+    async get() {
+        if (!this.canEncrypt())
+            return null;
+        try {
+            return this.o.safeStorage.decryptString(await node_fs_1.promises.readFile(this.file));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Saves `value`; false when it is not a string, too long, or the OS cannot encrypt it. */
+    async set(value) {
+        if (typeof value !== 'string' || value.length > this.maxLength || !this.canEncrypt())
+            return false;
+        // written beside it and renamed over it, so a crash or a second write mid-way never leaves half a file
+        const temp = `${this.file}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            await node_fs_1.promises.mkdir(this.o.dir, { recursive: true });
+            await node_fs_1.promises.writeFile(temp, this.o.safeStorage.encryptString(value));
+            await node_fs_1.promises.rename(temp, this.file);
+        }
+        catch (err) {
+            await node_fs_1.promises.rm(temp, { force: true });
+            throw err;
+        }
+        return true;
+    }
+    async clear() {
+        await node_fs_1.promises.rm(this.file, { force: true });
+    }
+}
+exports.SessionStore = SessionStore;
+/**
+ * Answers a renderer's `<prefix>:get`, `<prefix>:set` (one string) and `<prefix>:clear` from `store`, so the page only
+ * ever sees the plain value, and only its own. Expose them in the preload with `ipcRenderer.invoke`. Returns a function
+ * that removes the handlers.
+ */
+function registerSessionStore(ipcMain, store, prefix = 'session') {
+    ipcMain.handle(`${prefix}:get`, () => store.get());
+    ipcMain.handle(`${prefix}:set`, (_e, value) => store.set(value));
+    ipcMain.handle(`${prefix}:clear`, () => store.clear());
+    return () => {
+        for (const c of ['get', 'set', 'clear'])
+            ipcMain.removeHandler?.(`${prefix}:${c}`);
+    };
+}

package/dist/cjs/electron/shellId.d.ts

@@ -0,0 +1,22 @@
+/** What goes into a shell's identity besides the runtime's version. */
+export interface ShellIdOptions {
+    /** Folders whose files (non-recursive) are hashed, in this order. */
+    dirs: string[];
+    /** Which files of each folder count; default the compiled main-process code, `*.cjs`. */
+    match?: (fileName: string) => boolean;
+    /** More text to fold in (an engine or framework version the main process bundles from elsewhere). */
+    extra?: string[];
+    /** Hex characters kept; default 16. */
+    length?: number;
+}
+/**
+ * A desktop shell's identity: a hash of the main process's own code and the Electron version it runs on. A web patch
+ * is taken only by a shell with the same identity, because the web talks to the shell through its preload script and
+ * may need what a newer shell adds; anything else comes with an installer. The publish script reckons it the same way
+ * off the build it uploads, so nobody has to remember to raise a number when the shell changes.
+ *
+ * `shellId(version, dir)` hashes `dir`'s `*.cjs`; pass {@link ShellIdOptions} for more folders or other files. With one
+ * folder, the default match and no `extra`, both forms give the same hash. Code the shell takes from `node_modules`
+ * (this module included) is not in `dir`: name its version in `extra`, or a change there would not change the identity.
+ */
+export declare function shellId(electronVersion: string, dirOrOptions: string | ShellIdOptions): string;

package/dist/cjs/electron/shellId.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shellId = shellId;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * A desktop shell's identity: a hash of the main process's own code and the Electron version it runs on. A web patch
+ * is taken only by a shell with the same identity, because the web talks to the shell through its preload script and
+ * may need what a newer shell adds; anything else comes with an installer. The publish script reckons it the same way
+ * off the build it uploads, so nobody has to remember to raise a number when the shell changes.
+ *
+ * `shellId(version, dir)` hashes `dir`'s `*.cjs`; pass {@link ShellIdOptions} for more folders or other files. With one
+ * folder, the default match and no `extra`, both forms give the same hash. Code the shell takes from `node_modules`
+ * (this module included) is not in `dir`: name its version in `extra`, or a change there would not change the identity.
+ */
+function shellId(electronVersion, dirOrOptions) {
+    const o = typeof dirOrOptions === 'string' ? { dirs: [dirOrOptions] } : dirOrOptions;
+    const match = o.match ?? ((f) => f.endsWith('.cjs'));
+    const h = (0, node_crypto_1.createHash)('sha256');
+    h.update(`electron ${electronVersion}\n`);
+    for (const dir of o.dirs) {
+        for (const name of (0, node_fs_1.readdirSync)(dir).filter(match).sort()) {
+            h.update(`${name}\n`);
+            h.update((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, name)));
+        }
+    }
+    for (const e of o.extra ?? [])
+        h.update(`extra ${e}\n`);
+    return h.digest('hex').slice(0, o.length ?? 16);
+}

package/dist/cjs/electron/webFiles.d.ts

@@ -0,0 +1,13 @@
+/** Lower-case hex sha256. */
+export declare const sha256: (data: Uint8Array) => string;
+/** Every file under `dir`, as forward-slash paths relative to it. */
+export declare function listFiles(dir: string, base?: string): Promise<string[]>;
+/** Every file of the web in `dir`, path → sha256. */
+export declare function hashWeb(dir: string): Promise<Map<string, string>>;
+/** Writes `data` at the manifest path `path` under `dir`, making its folders. */
+export declare function putFile(dir: string, path: string, data: Uint8Array): Promise<void>;
+/**
+ * `fetch` that gives up after `ms` and never takes a cached answer: a store behind a CDN otherwise hands back
+ * yesterday's `latest.json`, and a stalled connection would hold an update check open for good.
+ */
+export declare function fetchWithTimeout(fetcher: typeof fetch, url: string, ms: number): Promise<Response>;

package/dist/cjs/electron/webFiles.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256 = void 0;
+exports.listFiles = listFiles;
+exports.hashWeb = hashWeb;
+exports.putFile = putFile;
+exports.fetchWithTimeout = fetchWithTimeout;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+/** Lower-case hex sha256. */
+const sha256 = (data) => (0, node_crypto_1.createHash)('sha256').update(data).digest('hex');
+exports.sha256 = sha256;
+/** Every file under `dir`, as forward-slash paths relative to it. */
+async function listFiles(dir, base = '') {
+    const out = [];
+    for (const e of await (0, promises_1.readdir)((0, node_path_1.join)(dir, base), { withFileTypes: true })) {
+        const rel = base ? `${base}/${e.name}` : e.name;
+        if (e.isDirectory())
+            out.push(...(await listFiles(dir, rel)));
+        else
+            out.push(rel);
+    }
+    return out;
+}
+/** Every file of the web in `dir`, path → sha256. */
+async function hashWeb(dir) {
+    const have = new Map();
+    for (const path of await listFiles(dir))
+        have.set(path, (0, exports.sha256)(await (0, promises_1.readFile)((0, node_path_1.join)(dir, ...path.split('/')))));
+    return have;
+}
+/** Writes `data` at the manifest path `path` under `dir`, making its folders. */
+async function putFile(dir, path, data) {
+    const file = (0, node_path_1.join)(dir, ...path.split('/'));
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(file), { recursive: true });
+    await (0, promises_1.writeFile)(file, data);
+}
+/**
+ * `fetch` that gives up after `ms` and never takes a cached answer: a store behind a CDN otherwise hands back
+ * yesterday's `latest.json`, and a stalled connection would hold an update check open for good.
+ */
+async function fetchWithTimeout(fetcher, url, ms) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), ms);
+    try {
+        return await fetcher(url, { signal: ctrl.signal, cache: 'no-store' });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}