Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

29.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    hostBridge.ts
 * @brief   Build a {@link NativeBridge} from the primitives a native host installs
 *          on the JS global.
 * @details The host's job is the small, unavoidable part — reading a packaged
 *          file, decoding an image, persisting a key — as `es_*` functions it
 *          binds from C++. Assembling those into the bridge the SDK consumes is
 *          the SDK's job, and belongs here rather than in a JS string inside the
 *          host: typed against the interface it must satisfy, checked by the
 *          compiler, and identical on every platform the host runs on.
 */

import { log } from '../../util/logger';
import type {
    NativeAudioBridge, NativeBridge, NativeFetchResult, NativeInputListener,
    NativeTextEditorBridge, NativeTextEditorPush, NativeSocketEvent, NativeChannelBridge,
} from './bridge';
import type { PlatformGlyph, PlatformGlyphRequest, PlatformRequestOptions } from '../types';
import { assertHostEnvironment } from './hostEnvironment';
import { cacheEntryName } from '../cacheEntryName';
import { NativeDevice, type NativeDeviceHost } from '../../device/native';
import { hasAudioBindings } from '../../ecs/bridge/nativeBindings';

/** Touch phases the host reports, matching the order it dispatches. */
const TOUCH_START = 0;
const TOUCH_MOVE = 1;
const TOUCH_END = 2;

/** Pointer phases, same convention: a mouse has no cancel. */
const POINTER_DOWN = 0;
const POINTER_MOVE = 1;

/** The `es_*` primitives a native host binds. Required unless marked optional. */
export interface NativeHostBindings extends NativeDeviceHost {
    /** A packaged file's bytes, or null when it is not in the package. */
    es_readAsset(path: string): ArrayBuffer | null;
    /** Decode a packaged image to top-first RGBA, or null on failure. */
    /** A packaged path, or bytes already fetched (a CDN image, a cached one). */
    es_loadImagePixels(pathOrBytes: string | ArrayBuffer): { width: number; height: number; pixels: ArrayBuffer } | null;
    /** Rasterize one glyph through the OS font stack — what a 2D canvas does on
     *  the web. Optional, all-or-nothing with the rest of {@link TEXT_BINDINGS}:
     *  a host that has not bound its font stack draws no text. */
    es_rasterizeGlyph?(request: PlatformGlyphRequest): {
        pixels: ArrayBuffer; width: number; height: number;
        advance: number; bearingX: number; bearingY: number;
    } | null;
    /** A writable byte store the platform may reclaim (the host's cache dir).
     *  Optional: without it there is no offline hot-update cache. */
    es_readCacheFile?(key: string): ArrayBuffer | null;
    es_writeCacheFile?(key: string, bytes: ArrayBuffer | Uint8Array | string): boolean;
    /** The durable store, for what a player would notice losing. Separate from the
     *  cache pair above because the platform is allowed to empty a cache and iOS
     *  does: a host that maps both onto one directory has decided saves are
     *  disposable, whether or not it meant to. */
    es_readDataFile?(key: string): ArrayBuffer | null;
    es_writeDataFile?(key: string, bytes: ArrayBuffer | Uint8Array | string): boolean;
    /** Native key-value store, when the host has one (NSUserDefaults /
     *  SharedPreferences). Absent hosts persist through es_writeDataFile. */
    es_getStorageItem?(key: string): string | null;
    es_setStorageItem?(key: string, value: string): void;
    es_removeStorageItem?(key: string): void;
    es_storageKeys?(): string[];
    /** Screen scale (1 when the host reports surface pixels directly). */
    es_devicePixelRatio?(): number;
    /** OS content insets, already converted to the rendered surface pixel domain. */
    es_safeAreaInsets?(): { top: number; bottom: number; left: number; right: number };

    /** The gamepads this frame, in the W3C standard layout. Absent on a host with
     *  no pads to report — a phone, where the SDK sees the same empty list a
     *  browser without navigator.getGamepads() gives it. */
    es_pollGamepads?(): { index: number; connected: boolean; buttons: number[]; axes: number[] }[];

    /** The Steam client. Bound only where one can exist (desktop). */
    es_steam_init?(appId: number): boolean;
    es_steam_available?(): boolean;
    es_steam_identity?(): { id: string; name: string };
    es_steam_unlock?(id: string): boolean;
    es_steam_unlocked?(id: string): boolean;
    es_steam_setStat?(name: string, value: number): boolean;
    es_steam_getStat?(name: string): number;
    es_steam_store?(): boolean;
    es_steam_reset?(): boolean;

    /** Ask the host's window to open at this size. Absent on a host that is given
     *  its screen rather than owning a window. */
    es_setWindowSize?(width: number, height: number): void;

    /** Perform an HTTP request off the main thread (native TLS stack), calling
     *  back with the reply. Optional — a host without it stays offline (remote
     *  asset groups and hot-update do not resolve). */
    es_fetch?(
        request: {
            url: string;
            method?: string;
            headers?: Record<string, string>;
            body?: string | ArrayBuffer;
            responseType?: string;
        },
        callback: (result: {
            ok: boolean;
            status: number;
            statusText: string;
            headers: Record<string, string>;
            arrayBuffer?: ArrayBuffer;
            text?: string;
            error?: string;
        }) => void,
    ): void;

    /** What the device is called in a list: its system and model. */
    es_deviceName?(): string;

    /** Whether this host is a phone or a tablet. */
    es_isHandheld?(): boolean;

    /** The device language, raw from the OS ('zh-Hans-CN'); empty when unknown. */
    es_language?(): string;

    /** The host's `ws://` client: events arrive on the JS thread, `close` last. */
    es_wsOpen?(url: string, onEvent: (event: NativeSocketEvent) => void): number;
    es_wsSend?(id: number, data: string | ArrayBuffer): boolean;
    es_wsClose?(id: number, code?: number, reason?: string): void;

    /** The native audio engine, all-or-nothing (see {@link AUDIO_BINDINGS}). A
     *  host without a sound device binds none and stays silent. */
    // The OS text-editing surface (soft keyboard + IME). Optional as a group:
    // hasTextEditorBindings gates them, so a host that wired none simply has no
    // editing surface. The host pushes what the user did through
    // es_onNativeTextEditor, installed here.
    es_textEditor_focus?(
        value: string, selectionStart: number, selectionEnd: number,
        multiline: boolean, maxLength: number, password: boolean,
    ): void;
    es_textEditor_blur?(): void;
    es_textEditor_write?(value: string, selectionStart: number, selectionEnd: number): void;

    // The app's own native code, by name (see ChannelBindings.cpp). Bound as a
    // pair; replies and events come back through es_onNativeMessage.
    es_native_has?(method: string): boolean;
    es_native_call?(id: number, method: string, args: string): boolean;

    es_audioSpectrum?(bins: number): ArrayBuffer | null;
    es_audioLoad?(bytes: ArrayBuffer, stream?: boolean): { id: number; duration: number; bytes: number; streamed?: boolean } | null;
    es_audioUnload?(bufferId: number): void;
    es_audioPlay?(bufferId: number, volume: number, pan: number, loop: boolean, rate: number, loopStart?: number, start?: number, end?: number, at?: number): number;
    es_audioTime?(): number;
    es_audioStop?(voiceId: number): void;
    es_audioPause?(voiceId: number): void;
    es_audioResume?(voiceId: number): void;
    es_audioSetVolume?(voiceId: number, volume: number): void;
    es_audioSetPan?(voiceId: number, pan: number): void;
    es_audioSetLoop?(voiceId: number, loop: boolean): void;
    es_audioSetRate?(voiceId: number, rate: number): void;
    es_audioVoiceState?(voiceId: number): { playing: boolean; currentTime: number } | null;
    es_audioSuspendAll?(): void;
    es_audioResumeAll?(): void;
}

/**
 * Assemble the bridge from a host's bindings. The returned object also installs
 * `es_onNativeTouch` on @p scope — the entry point the host calls per touch,
 * which fans out to whatever input sink the engine registered.
 *
 * @throws if a required binding is missing, naming it — a native boot should fail
 *         at the seam rather than somewhere deep in an asset load.
 */
export function createHostBridge(
    scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): NativeBridge {
    // Both halves of the contract, checked at the seam: the JS environment the
    // host had to install, then its own es_* primitives.
    assertHostEnvironment(scope);
    const bindings = scope as unknown as NativeHostBindings;
    for (const name of ['es_readAsset', 'es_loadImagePixels'] as const) {
        if (typeof bindings[name] !== 'function') {
            throw new Error(`[native] host binding ${name}() is missing — the shell must install it before booting`);
        }
    }

    let listener: NativeInputListener | null = null;
    scope.es_onNativeTouch = (type: number, id: number, x: number, y: number): void => {
        if (!listener) return;
        if (type === TOUCH_START) listener.onTouchStart(id, x, y);
        else if (type === TOUCH_MOVE) listener.onTouchMove(id, x, y);
        else if (type === TOUCH_END) listener.onTouchEnd(id);
        else listener.onTouchCancel(id);
    };
    scope.es_onNativePointer = (type: number, button: number, x: number, y: number): void => {
        if (!listener) return;
        if (type === POINTER_DOWN) listener.onPointerDown(button, x, y);
        else if (type === POINTER_MOVE) listener.onPointerMove(x, y);
        else listener.onPointerUp(button);
    };
    scope.es_onNativeWheel = (deltaX: number, deltaY: number): void => {
        listener?.onWheel(deltaX, deltaY);
    };
    scope.es_onNativeKey = (down: boolean, code: string): void => {
        if (!listener) return;
        if (down) listener.onKeyDown(code); else listener.onKeyUp(code);
    };

    const storage = hostStorage(bindings);
    const audio = hostAudio(bindings, scope);
    const textEditor = hostTextEditor(bindings, scope);
    const channel = hostChannel(bindings, scope);
    const lifecycle = hostLifecycle(scope);
    let device: NativeDevice | null = null;

    return {
        device: () => device ??= new NativeDevice(bindings, lifecycle),
        readFile: (path) => {
            const bytes = bindings.es_readAsset(path);
            return bytes ? Promise.resolve(bytes) : Promise.reject(new Error(`asset not found: ${path}`));
        },
        fileExists: (path) => Promise.resolve(bindings.es_readAsset(path) != null),
        fetch: (url, options) => hostFetch(bindings, url, options),
        ...(bindings.es_deviceName ? { deviceName: () => bindings.es_deviceName!() } : {}),
        ...(bindings.es_isHandheld ? { isHandheld: () => bindings.es_isHandheld!() } : {}),
        ...(bindings.es_language ? { language: () => bindings.es_language!() } : {}),
        ...(bindings.es_wsOpen && bindings.es_wsSend && bindings.es_wsClose ? {
            socket: {
                open: (url, onEvent) => {
                    const id = bindings.es_wsOpen!(url, onEvent);
                    return {
                        send: (data) => bindings.es_wsSend!(id, data),
                        close: (code, reason) => bindings.es_wsClose!(id, code, reason),
                    };
                },
            },
        } : {}),
        loadImagePixels: async (path) => {
            // The host decodes packaged paths; a CDN image is bytes the script brings,
            // from the hot-update cache when it is there, else from the network.
            let source: string | ArrayBuffer = path;
            if (/^https?:\/\//i.test(path)) {
                const cached = bindings.es_readCacheFile ? bindings.es_readCacheFile(cacheEntryName(path)) : null;
                if (cached) source = cached;
                else {
                    const got = await hostFetch(bindings, path, { responseType: 'arraybuffer' });
                    if (!got.ok || !got.arrayBuffer) throw new Error(`image fetch failed: ${path} (${got.status})`);
                    source = got.arrayBuffer;
                }
            }
            const decoded = bindings.es_loadImagePixels(source);
            if (!decoded) throw new Error(`image decode failed: ${path}`);
            return { width: decoded.width, height: decoded.height, pixels: new Uint8Array(decoded.pixels) };
        },
        ...(bindings.es_rasterizeGlyph ? { rasterizeGlyph: (request) => hostGlyph(bindings, request) } : {}),
        ...storage,
        ...(bindings.es_readCacheFile && bindings.es_writeCacheFile
            ? {
                readCacheFile: (key: string) => Promise.resolve(bindings.es_readCacheFile!(cacheEntryName(key))),
                writeCacheFile: (key: string, bytes: ArrayBuffer) => bindings.es_writeCacheFile!(cacheEntryName(key), bytes)
                    ? Promise.resolve()
                    : Promise.reject(new Error(`the host refused to cache ${key}`)),
            }
            : {}),
        registerInput: (sink) => {
            listener = sink;
            return () => { listener = null; };
        },
        devicePixelRatio: () => bindings.es_devicePixelRatio?.() ?? 1,
        safeAreaInsets: () => bindings.es_safeAreaInsets?.() ?? { top: 0, bottom: 0, left: 0, right: 0 },
        // All-or-nothing: the host binds the whole surface or none of it, so one
        // probe decides rather than nine optional calls at every site.
        ...(bindings.es_steam_init
            ? {
                steam: {
                    init: (appId: number) => bindings.es_steam_init!(appId),
                    available: () => bindings.es_steam_available?.() ?? false,
                    identity: () => bindings.es_steam_identity?.() ?? { id: '', name: '' },
                    unlock: (id: string) => bindings.es_steam_unlock?.(id) ?? false,
                    unlocked: (id: string) => bindings.es_steam_unlocked?.(id) ?? false,
                    setStat: (n: string, v: number) => bindings.es_steam_setStat?.(n, v) ?? false,
                    getStat: (n: string) => bindings.es_steam_getStat?.(n) ?? 0,
                    store: () => bindings.es_steam_store?.() ?? false,
                    reset: () => bindings.es_steam_reset?.() ?? false,
                    onOverlay: (listener: (covered: boolean) => void) => {
                        scope.es_onSteamOverlay = (covered: boolean) => listener(covered);
                    },
                },
            }
            : {}),
        ...(bindings.es_setWindowSize
            ? { setWindowSize: (w: number, h: number) => bindings.es_setWindowSize!(w, h) }
            : {}),
        ...(bindings.es_pollGamepads
            // 'standard' is asserted HERE rather than by the host: the layout is
            // this bridge's contract with the SDK, and a host that filled the
            // arrays in that order has already met it.
            ? {
                pollGamepads: () => bindings.es_pollGamepads!().map((pad) => ({
                    index: pad.index,
                    connected: pad.connected,
                    buttons: pad.buttons,
                    axes: pad.axes,
                    mapping: 'standard',
                })),
            }
            : {}),
        ...(audio ? { audio } : {}),
        ...(textEditor ? { textEditor } : {}),
        ...(channel ? { channel } : {}),
        ...lifecycle,
    };
}

/**
 * One glyph from the host's font stack, as the atlas wants it. The host answers
 * with an ArrayBuffer (a native JS engine hands raw buffers across, as it does
 * for decoded images); the view is the SDK's to put on, so the atlas' upload
 * path sees the same Uint8Array it gets from a canvas.
 */
function hostGlyph(bindings: NativeHostBindings, request: PlatformGlyphRequest): PlatformGlyph | null {
    const glyph = bindings.es_rasterizeGlyph!(request);
    if (!glyph) return null;
    return {
        pixels: new Uint8Array(glyph.pixels),
        width: glyph.width,
        height: glyph.height,
        advance: glyph.advance,
        bearingX: glyph.bearingX,
        bearingY: glyph.bearingY,
    };
}

/**
 * Perform an HTTP request through the host's native stack (es_fetch), wrapping
 * its callback in the Promise the adapter expects. A host without es_fetch is
 * offline — a 404, exactly as before, so remote groups just fail to resolve.
 */
function hostFetch(
    bindings: NativeHostBindings, url: string, options?: PlatformRequestOptions,
): Promise<NativeFetchResult> {
    if (typeof bindings.es_fetch !== 'function') {
        return Promise.resolve({ ok: false, status: 404, statusText: 'no network' });
    }
    return new Promise((resolve, reject) => {
        bindings.es_fetch!(
            {
                url,
                method: options?.method,
                headers: options?.headers,
                body: options?.body,
                responseType: options?.responseType,
            },
            (r) => {
                if (r.error) {
                    reject(new Error(r.error));
                    return;
                }
                resolve({
                    ok: r.ok,
                    status: r.status,
                    statusText: r.statusText,
                    headers: r.headers,
                    arrayBuffer: r.arrayBuffer,
                    text: r.text,
                });
            },
        );
    });
}

/**
 * Assemble the audio bridge from the host's es_audio* primitives, or undefined
 * when the host bound none (→ silent Null backend). Also installs
 * `es_onNativeAudioEnded`, the entry point the host calls when a voice ends on
 * its own, fanning out to the subscribed backends.
 */
function hostAudio(
    bindings: NativeHostBindings, scope: Record<string, unknown>,
): NativeAudioBridge | undefined {
    if (!hasAudioBindings(scope)) return undefined;
    let ended: Array<{ callback: (voiceId: number) => void; active: boolean }> = [];
    scope.es_onNativeAudioEnded = (voiceId: number): void => {
        let failed = false;
        let failure: unknown;
        for (const subscription of ended) {
            if (!subscription.active) continue;
            try { subscription.callback(voiceId); } catch (error) {
                if (!failed) { failed = true; failure = error; }
            }
        }
        if (failed) throw failure;
    };
    return {
        load: (bytes, stream) => bindings.es_audioLoad!(bytes, stream === true),
        unload: (id) => bindings.es_audioUnload!(id),
        play: (buf, vol, pan, loop, rate, loopStart, start, end, at) => bindings.es_audioPlay!(buf, vol, pan, loop, rate, loopStart ?? 0, start ?? 0, end ?? 0, at ?? 0),
        ...(bindings.es_audioTime ? { time: () => bindings.es_audioTime!() } : {}),
        stop: (v) => bindings.es_audioStop!(v),
        pause: (v) => bindings.es_audioPause!(v),
        resume: (v) => bindings.es_audioResume!(v),
        setVolume: (v, x) => bindings.es_audioSetVolume!(v, x),
        setPan: (v, x) => bindings.es_audioSetPan!(v, x),
        setLoop: (v, on) => bindings.es_audioSetLoop!(v, on),
        setRate: (v, x) => bindings.es_audioSetRate!(v, x),
        voiceState: (v) => bindings.es_audioVoiceState!(v),
        suspendAll: () => bindings.es_audioSuspendAll!(),
        resumeAll: () => bindings.es_audioResumeAll!(),
        onEnded: (callback) => {
            const subscription = { callback, active: true };
            ended = [...ended, subscription];
            return () => {
                if (!subscription.active) return;
                subscription.active = false;
                ended = ended.filter(entry => entry !== subscription);
            };
        },
        // Optional: a host without the analyser tap simply has no spectrum, and
        // a visualizer falls back to flat bars (as it does on any backend
        // without analysis).
        ...(bindings.es_audioSpectrum
            ? { spectrum: (bins: number) => bindings.es_audioSpectrum!(bins) }
            : {}),
    };
}

/**
 * The host's editing surface, when it bound one: calls out through its
 * `es_textEditor_*` entry points, and takes what the user did through
 * `es_onNativeTextEditor`, installed here the way the lifecycle signals are.
 * All-or-nothing — a host with only some of the entry points has no surface,
 * rather than one that opens a keyboard it cannot read.
 */
function hostTextEditor(
    bindings: NativeHostBindings,
    scope: Record<string, unknown>,
): NativeTextEditorBridge | undefined {
    if (!bindings.es_textEditor_focus || !bindings.es_textEditor_blur || !bindings.es_textEditor_write) {
        return undefined;
    }
    let subs: ((push: NativeTextEditorPush) => void)[] = [];
    scope.es_onNativeTextEditor = (push: NativeTextEditorPush): void => {
        for (const cb of subs) cb(push);
    };
    return {
        focus: (value, selectionStart, selectionEnd, multiline, maxLength, password) =>
            bindings.es_textEditor_focus!(value, selectionStart, selectionEnd, multiline, maxLength, password),
        blur: () => bindings.es_textEditor_blur!(),
        write: (value, selectionStart, selectionEnd) =>
            bindings.es_textEditor_write!(value, selectionStart, selectionEnd),
        subscribe: (handler) => {
            subs.push(handler);
            return () => { subs = subs.filter((s) => s !== handler); };
        },
    };
}

/** What the host pushes through `es_onNativeMessage`: a call's answer, or an event. */
type NativeChannelPush =
    | { kind: 'reply'; id: number; ok: boolean; payload: string }
    | { kind: 'event'; name: string; payload: string };

/**
 * The channel to the app's own native code, when the host bound it. A call is
 * numbered here and answered later through `es_onNativeMessage`; one the host
 * refuses at the door (nothing answers to the name) rejects at once, so no
 * promise is left waiting on a reply that cannot come.
 */
function hostChannel(
    bindings: NativeHostBindings,
    scope: Record<string, unknown>,
): NativeChannelBridge | undefined {
    if (!bindings.es_native_has || !bindings.es_native_call) return undefined;
    const pending = new Map<number, { method: string; resolve: (payload: string) => void; reject: (error: Error) => void }>();
    let subs: ((name: string, payload: string) => void)[] = [];
    let nextId = 1;
    scope.es_onNativeMessage = (push: NativeChannelPush): void => {
        if (push.kind === 'event') {
            for (const cb of subs) cb(push.name, push.payload);
            return;
        }
        const call = pending.get(push.id);
        if (!call) return;   // answered twice, or a reply to a realm that is gone
        pending.delete(push.id);
        if (push.ok) call.resolve(push.payload);
        else call.reject(new Error(`native "${call.method}" failed: ${push.payload || 'no reason given'}`));
    };
    return {
        has: (method) => bindings.es_native_has!(method),
        call: (method, args) => new Promise<string>((resolve, reject) => {
            const id = nextId++;
            pending.set(id, { method, resolve, reject });
            let started = false;
            try {
                started = bindings.es_native_call!(id, method, args);
            } finally {
                if (!started) pending.delete(id);
            }
            if (!started) reject(new Error(`native "${method}": nothing in this app answers to that name`));
        }),
        subscribe: (handler) => {
            subs.push(handler);
            return () => { subs = subs.filter((s) => s !== handler); };
        },
    };
}

/**
 * The lifecycle signals the host pushes (like touch), each installed as an
 * `es_onNative*` entry the shell calls and exposed as a subscribe/unsubscribe on
 * the bridge: foreground/background (`es_onNativeVisibility` → onShow/onHide, the
 * Lifecycle plugin auto-pauses) and memory pressure (`es_onNativeMemoryWarning` →
 * onMemoryWarning, residency caches trim).
 */
function hostLifecycle(
    scope: Record<string, unknown>,
): Pick<NativeBridge, 'onShow' | 'onHide' | 'onMemoryWarning'> {
    /** A subscriber list installed behind a host push entry; returns its API. */
    const signal = (install: (fire: () => void) => void): ((cb: () => void) => () => void) => {
        let subs: (() => void)[] = [];
        install(() => { for (const cb of subs) cb(); });
        return (cb) => { subs.push(cb); return () => { subs = subs.filter((c) => c !== cb); }; };
    };

    let onShow: (() => void) | undefined;
    let onHide: (() => void) | undefined;
    const subShow = signal((fire) => { onShow = fire; });
    const subHide = signal((fire) => { onHide = fire; });
    scope.es_onNativeVisibility = (visible: boolean): void => { (visible ? onShow : onHide)?.(); };

    return {
        onShow: subShow,
        onHide: subHide,
        onMemoryWarning: signal((fire) => { scope.es_onNativeMemoryWarning = fire; }),
    };
}

/** Where storage lands when the host has no native key-value store. */
const STORAGE_FILE = 'estella-storage.json';

/**
 * Key-value storage, best available: the host's own store, else a JSON file in
 * its durable directory, else memory for the session. The API is synchronous
 * (localStorage's shape), so the file variant keeps the map in memory and writes
 * through on every mutation — storage holds saves and settings, not bulk data.
 *
 * The file is WRITTEN to the DATA store, never the cache. An older host that binds
 * only the cache pair still persists through it, because a cache that usually
 * survives beats losing the save at every exit — but it is the wrong directory on
 * any platform that reclaims one, so say so once rather than let a player find out.
 *
 * It is READ from the cache too, once, when the durable store has nothing: builds
 * before the split wrote every save there, and a player updating across it would
 * otherwise open the game to a blank profile.
 */
function hostStorage(bindings: NativeHostBindings): Pick<
    NativeBridge, 'getStorageItem' | 'setStorageItem' | 'removeStorageItem' | 'storageKeys'
> {
    if (typeof bindings.es_getStorageItem === 'function') {
        return {
            getStorageItem: (key) => bindings.es_getStorageItem!(key),
            setStorageItem: (key, value) => bindings.es_setStorageItem?.(key, value),
            removeStorageItem: (key) => bindings.es_removeStorageItem?.(key),
            storageKeys: () => bindings.es_storageKeys?.() ?? [],
        };
    }

    const durable = typeof bindings.es_readDataFile === 'function'
        && typeof bindings.es_writeDataFile === 'function';
    const read = durable ? bindings.es_readDataFile! : bindings.es_readCacheFile;
    const write = durable ? bindings.es_writeDataFile! : bindings.es_writeCacheFile;

    const entries = new Map<string, string>();
    const persistent = typeof read === 'function' && typeof write === 'function';
    /** Read a stored blob into `entries`. False when it was not readable. */
    const adopt = (bytes: ArrayBuffer): boolean => {
        try {
            for (const [k, v] of Object.entries(JSON.parse(new TextDecoder().decode(bytes)) as Record<string, string>)) {
                entries.set(k, v);
            }
            return true;
        } catch {
            log.warn('native', 'stored data was unreadable — starting empty');
            return false;
        }
    };

    /** The save came from the cache directory and owes the durable one a copy. */
    let inherited = false;
    if (!persistent) {
        log.warn('native', 'host has no storage or file bindings — saves last only for this session');
    } else {
        if (!durable) {
            log.warn('native', 'host binds no durable store — saves go to its cache, which the platform may reclaim');
        }
        const own = read!(STORAGE_FILE);
        if (own) {
            adopt(own);
        } else if (durable) {
            // Nothing in the durable store. Either nothing was ever saved, in which
            // case the cache holds nothing either — or the player updated from a
            // build that knew only the cache directory, and their save is the file
            // sitting in it. Not looking there is indistinguishable from having
            // deleted it, and it would happen on exactly the version that claims to
            // have made saves safe.
            const previous = bindings.es_readCacheFile?.(STORAGE_FILE) ?? null;
            if (previous && adopt(previous) && entries.size > 0) {
                inherited = true;
                log.info('native', 'adopted the save an earlier build left in the cache directory');
            }
        }
    }
    const flush = (): void => {
        if (!persistent) return;
        // A string, not encoded bytes: the host writes UTF-8 itself, and a native
        // JS engine has no TextEncoder to reach for.
        write!(STORAGE_FILE, JSON.stringify(Object.fromEntries(entries)));
    };
    // Write an inherited save through now rather than at the next mutation: the
    // cache copy is never read again, and the directory it is in is the one the
    // platform is allowed to empty.
    if (inherited) flush();
    return {
        getStorageItem: (key) => entries.get(key) ?? null,
        setStorageItem: (key, value) => { entries.set(key, value); flush(); },
        removeStorageItem: (key) => { entries.delete(key); flush(); },
        storageKeys: () => [...entries.keys()],
    };
}