@driftengine/package 3.61.0

package/dist/main/window.d.ts

@@ -0,0 +1,19 @@
+import type { PackageManifest, Target } from '../manifest.ts';
+/**
+ * The window, the scheme the game is served over, and the switches it launches with.
+ *
+ * **`drift://` rather than `file://`, and it is not a preference.** ES modules, `fetch` and
+ * workers all need an origin, and `file://` is not one — a game served from it fails to load its
+ * own modules, which reads as a broken build rather than as a missing origin.
+ *
+ * **Every switch is appended before `ready`.** Chromium reads its command line once at startup;
+ * a switch appended after the app is ready is accepted silently and does nothing, which is the
+ * worst available failure mode for a flag whose whole job is invisible.
+ *
+ * Not unit-tested, deliberately: this is Electron lifecycle and window state, there is no Electron
+ * in the test environment, and the two pieces with logic worth checking — the flag plan and the
+ * path resolver — are pure modules that are. What proves this file is `drift-package run`.
+ */
+export declare function startApp(manifest: PackageManifest, root: string, target: Target, options?: {
+    readonly development: boolean;
+}): Promise<void>;

package/dist/main/window.js

@@ -0,0 +1,297 @@
+import { BrowserWindow, Menu, app, protocol, shell } from 'electron';
+import { createReadStream } from 'node:fs';
+import { basename, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { planFlags } from '../flags.js';
+import { installIpc, readStoreSnapshot } from './ipc.js';
+import { externalTarget } from './links.js';
+import { appMenuTemplate } from './menu.js';
+import { isBlockedShortcut } from './shortcuts.js';
+import { openSteam } from '../steam/main.js';
+import { contentTypeFor, resolveWithinRoot } from './serve.js';
+import { createSplash } from './splash.js';
+import { splashDecision } from './splashTiming.js';
+import { consoleLine, forwardsConsole } from './consoleForward.js';
+import { CSP } from './csp.js';
+import { electronMajor } from '../runtimeVersion.js';
+/** How often the swap condition is re-read. Fine enough not to be seen, coarse enough to cost
+    nothing during a boot that is already busy. */
+const SPLASH_POLL_MS = 80;
+/**
+ * The window, the scheme the game is served over, and the switches it launches with.
+ *
+ * **`drift://` rather than `file://`, and it is not a preference.** ES modules, `fetch` and
+ * workers all need an origin, and `file://` is not one — a game served from it fails to load its
+ * own modules, which reads as a broken build rather than as a missing origin.
+ *
+ * **Every switch is appended before `ready`.** Chromium reads its command line once at startup;
+ * a switch appended after the app is ready is accepted silently and does nothing, which is the
+ * worst available failure mode for a flag whose whole job is invisible.
+ *
+ * Not unit-tested, deliberately: this is Electron lifecycle and window state, there is no Electron
+ * in the test environment, and the two pieces with logic worth checking — the flag plan and the
+ * path resolver — are pure modules that are. What proves this file is `drift-package run`.
+ */
+export async function startApp(manifest, root, target, options = { development: false }) {
+    /*
+     * **The version is read here rather than assumed**, because this is the one place that cannot be
+     * wrong about it: `process.versions.electron` is the runtime executing this line, whatever a
+     * consumer's install resolved. A switch is only asked for on a runtime it has been seen to work
+     * on, and where one is declined the reason is printed rather than left to look like a driver
+     * with no adapter.
+     */
+    const plan = planFlags(manifest, target, electronMajor(process.versions.electron));
+    if (plan.refusal !== null)
+        throw new Error(plan.refusal);
+    for (const note of plan.notes)
+        console.log(`[drift-package] ${note}`);
+    for (const [name, value] of plan.switches) {
+        if (value === '')
+            app.commandLine.appendSwitch(name);
+        else
+            app.commandLine.appendSwitch(name, value);
+    }
+    /*
+     * **One instance, because the store is a snapshot.** The renderer reads preferences from a copy
+     * taken before the window opened, so two windows would each hold a copy and the last one to
+     * write would win silently. A second launch raises the first window instead.
+     */
+    if (!app.requestSingleInstanceLock()) {
+        app.quit();
+        return;
+    }
+    /*
+     * Privileged before `ready`, or the scheme is not a secure context: no modules, no workers,
+     * and `crossOriginIsolated` false. Registering it late throws rather than degrading, which is
+     * the behaviour to want.
+     */
+    protocol.registerSchemesAsPrivileged([
+        {
+            scheme: 'drift',
+            privileges: { standard: true, secure: true, supportFetchAPI: true, stream: true },
+        },
+    ]);
+    await app.whenReady();
+    /*
+     * **The default menu bar goes before the first window exists.** Electron installs File, Edit,
+     * View, Window and Help — with Reload and Toggle Developer Tools in it — and a game that ships
+     * with that menu is a game that announces what it was built in. macOS keeps a minimal one
+     * because that is where Cmd+Q lives; see `menu.ts`.
+     */
+    const template = appMenuTemplate(manifest.name, process.platform);
+    Menu.setApplicationMenu(template === null ? null : Menu.buildFromTemplate(template));
+    /*
+     * **Two roots, chosen by host.** `drift://app/` is the game and `drift://shell/` is the
+     * packager's own assets — the badge and the mark it draws. One handler with a table rather than
+     * two schemes, so the traversal check that guards the game's root guards the shell's by
+     * construction; an unknown host is refused rather than defaulted.
+     */
+    const roots = { app: root, shell: join(__dirname, 'shell') };
+    protocol.handle('drift', (request) => {
+        const url = new URL(request.url);
+        const base = roots[url.host];
+        if (base === undefined)
+            return new Response('unknown host', { status: 404 });
+        const resolved = resolveWithinRoot(base, decodeURIComponent(url.pathname));
+        if (resolved === null)
+            return new Response('forbidden', { status: 403 });
+        /* Streamed rather than read whole: a `.drft` world is tens of megabytes and the loader
+           consumes it progressively, which is the behaviour the streaming container exists for. */
+        return new Response(Readable.toWeb(createReadStream(resolved)), {
+            headers: { 'content-type': contentTypeFor(resolved), 'content-security-policy': CSP },
+        });
+    });
+    /*
+     * **Steam is opened before the window and before anything reads a save.** Whether the store
+     * answered decides where preferences come from, and a game that read a local file first and
+     * discovered a cloud second would show one set of settings and then replace them.
+     */
+    const steam = openSteam(manifest.steam.appId, __dirname);
+    let window = null;
+    const quit = installIpc(readStoreSnapshot(steam), () => window, steam);
+    window = new BrowserWindow({
+        width: manifest.window.width,
+        height: manifest.window.height,
+        resizable: manifest.window.resizable,
+        fullscreen: manifest.window.mode === 'fullscreen',
+        frame: manifest.window.mode !== 'borderless',
+        show: false,
+        backgroundColor: '#000000',
+        webPreferences: {
+            preload: join(__dirname, 'preload.cjs'),
+            contextIsolation: true,
+            nodeIntegration: false,
+            sandbox: true,
+            /*
+             * **Developer tools exist in a development run and do not exist in a shipped one.** Not
+             * hidden behind a shortcut nobody documents: `devTools: false` means the inspector cannot
+             * be opened at all, by a menu, an accelerator, or `webContents.openDevTools`. A player
+             * who opens one is a player looking at the inside of a game that was not built to be
+             * looked at, and a support request about it costs more than the feature is worth.
+             */
+            devTools: options.development,
+        },
+    });
+    /*
+     * **The badge holds the screen while the game builds its first frame.**
+     *
+     * Without it the sequence a player sees is: an icon bounces, a black window appears, and
+     * several seconds later a game arrives in it — which is indistinguishable from a hang. With it
+     * the window stays hidden until it has something to show.
+     *
+     * The decision itself is in `splashTiming.ts` and is pure, so the three rules that matter — has
+     * it painted, has the minimum passed, has the cap been reached — are tested without a window.
+     * Polled rather than driven by a timer per condition, because two independent deadlines and an
+     * event racing each other is how a splash ends up either flickering or permanent.
+     */
+    const splash = manifest.splash.show ? createSplash() : null;
+    if (splash === null) {
+        /* Shown on first paint rather than immediately: a window that appears white and then fills is
+           the single most common way a packaged web application looks unfinished. */
+        window.once('ready-to-show', () => window?.show());
+    }
+    else {
+        const startedAt = Date.now();
+        let painted = false;
+        let badgeShownAt = null;
+        window.once('ready-to-show', () => {
+            painted = true;
+        });
+        /*
+         * **The badge's own arrival, which is a second unbounded wait and not the same event.** It has
+         * a window to create, a protocol request to answer and an image to paint, and the minimum is
+         * the time it is meant to be readable for — so it is counted from here.
+         */
+        splash.once('show', () => {
+            badgeShownAt ??= Date.now();
+        });
+        /*
+         * And a badge that cannot load is not worth holding a game for: counting its minimum from
+         * process start is exactly what this did before, which is the right behaviour once there is
+         * nothing to wait for.
+         */
+        splash.webContents.once('did-fail-load', () => {
+            badgeShownAt ??= startedAt;
+        });
+        const poll = setInterval(() => {
+            const now = Date.now();
+            const sinceBadge = badgeShownAt === null ? null : now - badgeShownAt;
+            if (splashDecision(now - startedAt, sinceBadge, manifest.splash.minMs, painted) === 'hold')
+                return;
+            clearInterval(poll);
+            window?.show();
+            if (!splash.isDestroyed())
+                splash.close();
+        }, SPLASH_POLL_MS);
+        /* A window that is closed before the swap leaves an interval and an always-on-top badge
+           behind it, which outlives the application it was branding. */
+        window.once('closed', () => {
+            clearInterval(poll);
+            if (!splash.isDestroyed())
+                splash.close();
+        });
+    }
+    /*
+     * **The renderer's warnings reach a terminal, because a packaged game has no developer tools.**
+     * A player cannot open a console and a bug report cannot quote one, so the two levels worth
+     * reading are forwarded to the process's own output where a launcher, a log file or a support
+     * request can carry them. Info and debug are not: a game that logs per frame would make its own
+     * log useless.
+     */
+    /*
+     * **A link to the outside opens in the person's own browser, and never in a window of this
+     * application.** Both routes have to be closed or the other one is the hole: `window.open` and
+     * `target="_blank"` come through the open handler, and an ordinary click on an absolute link
+     * comes through `will-navigate`. What is refused rather than opened is in `links.ts`.
+     */
+    const openOutside = (url, route) => {
+        const target = externalTarget(url);
+        /* Named, with the route it took, in a development run: a game that opens a browser on its own
+           at startup is doing something its author will want to see rather than guess at, and which
+           of the two routes it took is most of the answer. */
+        if (options.development) {
+            console.log(`[drift-package] opening externally via ${route}: ${url}`);
+        }
+        if (target !== null)
+            void shell.openExternal(target);
+    };
+    window.webContents.setWindowOpenHandler(({ url }) => {
+        openOutside(url, 'window.open');
+        return { action: 'deny' };
+    });
+    window.webContents.on('will-navigate', (event, url) => {
+        /* The game navigating within itself is ordinary — a single-page game never does, and one
+           that does must not be interrupted. Anything leaving `drift://` is a link to the outside. */
+        if (url.startsWith('drift://'))
+            return;
+        event.preventDefault();
+        openOutside(url, 'navigation');
+    });
+    /*
+     * **The renderer's own output reaches a terminal, and how much of it depends on the build.**
+     *
+     * A player cannot open developer tools in a shipped artifact — see `devTools` above — so an
+     * error that has nowhere to go is an error nobody can quote in a bug report. Errors are
+     * forwarded in both kinds of build for exactly that reason. Warnings are development only:
+     * they are where a framework's advice and a game's own diagnostics live, and a shipped game
+     * printing them to a terminal nobody is watching is noise that hides the line that matters.
+     */
+    /*
+     * **Both argument shapes, because the event changed and the failure of reading the wrong one is
+     * silence.** Electron 35 moved the details into the first argument and made the level a string;
+     * before that the first argument was the bare event and the details came second, with a numeric
+     * level. Reading only the newer shape on an older runtime compares `undefined` against `'error'`
+     * for every message, forwards nothing, and looks exactly like a renderer that never logged —
+     * which is how this was found, and why the reading is a pure module with tests rather than a
+     * predicate written inline against one version's typings.
+     */
+    window.webContents.on('console-message', (first, second, third) => {
+        const line = consoleLine(first, second, third);
+        if (line === null || !forwardsConsole(line.level, options.development))
+            return;
+        console.log(`[renderer:${line.level}] ${line.message}`);
+    });
+    /*
+     * **The browser's own key bindings, gone from a shipped build.** Chromium answers Ctrl+R, F5,
+     * Ctrl+P, Ctrl+F, the zoom keys and the inspector combinations itself, with no menu item left
+     * to remove them — so a player leaning on Ctrl+R loses the run they were in. What is blocked
+     * and what is left alone is in `shortcuts.ts`, with a test per rule.
+     *
+     * In a development run nothing is blocked and F12 opens the inspector, which is most of what a
+     * development run is for.
+     */
+    window.webContents.on('before-input-event', (event, input) => {
+        if (isBlockedShortcut(input, process.platform, options.development)) {
+            event.preventDefault();
+            return;
+        }
+        if (options.development && input.type === 'keyDown' && input.key === 'F12') {
+            window?.webContents.toggleDevTools();
+        }
+    });
+    /*
+     * Pinch-zoom and Ctrl+wheel are the other two ways a page gets scaled, and neither goes through
+     * the keyboard. A game draws its own interface at its own scale; a scaled one is half off the
+     * screen with no way back, because the gesture that undoes it is a browser gesture.
+     */
+    window.webContents.setVisualZoomLevelLimits(1, 1).catch(() => undefined);
+    window.webContents.setZoomFactor(1);
+    window.on('focus', () => window?.webContents.send('drift:focus', true));
+    window.on('blur', () => window?.webContents.send('drift:focus', false));
+    window.on('close', (event) => {
+        const target = window;
+        if (target === null || quit.mayClose() || !quit.wantsNotice())
+            return;
+        /* Only a game that registered `onQuitRequest` is waited for. See `installIpc` for why the
+           interest flag exists rather than a grace period on every close. */
+        event.preventDefault();
+        quit.deferClose(target);
+    });
+    window.on('closed', () => {
+        window = null;
+    });
+    /* The manifest's own entry, not a hardcoded `index.html`: a project that builds to
+       `dist/game.html` is an ordinary project, and a shell that silently looked for the wrong file
+       would fail with a 404 in a window nobody can open developer tools on. */
+    await window.loadURL(`drift://app/${basename(manifest.entry)}`);
+}

package/dist/manifest.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `drift.package.json`, parsed once and trusted afterwards.
+ *
+ * **Every rejection names its field.** A packaging manifest is written by hand, usually once, and
+ * a wrong value surfaces at signing or at first launch on a machine the author does not have. The
+ * cost of validating here is a few dozen lines; the cost of not validating is a build.
+ *
+ * **What is defaulted and what is not** is the only interesting decision in this file. Window size
+ * and features default, because a short manifest is easier to read and a wrong window is visible
+ * immediately. The id, the entry, the targets and the backend policy do not, because each of them
+ * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
+ */
+export type WebGpuPolicy = 'prefer' | 'require' | 'off';
+export type Target = 'win-x64' | 'mac-arm64' | 'mac-x64' | 'linux-x64' | 'android' | 'ios';
+/** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
+export declare const MOBILE_TARGETS: readonly Target[];
+export interface PackageManifest {
+    readonly id: string;
+    readonly name: string;
+    readonly entry: string;
+    readonly window: {
+        readonly width: number;
+        readonly height: number;
+        readonly mode: 'windowed' | 'borderless' | 'fullscreen';
+        readonly resizable: boolean;
+    };
+    readonly backend: {
+        readonly webgpu: WebGpuPolicy;
+        readonly allowSoftwareRenderer: boolean;
+    };
+    readonly features: {
+        readonly clipExport: boolean;
+        readonly gamepad: boolean;
+    };
+    readonly targets: readonly Target[];
+    readonly steam: {
+        readonly appId: number | null;
+    };
+    readonly splash: {
+        readonly show: boolean;
+        readonly minMs: number;
+    };
+    /**
+     * Who an installer says this is from.
+     *
+     * Defaulted from the id's own organisation label rather than demanded, because it is right
+     * there and a manifest a person writes by hand should be short — `dev.example.title` gives
+     * `example`. It is worth setting properly before a Windows release: it is the name in the
+     * installer's header and in Add or Remove Programs.
+     */
+    readonly publisher: string;
+    /**
+     * A 1024x1024 PNG for the application, relative to the project. `null` uses the engine's mark.
+     *
+     * **A default that is a real icon rather than none**, because electron-builder's fallback is
+     * Electron's own logo — which ships a game branded as the framework that built it. The engine's
+     * mark is at least honest about what made it, and a game replaces it in one line.
+     */
+    readonly icon: string | null;
+}
+export declare function parseManifest(raw: unknown): PackageManifest;

package/dist/manifest.js

@@ -0,0 +1,91 @@
+/** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
+export const MOBILE_TARGETS = ['android', 'ios'];
+const POLICIES = ['prefer', 'require', 'off'];
+const TARGETS = [
+    'win-x64',
+    'mac-arm64',
+    'mac-x64',
+    'linux-x64',
+    'android',
+    'ios',
+];
+/**
+ * How long the engine badge holds the screen before the game gets it.
+ *
+ * **Both ends are clamped rather than trusted.** Long enough to be read is about a second and a
+ * half; past six seconds it is a wait somebody resents, and a splash that outlives a failed boot
+ * hides the failure behind a logo. Zero is allowed and means the badge shows only for as long as
+ * the game takes to paint, which on a fast machine is a flash.
+ */
+const SPLASH_DEFAULT_MS = 1400;
+const SPLASH_MAX_MS = 6000;
+/** Reverse-DNS, which is what all three platforms key an application on. */
+const ID = /^[a-z0-9]+(\.[a-z0-9][a-z0-9-]*)+$/;
+function requireString(source, field) {
+    const value = source[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`drift.package.json: "${field}" must be a non-empty string`);
+    }
+    return value;
+}
+export function parseManifest(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        throw new Error('drift.package.json: not an object');
+    const source = raw;
+    const id = requireString(source, 'id');
+    if (!ID.test(id)) {
+        throw new Error(`drift.package.json: "id" must be reverse-DNS, like dev.example.title — got "${id}"`);
+    }
+    const backendRaw = (source.backend ?? {});
+    const webgpu = backendRaw.webgpu;
+    if (typeof webgpu !== 'string' || !POLICIES.includes(webgpu)) {
+        throw new Error(`drift.package.json: "backend.webgpu" must be one of ${POLICIES.join(', ')} — got "${String(webgpu)}"`);
+    }
+    const targetsRaw = source.targets;
+    if (!Array.isArray(targetsRaw) || targetsRaw.length === 0) {
+        throw new Error('drift.package.json: "targets" must be a non-empty array');
+    }
+    for (const target of targetsRaw) {
+        if (typeof target !== 'string' || !TARGETS.includes(target)) {
+            throw new Error(`drift.package.json: unknown target "${String(target)}" — expected one of ${TARGETS.join(', ')}`);
+        }
+    }
+    const windowRaw = (source.window ?? {});
+    const featuresRaw = (source.features ?? {});
+    const steamRaw = (source.steam ?? {});
+    const splashRaw = (source.splash ?? {});
+    const appId = steamRaw.appId;
+    return {
+        id,
+        name: requireString(source, 'name'),
+        entry: requireString(source, 'entry'),
+        window: {
+            width: typeof windowRaw.width === 'number' ? windowRaw.width : 1280,
+            height: typeof windowRaw.height === 'number' ? windowRaw.height : 720,
+            mode: windowRaw.mode === 'fullscreen' || windowRaw.mode === 'borderless'
+                ? windowRaw.mode
+                : 'windowed',
+            resizable: windowRaw.resizable !== false,
+        },
+        backend: {
+            webgpu: webgpu,
+            allowSoftwareRenderer: backendRaw.allowSoftwareRenderer === true,
+        },
+        features: {
+            clipExport: featuresRaw.clipExport === true,
+            gamepad: featuresRaw.gamepad !== false,
+        },
+        targets: targetsRaw,
+        steam: { appId: typeof appId === 'number' ? appId : null },
+        publisher: typeof source.publisher === 'string' && source.publisher.length > 0
+            ? source.publisher
+            : (id.split('.')[1] ?? id),
+        icon: typeof source.icon === 'string' && source.icon.length > 0 ? source.icon : null,
+        splash: {
+            show: splashRaw.show !== false,
+            minMs: typeof splashRaw.minMs === 'number'
+                ? Math.min(SPLASH_MAX_MS, Math.max(0, splashRaw.minMs))
+                : SPLASH_DEFAULT_MS,
+        },
+    };
+}

package/dist/mobile/assetCheck.d.ts

@@ -0,0 +1 @@
+export declare function missingReferences(html: string, present: ReadonlySet<string>): string[];

package/dist/mobile/assetCheck.js

@@ -0,0 +1,28 @@
+/**
+ * Whether a page's own references land on files that are actually there.
+ *
+ * **This exists because of a failure with no error in it.** A game built by Vite references
+ * `/assets/index-abc.js` — absolute, from the site root. Host that game from a subdirectory and
+ * every such reference resolves to nothing: the HTML loads and the CSS and the script do not, so
+ * the page appears as unstyled text with no console open to say why. Measured on a real APK, which
+ * installed, launched, and showed a title in Times New Roman.
+ *
+ * Checked at build time rather than trusted, because the alternative is finding out from a phone.
+ */
+const REFERENCE = /(?:src|href)\s*=\s*"([^"]+)"/g;
+export function missingReferences(html, present) {
+    const missing = [];
+    for (const [, raw] of html.matchAll(REFERENCE)) {
+        if (raw === undefined)
+            continue;
+        /* Anything with a scheme, a protocol-relative host, or a fragment belongs to somebody else. */
+        if (!raw.startsWith('/') || raw.startsWith('//'))
+            continue;
+        const path = raw.slice(1).split(/[?#]/)[0] ?? '';
+        if (path.length === 0)
+            continue;
+        if (!present.has(path))
+            missing.push(raw);
+    }
+    return missing;
+}

package/dist/mobile/bridgeShim.d.ts

@@ -0,0 +1,83 @@
+import type { DriftHostBridge } from '../preload/bridge.ts';
+/**
+ * One bridge shape, assembled from what a mobile WebView is able to hand over.
+ *
+ * **Android's `@JavascriptInterface` can pass strings, numbers and booleans and nothing else.** It
+ * cannot return a promise, an object, an array or a callback. So the native surface is flat,
+ * synchronous and string-only — `snapshot()` returns JSON, `displays()` returns JSON — and this
+ * file turns it into the same `DriftHostBridge` the desktop shell exposes. The engine then sees
+ * **one** seam with three shells behind it rather than three seams, which is the whole design.
+ *
+ * **Naming them differently is deliberate.** The native object is `__driftHostNative`; the one a
+ * game reaches is `__driftHost`. A single half-typed object would hide the adaptation; two names
+ * make it a file somebody can read.
+ *
+ * **Events come the other way through a global**, because a WebView cannot call into the page: the
+ * host evaluates `globalThis.__driftHostEvents.focus(false)` when the activity pauses. Installed
+ * here rather than in the host, so the subscription bookkeeping is written once in TypeScript.
+ */
+export interface NativeShimSurface {
+    snapshot(): string;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+    isFullscreen(): boolean;
+    setFullscreen(on: boolean): void;
+    refreshHz(): number;
+    mode(): string;
+    setMode(mode: string): boolean;
+    size(): string;
+    setSize(width: number, height: number): boolean;
+    canSetSize(): boolean;
+    displays(): string;
+    /**
+     * Whether this platform lets an application end itself.
+     *
+     * Android does — `finish()` closes the activity. iOS does not, and Apple's guidance is explicit
+     * that an application should not: a game there answers false and draws no exit button.
+     */
+    canQuit(): boolean;
+    /**
+     * Writing a file, in three calls, because a bridge that can only carry strings cannot carry a
+     * twenty megabyte clip in one.
+     *
+     * `saveBegin` returns false where the platform refused to start — no space, no permission — and
+     * `saveEnd` returns where the file landed, in words a person can be told.
+     */
+    saveBegin(name: string, mime: string): boolean;
+    saveChunk(base64: string): boolean;
+    saveEnd(): string;
+    saveAbort(): void;
+    requestQuit(): void;
+}
+/**
+ * Half a megabyte of bytes a call, which is about seven hundred kilobytes of base64.
+ *
+ * Large enough that a twenty megabyte clip is forty calls rather than four thousand, and small
+ * enough that neither the string nor the argument list is anywhere near a limit.
+ */
+export declare const SAVE_CHUNK_BYTES: number;
+/**
+ * Bytes as base64, built in pieces.
+ *
+ * `String.fromCharCode(...bytes)` on a whole file overflows the argument list and throws — at a
+ * size that depends on the engine, so it works in a test and fails on a real clip.
+ */
+export declare function base64Of(bytes: Uint8Array): string;
+/**
+ * What the platform files a name under.
+ *
+ * Android sorts a download by its declared type, so a clip saved as `application/octet-stream`
+ * lands somewhere a gallery will not look for it. Wrong is worse than unknown here, so anything
+ * unrecognised stays octet-stream rather than being guessed at.
+ */
+export declare function mimeForName(name: string): string;
+export declare function installShim(native: NativeShimSurface): DriftHostBridge;
+/**
+ * Wire the native surface into the global the engine's `hostBridge()` looks for.
+ *
+ * Called by the injected shim script, which the host evaluates before the game's own scripts run —
+ * `WebViewCompat.addDocumentStartJavaScript` on Android, a user script on iOS. That timing is what
+ * makes this the mobile equivalent of the desktop preload rather than something a game has to
+ * remember to import.
+ */
+export declare function attachShim(key: string): void;