1681-engine 0.5.9 → 0.6.0

package/dist/cjs/electron/webPatcher.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebPatcher = void 0;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const manifest_1 = require("../updates/manifest");
+const webPlan_1 = require("../updates/webPlan");
+const webFiles_1 = require("./webFiles");
+const webPointers_1 = require("./webPointers");
+/**
+ * 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.
+ */
+class WebPatcher {
+    options;
+    o;
+    pointers;
+    shellValue = null;
+    /** The web this run loads, and its version (the installed build's own when none is patched in). */
+    loaded = null;
+    /** The tidy a start began: a build waits for it, or it could delete the `.part` folder being filled. */
+    tidying = Promise.resolve();
+    tidyChain = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.o = {
+            root: options.root,
+            builtinDir: options.builtinDir,
+            appVersion: options.appVersion,
+            channelUrl: options.channelUrl,
+            packaged: options.packaged ?? true,
+            maxTries: options.maxTries ?? 2,
+            keepPrevious: options.keepPrevious ?? true,
+            entry: options.entry ?? 'index.html',
+            parallel: options.parallel ?? 6,
+            fetchTimeoutMs: options.fetchTimeoutMs ?? 15_000,
+            fetch: options.fetch ?? ((url, init) => globalThis.fetch(url, init)),
+            log: options.log ?? ((...a) => console.error(...a)),
+        };
+        this.pointers = new webPointers_1.WebPointers(options.root);
+    }
+    /** This shell's identity. */
+    get shell() {
+        const s = this.options.shell;
+        this.shellValue ??= typeof s === 'string' ? s : s();
+        return this.shellValue;
+    }
+    /** Where the window loads the page from: a patched web when there is a good one, else the built-in copy. */
+    startEntry() {
+        if (!this.o.packaged) {
+            this.loaded = { dir: this.o.builtinDir, version: this.o.appVersion };
+            return (0, node_path_1.join)(this.o.builtinDir, this.o.entry);
+        }
+        try {
+            // a web built and left for later becomes the one in use on this start
+            const pending = this.pointers.read('pending');
+            if (this.usable(pending))
+                this.promote(pending, 0);
+            this.pointers.write('pending', null);
+            const active = this.pointers.read('active');
+            if (this.usable(active) && (active.booted || active.tries < this.o.maxTries)) {
+                if (!active.booted)
+                    this.pointers.write('active', { ...active, tries: active.tries + 1 });
+                this.loaded = { dir: (0, node_path_1.join)(this.o.root, active.version), version: active.version };
+            }
+            else {
+                // never booted, from another shell, or overtaken by an installer: back to the last good web, else the built-in
+                if (active)
+                    this.pointers.write('active', null);
+                const previous = this.pointers.read('previous');
+                this.pointers.write('previous', null);
+                if (this.o.keepPrevious && previous?.booted && this.usable(previous)) {
+                    this.pointers.write('active', previous);
+                    this.loaded = { dir: (0, node_path_1.join)(this.o.root, previous.version), version: previous.version };
+                }
+            }
+        }
+        catch (err) {
+            this.o.log('[web] could not read the patched web, using the built-in one', err);
+        }
+        this.loaded ??= { dir: this.o.builtinDir, version: this.o.appVersion };
+        this.tidying = this.tidy();
+        return (0, node_path_1.join)(this.loaded.dir, this.o.entry);
+    }
+    /** The version of the web running now. */
+    webVersion() {
+        return this.loaded?.version ?? this.o.appVersion;
+    }
+    /** 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() {
+        const active = this.pointers.read('active');
+        if (active && this.loaded && active.version === this.loaded.version && !active.booted)
+            this.pointers.write('active', { ...active, booted: true });
+    }
+    /** The channel's newest build, or null when the store cannot be read. */
+    async latest() {
+        try {
+            const res = await (0, webFiles_1.fetchWithTimeout)(this.o.fetch, `${this.o.channelUrl}/latest.json`, this.o.fetchTimeoutMs);
+            if (!res.ok)
+                return null;
+            const l = (await res.json());
+            return typeof l?.version === 'string' ? l : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Whether `l`'s web can be patched in here rather than installed: newer than the web running, for this shell. */
+    patchable(l) {
+        return !!l.web && l.web.shell === this.shell && (0, manifest_1.isNewer)(l.version, this.webVersion());
+    }
+    /**
+     * 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.
+     */
+    async prepare(l, onProgress = () => undefined) {
+        if (!l.web)
+            throw new Error('no web in this release');
+        const res = await (0, webFiles_1.fetchWithTimeout)(this.o.fetch, `${this.o.channelUrl}/${l.web.manifest}`, this.o.fetchTimeoutMs);
+        if (!res.ok)
+            throw new Error(`web manifest ${res.status}`);
+        const target = await res.json();
+        if (!(0, manifest_1.validManifest)(target) || target.version !== l.version || target.shell !== this.shell)
+            throw new Error('bad web manifest');
+        const done = (0, node_path_1.join)(this.o.root, target.version);
+        const pointer = { version: target.version, shell: target.shell, booted: false, tries: 0 };
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(done, this.o.entry)) && this.pointers.read('active')?.version !== target.version) {
+            // already assembled by an earlier run that stopped before it was put in use
+            this.pointers.write('pending', pointer);
+            onProgress(100);
+            return target.version;
+        }
+        await this.tidying;
+        const from = this.loaded?.dir ?? this.o.builtinDir;
+        const plan = (0, webPlan_1.planWeb)(target, await (0, webFiles_1.hashWeb)(from));
+        const part = (0, node_path_1.join)(this.o.root, `${target.version}.part`);
+        await (0, promises_1.rm)(part, { recursive: true, force: true });
+        await (0, promises_1.mkdir)(part, { recursive: true });
+        for (const c of plan.copy)
+            await (0, webFiles_1.putFile)(part, c.path, await (0, promises_1.readFile)((0, node_path_1.join)(from, ...c.from.split('/'))));
+        let got = 0;
+        const fetched = new Map();
+        const queue = [...plan.download];
+        onProgress(plan.bytes ? 0 : 100);
+        const worker = async () => {
+            for (let f = queue.shift(); f; f = queue.shift()) {
+                let data = fetched.get(f.sha256);
+                if (!data) {
+                    const r = await (0, webFiles_1.fetchWithTimeout)(this.o.fetch, (0, manifest_1.fileUrl)(this.o.channelUrl, f.sha256), this.o.fetchTimeoutMs);
+                    if (!r.ok)
+                        throw new Error(`${f.path}: ${r.status}`);
+                    data = new Uint8Array(await r.arrayBuffer());
+                    if ((0, webFiles_1.sha256)(data) !== f.sha256)
+                        throw new Error(`${f.path}: checksum`);
+                    fetched.set(f.sha256, data);
+                    got += f.size;
+                    onProgress(Math.min(99, Math.round((got / Math.max(1, plan.bytes)) * 100)));
+                }
+                await (0, webFiles_1.putFile)(part, f.path, data);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.max(1, this.o.parallel) }, worker));
+        await (0, promises_1.rm)(done, { recursive: true, force: true });
+        await (0, promises_1.rename)(part, done);
+        this.pointers.write('pending', pointer);
+        onProgress(100);
+        return target.version;
+    }
+    /**
+     * 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() {
+        const pending = this.pointers.read('pending');
+        if (!this.usable(pending))
+            return null;
+        this.promote(pending, 1);
+        this.pointers.write('pending', null);
+        this.loaded = { dir: (0, node_path_1.join)(this.o.root, pending.version), version: pending.version };
+        return (0, node_path_1.join)(this.loaded.dir, this.o.entry);
+    }
+    /** Makes `p` the active web, keeping the one it replaces as the fallback when that one ever booted. */
+    promote(p, tries) {
+        const active = this.pointers.read('active');
+        if (this.o.keepPrevious && active?.booted && active.version !== p.version)
+            this.pointers.write('previous', active);
+        this.pointers.write('active', { ...p, booted: false, tries });
+    }
+    /** A pointer this shell may load: its own shell, newer than the installed build, its folder whole. */
+    usable(p) {
+        return !!p && p.shell === this.shell && (0, manifest_1.isNewer)(p.version, this.o.appVersion) && (0, node_fs_1.existsSync)((0, node_path_1.join)(this.o.root, p.version, this.o.entry));
+    }
+    /** Removes every patched web but the active, pending and previous one, and any half-made folder. A call made while
+     * one is running waits for it and then runs once more, so two never delete the same folder at once. */
+    tidy() {
+        const next = this.tidyChain.then(() => this.tidyOnce());
+        this.tidyChain = next;
+        return next;
+    }
+    async tidyOnce() {
+        try {
+            const names = ['active', 'pending', 'previous'];
+            const keep = new Set([...names.map((n) => this.pointers.read(n)?.version), this.loaded?.version].filter((v) => !!v));
+            for (const name of await (0, promises_1.readdir)(this.o.root)) {
+                if (name.endsWith('.json') || keep.has(name))
+                    continue;
+                await (0, promises_1.rm)((0, node_path_1.join)(this.o.root, name), { recursive: true, force: true });
+            }
+        }
+        catch {
+            // no web folder yet
+        }
+    }
+}
+exports.WebPatcher = WebPatcher;

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

@@ -0,0 +1,19 @@
+/** Which patched web a pointer names, and whether it ever came up. */
+export interface WebPointer {
+    version: string;
+    shell: string;
+    /** The page reported booting from it at least once. */
+    booted: boolean;
+    /** Starts it was loaded on without booting. */
+    tries: number;
+}
+/** `active`: in use; `pending`: built, put in use on the next start; `previous`: the last web that booted before `active`. */
+export type PointerName = 'active' | 'pending' | 'previous';
+/** The pointer files beside the patched webs (`<root>/<name>.json`), read and written whole. */
+export declare class WebPointers {
+    private readonly root;
+    constructor(root: string);
+    read(name: PointerName): WebPointer | null;
+    write(name: PointerName, p: WebPointer | null): void;
+    private file;
+}

package/dist/cjs/electron/webPointers.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebPointers = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** The pointer files beside the patched webs (`<root>/<name>.json`), read and written whole. */
+class WebPointers {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    read(name) {
+        try {
+            const p = JSON.parse((0, node_fs_1.readFileSync)(this.file(name), 'utf8'));
+            if (typeof p?.version !== 'string' || typeof p.shell !== 'string')
+                return null;
+            return { version: p.version, shell: p.shell, booted: p.booted === true, tries: typeof p.tries === 'number' ? p.tries : 0 };
+        }
+        catch {
+            return null;
+        }
+    }
+    write(name, p) {
+        if (p) {
+            (0, node_fs_1.mkdirSync)(this.root, { recursive: true });
+            (0, node_fs_1.writeFileSync)(this.file(name), JSON.stringify(p));
+        }
+        else
+            (0, node_fs_1.rmSync)(this.file(name), { force: true });
+    }
+    file(name) {
+        return (0, node_path_1.join)(this.root, `${name}.json`);
+    }
+}
+exports.WebPointers = WebPointers;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

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

@@ -0,0 +1,8 @@
+/**
+ * `1681-engine/updates`: file-by-file web updates from a release store, the pure half — the feed's shapes, which web
+ * to take, and what to copy or download to build it. No Node, DOM or Electron: shared by the desktop shell
+ * (`1681-engine/electron`), a browser build and the phone apps.
+ */
+export { isNewer, safePath, isSha256, validManifest, fileUrl, type WebFile, type WebManifest, type LatestJson, type ReleaseFile, } from './manifest';
+export { planWeb, type WebPlan } from './webPlan';
+export { pickWebUpdate, apkUpdateOf, pluginEntries, heldBundle, type WebBundle, type NewerRelease, type PluginEntry } from './pickUpdate';

package/dist/cjs/updates/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.heldBundle = exports.pluginEntries = exports.apkUpdateOf = exports.pickWebUpdate = exports.planWeb = exports.fileUrl = exports.validManifest = exports.isSha256 = exports.safePath = exports.isNewer = void 0;
+/**
+ * `1681-engine/updates`: file-by-file web updates from a release store, the pure half — the feed's shapes, which web
+ * to take, and what to copy or download to build it. No Node, DOM or Electron: shared by the desktop shell
+ * (`1681-engine/electron`), a browser build and the phone apps.
+ */
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "isNewer", { enumerable: true, get: function () { return manifest_1.isNewer; } });
+Object.defineProperty(exports, "safePath", { enumerable: true, get: function () { return manifest_1.safePath; } });
+Object.defineProperty(exports, "isSha256", { enumerable: true, get: function () { return manifest_1.isSha256; } });
+Object.defineProperty(exports, "validManifest", { enumerable: true, get: function () { return manifest_1.validManifest; } });
+Object.defineProperty(exports, "fileUrl", { enumerable: true, get: function () { return manifest_1.fileUrl; } });
+var webPlan_1 = require("./webPlan");
+Object.defineProperty(exports, "planWeb", { enumerable: true, get: function () { return webPlan_1.planWeb; } });
+var pickUpdate_1 = require("./pickUpdate");
+Object.defineProperty(exports, "pickWebUpdate", { enumerable: true, get: function () { return pickUpdate_1.pickWebUpdate; } });
+Object.defineProperty(exports, "apkUpdateOf", { enumerable: true, get: function () { return pickUpdate_1.apkUpdateOf; } });
+Object.defineProperty(exports, "pluginEntries", { enumerable: true, get: function () { return pickUpdate_1.pluginEntries; } });
+Object.defineProperty(exports, "heldBundle", { enumerable: true, get: function () { return pickUpdate_1.heldBundle; } });

package/dist/cjs/updates/manifest.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The shapes of a release store's feed for file-by-file web updates, and the rules for trusting one. One definition
+ * for every client that reads it: the desktop shell's patcher (`1681-engine/electron`), a browser build and the phone
+ * apps' over-the-air updater. A publish script writes, per channel:
+ *
+ * - `<channel>/latest.json` ({@link LatestJson}): the newest build and where its pieces lie, as paths under the channel,
+ *   written last so a client never reads a release that is half up;
+ * - `<channel>/web/<version>.json` ({@link WebManifest}): every file of the built web with its sha256;
+ * - `<channel>/files/<sha256>`: each content once, so a release uploads and a client downloads only what is new.
+ *
+ * Kept pure (no Node, no DOM, no Electron) so a phone's web view and an Electron main process share it.
+ */
+/** One file of a built web, as the manifest lists it. */
+export interface WebFile {
+    /** Relative to the web's root, forward slashes (`assets/index-3f2a.js`). */
+    path: string;
+    /** Lower-case hex sha256 of the content; also its name under `<channel>/files/`. */
+    sha256: string;
+    size: number;
+}
+/** `<channel>/web/<version>.json`. */
+export interface WebManifest {
+    version: string;
+    /**
+     * The desktop shell this web needs (`shellId` in `1681-engine/electron`): a web talks to its shell through a
+     * preload script and may need what a newer shell adds, so any other shell takes the installer instead.
+     */
+    shell: string;
+    /** The lowest native build of the phone apps this web needs: a web calling a plugin the app lacks must never reach it. */
+    minNative: number;
+    files: WebFile[];
+}
+/** A packaged download listed in `latest.json` (an APK, an installer). */
+export interface ReleaseFile {
+    file: string;
+    size: number;
+    sha256?: string;
+}
+/** `<channel>/latest.json`. */
+export interface LatestJson {
+    version: string;
+    date?: string;
+    /** The build's web: its manifest's path under the channel, the shell and native build it needs. */
+    web?: {
+        manifest: string;
+        shell: string;
+        minNative: number;
+    };
+    /** The Android package, when the channel publishes one. */
+    apk?: {
+        file: string;
+        size: number;
+        sha256: string;
+    };
+    /** Desktop installers by platform key (the publisher names the keys, e.g. `win`, `macArm`, `macX64`). */
+    desktop?: Record<string, ReleaseFile | undefined>;
+}
+/** Whether version `a` ("0.5.23", "v0.5.23") is newer than `b`, number by number; a missing part counts 0. */
+export declare function isNewer(a: string, b: string): boolean;
+/**
+ * A path a manifest may name: relative, forward slashes, no `.` or `..` segment, no NUL — nothing that could write
+ * outside the web's own folder once joined to it.
+ */
+export declare function safePath(p: string): boolean;
+/** Whether `s` is a lower-case hex sha256. */
+export declare function isSha256(s: unknown): s is string;
+/**
+ * A manifest whose shape may be trusted: every path safe and listed once, every hash a sha256, every size a number,
+ * and an `index.html` (a web without one cannot be loaded, and a truncated upload is the usual way to get one).
+ */
+export declare function validManifest(m: unknown): m is WebManifest;
+/** Where a content lies in the store: `<channelUrl>/files/<sha256>`. */
+export declare function fileUrl(channelUrl: string, sha256: string): string;

package/dist/cjs/updates/manifest.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * The shapes of a release store's feed for file-by-file web updates, and the rules for trusting one. One definition
+ * for every client that reads it: the desktop shell's patcher (`1681-engine/electron`), a browser build and the phone
+ * apps' over-the-air updater. A publish script writes, per channel:
+ *
+ * - `<channel>/latest.json` ({@link LatestJson}): the newest build and where its pieces lie, as paths under the channel,
+ *   written last so a client never reads a release that is half up;
+ * - `<channel>/web/<version>.json` ({@link WebManifest}): every file of the built web with its sha256;
+ * - `<channel>/files/<sha256>`: each content once, so a release uploads and a client downloads only what is new.
+ *
+ * Kept pure (no Node, no DOM, no Electron) so a phone's web view and an Electron main process share it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNewer = isNewer;
+exports.safePath = safePath;
+exports.isSha256 = isSha256;
+exports.validManifest = validManifest;
+exports.fileUrl = fileUrl;
+/** Whether version `a` ("0.5.23", "v0.5.23") is newer than `b`, number by number; a missing part counts 0. */
+function isNewer(a, b) {
+    const parse = (v) => v.replace(/^v/, '').split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d > 0;
+    }
+    return false;
+}
+/**
+ * A path a manifest may name: relative, forward slashes, no `.` or `..` segment, no NUL — nothing that could write
+ * outside the web's own folder once joined to it.
+ */
+function safePath(p) {
+    if (!p || p.startsWith('/') || p.includes('\\') || p.includes('\0'))
+        return false;
+    return p.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+const SHA256 = /^[0-9a-f]{64}$/;
+/** Whether `s` is a lower-case hex sha256. */
+function isSha256(s) {
+    return typeof s === 'string' && SHA256.test(s);
+}
+/**
+ * A manifest whose shape may be trusted: every path safe and listed once, every hash a sha256, every size a number,
+ * and an `index.html` (a web without one cannot be loaded, and a truncated upload is the usual way to get one).
+ */
+function validManifest(m) {
+    const x = m;
+    if (!x || typeof x.version !== 'string' || typeof x.shell !== 'string' || !Array.isArray(x.files))
+        return false;
+    const seen = new Set();
+    for (const f of x.files) {
+        if (!f || typeof f.path !== 'string' || !safePath(f.path) || seen.has(f.path))
+            return false;
+        if (!isSha256(f.sha256) || typeof f.size !== 'number')
+            return false;
+        seen.add(f.path);
+    }
+    return seen.has('index.html');
+}
+/** Where a content lies in the store: `<channelUrl>/files/<sha256>`. */
+function fileUrl(channelUrl, sha256) {
+    return `${channelUrl}/files/${sha256}`;
+}

package/dist/cjs/updates/pickUpdate.d.ts

@@ -0,0 +1,42 @@
+import { type LatestJson } from './manifest';
+/** A web a client may take: its version, its manifest's full URL and the native build it needs. */
+export interface WebBundle {
+    version: string;
+    manifestUrl: string;
+    minNative: number;
+}
+/**
+ * The web to take from `latest`: newer than the web running (`webVersion`), and needing no native code this app lacks
+ * (`nativeBuild` ≥ the web's `minNative`). A browser or desktop build with no native layer passes `Infinity`.
+ */
+export declare function pickWebUpdate(latest: LatestJson, channelUrl: string, webVersion: string, nativeBuild: number): WebBundle | null;
+/** A newer build than this one, and where its Android package downloads from. */
+export interface NewerRelease {
+    version: string;
+    apkUrl: string;
+}
+/**
+ * The build's APK, when it is newer than this client and its web cannot come over the air instead (`webBundle` is
+ * what {@link pickWebUpdate} found): the package is the slow road, for native changes.
+ */
+export declare function apkUpdateOf(latest: LatestJson, channelUrl: string, clientVersion: string, webBundle: WebBundle | null): NewerRelease | null;
+/** One entry of a multi-file bundle download, in the shape `@capgo/capacitor-updater`'s `ManifestEntry` takes. */
+export interface PluginEntry {
+    file_name: string;
+    file_hash: string;
+    download_url: string;
+}
+/**
+ * A phone updater's download list for `manifest`, or null when the manifest is not one to trust (another version, an
+ * unsafe or repeated path, a bad hash, no `index.html`). The updater checks each file against its hash and reuses
+ * every file it already holds, so only new content is fetched.
+ */
+export declare function pluginEntries(manifest: unknown, version: string, channelUrl: string): PluginEntry[] | null;
+/**
+ * A copy of `bundle` the updater already holds whole (downloaded and checked, applied or waiting), so asking again —
+ * a settings screen's check after the login screen's — takes it instead of downloading the same files twice.
+ */
+export declare function heldBundle<T extends {
+    version: string;
+    status: string;
+}>(held: readonly T[], bundle: WebBundle): T | null;

package/dist/cjs/updates/pickUpdate.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickWebUpdate = pickWebUpdate;
+exports.apkUpdateOf = apkUpdateOf;
+exports.pluginEntries = pluginEntries;
+exports.heldBundle = heldBundle;
+const manifest_1 = require("./manifest");
+/**
+ * The web to take from `latest`: newer than the web running (`webVersion`), and needing no native code this app lacks
+ * (`nativeBuild` ≥ the web's `minNative`). A browser or desktop build with no native layer passes `Infinity`.
+ */
+function pickWebUpdate(latest, channelUrl, webVersion, nativeBuild) {
+    const w = latest.web;
+    if (!w || !(0, manifest_1.isNewer)(latest.version, webVersion) || nativeBuild < w.minNative)
+        return null;
+    return { version: latest.version, manifestUrl: `${channelUrl}/${w.manifest}`, minNative: w.minNative };
+}
+/**
+ * The build's APK, when it is newer than this client and its web cannot come over the air instead (`webBundle` is
+ * what {@link pickWebUpdate} found): the package is the slow road, for native changes.
+ */
+function apkUpdateOf(latest, channelUrl, clientVersion, webBundle) {
+    if (webBundle || !latest.apk || !(0, manifest_1.isNewer)(latest.version, clientVersion))
+        return null;
+    return { version: latest.version, apkUrl: `${channelUrl}/${latest.apk.file}` };
+}
+/**
+ * A phone updater's download list for `manifest`, or null when the manifest is not one to trust (another version, an
+ * unsafe or repeated path, a bad hash, no `index.html`). The updater checks each file against its hash and reuses
+ * every file it already holds, so only new content is fetched.
+ */
+function pluginEntries(manifest, version, channelUrl) {
+    const m = manifest;
+    if (!m || m.version !== version || !Array.isArray(m.files))
+        return null;
+    const out = [];
+    const seen = new Set();
+    for (const f of m.files) {
+        if (!f || typeof f.path !== 'string' || !(0, manifest_1.safePath)(f.path) || seen.has(f.path) || !(0, manifest_1.isSha256)(f.sha256))
+            return null;
+        seen.add(f.path);
+        out.push({ file_name: f.path, file_hash: f.sha256, download_url: (0, manifest_1.fileUrl)(channelUrl, f.sha256) });
+    }
+    return seen.has('index.html') ? out : null;
+}
+/**
+ * A copy of `bundle` the updater already holds whole (downloaded and checked, applied or waiting), so asking again —
+ * a settings screen's check after the login screen's — takes it instead of downloading the same files twice.
+ */
+function heldBundle(held, bundle) {
+    return held.find((b) => b.version === bundle.version && (b.status === 'pending' || b.status === 'success')) ?? null;
+}

package/dist/cjs/updates/webPlan.d.ts

@@ -0,0 +1,20 @@
+import type { WebFile, WebManifest } from './manifest';
+/** What building a new web takes, given the files a client already holds. */
+export interface WebPlan {
+    /** Files taken from the web held now: `from` is their path there. */
+    copy: {
+        path: string;
+        from: string;
+    }[];
+    /** Files to fetch from `<channel>/files/<sha256>`; content shared by several paths appears once per path. */
+    download: WebFile[];
+    /** Bytes to download, each distinct content counted once. */
+    bytes: number;
+}
+/**
+ * What to copy and what to download for `target`, given the web held now (`have`: path → sha256): a file whose path
+ * holds the same content is copied from there, one whose content lies under another path (a bundler renamed it) is
+ * copied from that path, and only content found nowhere is downloaded — once, however many paths share it. This is
+ * what makes a patch cost only what changed, the way a game launcher patches.
+ */
+export declare function planWeb(target: WebManifest, have: ReadonlyMap<string, string>): WebPlan;

package/dist/cjs/updates/webPlan.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planWeb = planWeb;
+/**
+ * What to copy and what to download for `target`, given the web held now (`have`: path → sha256): a file whose path
+ * holds the same content is copied from there, one whose content lies under another path (a bundler renamed it) is
+ * copied from that path, and only content found nowhere is downloaded — once, however many paths share it. This is
+ * what makes a patch cost only what changed, the way a game launcher patches.
+ */
+function planWeb(target, have) {
+    const byHash = new Map();
+    for (const [path, sha] of have)
+        if (!byHash.has(sha))
+            byHash.set(sha, path);
+    const copy = [];
+    const download = [];
+    const fetched = new Set();
+    let bytes = 0;
+    for (const f of target.files) {
+        const there = byHash.get(f.sha256);
+        if (have.get(f.path) === f.sha256)
+            copy.push({ path: f.path, from: f.path });
+        else if (there !== undefined)
+            copy.push({ path: f.path, from: there });
+        else {
+            download.push(f);
+            if (!fetched.has(f.sha256)) {
+                fetched.add(f.sha256);
+                bytes += f.size;
+            }
+        }
+    }
+    return { copy, download, bytes };
+}