1681-engine 0.5.8 → 0.5.10

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);
+    }
+}

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

@@ -0,0 +1,80 @@
+import { type LatestJson } from '../updates/manifest';
+/** How a {@link WebPatcher} finds its webs and its store. */
+export interface WebPatcherOptions {
+    /** Where patched webs are built and kept, e.g. `join(app.getPath('userData'), 'web')`. */
+    root: string;
+    /** The web the installed build ships (the folder holding its `index.html`). */
+    builtinDir: string;
+    /** The installed build's version (`app.getVersion()`): a patched web must be newer to be loaded. */
+    appVersion: string;
+    /** This shell's identity (`shellId`), or a function reckoning it on first use. */
+    shell: string | (() => string);
+    /** The store's channel, e.g. `https://store.example/public/live`: `latest.json`, `web/…`, `files/…` lie under it. */
+    channelUrl: string;
+    /** False in a dev run: the built-in web is always loaded and nothing is read or tidied. Default true. */
+    packaged?: boolean;
+    /** Starts an unconfirmed web gets before it is dropped. Default 2. */
+    maxTries?: number;
+    /** Fall back to the last web that booted, rather than the built-in one, when a new web never boots. Default true. */
+    keepPrevious?: boolean;
+    /** The page file in a web. Default `index.html`. */
+    entry?: string;
+    /** Downloads at once. Default 6. */
+    parallel?: number;
+    /** Per request. Default 15 000 ms. */
+    fetchTimeoutMs?: number;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Where a failure to read the patched webs is reported. Default `console.error`. */
+    log?: (...args: unknown[]) => void;
+}
+/**
+ * A desktop shell that patches its web file by file, the way a game launcher does: the web a build ships is its
+ * built-in copy, and every newer web is assembled beside it in `<root>/<version>/` from the files already held plus
+ * only those whose content is new (`<channel>/files/<sha256>`, checked against their hash), then loaded in its place.
+ * A web is taken only by a shell of the same identity; any other change needs an installer. A web that never reports
+ * booting ({@link markBooted}, from the page) within `maxTries` starts is dropped, and the shell goes back to the last
+ * web that did — or the built-in one — so a broken release cannot lock a player out.
+ *
+ * Use one per process: {@link startEntry} first (it decides which web this run loads), then the update calls.
+ */
+export declare class WebPatcher {
+    private readonly options;
+    private readonly o;
+    private readonly pointers;
+    private shellValue;
+    /** The web this run loads, and its version (the installed build's own when none is patched in). */
+    private loaded;
+    /** The tidy a start began: a build waits for it, or it could delete the `.part` folder being filled. */
+    private tidying;
+    constructor(options: WebPatcherOptions);
+    /** This shell's identity. */
+    get shell(): string;
+    /** Where the window loads the page from: a patched web when there is a good one, else the built-in copy. */
+    startEntry(): string;
+    /** The version of the web running now. */
+    webVersion(): string;
+    /** The page came up: the web it was loaded from is kept from now on. Call it from the page's own "booted" message. */
+    markBooted(): void;
+    /** The channel's newest build, or null when the store cannot be read. */
+    latest(): Promise<LatestJson | null>;
+    /** Whether `l`'s web can be patched in here rather than installed: newer than the web running, for this shell. */
+    patchable(l: LatestJson): boolean;
+    /**
+     * Builds `l`'s web beside the one running: the files held are copied, the rest downloaded and checked, into
+     * `<version>.part/`, which becomes `<version>/` and the pending web once whole — a crash mid-way never leaves a
+     * folder that looks finished. `onProgress` gets 0–100. Resolves with the version built; throws on any failure.
+     */
+    prepare(l: LatestJson, onProgress?: (percent: number) => void): Promise<string>;
+    /**
+     * Puts the pending web in use now and returns the page to load (reload every window from it), or null when there is
+     * none this shell may load. The switch counts as its first start, so a web that never boots is still dropped.
+     */
+    applyPending(): string | null;
+    /** Makes `p` the active web, keeping the one it replaces as the fallback when that one ever booted. */
+    private promote;
+    /** A pointer this shell may load: its own shell, newer than the installed build, its folder whole. */
+    private usable;
+    /** Removes every patched web but the active, pending and previous one, and any half-made folder. */
+    tidy(): Promise<void>;
+}