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.

146 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Backend } from './Backend';
import { packedBackend } from './packedBackend';
import { Catalog, type AtlasFrameInfo } from './Catalog';
import { ManifestModel, normalizeBundleMode, type AddressableManifest, type AddressableAssetType } from './AddressableManifest';
import { diffManifests, type UpdatePlan, type AssetChange } from './hotUpdate';
import { contentHashHex } from './contentHash';
import { encodeUtf8 } from '../util/utf8';
import { getPlatform, isPlatformInitialized } from '../platform/base';
import { contentCacheFor, type CacheVersion, type ContentCacheReport, type CacheCleanupResult } from '../platform/contentCache';
import { platformLoadSubpackage, platformGetStorageItem, platformSetStorageItem, platformRemoveStorageItem, platformWriteCacheFile } from '../platform';
import type {
    AssetLoader, LoadContext, TextureResult, SpineResult,
    MaterialResult, FontResult, AudioResult, AnimClipResult,
    TilemapResult, TilesetResult, TimelineResult, PrefabResult,
    LocaleResult, FsmResult, BtResult, AnimatorControllerResult, JsonResult,
} from './AssetLoader';
import { AsyncCache } from './AsyncCache';
import { TextureContent, textureContentName, type ESEngineModule } from '../wasm';
import type { CppResourceManager } from '../wasm';
import { requireResourceManager, getResourceManager, evictTextureDimensions, textureRefill } from '../wasm/resourceManager';
import type { TextureImportSettings, TextureImportSettingsResolver } from './loaders/TextureLoader';
import type { TextureFormatReport } from './textureFormatReport';
import { TextureLoader, textureResidencyKey } from './loaders/TextureLoader';
import { AssetRefLedger, type AssetRefLease } from './AssetRefLedger';
import { optionalAssetLoaders } from './optionalLoaders';
import { AssetScope, ownedAssetLease, type AssetLease } from './AssetLease';
import { EntityAssetScopes } from './entityAssetScopes';
import { RegistryAssetSlots, type RegistryAssetKind } from './registryAssets';
import { DependencyRecorder, PreparationFailure, preparationFailureReason, isInvalidatable, rebuildPlan, type AssetIdentity,
         type DependencyReceipt, type Preparation, type PreparedLoad } from './dependencies';
import { SpineAssetLoader } from './loaders/SpineAssetLoader';
import { spinePairKey } from './spinePairKey';
import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';
import { MaterialShaderAssetLoader } from './loaders/MaterialShaderAssetLoader';
import { isBuiltinAssetRef } from './documentRef';
import { MeshAssetLoader, type MeshResult } from './loaders/MeshAssetLoader';
import type { MeshData } from './meshFormat';
import { nativeEngineApi, type EngineApi } from '../ecs/bridge/engineApi';
import { isBuiltinMeshRef } from './builtinMeshes';
import { EnvironmentAssetLoader } from './loaders/EnvironmentAssetLoader';
import { ProbeVolumeAssetLoader } from './loaders/ProbeVolumeAssetLoader';
import { MeshSdfAssetLoader } from './loaders/MeshSdfAssetLoader';
import { MeshCardsAssetLoader } from './loaders/MeshCardsAssetLoader';
import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
import { preparePrefabFromSource, type PreparedPrefab } from '../prefab/preparedPrefab';
import type { PrefabOverride } from '../prefab';
import { LocaleAssetLoader } from './loaders/LocaleAssetLoader';
import { JsonAssetLoader } from './loaders/JsonAssetLoader';
import { SoundEventAssetLoader } from './loaders/SoundEventAssetLoader';
import { getComponentDefaults } from '../ecs/component';
import { getComponentAssetFieldDescriptors } from '../scene/scene';
import { discoverSceneAssets } from './discoverAssets';
import { fetchDecodePixels } from './imageDecode';
import type { SceneData, AssetFieldType } from '../scene/scene';
import { SceneHandle, type ReleaseCallback } from './SceneHandle';
import { UUID_REF_PREFIX } from './AssetRegistry';
import type { AssetRefCounter } from './AssetRefCounter';
import { log } from '../util/logger';
import { disposeAll } from '../util/disposeAll';
import { recoverDevice, getDeviceStatus, DeviceStatus } from '../render/renderer';

/**
 * One asset generation ending: which ref, what kind of asset it was, and what
 * live holders were bound to just before the drop.
 *
 * The kind travels because every source of one knows it, and a listener that
 * has to guess can only serve the kind somebody had in mind.
 */
export interface AssetInvalidation {
    /** As the caller spelled it, not the resolved path. */
    readonly ref: string;
    /** In whichever vocabulary the source knew: a loader/field type, or the
     *  manifest's type for an applied update. */
    readonly type: AssetFieldType | AddressableAssetType;
    /** What holders were bound to: a texture's handle, a loader's value.
     *  Undefined when nothing was cached to report. */
    readonly oldValue?: unknown;
}

/** Callback fired when an asset generation ends — `Assets.invalidate(ref)`
 *  dropped cache entries, or `applyUpdate` replaced the content behind a ref. */
export type InvalidateListener = (event: AssetInvalidation) => void;

/** Input to {@link Assets.checkForUpdate}. */
export interface CheckForUpdateOptions {
    /** Url of the candidate (remote) manifest JSON — diffed against the active one. */
    manifestUrl: string;
    /** CDN root the candidate's `remote`-group assets are served from; remembered
     *  and applied by {@link Assets.applyUpdate}. Defaults to the current root. */
    remoteRoot?: string;
}

/** One asset {@link Assets.applyUpdate} could not deliver: `fetch` (download
 *  failed) or `integrity` (bytes' content hash ≠ the manifest's). */
export interface AssetDownloadFailure {
    path: string;
    /** `packed`: the update's manifest packs the asset, and an update downloads assets one by one. */
    reason: 'fetch' | 'integrity' | 'packed';
}

/**
 * How far an update got. Each is its own answer: an update can be running in this
 * session and still be gone on the next launch, which a single `ok` cannot say.
 */
export interface UpdateStages {
    /** Every changed asset downloaded and matched its content hash. */
    verified: boolean;
    /** This session runs on the new manifest, and its asset graph has settled on it. */
    applied: boolean;
    /** The next launch starts on it: stored, and read back. Null without a persistence key. */
    persisted: boolean | null;
    /** Every changed remote asset is in the disk cache, so the next launch reads them
     *  without the network. Null where the platform keeps no cache. */
    cached: boolean | null;
}

/** Outcome of {@link Assets.applyUpdate} — atomic: `ok` only when every changed
 *  asset downloaded + verified and the manifest was swapped. On failure nothing
 *  is applied (`updated: 0`) and `failed` lists why (rollback). */
export interface ApplyUpdateResult {
    ok: boolean;
    updated: number;
    failed: AssetDownloadFailure[];
    stages: UpdateStages;
    /** The revision this session runs on afterwards. */
    revision: string | null;
    /** The changed assets the cache refused, by url: what the next launch fetches again. */
    uncached: string[];
    /** Why nothing was attempted: no update staged (none checked, or another apply took it). */
    reason?: 'nothing-staged';
}

/** What {@link Assets.updateStatus} reports. */
export interface UpdateStatus {
    /** The revision this session runs on. */
    revision: string | null;
    /** The revision the next launch starts on, when an update was persisted. */
    persistedRevision: string | null;
    /** The update {@link Assets.checkForUpdate} staged, and what applying it downloads. */
    staged: { revision: string | null; assets: number; bytes: number } | null;
    applying: boolean;
}

/** The manifest + root staged by checkForUpdate, awaiting applyUpdate. */
interface PendingUpdate {
    model: ManifestModel;
    manifestJson: AddressableManifest;
    remoteRoot: string | null;
}

/**
 * Default upper bound on concurrent loads inside preloadSceneAssets.
 * Picked to match typical browser per-origin connection limits; scenes
 * with hundreds of assets would otherwise fan out all at once and
 * saturate the network, CPU image decoders, and WASM memory.
 */
const DEFAULT_PRELOAD_CONCURRENCY = 6;

/** A preload's timings are a report, so they need no platform: a realm without
 *  one (a test, a tool) still loads. */
const preloadClock = (): number => (typeof performance !== 'undefined' ? performance.now() : Date.now());

/**
 * Run an array of lazy task thunks with at most `maxConcurrent` in
 * flight. Calls `onEach` once per task completion (success or failure)
 * so callers can drive a progress indicator. Never rejects — individual
 * task errors are expected to be handled inside the thunk itself.
 */
async function runWithConcurrency(
    tasks: ReadonlyArray<() => Promise<void>>,
    maxConcurrent: number,
    onEach: () => void,
): Promise<void> {
    if (tasks.length === 0) return;
    let cursor = 0;
    const workers: Promise<void>[] = [];
    const worker = async (): Promise<void> => {
        while (cursor < tasks.length) {
            const i = cursor++;
            try {
                await tasks[i]();
            } finally {
                onEach();
            }
        }
    };
    const slots = Math.min(maxConcurrent, tasks.length);
    for (let i = 0; i < slots; i++) {
        workers.push(worker());
    }
    await Promise.all(workers);
}

export interface AssetsOptions {
    backend: Backend;
    catalog?: Catalog;
    /**
     * Addressable manifest (groups + bundle modes). When set, enables
     * `loadGroup(name)`. Accepts the raw manifest JSON or a pre-built
     * {@link ManifestModel}. Optional — label/path loading works without it.
     */
    manifest?: AddressableManifest | ManifestModel;
    /** The wasm module, or null on the native (embedded-Dawn) backend, which has
     *  no wasm heap — its ResourceManager uploads texture bytes directly. */
    module: ESEngineModule | null;
    /**
     * Lazy accessor for the owning app's Audio API. AudioAssetLoader
     * calls it at load time so AssetPlugin and AudioPlugin can be built
     * in any order. Pass null (or omit) if no audio support is needed.
     */
    getAudio?: () => import('../audio/Audio').AudioAPI | null;
    getSpriteAnimation?: () => import('../animation/SpriteAnimator').SpriteAnimationAPI | null;
    /** Lazy accessor for the owning app's Localization service, same contract
     *  as {@link getAudio} — `.eslocale` tables register through it. */
    getLocalization?: () => import('../i18n/Localization').LocalizationAPI | null;
}

export interface AssetBundle {
    textures: Map<string, TextureResult>;
    materials: Map<string, MaterialResult>;
    spine: Map<string, SpineResult>;
    fonts: Map<string, FontResult>;
    /**
     * What this load actually acquired. Release through it rather than by group
     * name: a manifest can be updated between the two, and then the group's
     * membership is no longer the set this bundle took out.
     */
    scope: AssetScope;
    /** Give back everything this bundle acquired. Idempotent. */
    release(): void;
}

function emptyBundle(): AssetBundle {
    const scope = new AssetScope();
    return {
        textures: new Map(), materials: new Map(), spine: new Map(), fonts: new Map(),
        scope, release: () => scope.releaseAll(),
    };
}


/**
 * How one addressable asset type is acquired and given back.
 *
 * ONE table, because two of them drift: load handled `font` and release did
 * not, so every group carrying a font kept its reference forever. A type that
 * can be loaded and has no release channel now has to say so out loud.
 */
interface GroupAssetChannel {
    load(assets: Assets, path: string, bundle: AssetBundle): Promise<void>;
    /** null when something else owns the lifetime — see `spine`. */
    release: ((assets: Assets, path: string) => void) | null;
    /** In the bundle `loadByLabel` returns: the types a scene can display. */
    displayable: boolean;
}

const GROUP_ASSET_CHANNELS: Readonly<Record<string, GroupAssetChannel>> = {
    texture: {
        load: (a, path, b) => a.acquireTexture(path)
            .then((l) => { b.scope.add(l); b.textures.set(path, l.value); }),
        release: (a, path) => a.releaseTexture(path),
        displayable: true,
    },
    material: {
        load: (a, path, b) => a.acquireTyped<MaterialResult>('material', path)
            .then((l) => { b.scope.add(l); b.materials.set(path, l.value); }),
        release: (a, path) => a.releaseTyped('material', path),
        displayable: true,
    },
    font: {
        load: (a, path, b) => a.acquireTyped<FontResult>('font', path)
            .then((l) => { b.scope.add(l); b.fonts.set(path, l.value); }),
        release: (a, path) => a.releaseTyped('font', path),
        displayable: true,
    },
    'bitmap-font': {
        load: (a, path, b) => a.acquireTyped<FontResult>('font', path)
            .then((l) => { b.scope.add(l); b.fonts.set(path, l.value); }),
        release: (a, path) => a.releaseTyped('font', path),
        displayable: true,
    },
    spine: {
        load: (a, path, b) => a.acquireSpine(path)
            .then((l) => { b.scope.add(l); b.spine.set(path, l.value); }),
        release: (a, path) => a.releaseTyped('spine', path),
        displayable: true,
    },
    prefab: {
        load: (a, path, b) => a.acquireTyped('prefab', path).then((l) => { b.scope.add(l); }),
        release: (a, path) => a.releaseTyped('prefab', path),
        displayable: false,
    },
    audio: {
        load: (a, path, b) => a.acquireTyped('audio', path).then((l) => { b.scope.add(l); }),
        release: (a, path) => a.releaseTyped('audio', path),
        displayable: false,
    },
};

/**
 * Describes one asset a scene / prefab referenced that couldn't be
 * materialized into a usable handle. The caller of preloadSceneAssets
 * uses this to surface editor UI ("missing asset") or to abort the
 * load entirely — instead of the old behaviour of silently storing
 * `texture: 0` and hoping the renderer notices.
 */
export interface MissingAsset {
    /** The original serialized ref (`"@uuid:..."` or a plain path). */
    ref: string;
    /** Asset type (`"texture"`, `"material"`, ...) when known. */
    type?: string;
    /** `unresolved` = UUID not in registry; `load-failed` = fetch threw. */
    reason: 'unresolved' | 'load-failed';
    /** Stringified error for `load-failed`. */
    error?: string;
}

/**
 * Say what failed, wherever it failed. Two loading doors reached this same dead
 * end — a caller holding an empty result it cannot tell from an empty group —
 * so the sentence is written once rather than at each of them.
 */
function warnFailedLoads(failed: readonly MissingAsset[], where?: string): void {
    if (failed.length === 0) return;
    log.warn('asset', `${where ? `${where}: ` : ''}${failed.length} asset(s) failed to load`, failed);
}

export interface SceneAssetResult {
    textureHandles: Map<string, number>;
    materialHandles: Map<string, number>;
    fontHandles: Map<string, number>;
    meshHandles: Map<string, number>;
    environmentHandles: Map<string, number>;
    probeVolumeHandles: Map<string, number>;
    releaseCallbacks: ReleaseCallback[];
    /**
     * What this preload actually acquired. Release side reads THIS rather than
     * re-deriving from the scene's declared refs: a failed load left no lease,
     * and an invalidate mid-load left the receipt of the era we really got.
     */
    scope: AssetScope;
    /** @internal Projection of successful acquisitions; their scope/era remains the owner. */
    acquisitions?: readonly { readonly type: string; readonly path: string; readonly lease: AssetLease }[];
    missing: MissingAsset[];
    /** Per asset type: how many loaded, the sum of their load times and the
     *  slowest one, in ms. Loads overlap, so the sums exceed the wall time. */
    timings: Record<string, { count: number; ms: number; slowestMs: number }>;
    /** Wall time of the whole preload, in ms. */
    wallMs: number;
}

export type AssetRefResolver = (ref: string) => string | null;

/**
 * The asset server: one typed loader per asset type, over one ref vocabulary.
 *
 * Every `ref` a loader takes is one of two spellings, and both land on the same
 * file:
 *
 *  - a **project-root-relative path** — `'assets/textures/player.png'`. Relative
 *    to the project root, NOT to the assets folder, so it carries the `assets/`
 *    segment: it is the path the Content Browser shows, the key the cook's
 *    manifest is built on, and what the backend appends to its base url. A ref
 *    that drops the root resolves just the same and 404s, because nothing lives
 *    at the project root.
 *  - an **`@uuid:` ref** — what the editor serializes into scenes and prefabs so
 *    renaming or moving the file breaks nothing. Not hand-written; the realm's
 *    resolver turns it back into the path above before any fetch.
 */
/**
 * A path-addressed release had more than one generation to choose from, so it
 * took the oldest and may have freed somebody else's asset. Reported once per
 * key: the caller that can carry a lease should, and one that cannot needs to
 * hear it once, not every frame.
 */
const ambiguousWarned_ = new Set<string>();
function warnAmbiguousRelease_(key: string): void {
    if (ambiguousWarned_.has(key)) return;
    ambiguousWarned_.add(key);
    log.warn('asset',
        `release("${key}") had more than one live generation and released the oldest — `
        + 'which may not be the one the caller holds. Release it by its lease instead.');
}

/**
 * What edge a mesh texture is first loaded at, asked as each one loads (texture streaming says, by the quality level): set once per
 * realm, before any Assets exists, since a scene can load before the first frame. 0 loads it whole.
 */
let textureStreamingStart: () => number = () => 0;
/** @internal */
export function setTextureStreamingStartProvider(provider: () => number): void { textureStreamingStart = provider; }

export class Assets {
    readonly backend: Backend;
    readonly catalog: Catalog;

    get baseUrl(): string | undefined { return this.baseUrl_; }
    set baseUrl(url: string | undefined) {
        this.baseUrl_ = url;
        if (this.backend.setBaseUrl) {
            this.backend.setBaseUrl(url ?? '');
        }
    }
    private baseUrl_?: string;

    private module_: ESEngineModule | null;
    private manifestModel_: ManifestModel | null = null;
    /** CDN root that `remote`-group assets resolve against; see {@link setRemoteRoot}. */
    private remoteRoot_?: string;
    /** Applies run one after another: two at once would each commit, and one that
     *  finishes after a newer check would clear the newer candidate. */
    private applyChain_: Promise<unknown> = Promise.resolve();
    private applying_ = 0;
    /** The update staged by {@link checkForUpdate}, consumed by {@link applyUpdate}. */
    private pendingUpdate_: PendingUpdate | null = null;
    /** Storage key {@link applyUpdate} persists the active manifest under; set by
     *  {@link restorePersistedUpdate}. Null → persistence off. */
    private persistKey_: string | null = null;
    /** The revision this package shipped, read when persistence is armed at boot. */
    private shippedRevision_: string | null = null;
    private cacheOwner_: string | null = null;
    private cacheRollback_: CacheVersion | null = null;
    private cacheLaunch_: CacheVersion | null = null;
    private cacheLaunchRollback_: CacheVersion | null = null;
    private activeUpdate_: PendingUpdate | null = null;
    private getAudio_: () => import('../audio/Audio').AudioAPI | null;
    private getSpriteAnimation_: () => import('../animation/SpriteAnimator').SpriteAnimationAPI | null;
    private getLocalization_: () => import('../i18n/Localization').LocalizationAPI | null;
    private loaders_ = new Map<string, AssetLoader<unknown>>();
    private textureLoader_: TextureLoader;
    private textureImportResolver_: TextureImportSettingsResolver | null = null;
    private spineLoader_: SpineAssetLoader;

    private textureCache_ = new AsyncCache<TextureResult>((result) => {
        // A texture whose load finished after its getOrLoad timed out has no
        // owner; release its GL handle so it doesn't leak VRAM.
        requireResourceManager().releaseTexture(result.handle);
    });
    /** Live texture references per cache key. See {@link AssetRefLedger}. */
    private textureRefs_ = new AssetRefLedger<number>();

    /**
     * Bumped by releaseAll(). A load in flight across one has no owner left: the
     * scene that asked is gone and its references were dropped, so the texture
     * it produces is destroyed by the pool before the caller's `await` ever
     * resumes. Delivering that handle is a use-after-free; the load fails instead.
     */
    private resetEpoch_ = 0;
    private releasing_ = false;
    private preparations_ = new Set<DependencyRecorder>();

    /** @internal How many times everything this loader held has been given back: what a holder kept of an earlier one names things that are gone. */
    get epoch(): number { return this.resetEpoch_; }

    private assertLoading_(epoch = this.resetEpoch_): void {
        if (this.releasing_ || epoch !== this.resetEpoch_) {
            throw new Error('Assets were released while loading; this request has no owner. Load it again.');
        }
    }
    /** Handles already disowned in this epoch, so N callers sharing one load
     *  drop its single C++ reference once between them, not N times. */
    private abandoned_ = new Set<number>();
    private genericCache_ = new Map<string, AsyncCache<PreparedLoad<unknown>>>();
    /** Per-asset reference counts for the generic caches, keyed `type:path`.
     *  Same contract as textures: every load*() increments, every release*()
     *  decrements, and the loader's unload runs only at zero — so an asset
     *  shared by two scenes survives the first scene's unload. */
    private genericRefs_ = new AssetRefLedger<PreparedLoad<unknown>>();
    /** Eras already given back, so N callers abandoning one shared load hand it
     *  over once between them rather than unloading it N times. */
    private retired_ = new WeakSet<PreparedLoad<unknown>>();
    /** Propagations in flight — what {@link assetGraphSettled} waits on. */
    private settling_ = new Set<Promise<void>>();
    private loadContext_: LoadContext | null = null;
    private assetRefResolver_: AssetRefResolver | null = null;
    private refCounter_: AssetRefCounter | null = null;
    private invalidateListeners_ = new Set<InvalidateListener>();
    private readonly appScope_ = new AssetScope();
    private readonly entityScopes_ = new EntityAssetScopes();
    private readonly registrySlots_ = new RegistryAssetSlots();
    /** `"<kind>:<handle>"` → resolved load path, recorded on every handle-yielding
     *  load. The REVERSE of resolution — inspectors and tooling that only hold a
     *  live World handle use it to name the asset (see {@link pathForHandle}). */
    private handleToPath_ = new Map<string, string>();
    /** Textures a mesh draws, by resolved path, directly or through a material: what texture streaming may load small to begin with. */
    private readonly meshTextures_ = new Set<string>();
    /** Materials a mesh draws with, by resolved path: their textures join {@link meshTextures_} as the material loads them. */
    private readonly meshMaterials_ = new Set<string>();
    /** The edge a mesh texture is first loaded at while texture streaming is on; 0 loads it whole. */
    private streamingStartEdge_: number | (() => number) = 0;

    /**
     * Geometry built at run time rather than loaded (a static batch), by handle. It has no file to be replayed
     * from, so the data itself is kept: a device loss puts it back from here.
     */
    private builtMeshes_ = new Map<number, MeshData>();

    private constructor(options: AssetsOptions) {
        this.backend = options.backend && packedBackend(options.backend, () => this.manifestModel_);
        this.catalog = options.catalog ?? Catalog.empty();
        this.module_ = options.module;
        this.getAudio_ = options.getAudio ?? (() => null);
        this.getSpriteAnimation_ = options.getSpriteAnimation ?? (() => null);
        this.getLocalization_ = options.getLocalization ?? (() => null);
        this.setManifest(options.manifest ?? null);

        this.textureLoader_ = new TextureLoader(options.module);
        this.spineLoader_ = new SpineAssetLoader();

        this.registerBuiltinLoaders();
    }

    static create(options: AssetsOptions): Assets {
        return new Assets(options);
    }

    // =========================================================================
    // Loader Registry
    // =========================================================================

    register<T>(loader: AssetLoader<T>): void {
        this.loaders_.set(loader.type, loader as AssetLoader<unknown>);
    }

    getLoader<T>(type: string): AssetLoader<T> | undefined {
        return this.loaders_.get(type) as AssetLoader<T> | undefined;
    }

    // =========================================================================
    // Typed Load Methods (User API)
    // =========================================================================

    async loadTexture(ref: string): Promise<TextureResult> {
        return this.loadTextureVariant_(ref, true);
    }

    async loadTextureRaw(ref: string): Promise<TextureResult> {
        return this.loadTextureVariant_(ref, false);
    }

    /**
     * The textures the engine is waiting for content for — its ledger, not a
     * mirror of this cache — with who refills each and the path it was
     * registered under. A blank path is not this layer's to fetch.
     */
    texturesAwaitingReupload(): { handle: number; content: TextureContent; path: string }[] {
        const raw = requireResourceManager().texturesAwaitingReupload?.() ?? '';
        if (!raw) return [];
        return raw.split('\n').map((line) => {
            const [handle, content, ...path] = line.split('|');
            return {
                handle: Number(handle),
                content: Number(content) as TextureContent,
                path: path.join('|'),
            };
        });
    }

    /**
     * Decode the texture behind @p handle again, no larger than @p maxEdge texels on a side (0 is its full size), behind the same handle:
     * what texture streaming moves a texture between sizes with. Null for a texture no file of this realm's stands behind.
     */
    async resizeTexture(handle: number, maxEdge: number): Promise<{ width: number; height: number } | null> {
        const size = await this.textureLoader_.resize(handle, maxEdge, this.getLoadContext_());
        if (size) evictTextureDimensions(handle);
        return size;
    }

    /** The size of the file behind @p handle, whatever size it is held at; null for a texture no file of this realm's stands behind. */
    textureFullSize(handle: number): { width: number; height: number } | null {
        return this.textureLoader_.fullSize(handle);
    }

    /**
     * Load the textures meshes draw no larger than @p edge on a side to begin with (0 loads them whole): texture streaming grows each
     * to what its views need. A texture something else also draws is put back at its size by the streamer.
     */
    setTextureStreamingStart(edge: number | (() => number)): void {
        this.streamingStartEdge_ = edge;
    }

    /** Whether {@link resizeTexture} can move @p handle between sizes. */
    textureResizable(handle: number): boolean {
        return this.textureLoader_.resizable(handle);
    }

    /**
     * Refills every owed texture someone can: an asset texture is loaded again and
     * moved behind its handle, any other goes to the refill its creator provided.
     * Content nobody can remake is forgone by name, or the device recovers forever.
     */
    async reuploadTexturesAfterDeviceLoss(): Promise<number> {
        const rm = requireResourceManager();
        if (!rm.adoptTextureContent) return 0;

        let restored = 0;
        for (const { handle, content, path } of this.texturesAwaitingReupload()) {
            if (content !== TextureContent.Asset || !path) {
                const refill = textureRefill(handle);
                if (!refill) {
                    log.warn('assets', `Device recovery: texture ${handle} (${textureContentName(content)})`
                        + ' has no provider to refill it; it stays blank');
                    rm.forgoTextureContent?.(handle);
                    continue;
                }
                try {
                    if (await refill()) restored++;
                } catch (e) {
                    log.warn('assets', `Device recovery: refilling texture ${handle}`
                        + ` (${textureContentName(content)}) failed`, e);
                }
                continue;
            }
            const cut = path.lastIndexOf(':');
            const ref = cut < 0 ? path : path.slice(0, cut);
            const flip = cut < 0 || path.slice(cut + 1) === 'f';
            try {
                const fresh = await this.textureLoader_.loadDetached(
                    this.resolveLoadPath_(ref), this.getLoadContext_(), flip,
                    this.textureImportResolver_?.(ref));
                if (rm.adoptTextureContent(handle, fresh.handle)) restored++;
                rm.releaseTexture(fresh.handle);
            } catch (e) {
                log.warn('assets', `Device recovery: re-upload failed for ${ref}`, e);
            }
        }
        log.info('assets', `Device recovery: ${restored} texture(s) re-uploaded`);
        return restored;
    }

    /**
     * The meshes the engine is waiting for geometry for, by handle. No path
     * travels with them: the engine never knew one, and this layer does.
     */
    meshesAwaitingRematerialization(): number[] {
        const raw = requireResourceManager().meshesAwaitingRemat?.() ?? '';
        return raw ? raw.split(',').map(Number).filter((h) => h > 0) : [];
    }

    /** Every live mesh and whether its geometry is on the device. */
    meshRealizations(): { handle: number; realized: boolean }[] {
        const raw = requireResourceManager().meshRealizations?.() ?? '';
        if (!raw) return [];
        return raw.split(',').map((row) => {
            const [handle, realized] = row.split(':');
            return { handle: Number(handle), realized: realized === '1' };
        });
    }

    /**
     * Replays each owed mesh from its source, into the handle it already has.
     *
     * A missing provenance is a CONTRACT VIOLATION, not a mesh that turns out to
     * be unrecoverable: the engine only owes what a producer declared
     * replayable, so an absent path means this layer lost the record.
     *
     * @return How many came back. The rest stay owed.
     */
    async rematerializeMeshesAfterDeviceLoss(): Promise<number> {
        const loader = this.getLoader<MeshResult>('mesh');
        if (!(loader instanceof MeshAssetLoader)) return 0;

        let restored = 0;
        for (const handle of this.meshesAwaitingRematerialization()) {
            const built = this.builtMeshes_.get(handle);
            if (built) {
                if (loader.uploadData(built, handle) !== 0) restored++;
                else log.error('assets', `Device recovery: the engine refused built geometry ${handle}`);
                continue;
            }
            const path = this.pathForHandle('mesh', handle);
            if (!path) {
                log.error('assets', `Device recovery: mesh ${handle} is declared replayable and`
                    + ' has no recorded source — its provenance was lost, so it cannot come back');
                continue;
            }
            try {
                if (await loader.rematerialize(handle, path, this.getLoadContext_())) restored++;
                else log.error('assets', `Device recovery: the engine refused geometry for ${path}`);
            } catch (e) {
                log.error('assets', `Device recovery: replaying ${path} failed`, e);
            }
        }
        log.info('assets', `Device recovery: ${restored} mesh(es) rematerialized`);
        return restored;
    }

    /**
     * Pays what the engine owes after rebuilding the device. The rebuild itself
     * is the engine's, once per loss; this only refills content. Returns whether
     * the device is whole — false while the context is not back yet, or while
     * content is still owed, so a caller retries.
     */
    async recoverFromDeviceLoss(): Promise<boolean> {
        if (!recoverDevice()) return false;
        await this.reuploadTexturesAfterDeviceLoss();
        await this.rematerializeMeshesAfterDeviceLoss();
        const whole = getDeviceStatus() === DeviceStatus.Live;
        if (!whole) {
            const owed = this.texturesAwaitingReupload().length + this.meshesAwaitingRematerialization().length;
            log.warn('assets', `Device recovery: ${owed} texture(s)/mesh(es) have not come back`);
        }
        return whole;
    }

    /** The decoded geometry behind a mesh handle this realm loaded, or null when nothing here can name it. */
    async readMeshData(handle: number): Promise<MeshData | null> {
        const loader = this.getLoader<MeshResult>('mesh');
        const path = this.pathForHandle('mesh', handle);
        if (!(loader instanceof MeshAssetLoader) || !path) return null;
        try {
            return await loader.readSource(path, this.getLoadContext_());
        } catch (e) {
            log.warn('assets', `Reading the geometry of ${path} failed`, e);
            return null;
        }
    }

    /** Uploads geometry built at run time. Returns its handle, or 0 when the engine refused it. */
    createMesh(data: MeshData): number {
        const loader = this.getLoader<MeshResult>('mesh');
        if (!(loader instanceof MeshAssetLoader)) return 0;
        const handle = loader.uploadData(data);
        if (handle !== 0) this.builtMeshes_.set(handle, data);
        return handle;
    }

    /** Gives back geometry {@link createMesh} made. */
    releaseBuiltMesh(handle: number): void {
        if (!this.builtMeshes_.delete(handle)) return;
        const loader = this.getLoader<MeshResult>('mesh');
        if (loader instanceof MeshAssetLoader) loader.releaseData(handle);
    }

    private async loadTextureVariant_(ref: string, flip: boolean): Promise<TextureResult> {
        return (await this.acquireTextureVariant_(ref, flip)).result;
    }

    private async acquireTextureVariant_(
        ref: string, flip: boolean,
    ): Promise<{ result: TextureResult; lease: AssetRefLease<number> }> {
        this.assertLoading_();
        const path = this.resolveLoadPath_(ref);
        const cacheKey = this.textureCacheKey_(path, flip);
        const settings = this.textureImportResolver_?.(ref);
        const epoch = this.resetEpoch_;
        const result = await this.textureCache_.getOrLoad(cacheKey, () => {
            // Warm-cache hit: a texture whose last reference was released stays
            // resident in the C++ pool (up to the texture budget) under this
            // exact key — reviving it skips the whole fetch + decode + upload.
            const revived = this.reviveResidentTexture_(cacheKey);
            if (revived) return Promise.resolve(revived);
            this.textureLoader_.setPendingSettings(settings);
            // Asked as each texture loads: what decides it (the quality level) may arrive after whoever said how to ask.
            const own = typeof this.streamingStartEdge_ === 'function' ? this.streamingStartEdge_() : this.streamingStartEdge_;
            const start = own > 0 ? own : textureStreamingStart();
            if (start > 0 && this.meshTextures_.has(path)) this.textureLoader_.setPendingStartEdge(start);
            return flip
                ? this.textureLoader_.load(path, this.getLoadContext_())
                : this.textureLoader_.loadRaw(path, this.getLoadContext_());
        });
        // BEFORE acquiring, so no ledger entry is ever created for a load nobody
        // is left to own — one that N shared callers would each then drop,
        // releasing the load's single C++ reference N times.
        if (epoch !== this.resetEpoch_) {
            if (!this.abandoned_.has(result.handle)) {
                this.abandoned_.add(result.handle);
                requireResourceManager().releaseTexture(result.handle);
                evictTextureDimensions(result.handle);
            }
            throw new Error(
                `Assets were released while "${ref}" was loading; its texture has no owner. Load it again.`,
            );
        }
        const lease = this.textureRefs_.acquire(cacheKey, result.handle);
        this.recordHandlePath_('texture', result.handle, path);
        // The 9-slice border belongs to the IMAGE, so it rides its import
        // settings and is stamped onto the handle here — the one place every
        // creation path (decode, revive, external, cooked) funnels through, and
        // where the settings are already resolved. Without this a UIVisual set
        // to NineSlice finds no texture metadata and stretches its corners.
        if (settings?.sliceBorder) {
            const b = settings.sliceBorder;
            requireResourceManager().setTextureMetadata(result.handle, b.left, b.right, b.top, b.bottom);
        }
        return { result, lease };
    }

    /**
     * Try to revive an evictable texture from the C++ pool's residency cache.
     * Returns null on a miss — or when the resource-manager surface doesn't
     * support residency (minimal test mocks). Gated on invalidateTexturePath
     * too: reviving without the ability to sever a path on hot reload could
     * hand out stale bytes, so both must be present or neither is used.
     */
    private reviveResidentTexture_(cacheKey: string): TextureResult | null {
        const rm = requireResourceManager();
        if (typeof rm.acquireTextureByPath !== 'function'
            || typeof rm.invalidateTexturePath !== 'function') return null;
        const handle = rm.acquireTextureByPath(cacheKey);
        if (!handle) return null;
        const dims = rm.getTextureDimensions(handle);
        if (!dims) {
            rm.releaseTexture(handle);
            return null;
        }
        this.textureLoader_.adoptRevived(handle, cacheKey);
        return { handle, width: dims.width, height: dims.height };
    }

    /**
     * Provide per-asset texture import settings at load time (filter, wrap,
     * mipmaps). The resolver is called with the original ref — keyed off
     * `@uuid:...` in editor scenarios. Returning `undefined` uses defaults.
     */
    setTextureImportSettingsResolver(resolver: TextureImportSettingsResolver | null): void {
        this.textureImportResolver_ = resolver;
    }

    getTexture(ref: string): TextureResult | undefined {
        const path = this.resolveLoadPath_(ref);
        return this.textureCache_.get(this.textureCacheKey_(path, true));
    }

    /**
     * The load path behind a LIVE handle (`kind` = the asset slot type:
     * 'texture' | 'material' | 'font' | …), or null when this realm never
     * loaded such a handle. The reverse of ref resolution — the live "Game"
     * inspector uses it to show WHICH asset a World component's handle-valued
     * slot is wearing (a raw handle number names nothing to a human).
     */
    pathForHandle(kind: string, handle: number): string | null {
        return this.handleToPath_.get(`${kind}:${handle}`) ?? null;
    }

    /**
     * The load path of a texture by the id the renderer bound it with — a frame
     * capture's `textureId` — rather than by asset handle. Null for a texture no
     * asset of this realm loaded: the white fill, a render target, a glyph atlas.
     */
    pathForRenderedTexture(renderId: number): string | null {
        const rm = getResourceManager();
        if (!rm || renderId === 0) return null;
        for (const [key, path] of this.handleToPath_) {
            if (key.startsWith('texture:') && rm.getTextureGLId(Number(key.slice('texture:'.length))) === renderId) {
                return path;
            }
        }
        return null;
    }

    /** Record a handle→path pair, dropped on invalidation or final release. */
    private recordHandlePath_(kind: string, handle: number, path: string): void {
        if (handle !== 0) this.handleToPath_.set(`${kind}:${handle}`, path);
    }

    /** {@link acquireSpine} without the receipt, for a caller that will let the
     *  realm's teardown be its release. */
    async loadSpine(skeletonRef: string, atlasRef?: string): Promise<SpineResult> {
        return (await this.acquireSpine(skeletonRef, atlasRef)).value;
    }

    /**
     * One spine PAIR — a skeleton and the atlas it is drawn with. The same
     * skeleton with another atlas is another asset, which is why the receipt
     * names the pair and not the skeleton's path.
     */
    async acquireSpine(skeletonRef: string, atlasRef?: string): Promise<AssetLease<SpineResult>> {
        try { return await this.acquireSpineLease_(skeletonRef, atlasRef); }
        catch (error) { throw preparationFailureReason(error); }
    }

    private async acquireSpineLease_(skeletonRef: string, atlasRef?: string): Promise<AssetLease<SpineResult>> {
        const skeleton = this.resolveLoadPath_(skeletonRef);
        const atlas = this.spineAtlasOf_(skeleton, atlasRef);
        const key = spinePairKey(skeleton, atlas);
        const { value, lease } = await this.acquirePrepared_<SpineResult>(
            'spine', key, skeletonRef,
            (ctx) => this.spineLoader_.prepare(skeleton, atlas, ctx),
        );
        return this.typedLease_('spine', lease, value);
    }

    /** The atlas of a pair the caller named only half of: a skeleton's atlas is
     *  a Catalog dependency, which is what a cook records for it. */
    private spineAtlasOf_(skeleton: string, atlasRef?: string): string {
        if (atlasRef) return this.resolveLoadPath_(atlasRef);
        const deps = this.catalog.getDeps(skeleton);
        if (deps.length === 0) {
            throw new Error(`Spine skeleton has no atlas dependency: ${skeleton}. `
                + 'Pass the atlas explicitly or configure Catalog deps.');
        }
        return deps[0];
    }

    async loadMaterial(ref: string): Promise<MaterialResult> {
        return this.loadTyped('material', ref);
    }

    async loadFont(ref: string): Promise<FontResult> {
        return this.loadTyped('font', ref);
    }

    async loadAudio(ref: string): Promise<AudioResult> {
        return this.loadTyped('audio', ref);
    }

    async loadAnimClip(ref: string): Promise<AnimClipResult> {
        return (await this.acquireAnimClip_(ref)).value;
    }

    /**
     * A clip is published under the load path AND the ref as it was spelled: a
     * realm whose resolver returns URLs hands the loader `estella://…/walk.esanim`
     * while components ask for `assets/animations/walk.esanim`. Both names are
     * the slot's, so a republish is seen through either.
     */
    private async acquireAnimClip_(ref: string): Promise<AssetLease<AnimClipResult>> {
        return this.acquireTyped<AnimClipResult>('anim-clip', ref);
    }

    async loadTilemap(ref: string): Promise<TilemapResult> {
        return this.loadTyped('tilemap', ref);
    }

    async loadTileset(ref: string): Promise<TilesetResult> {
        return this.loadTyped('tileset', ref);
    }

    async loadTimeline(ref: string): Promise<TimelineResult> {
        return this.loadTyped('timeline', ref);
    }

    /** Load a `.eslocale` string table and merge it into the app's Localization
     *  catalogs. Requires the LocalizationPlugin (fails loud otherwise). */
    async loadLocaleTable(ref: string): Promise<LocaleResult> {
        return this.loadTyped('locale', ref);
    }

    /** Load a `.esfsm` state machine into the shared AI store, keyed by its
     *  asset path — the ref a StateMachineAgent's `fsm` field resolves. */
    async loadStateMachine(ref: string): Promise<FsmResult> {
        return this.loadTyped('statemachine', ref);
    }

    /** Load a `.esbt` behavior tree into the shared AI store, keyed by its
     *  asset path — the ref a BehaviorTreeAgent's `bt` field resolves. */
    async loadBehaviorTree(ref: string): Promise<BtResult> {
        return this.loadTyped('behaviortree', ref);
    }

    /** Load a `.esanimator` controller into the shared animator store, keyed by
     *  its asset path — the ref an Animator's `controller` field resolves. */
    async loadAnimatorController(ref: string): Promise<AnimatorControllerResult> {
        return this.loadTyped('animatorcontroller', ref);
    }

    async loadPrefab(ref: string): Promise<PrefabResult> {
        return this.loadTyped('prefab', ref);
    }

    /**
     * Load a `.json` data asset — a game's own table, tuning or dialogue file.
     *
     * `T` is what the caller expects the document to be; nothing validates it,
     * so this is `JSON.parse`'s guarantee, not a schema's. What the asset system
     * adds over fetching the file yourself is everything around the parse: ref
     * resolution (`@uuid:` and manifest paths), one parse per file, group /
     * subpackage delivery, and hot update.
     */
    async loadJson<T = unknown>(ref: string): Promise<JsonResult<T>> {
        return this.loadTyped('json', ref);
    }

    // =========================================================================
    // Generic Load (for custom loaders)
    // =========================================================================

    async load<T>(type: string, ref: string): Promise<T> {
        return this.loadTyped<T>(type, ref);
    }

    // =========================================================================
    // Atlas Query
    // =========================================================================

    getAtlasFrame(ref: string): AtlasFrameInfo | null {
        // Raw ref first: atlas frames register under every ref SPELLING
        // (`@uuid:…`, logical, "/"-rooted). The resolved path is the fallback —
        // for packed frames it is the shared PAGE path, which cannot key
        // per-frame data.
        return this.catalog.getAtlasFrame(ref)
            ?? this.catalog.getAtlasFrame(this.resolveLoadPath_(ref));
    }

    // =========================================================================
    // Addressable Manifest (groups / bundle modes)
    // =========================================================================

    /**
     * Set (or clear) the addressable manifest used by {@link loadGroup}.
     * Accepts the raw manifest JSON or a pre-built {@link ManifestModel};
     * `null` clears it.
     */
    setManifest(manifest: AddressableManifest | ManifestModel | null): void {
        this.manifestModel_ =
            manifest == null ? null
            : manifest instanceof ManifestModel ? manifest
            : ManifestModel.fromJson(manifest);
    }

    getManifest(): ManifestModel | null {
        return this.manifestModel_;
    }

    // =========================================================================
    // Batch Load (by label / by group)
    // =========================================================================

    async loadByLabel(
        label: string,
        onProgress?: (loaded: number, total: number) => void,
    ): Promise<AssetBundle> {
        const bundle = emptyBundle();
        let loadedCount = 0;
        const promises: Promise<void>[] = [];
        const track = (p: Promise<void>): Promise<void> =>
            p.then(() => { onProgress?.(++loadedCount, totalCount); })
             .catch(() => { onProgress?.(++loadedCount, totalCount); });

        for (const path of this.catalog.getByLabel(label)) {
            const entry = this.catalog.getEntry(path);
            if (!entry) continue;
            const task = this.bundleLoadTask_(path, entry.type, bundle);
            if (task) promises.push(track(task));
        }

        const totalCount = promises.length;
        onProgress?.(0, totalCount);
        loadedCount = 0;

        await Promise.allSettled(promises);
        return bundle;
    }

    /**
     * Load every asset in an addressable group through the typed loaders,
     * warming the cache (and populating the returned bundle for the four
     * displayable types). Requires a manifest (see {@link setManifest}); with
     * no manifest set, this is a no-op returning an empty bundle.
     *
     * This is the single group-loading channel — the basis for on-demand /
     * subpackage delivery. It dispatches through the same per-type loaders as
     * {@link loadByLabel}, so the two never diverge.
     */
    async loadGroup(
        groupName: string,
        onProgress?: (loaded: number, total: number) => void,
    ): Promise<AssetBundle> {
        const bundle = emptyBundle();
        const model = this.manifestModel_;
        if (!model) {
            log.warn('asset', `loadGroup('${groupName}') called but no manifest is set`);
            onProgress?.(0, 0);
            return bundle;
        }

        const mode = model.bundleMode(groupName);
        // A lazy group is an on-demand subpackage — download it before loading its
        // assets (no-op on platforms without a subpackage concept, e.g. web).
        if (mode === 'lazy') {
            await platformLoadSubpackage(groupName);
        }

        let loadedCount = 0;
        const promises: Promise<void>[] = [];
        // A subpackage that downloads but stages nothing reads exactly like a
        // group that was always empty, so the failures are named, not counted.
        const failed: MissingAsset[] = [];
        const track = (p: Promise<void>, ref: string, type: string): Promise<void> =>
            p.then(() => { onProgress?.(++loadedCount, totalCount); })
             .catch((e: unknown) => {
                 failed.push({ ref, type, reason: 'load-failed', error: String(e) });
                 onProgress?.(++loadedCount, totalCount);
             });

        for (const asset of model.assetsInGroup(groupName)) {
            const path = this.manifestAssetUrl_(asset.path, mode === 'remote');
            const task = this.groupLoadTask_(path, asset.type, bundle);
            if (task) promises.push(track(task, path, asset.type));
        }

        const totalCount = promises.length;
        onProgress?.(0, totalCount);
        loadedCount = 0;

        await Promise.allSettled(promises);
        warnFailedLoads(failed, `loadGroup('${groupName}')`);
        return bundle;
    }

    /**
     * Release every asset the group's CURRENT membership names.
     *
     * @details Prefer `bundle.release()` on what {@link loadGroup} returned:
     *          this door re-reads the manifest, so an update between the two
     *          releases a set the load never took. No-op without a manifest.
     */
    releaseGroup(groupName: string): void {
        const model = this.manifestModel_;
        if (!model) {
            log.warn('asset', `releaseGroup('${groupName}') called but no manifest is set`);
            return;
        }
        const mode = model.bundleMode(groupName);
        for (const asset of model.assetsInGroup(groupName)) {
            // The SAME path loadGroup acquired under. Resolving it a different
            // way here would release a key nobody holds, which is a leak that
            // looks exactly like a working release.
            const path = this.manifestAssetUrl_(asset.path, mode === 'remote');
            GROUP_ASSET_CHANNELS[asset.type]?.release?.(this, path);
        }
    }

    // =========================================================================
    // Hot Update (content-addressed remote delivery)
    // =========================================================================

    /** The CDN / remote root that `remote`-group assets resolve against. */
    get remoteRoot(): string | undefined { return this.remoteRoot_; }

    /** Point `remote`-group resolution at a CDN root: their content-addressed
     *  paths then fetch from `<root>/<path>`. A trailing slash is trimmed;
     *  `undefined` clears it (same-origin fallback). */
    setRemoteRoot(url: string | undefined): void {
        this.remoteRoot_ = url ? url.replace(/\/+$/, '') : undefined;
    }

    /** Absolute url of a `remote`-group asset against `root` (default the active
     *  remote root). An already-absolute manifest path (a fully-qualified CDN url)
     *  passes through; with no root the path returns as-is (same-origin fallback). */
    private remoteUrlFor_(path: string, root: string | undefined = this.remoteRoot_): string {
        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) return path;
        if (!root) return path;
        return `${root.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
    }

    /** The load url for a manifest asset. A `remote`-group asset resolves to its
     *  `<root>/<path>` CDN url when a root is set; every other case (local / lazy
     *  group, or a remote group with no CDN root — same-origin realms like editor
     *  Play) resolves through the normal resolver + Catalog. The single remote/local
     *  routing rule shared by {@link loadGroup} and {@link fetchAndVerify_}, so a
     *  loadGroup'd asset and the same asset reached by a scene `@uuid` ref (via
     *  {@link resolveLoadPath_} → {@link remoteAssetPath_}) never resolve two ways. */
    private manifestAssetUrl_(path: string, isRemote: boolean, root: string | undefined = this.remoteRoot_): string {
        return isRemote && root ? this.remoteUrlFor_(path, root) : this.resolveLoadPath_(path);
    }

    /**
     * Fetch a candidate manifest and diff it against the active one WITHOUT
     * applying anything — the "is there an update, and how big?" query. The
     * returned plan (changed assets + byte total) is what a UI shows before
     * asking the player to download; the candidate is staged for {@link applyUpdate}.
     *
     * Diffing is by content hash (see {@link diffManifests}); because assets are
     * content-addressed, a changed asset is a brand-new url, so applying can never
     * overwrite or corrupt a cached file.
     */
    async checkForUpdate(options: CheckForUpdateOptions): Promise<UpdatePlan> {
        const text = await this.backend.fetchText(this.backend.resolveUrl(options.manifestUrl));
        const json = JSON.parse(text) as AddressableManifest;
        const model = ManifestModel.fromJson(json);
        const plan = diffManifests(this.manifestModel_, model);
        const remoteRoot = options.remoteRoot ?? this.remoteRoot_ ?? null;
        this.pendingUpdate_ = { model, manifestJson: json, remoteRoot };
        await this.protectCacheVersions_();
        return plan;
    }

    /**
     * Apply the update staged by the last {@link checkForUpdate}, ATOMICALLY.
     * Phase 1 downloads AND integrity-verifies every changed (content-addressed)
     * asset — bytes are hashed and checked against the manifest's `contentHash`,
     * so a corrupted / tampered CDN response is caught. Only if ALL succeed does
     * phase 2 commit: swap the active manifest + root, rebind live handles (via
     * `onInvalidate`), and persist. If any asset fails to download or fails its
     * hash check, NOTHING is swapped — the old manifest stays active (rollback)
     * and the failures are returned. No-op with nothing staged.
     */
    async applyUpdate(onProgress?: (loaded: number, total: number) => void): Promise<ApplyUpdateResult> {
        this.applying_++;
        const run = this.applyChain_.then(async () => {
            try { return await this.applyStaged_(onProgress); }
            finally { this.activeUpdate_ = null; }
        });
        this.applyChain_ = run.catch(() => {});
        try {
            return await run;
        } finally {
            this.applying_--;
        }
    }

    private async applyStaged_(onProgress?: (loaded: number, total: number) => void): Promise<ApplyUpdateResult> {
        const pending = this.pendingUpdate_;
        const revision = (): string | null => this.manifestModel_?.revision() ?? null;
        const none: UpdateStages = { verified: false, applied: false, persisted: false, cached: false };
        if (!pending) {
            log.warn('asset', 'applyUpdate() called with no pending update — call checkForUpdate first');
            onProgress?.(0, 0);
            return { ok: false, updated: 0, failed: [], stages: none, revision: revision(), uncached: [], reason: 'nothing-staged' };
        }
        // Against what runs NOW, not what ran when it was checked: an apply that
        // finished in between moved the base, and its assets need no second download.
        const changed = diffManifests(this.manifestModel_, pending.model).changedAssets;
        const root = pending.remoteRoot ?? undefined;
        this.activeUpdate_ = pending;
        await this.protectCacheVersions_();

        // Phase 1 — download + verify EVERY changed asset WITHOUT touching the
        // active manifest. Content-addressed, so these are brand-new urls (nothing
        // is overwritten); any failure here leaves the old manifest active = rollback.
        const failed: AssetDownloadFailure[] = [];
        const uncached: string[] = [];
        let cacheable = false;
        let done = 0;
        onProgress?.(0, changed.length);
        const tasks = changed.map((c) => async (): Promise<void> => {
            const got = await this.fetchAndVerify_(c, pending.model, root);
            if (got.failure) failed.push({ path: c.path, reason: got.failure });
            if (got.cache !== 'unsupported' && got.cache !== undefined) cacheable = true;
            if (got.cache === 'failed') uncached.push(got.url);
        });
        await runWithConcurrency(tasks, DEFAULT_PRELOAD_CONCURRENCY, () => {
            onProgress?.(++done, changed.length);
        });

        if (failed.length > 0) {
            log.warn('asset', `applyUpdate: ${failed.length}/${changed.length} asset(s) failed — update rolled back (manifest unchanged)`);
            return { ok: false, updated: 0, failed, stages: none, revision: revision(), uncached: [] };
        }

        // Phase 2 — commit atomically. Capture the texture handle bound to each
        // changed asset BEFORE the swap (it resolves to the OLD path), then swap
        // root + manifest and notify with that handle so the built-in rebinder
        // swaps it to the freshly-fetched content in live components.
        const oldHandles = new Map<string, number>();
        for (const c of changed) {
            // A manifest names an asset by its bare key and a scene serializes it as
            // `@uuid:<key>`; the two resolve down different routes. Ask both, or the
            // handle a scene is holding is invisible from here.
            const tex = this.getTexture(c.key) ?? this.getTexture(`${UUID_REF_PREFIX}${c.key}`);
            if (tex) oldHandles.set(c.key, tex.handle);
        }
        const rollback = this.cacheVersion_(this.manifestModel_, this.remoteRoot_, 'rollback');
        // Protect both sides durably BEFORE committing: a crash may still boot
        // the old persisted manifest until the new one has been stored.
        const previousRollback = this.cacheRollback_;
        this.cacheRollback_ = rollback;
        try {
            await this.protectCacheVersions_(this.cacheVersion_(pending.model, root, 'current'));
        } catch (err) {
            this.cacheRollback_ = previousRollback;
            throw err;
        }
        if (pending.remoteRoot != null) this.setRemoteRoot(pending.remoteRoot);
        this.setManifest(pending.model);
        // A newer check staged while this one downloaded stays staged.
        if (this.pendingUpdate_ === pending) this.pendingUpdate_ = null;
        // The manifest record already says what kind each changed asset is; the
        // notification carries it rather than collapsing to "maybe a texture".
        // Changing content and rebinding nothing had no words: every holder keeps
        // the old pixels while the caller is told `applied: true, failed: 0`. With
        // the keys, because a key the cache never saw is what that looks like.
        if (changed.length > 0 && oldHandles.size === 0) {
            log.warn('asset', 'applyUpdate: no changed asset is bound to a live texture, so this'
                + ` update will rebind nothing. ${changed.map((c) => `${c.type} ${c.key}`
                + ` -> ${this.resolveLoadPath_(c.key)}`).join('; ')}`);
        }
        for (const c of changed) this.fireInvalidate_({ ref: c.key, type: c.type, oldValue: oldHandles.get(c.key) });
        // A changed asset is content-addressed, so its next load finds the update
        // on its own. An era already BUILT from one cannot: it holds what it read
        // at the revision it was prepared in, and only the walk ends it.
        for (const c of changed) {
            // Read the plan before anything is re-prepared, then the changed
            // asset's own slot: it is keyed by its identity, so the update
            // reaches it by preparing an era from the new revision's locator.
            const plan = this.rebuildPlan_(c.key);
            this.track_(this.republishSlots_(c.key).rebuilt.then(() => this.rebuildAssetGraph_(plan)));
        }
        // The update is applied when the asset graph agrees with the manifest —
        // not when the manifest was swapped. Bindings converge on a frame, which
        // an app that is not ticking would never reach from here.
        await this.assetGraphSettled();
        const persisted = this.persistActiveManifest_(pending.manifestJson);
        // Until storage accepts the new manifest, the previous next-launch
        // version AND its rollback must remain pinned across subsequent updates.
        if (persisted === true) {
            this.cacheLaunch_ = this.cacheVersion_(pending.model, root, 'retained');
            this.cacheLaunchRollback_ = rollback ? { ...rollback, reason: 'retained' } : null;
        }
        await this.protectCacheVersions_().catch(e => log.warn('asset', 'updated content is protected but its cache index could not be refreshed', e));
        if (persisted !== true) {
            log.warn('asset', persisted === false
                ? 'applyUpdate: the update runs now, but was not stored — the next launch starts on the previous version'
                : 'applyUpdate: no persistence key (restorePersistedUpdate was never called), so the next launch starts on what shipped');
        }
        return {
            ok: true, updated: changed.length, failed: [], revision: revision(), uncached,
            stages: { verified: true, applied: true, persisted, cached: cacheable ? uncached.length === 0 : null },
        };
    }

    /** Which revision runs, which one the next launch starts on, and what is staged. */
    updateStatus(): UpdateStatus {
        const pending = this.pendingUpdate_;
        const changed = pending ? diffManifests(this.manifestModel_, pending.model).changedAssets : [];
        return {
            revision: this.manifestModel_?.revision() ?? null,
            persistedRevision: this.persistedRevision_(),
            staged: pending ? {
                revision: pending.model.revision(), assets: changed.length,
                bytes: changed.reduce((n, c) => n + c.size, 0),
            } : null,
            applying: this.applying_ > 0,
        };
    }

    private cacheVersion_(model: ManifestModel | null, root: string | undefined, reason: CacheVersion['reason']): CacheVersion | null {
        if (!model) return null;
        const keys = model.entries().filter(e => normalizeBundleMode(model.group(e.group)?.bundleMode) === 'remote')
            .map(e => this.backend.resolveUrl(this.manifestAssetUrl_(e.asset.path, true, root)))
            // A remote group with no CDN root is shipped in the package. Its
            // files need no cache protection and are not missing offline bytes.
            .filter(key => /^https?:\/\//i.test(key));
        return { revision: model.revision() ?? contentHashHex(encodeUtf8(JSON.stringify(keys))), reason, keys };
    }

    private async protectCacheVersions_(current?: CacheVersion | null): Promise<void> {
        if (!isPlatformInitialized()) return;
        const cache = contentCacheFor(getPlatform());
        if (cache.capability() !== 'managed') return;
        this.cacheOwner_ ??= `assets:${this.persistKey_ ?? this.remoteRoot_ ?? 'package'}`;
        this.cacheLaunch_ ??= this.cacheVersion_(this.manifestModel_, this.remoteRoot_, 'retained');
        const versions = [current ?? this.cacheVersion_(this.manifestModel_, this.remoteRoot_, 'current'),
            this.cacheRollback_, this.cacheLaunch_, this.cacheLaunchRollback_];
        for (const update of [this.pendingUpdate_, this.activeUpdate_]) if (update) {
            versions.push(this.cacheVersion_(update.model, update.remoteRoot ?? undefined, 'pending'));
        }
        await cache.protect(this.cacheOwner_, versions.filter((v): v is CacheVersion => v !== null));
    }

    /** Disk cache statistics, distinct from texture/audio residency budgets.
     * A scan reconciles interrupted writes/deletes; unknown files stay pinned. */
    async diskCacheReport(rescan = false): Promise<ContentCacheReport> {
        if (!isPlatformInitialized()) return { capability: 'unavailable', usedBytes: null, indexBytes: null,
            protectedBytes: null, reclaimableBytes: null, entries: [], versions: [] };
        // Keep in-memory protection even at quota: requiring an index write
        // before showing/cleaning a full disk would make it impossible to free.
        await this.protectCacheVersions_().catch(e => log.warn('asset', 'cache protection is active but its index could not be stored', e));
        return { ...await contentCacheFor(getPlatform()).report(rescan), owner: this.cacheOwner_ ?? undefined };
    }

    /** Preview by default; execution recomputes LRU against current protections. */
    async cleanDiskCache(budgetBytes: number, execute = false): Promise<CacheCleanupResult> {
        if (!Number.isSafeInteger(budgetBytes) || budgetBytes < 0) throw Error('cache budget must be a non-negative safe integer');
        await this.diskCacheReport();
        if (!isPlatformInitialized()) return { report: await this.diskCacheReport(), budgetBytes,
            candidates: [], releaseBytes: 0, remainingBytes: null, budgetMet: null, removed: [], failed: [] };
        const result = await contentCacheFor(getPlatform()).cleanup(budgetBytes, execute);
        result.report.owner = this.cacheOwner_ ?? undefined;
        return result;
    }

    /** Keep an older downloaded build, independently of the rolling rollback. */
    async retainDiskCacheVersion(revision: string, retain = true): Promise<ContentCacheReport> {
        await this.diskCacheReport();
        if (!isPlatformInitialized() || !this.cacheOwner_) throw Error('cache management unavailable');
        const cache = contentCacheFor(getPlatform());
        await cache.retainVersion(this.cacheOwner_, revision, retain);
        return { ...await cache.report(), owner: this.cacheOwner_ };
    }

    /** Download one changed asset's bytes from its delivery source (remote → CDN
     *  url against `root`, else the normal resolved path) and verify the content
     *  hash. Null on success, else the failure reason. Uses the PENDING manifest +
     *  root — phase 1 runs before the swap. */
    private async fetchAndVerify_(
        c: AssetChange, model: ManifestModel, root: string | undefined,
    ): Promise<{ url: string; failure?: AssetDownloadFailure['reason']; cache?: 'stored' | 'failed' | 'unsupported' }> {
        const group = model.group(c.group);
        const remote = group != null && normalizeBundleMode(group.bundleMode) === 'remote';
        // An export with hot update configured does not pack; a manifest that does
        // was built for a package that is not updated, and is refused rather than
        // fetched as files that do not exist.
        if (model.packOf(c.path)) return { url: c.path, failure: 'packed' };
        const path = this.manifestAssetUrl_(c.path, remote, root);
        const url = this.backend.resolveUrl(path);
        try {
            const buf = await this.backend.fetchBinary(url);
            if (c.contentHash && contentHashHex(new Uint8Array(buf)) !== c.contentHash) {
                return { url, failure: 'integrity' };
            }
            // Verified, content-addressed bytes go to the disk cache keyed by the
            // immutable CDN url, so the next launch reads them offline. A refused
            // write does not fail the update; it is reported as not cached.
            return { url, cache: remote ? await platformWriteCacheFile(url, buf) : undefined };
        } catch {
            return { url, failure: 'fetch' };
        }
    }

    /**
     * Remember a storage key under which {@link applyUpdate} persists the active
     * manifest, and immediately restore any manifest a prior run persisted there —
     * so a returning player boots straight onto the updated content, even offline.
     * Returns true if a persisted manifest was found and made active. Call at
     * boot, before the first scene loads.
     */
    restorePersistedUpdate(key: string): boolean {
        this.persistKey_ = key;
        // What this package shipped: an update stored against any other package is
        // older than what the player now has installed.
        this.shippedRevision_ = this.manifestModel_?.revision() ?? null;
        const raw = platformGetStorageItem(key);
        if (!raw) return false;
        try {
            const parsed = JSON.parse(raw) as { manifest: AddressableManifest; remoteRoot?: string | null; base?: string | null; cacheRollback?: CacheVersion | null };
            if (parsed.base === undefined || parsed.base !== this.shippedRevision_) {
                log.info('asset', `a stored update (${parsed.manifest?.revision ?? '?'}) was made for another package `
                    + `(${parsed.base ?? 'unknown'}, this one ships ${this.shippedRevision_ ?? 'none'}) — starting on what shipped`);
                platformRemoveStorageItem(key);
                return false;
            }
            if (parsed.remoteRoot) this.setRemoteRoot(parsed.remoteRoot);
            this.setManifest(parsed.manifest);
            if (parsed.cacheRollback && typeof parsed.cacheRollback.revision === 'string'
                && Array.isArray(parsed.cacheRollback.keys) && parsed.cacheRollback.keys.every(k => typeof k === 'string')) {
                this.cacheRollback_ = { ...parsed.cacheRollback, reason: 'rollback' };
                this.cacheLaunchRollback_ = { ...this.cacheRollback_, reason: 'retained' };
            }
            void this.protectCacheVersions_().catch(e => log.warn('asset', 'cache protection could not be persisted', e));
            return true;
        } catch (e) {
            log.warn('asset', 'failed to restore persisted manifest', e);
            return false;
        }
    }

    /** True once stored and read back; a store can drop a write without throwing.
     *  Null with no persistence key. */
    private persistActiveManifest_(json: AddressableManifest): boolean | null {
        if (!this.persistKey_) return null;
        const value = JSON.stringify({ manifest: json, remoteRoot: this.remoteRoot_ ?? null, base: this.shippedRevision_, cacheRollback: this.cacheRollback_ });
        try {
            platformSetStorageItem(this.persistKey_, value);
            return platformGetStorageItem(this.persistKey_) === value;
        } catch (e) {
            log.warn('asset', 'failed to persist updated manifest', e);
            return false;
        }
    }

    private persistedRevision_(): string | null {
        const raw = this.persistKey_ ? platformGetStorageItem(this.persistKey_) : null;
        if (!raw) return null;
        try {
            return (JSON.parse(raw) as { manifest?: AddressableManifest }).manifest?.revision ?? null;
        } catch {
            return null;
        }
    }

    /**
     * Load one asset into the displayable bundle maps. Returns the in-flight
     * promise for the four bundle-able types (texture / material / spine /
     * font), or null for any other type. Shared by `loadByLabel` and
     * `loadGroup` so both dispatch through one channel.
     */
    private bundleLoadTask_(
        path: string, type: string, bundle: AssetBundle,
    ): Promise<void> | null {
        const channel = GROUP_ASSET_CHANNELS[type];
        if (!channel?.displayable) return null;
        return channel.load(this, path, bundle);
    }

    /**
     * Like {@link bundleLoadTask_} but also warms the cache for non-displayable
     * types that have a typed loader (prefab, audio), so a whole group / sub-
     * package preloads. Raw types (json / text / binary) and unknowns return
     * null — they have no typed loader and are fetched lazily on demand.
     */
    private groupLoadTask_(
        path: string, type: string, bundle: AssetBundle,
    ): Promise<void> | null {
        const channel = GROUP_ASSET_CHANNELS[type];
        return channel ? channel.load(this, path, bundle) : null;
    }

    /**
     * Preload an explicit list of refs (`@uuid:` or paths) through the typed
     * loaders, warming every cache with bounded concurrency and progress.
     * This is the streaming prefetch primitive: point it at the next area's
     * assets while gameplay continues, and the eventual real loads hit warm
     * caches (or revive resident textures) instead of the network.
     *
     * Asset types come from the catalog / manifest when known, falling back
     * to file-extension matching against the registered loaders. Refs whose
     * type can't be determined — and refs that fail to load — are reported
     * in `failed`; preload itself never rejects.
     */
    async preload(
        refs: ReadonlyArray<string>,
        onProgress?: (loaded: number, total: number) => void,
        options?: { readonly maxConcurrent?: number },
    ): Promise<{ failed: MissingAsset[] }> {
        const failed: MissingAsset[] = [];
        const tasks: Array<() => Promise<void>> = [];

        for (const ref of refs) {
            const path = this.resolveLoadPath_(ref);
            const type = this.inferAssetType_(path);
            if (!type) {
                log.warn('asset', `preload: cannot determine asset type for ${ref}`);
                failed.push({ ref, reason: 'unresolved' });
                continue;
            }
            const load = this.typedLoadFor_(path, type);
            if (!load) {
                log.warn('asset', `preload: no loader for type '${type}' (${ref})`);
                failed.push({ ref, type, reason: 'unresolved' });
                continue;
            }
            tasks.push(() =>
                load().then(() => {}).catch(e => {
                    log.warn('asset', `preload: failed to load ${ref}`, e);
                    failed.push({
                        ref, type, reason: 'load-failed',
                        error: e instanceof Error ? e.message : String(e),
                    });
                }),
            );
        }

        let loadedCount = 0;
        const totalCount = tasks.length;
        onProgress?.(0, totalCount);
        const maxConcurrent = Math.max(1, options?.maxConcurrent ?? DEFAULT_PRELOAD_CONCURRENCY);
        await runWithConcurrency(tasks, maxConcurrent, () => {
            onProgress?.(++loadedCount, totalCount);
        });
        return { failed };
    }

    /** Asset type for a resolved path: catalog entry → manifest entry →
     *  extension match against the registered loaders → null. */
    private inferAssetType_(path: string): string | null {
        const catalogType = this.catalog.getEntry(path)?.type;
        if (catalogType) return catalogType;
        const manifestType = this.manifestModel_?.assetByPath(path)?.type;
        if (manifestType) return manifestType;
        const dot = path.lastIndexOf('.');
        if (dot < 0) return null;
        const ext = path.slice(dot).toLowerCase();
        for (const loader of this.loaders_.values()) {
            if (loader.extensions.includes(ext)) return loader.type;
        }
        return null;
    }

    /** Thunk that loads `path` through its type's canonical channel, or null
     *  when no loader handles the type. Textures/spine have dedicated entry
     *  points (refcount / two-file pairing); everything else is loadTyped. */
    private typedLoadFor_(path: string, type: string): (() => Promise<unknown>) | null {
        switch (type) {
            case 'texture': return () => this.loadTexture(path);
            case 'spine':   return () => this.loadSpine(path);
            case 'font':
            case 'bitmap-font': return () => this.loadFont(path);
            default:
                return this.loaders_.has(type) ? () => this.loadTyped(type, path) : null;
        }
    }

    // =========================================================================
    // Raw Data (escape hatch)
    // =========================================================================

    async fetchJson<T = unknown>(ref: string): Promise<T> {
        const path = this.resolveLoadPath_(ref);
        const url = this.backend.resolveUrl(this.catalog.getBuildPath(path));
        const text = await this.backend.fetchText(url);
        return JSON.parse(text) as T;
    }

    async fetchBinary(ref: string): Promise<ArrayBuffer> {
        const path = this.resolveLoadPath_(ref);
        const url = this.backend.resolveUrl(this.catalog.getBuildPath(path));
        return this.backend.fetchBinary(url);
    }

    async fetchText(ref: string): Promise<string> {
        const path = this.resolveLoadPath_(ref);
        const url = this.backend.resolveUrl(this.catalog.getBuildPath(path));
        return this.backend.fetchText(url);
    }

    // =========================================================================
    // Scene Asset Preloading
    // =========================================================================

    async preloadSceneAssets(
        sceneData: SceneData,
        onProgress?: (loaded: number, total: number) => void,
        options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean },
    ): Promise<SceneAssetResult> {
        return this.preloadSceneAssets_(sceneData, onProgress, options);
    }

    private async preloadSceneAssets_(
        sceneData: SceneData,
        onProgress?: (loaded: number, total: number) => void,
        options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean },
        recorder?: DependencyRecorder,
    ): Promise<SceneAssetResult> {
        const missing: MissingAsset[] = [];
        const discovered = discoverSceneAssets(sceneData, (ref) => this.resolveRef(ref));
        for (const p of discovered.meshTextures) this.meshTextures_.add(p);
        for (const p of discovered.meshMaterials) this.meshMaterials_.add(p);
        for (const ref of discovered.unresolved) {
            missing.push({ ref, reason: 'unresolved' });
        }
        if (discovered.unresolved.length > 0) {
            log.warn(
                'asset',
                `${discovered.unresolved.length} unresolved asset ref(s)`,
                discovered.unresolved,
            );
        }
        const texturePaths = discovered.byType.get('texture') ?? new Set<string>();
        const materialPaths = discovered.byType.get('material') ?? new Set<string>();
        const fontPaths = discovered.byType.get('font') ?? new Set<string>();
        // Anim clips load by their RAW serialized ref: components (SpriteAnimator.clip,
        // Animator states) look clips up by that ref, and loadAnimClip aliases it to
        // the resolved registration. Feeding the resolved path here (like the handle
        // types) would strip the alias and leave play-realm lookups keyless.
        const animClipPaths = discovered.rawByType.get('anim-clip') ?? new Set<string>();
        const audioPaths = discovered.byType.get('audio') ?? new Set<string>();
        const soundEventPaths = discovered.byType.get('sound-event') ?? new Set<string>();
        const tilemapPaths = discovered.byType.get('tilemap') ?? new Set<string>();
        const tilesetPaths = discovered.byType.get('tileset') ?? new Set<string>();
        const timelinePaths = discovered.byType.get('timeline') ?? new Set<string>();
        const fsmPaths = discovered.byType.get('statemachine') ?? new Set<string>();
        const btPaths = discovered.byType.get('behaviortree') ?? new Set<string>();
        const graphPaths = discovered.byType.get('scriptgraph') ?? new Set<string>();
        const animatorPaths = discovered.byType.get('animatorcontroller') ?? new Set<string>();
        const avatarPaths = discovered.byType.get('avatar') ?? new Set<string>();
        const meshPaths = discovered.byType.get('mesh') ?? new Set<string>();
        const environmentPaths = discovered.byType.get('environment') ?? new Set<string>();
        const probeVolumePaths = discovered.byType.get('probeVolume') ?? new Set<string>();
        const prefabPaths = discovered.byType.get('prefab') ?? new Set<string>();
        const spinePairs = discovered.spines;

        const textureHandles = new Map<string, number>();
        const materialHandles = new Map<string, number>();
        const fontHandles = new Map<string, number>();
        const meshHandles = new Map<string, number>();
        const environmentHandles = new Map<string, number>();
        const probeVolumeHandles = new Map<string, number>();
        const releaseCallbacks: ReleaseCallback[] = [];
        const scope = new AssetScope();
        const acquisitions: { type: string; path: string; lease: AssetLease }[] = [];

        let loadedCount = 0;

        const recordFailure = (path: string, label: string, err: unknown): void => {
            recorder?.failed(path, err);
            missing.push({
                ref: path,
                type: label,
                reason: 'load-failed',
                error: err instanceof Error ? err.message : String(err),
            });
        };

        // Build task thunks instead of starting the promises eagerly — the
        // worker pool below calls them one at a time per slot so a scene
        // with hundreds of assets doesn't saturate the network or tie up
        // image decoders all at once.
        const tasks: Array<() => Promise<void>> = [];
        /**
         * One task per path. The receipt is recorded only when the acquire
         * SUCCEEDED — a failed load owns nothing, so there is nothing for the
         * scene to give back and nothing to guess about at unload.
         */
        const timings: SceneAssetResult['timings'] = {};
        const timedLoad = <R>(label: string, load: () => Promise<R>): Promise<R> => {
            const began = preloadClock();
            return load().finally(() => {
                const ms = preloadClock() - began;
                const t = timings[label] ??= { count: 0, ms: 0, slowestMs: 0 };
                t.count++;
                t.ms += ms;
                t.slowestMs = Math.max(t.slowestMs, ms);
            });
        };
        const pushAcquire = <T>(
            paths: Set<string>,
            acquire: (p: string) => Promise<AssetLease<T>>,
            label: string,
            handles?: Map<string, number>,
        ): void => {
            for (const path of paths) {
                tasks.push(() =>
                    timedLoad(label, () => acquire(path)).then(lease => {
                        // A baked asset's era owns these acquisitions. An ordinary
                        // scene owns them through the returned scope instead.
                        if (recorder) recorder.own(path, lease, label);
                        else scope.add(lease);
                        acquisitions.push({ type: label, path, lease });
                        releaseCallbacks.push(() => lease.release());
                        if (handles) {
                            handles.set(path, (lease.value as { handle?: number } | null)?.handle ?? 0);
                        }
                    }).catch(e => {
                        log.warn('asset', `Failed to load ${label}: ${path}`, e);
                        handles?.set(path, 0);
                        recordFailure(path, label, e);
                    }),
                );
            }
        };

        // Textures load through their AUTHORED ref, not the resolved path the
        // handle map is keyed by: per-asset import settings (filter/wrap/sRGB and
        // the 9-slice border) are looked up by the spelling a component carries,
        // which is the resolver's documented contract. Resolution happens inside
        // loadTexture anyway, so the bytes fetched are identical either way —
        // feeding it the resolved path only strips the lookup of its key.
        pushAcquire(
            texturePaths,
            p => this.acquireTexture(discovered.rawFor.get(p) ?? p),
            'texture',
            textureHandles,
        );
        pushAcquire(materialPaths, p => this.acquireTypedLease_<MaterialResult>('material', p),
                    'material', materialHandles);
        pushAcquire(fontPaths, p => this.acquireTypedLease_<FontResult>('font', p), 'font', fontHandles);
        pushAcquire(meshPaths, p => this.acquireTypedLease_<{ handle: number }>('mesh', p),
                    'mesh', meshHandles);
        pushAcquire(environmentPaths, p => this.acquireTypedLease_<{ handle: number }>('environment', p),
                    'environment', environmentHandles);
        pushAcquire(probeVolumePaths, p => this.acquireTypedLease_<{ handle: number }>('probeVolume', p),
                    'probeVolume', probeVolumeHandles);
        // A pair, so not `pushAcquire` (which keys by one path); the receipt is
        // the scene's exactly as every other one is. The runtime scene loader
        // opts out: its second phase binds to entities that do not exist yet.
        if (!options?.skipSpine) {
            for (const pair of spinePairs) {
                tasks.push(() =>
                    this.acquireSpineLease_(pair.skeleton, pair.atlas).then((lease) => {
                        if (recorder) recorder.own(spinePairKey(pair.skeleton, pair.atlas), lease, 'spine');
                        else scope.add(lease);
                        acquisitions.push({ type: 'spine', path: spinePairKey(pair.skeleton, pair.atlas), lease });
                        releaseCallbacks.push(() => lease.release());
                    }).catch(e => {
                        log.warn('asset', `Failed to load spine: ${pair.skeleton}`, e);
                        recordFailure(pair.skeleton, 'spine', e);
                    }),
                );
            }
        }
        pushAcquire(animClipPaths, p => this.acquireTypedLease_('anim-clip', p), 'anim-clip');
        pushAcquire(tilemapPaths, p => this.acquireTypedLease_('tilemap', p), 'tilemap');
        pushAcquire(tilesetPaths, p => this.acquireTypedLease_('tileset', p), 'tileset');
        pushAcquire(timelinePaths, p => this.acquireTypedLease_('timeline', p), 'timeline');
        pushAcquire(audioPaths, p => this.acquireTypedLease_('audio', p), 'audio');
        pushAcquire(soundEventPaths, p => this.acquireTypedLease_('sound-event', p), 'sound-event');
        // FSM/BT loaders register the parsed definition into the shared AI store
        // under the asset path, so a StateMachineAgent/BehaviorTreeAgent whose
        // fsm/bt is that path resolves once the scene finishes preloading.
        pushAcquire(fsmPaths, p => this.acquireTypedLease_('statemachine', p), 'statemachine');
        pushAcquire(btPaths, p => this.acquireTypedLease_('behaviortree', p), 'behaviortree');
        pushAcquire(graphPaths, p => this.acquireTypedLease_('scriptgraph', p), 'scriptgraph');
        pushAcquire(animatorPaths, p => this.acquireTypedLease_('animatorcontroller', p), 'animatorcontroller');
        pushAcquire(avatarPaths, p => this.acquireTypedLease_('avatar', p), 'avatar');
        pushAcquire(prefabPaths, p => this.acquireTypedLease_('prefab', p), 'prefab');

        const totalCount = tasks.length;
        onProgress?.(0, totalCount);

        const maxConcurrent = Math.max(1, options?.maxConcurrent ?? DEFAULT_PRELOAD_CONCURRENCY);
        const began = preloadClock();
        await runWithConcurrency(tasks, maxConcurrent, () => {
            onProgress?.(++loadedCount, totalCount);
        });
        const wallMs = preloadClock() - began;
        if (totalCount > 0) {
            const parts = Object.entries(timings).sort((a, b) => b[1].ms - a[1].ms)
                .map(([k, t]) => `${k} ${t.count} (${Math.round(t.ms)}ms, slowest ${Math.round(t.slowestMs)}ms)`);
            log.info('asset', `preloaded ${totalCount} asset(s) in ${Math.round(wallMs)}ms, ${maxConcurrent} at a time: ${parts.join(', ')}`);
        }

        // `unresolved` refs warn above; a load that THREW only reached `missing`,
        // which callers may ignore — so a scene drew with no textures and no
        // complaint, indistinguishable from a scene that has none.
        warnFailedLoads(missing.filter((m) => m.reason === 'load-failed'));

        return { textureHandles, materialHandles, fontHandles, meshHandles, environmentHandles,
                 probeVolumeHandles, releaseCallbacks, scope, acquisitions, missing, timings, wallMs };
    }

    resolveSceneAssetPaths(sceneData: SceneData, result: SceneAssetResult): void {
        const { textureHandles, materialHandles, fontHandles, meshHandles,
                environmentHandles, probeVolumeHandles } = result;

        for (const entity of sceneData.entities) {
            // Prefab-instance entries carry no inline components (a prefab ref +
            // overrides); their handles bind when the prefab expands, not here.
            if (!Array.isArray(entity.components)) continue;
            for (const comp of entity.components) {
                // Single source: the component def's declared asset fields.
                // Handle write-back always keys off assetFields (the direct
                // texture/material/font members), even for components whose
                // discovery is driven by a discoverAssets callback instead.
                const fields = getComponentAssetFieldDescriptors(comp.type);
                for (const { field, type } of fields) {
                    const ref = comp.data[field];
                    if (typeof ref !== 'string' || !ref) continue;

                    // UUID refs resolve to their current path; plain paths
                    // pass through. Unknown UUID → null, handle will be 0
                    // (caller's getter returns 0 when the key is missing).
                    const path = this.resolveRef(ref);
                    if (path == null) {
                        comp.data[field] = getComponentDefaults(comp.type)?.[field] ?? 0;
                        continue;
                    }

                    switch (type) {
                        case 'texture': {
                            const handle = textureHandles.get(path) ?? 0;
                            comp.data[field] = handle;
                            this.recordHandlePath_('texture', handle, path);
                            // Ref spelling first (per-frame keys); the resolved
                            // path for packed frames is the shared page.
                            const atlasInfo = this.catalog.getAtlasFrame(ref) ?? this.catalog.getAtlasFrame(path);
                            if (atlasInfo) {
                                // COMPOSE with any authored sub-region rather than
                                // stomping it: the authored uv nests inside the frame.
                                const aOff = comp.data['uvOffset'] as { x: number; y: number } | undefined;
                                const aSc = comp.data['uvScale'] as { x: number; y: number } | undefined;
                                const ox = aOff?.x ?? 0, oy = aOff?.y ?? 0;
                                const sx = aSc?.x ?? 1, sy = aSc?.y ?? 1;
                                comp.data['uvOffset'] = {
                                    x: atlasInfo.uvOffset[0] + ox * atlasInfo.uvScale[0],
                                    y: atlasInfo.uvOffset[1] + oy * atlasInfo.uvScale[1],
                                };
                                comp.data['uvScale'] = {
                                    x: sx * atlasInfo.uvScale[0],
                                    y: sy * atlasInfo.uvScale[1],
                                };
                                if (atlasInfo.trim) {
                                    comp.data['_trimOffsetX'] = atlasInfo.trim.offsetX;
                                    comp.data['_trimOffsetY'] = atlasInfo.trim.offsetY;
                                    comp.data['_trimSourceW'] = atlasInfo.trim.sourceW;
                                    comp.data['_trimSourceH'] = atlasInfo.trim.sourceH;
                                }
                            }
                            break;
                        }
                        case 'material': {
                            const handle = materialHandles.get(path) ?? 0;
                            comp.data[field] = handle;
                            this.recordHandlePath_('material', handle, path);
                            break;
                        }
                        case 'font': {
                            const handle = fontHandles.get(path) ?? 0;
                            comp.data[field] = handle;
                            this.recordHandlePath_('font', handle, path);
                            break;
                        }
                        case 'mesh': {
                            comp.data[field] = meshHandles.get(path) ?? 0;
                            break;
                        }
                        case 'environment': {
                            comp.data[field] = environmentHandles.get(path) ?? 0;
                            break;
                        }
                        case 'probeVolume': {
                            comp.data[field] = probeVolumeHandles.get(path) ?? 0;
                            break;
                        }
                    }
                }
            }
        }
    }

    /** Record scene users only after source IDs have been mapped to live World entities.
     * Resolution is preparation; source IDs cannot be removed by World.onDespawn. */
    trackSceneAssetReferences(scene: SceneData, entities: ReadonlyMap<number, number>): void {
        const counter = this.refCounter_;
        if (!counter) return;
        for (const source of scene.entities) {
            const entity = entities.get(source.id);
            if (entity === undefined || !Array.isArray(source.components)) continue;
            for (const comp of source.components) {
                for (const { field, type } of getComponentAssetFieldDescriptors(comp.type)) {
                    const handle = comp.data[field];
                    if (typeof handle !== 'number' || !handle) continue;
                    const path = this.pathForHandle(type, handle);
                    if (path === null) continue;
                    if (type === 'texture') counter.addTextureRef(path, entity);
                    else if (type === 'material') counter.addMaterialRef(path, entity);
                    else if (type === 'font') counter.addFontRef(path, entity);
                }
            }
        }
    }

    // =========================================================================
    // Acquire — the same loads, but handing back an ownership receipt
    // =========================================================================

    /**
     * Load a texture and get the receipt for THIS acquisition.
     *
     * The difference from {@link loadTexture} is who can be released correctly
     * afterwards: a path names an asset, a lease names the instance this caller
     * was handed. After `invalidate()` those are no longer the same thing.
     */
    async acquireTexture(ref: string): Promise<AssetLease<TextureResult>> {
        const { result, lease } = await this.acquireTextureVariant_(ref, true);
        return this.textureLease_(lease, result);
    }

    /** {@link acquireTexture} for everything that goes through a typed loader. */
    async acquireTyped<T>(type: string, ref: string): Promise<AssetLease<T>> {
        try { return await this.acquireTypedLease_<T>(type, ref); }
        catch (error) { throw preparationFailureReason(error); }
    }

    private async acquireTypedLease_<T>(type: string, ref: string): Promise<AssetLease<T>> {
        const epoch = this.resetEpoch_;
        this.assertLoading_(epoch);
        const slot = await this.acquireSlot_<T>(type, ref);
        try { this.assertLoading_(epoch); }
        catch (error) { slot?.release(); throw error; }
        if (slot) return slot;
        const { value, lease } = await this.acquireTyped_<T>(type, ref);
        return this.typedLease_(type, lease, value);
    }

    /**
     * A claim on the slot for a registry-backed asset, or null when this type is
     * not one. The ref the caller spelled is an ALIAS of the slot: a component
     * carries that spelling and looks the asset up by it, while the load path is
     * whatever this realm resolved it to.
     */
    private async acquireSlot_<T>(type: string, ref: string): Promise<AssetLease<T> | null> {
        const kind = this.registryKind_<T>(type);
        if (!kind) return null;
        // Keyed by identity, never by the locator: a content-addressed url is
        // revision-specific, so a slot keyed by one is a slot PER REVISION and
        // an update publishes into a new one while every holder reads the old.
        const identity = this.assetIdentity_(ref);
        // Answering to the ref as the caller spelled it too: a component looks
        // the asset up by the spelling a scene serialized.
        const names = ref === identity ? [identity] : [identity, ref];
        return this.registrySlots_.acquire(kind, type, identity, names);
    }

    /**
     * The owner-facing receipt for one ledger acquisition.
     *
     * `retain` goes through the ledger rather than through this class's load
     * path: an owner splitting what it holds joins the era it already has, which
     * after an invalidate is not the era a path resolves to.
     */
    private textureLease_(
        lease: AssetRefLease<number>, value: TextureResult,
    ): AssetLease<TextureResult> {
        return {
            key: lease.key, generation: lease.generation, value,
            release: () => this.releaseTextureLease(lease),
            retain: () => {
                const child = this.textureRefs_.retain(lease);
                return child ? this.textureLease_(child, value) : null;
            },
        };
    }

    /**
     * A receipt for a texture this engine COMPOSED — no path, no generation, no
     * cache entry to join. Its only identity is the handle, so the last holder
     * destroys it rather than handing it back to a pool that could revive it.
     */
    private ownedTextureLease_(value: TextureResult): AssetLease<TextureResult> {
        return ownedAssetLease(`composed:${value.handle}`, value.handle, value, texture => {
            requireResourceManager().releaseTexture(texture.handle);
            evictTextureDimensions(texture.handle);
        });
    }

    /** {@link textureLease_} for everything that goes through a typed loader. */
    private typedLease_<T>(
        type: string, lease: AssetRefLease<PreparedLoad<unknown>>, value: T,
    ): AssetLease<T> {
        return {
            key: lease.key, generation: lease.generation, value,
            failedDependencies: lease.value.failedDependencies,
            release: () => this.releaseTypedLease(type, lease),
            retain: () => {
                const child = this.genericRefs_.retain(lease);
                return child ? this.typedLease_(type, child, value) : null;
            },
        };
    }

    // =========================================================================
    // Release
    // =========================================================================

    releaseTexture(ref: string): void {
        const path = this.resolveLoadPath_(ref);
        for (const flip of [true, false]) {
            const key = this.textureCacheKey_(path, flip);
            const dropped = this.textureRefs_.releaseOldest(key);
            if (!dropped) continue;
            if (dropped.ambiguous) warnAmbiguousRelease_(key);
            if (dropped.exhausted) this.disposeTexture_(key, dropped.value);
        }
    }

    /**
     * @internal Give back one texture acquisition by its receipt — exact even
     * when `invalidate()` left two generations of the same path live. Callers
     * hold an {@link AssetLease} and use its `release()`.
     */
    releaseTextureLease(lease: AssetRefLease<number>): void {
        const dropped = this.textureRefs_.release(lease);
        if (dropped?.exhausted) this.disposeTexture_(lease.key, dropped.value);
    }

    /** The last SDK reference to a texture handle is gone: let the C++ pool decide. */
    private disposeTexture_(key: string, handle: number): void {
        // The pool decides what that means — free immediately (no budget), or
        // retain as an evictable cache entry that the next load revives by key.
        evictTextureDimensions(handle);
        this.handleToPath_.delete(`texture:${handle}`);
        // Only when it is still the cached value: a superseded handle left the
        // cache when its generation ended, and the entry there now belongs to a
        // generation with holders of its own.
        if (this.textureCache_.get(key)?.handle === handle) this.textureCache_.delete(key);
        requireResourceManager().releaseTexture(handle);
    }

    releaseFont(ref: string): void {
        this.releaseTyped('font', ref);
    }

    releaseAudio(ref: string): void {
        this.releaseTyped('audio', ref);
    }

    releaseAnimClip(ref: string): void {
        this.releaseTyped('anim-clip', ref);
    }

    releaseTimeline(ref: string): void {
        this.releaseTyped('timeline', ref);
    }

    releaseTilemap(ref: string): void {
        this.releaseTyped('tilemap', ref);
    }

    releasePrefab(ref: string): void {
        this.releaseTyped('prefab', ref);
    }

    /**
     * Release a material obtained via {@link loadMaterial}, addressed by its
     * handle (materials are tracked by handle, not ref, in the scene manager).
     * Routes through the shared refcount + cache path so a material shared by
     * two scenes survives until its last owner releases it, and the cache never
     * hands the next load a destroyed handle. Destroying the handle directly
     * (bypassing this) would strand a dead handle in the material cache.
     */
    releaseMaterial(handle: number): void {
        const path = this.pathForHandle('material', handle);
        if (path !== null) this.releaseTyped('material', path);
    }

    /**
     * Give back one reference to every asset in `byType` — what a scene, a
     * document or a group acquired, in one call.
     *
     * Materials (handle-keyed) and skeletons (SpineManager's) are skipped.
     * @beta Pre-1.0: the type vocabulary follows the loader registry.
     */
    releaseAssets(byType: ReadonlyMap<string, ReadonlySet<string>>): void {
        for (const [type, paths] of byType) {
            if (type === 'material' || type === 'spine') continue;
            for (const path of paths) {
                if (type === 'texture') this.releaseTexture(path);
                else this.releaseTyped(type, path);
            }
        }
    }

    /**
     * @internal Release one reference to a typed asset by path — the door the
     * group channel table uses. Game code calls the named release* methods.
     */
    releaseTyped(type: string, ref: string): void {
        const path = type === 'spine'
            ? spinePairKey(this.resolveLoadPath_(ref), this.spineAtlasOf_(this.resolveLoadPath_(ref)))
            : this.resolveLoadPath_(ref);
        const kind = this.registryKind_(type);
        if (kind) {
            this.registrySlots_.releaseByName(type, this.assetIdentity_(ref));
            return;
        }
        // NOT gated on a live cache entry: a generation superseded by
        // invalidate() is out of the cache while its holders still owe a
        // release, and returning here left their asset unreachable.
        const key = `${type}:${path}`;
        const dropped = this.genericRefs_.releaseOldest(key);
        if (!dropped) return;
        if (dropped.ambiguous) warnAmbiguousRelease_(key);
        if (dropped.exhausted) this.disposeGeneric_(type, path, dropped.value);
    }

    /**
     * @internal The typed twin of {@link releaseTextureLease}; callers use the
     * lease's own `release()`.
     */
    releaseTypedLease(type: string, lease: AssetRefLease<PreparedLoad<unknown>>): void {
        const dropped = this.genericRefs_.release(lease);
        if (!dropped?.exhausted) return;
        const path = lease.key.slice(type.length + 1);
        this.disposeGeneric_(type, path, dropped.value);
    }

    /** The last reference to a typed asset is gone: hand it to its loader. */
    private disposeGeneric_(type: string, path: string, era: PreparedLoad<unknown>): void {
        const cache = this.genericCache_.get(type);
        if (cache && cache.get(path) === era) cache.delete(path);
        this.retire_(type, era);
    }

    /** End one handle-bound era: its loader destroys what it made, then what its
     *  preparation acquired goes back — in that order, since the value is what
     *  is still using it. */
    private retire_(type: string, era: PreparedLoad<unknown>): void {
        if (this.retired_.has(era)) return;
        this.retired_.add(era);
        const handle = (era.value as { handle?: unknown } | null)?.handle;
        if (typeof handle === 'number') this.handleToPath_.delete(`${type}:${handle}`);
        disposeAll([
            () => this.loaders_.get(type)?.unload?.(era.value),
            () => era.dependencies.releaseAll(),
        ], dispose => dispose());
    }

    /**
     * Drop every internal cache entry for `ref` so the next `loadTexture` /
     * `loadMaterial` / ... fetches fresh bytes. Call this when the source
     * file changed on disk (hot reload).
     *
     * Any GPU handle that was already handed out stays valid and keeps
     * rendering — that's the caller's concern to release. The next load
     * produces a brand-new handle from the updated bytes; the old handle
     * is evicted from the cache but not freed, so currently-rendering
     * entities don't flicker.
     *
     * If any cache held `ref`, invokes every listener registered via
     * `onInvalidate` with the original ref. Listeners that throw are
     * caught and logged — one bad subscriber can't prevent other
     * subscribers from observing the invalidation.
     *
     * What was BUILT from `ref` ends too. The plan is read BEFORE anything is
     * dropped, and walked deepest-first with each group awaiting the one before
     * it: a parent re-prepared too early acquires the era it already had.
     *
     * Returns true if any cache held `ref` itself.
     */
    invalidate(ref: string): boolean {
        const plan = this.rebuildPlan_(ref);
        // A failed preparation has no live era, but its canonical cooldown
        // rejection still records why it failed. Clear it before rebuilding
        // holders reached by the restored source, rather than reusing failure.
        const source = this.assetIdentity_(ref);
        for (const cache of this.genericCache_.values()) {
            for (const [key, error] of cache.failures()) {
                if (error instanceof PreparationFailure
                    && error.sources.some(path => this.assetIdentity_(path) === source)) cache.invalidate(key);
            }
        }
        const { hit, rebuilt } = this.invalidateSource_(ref);
        if (plan.length > 0) this.track_(rebuilt.then(() => this.rebuildAssetGraph_(plan)));
        return hit;
    }

    /**
     * Resolves when every propagation started so far has landed.
     *
     * The ASSET graph only. What reads it — a component bound to a handle — is
     * the second barrier, and it moves on a frame rather than here: see the
     * live-binding coordinator's `settled`.
     *
     * @internal
     */
    async assetGraphSettled(): Promise<void> {
        // A rebuild can start another (a group awaits the one before it), so
        // draining once is not the same as being settled.
        while (this.settling_.size > 0) {
            const inFlight = [...this.settling_];
            await Promise.all(inFlight);
            for (const work of inFlight) this.settling_.delete(work);
        }
    }

    /** What a change to `ref` reaches. Not filtered by path: an asset that
     *  happens to live at the changed file can still be what the chain reaches
     *  LAST, and dropping it there is the same erasure one level up. */
    private rebuildPlan_(ref: string): AssetIdentity[][] {
        return rebuildPlan(this.resolveLoadPath_(ref), {
            ofSource: (path) => this.dependentsOfSource(path),
            ofAsset: (asset) => this.dependentsOfAsset(asset),
        });
    }

    /** Count one propagation as in flight until it lands. It answers to nobody
     *  in the ordinary case, so a failure is reported here rather than thrown at
     *  whoever happens to be waiting. */
    private track_(work: Promise<void>): void {
        const settled = work.catch((e: unknown) => {
            log.warn('asset', 'propagating a change failed; what it reached keeps what it has', e);
        });
        this.settling_.add(settled);
        void settled.finally(() => this.settling_.delete(settled));
    }

    /** Each group only once everything it was built from has landed. */
    private async rebuildAssetGraph_(plan: AssetIdentity[][]): Promise<void> {
        for (const group of plan) {
            await Promise.all(group.map((vertex) => this.invalidateAsset_(vertex).rebuilt));
        }
    }

    /**
     * End every era at one PATH: a file changed, and whatever it names changed
     * with it. What `invalidate(ref)` is, and what a hot update's changed key is.
     */
    private invalidateSource_(ref: string): { hit: boolean; rebuilt: Promise<void> } {
        let hit = false;
        const work: Array<Promise<void>> = [];
        for (const type of this.loaders_.keys()) {
            const ended = this.invalidateAsset_({ type, path: ref });
            hit = ended.hit || hit;
            work.push(ended.rebuilt);
        }
        return { hit, rebuilt: Promise.all(work).then(() => undefined) };
    }

    /**
     * End ONE asset's era — its type all the way down. A path can name a texture
     * and a material, and what one of them acquired changing is not a change to
     * the other; a plan that knows the difference and then ends both has thrown
     * away what it knew.
     */
    private invalidateAsset_(asset: AssetIdentity): { hit: boolean; rebuilt: Promise<void> } {
        const { type } = asset;
        const path = this.resolveLoadPath_(asset.path);
        // Held by a cache or by a loader's own residency: what a listener is
        // told about. A slot swaps its era instead, and reports nothing.
        let dropped = false;
        let oldValue: unknown;

        if (type === 'texture') {
            // The handle bound to this path, captured BEFORE the caches drop it,
            // so a rebind listener can swap it in live components.
            oldValue = this.textureCache_.get(this.textureCacheKey_(path, true))?.handle ?? 0;
            const rm = getResourceManager();
            // Both flip variants: the cache key carries the flag. The C++ pool's
            // residency identity is severed too — an evictable entry under this
            // key is freed and can never be revived with stale bytes.
            for (const flip of [true, false]) {
                const key = this.textureCacheKey_(path, flip);
                if (this.textureCache_.invalidate(key)) dropped = true;
                // The ledger is NOT dropped: holders of the outgoing generation
                // still owe a release, and forgetting them strands their texture
                // with nobody able to free it. The era still ends here.
                this.textureRefs_.supersede(key);
                if (typeof rm?.invalidateTexturePath === 'function' && rm.invalidateTexturePath(key)) {
                    dropped = true;
                }
            }
            // Skeletal atlas pages register the image path without a flip suffix.
            // End their residency too, even when no SDK texture cache holds them.
            if (typeof rm?.invalidateTexturePath === 'function' && rm.invalidateTexturePath(path)) {
                dropped = true;
            }
        } else {
            const cache = this.genericCache_.get(type);
            if (cache) {
                oldValue = cache.get(path)?.value;
                if (cache.invalidate(path)) dropped = true;
            }
            // The ledger stays, for the same reason as a texture's.
            this.genericRefs_.supersede(`${type}:${path}`);
        }

        // A registry-backed asset has no cache entry to drop and no handle to
        // swap: the update IS a new era published under the same names.
        const slot = this.republishSlot_(type, asset.path);

        // Loader-owned residency (e.g. the AudioAPI warm cache) can outlive the
        // Assets-level entry — sever it so a warm-cache revive can never serve
        // stale bytes after a hot reload.
        if (this.loaders_.get(type)?.invalidate?.(path)) dropped = true;

        // The reverse handle→path records of this kind are stale now: a reload
        // mints new handles, and the old ones must stop naming the asset.
        for (const [key, held] of this.handleToPath_) {
            if (held === path && key.startsWith(`${type}:`)) this.handleToPath_.delete(key);
        }

        if (dropped) {
            this.fireInvalidate_({ ref: asset.path, type: type as AssetFieldType, oldValue });
        }
        return { hit: dropped || slot.found, rebuilt: slot.rebuilt };
    }

    /**
     * Prepare a new era for the slot (type, ref) names, and publish it
     * atomically. By IDENTITY: the slot is keyed by what the asset is, and this
     * preparation resolves where the current revision serves it.
     */
    private republishSlot_(type: string, ref: string): { found: boolean; rebuilt: Promise<void> } {
        const kind = this.registryKind_(type);
        const identity = this.assetIdentity_(ref);
        if (!kind || !this.registrySlots_.has(type, identity)) {
            return { found: false, rebuilt: Promise.resolve() };
        }
        const rebuilt = this.registrySlots_.republish(kind, type, identity).then(
            () => undefined,
            (e: unknown) => {
                log.warn('asset', `hot update: re-publishing "${ref}" failed; holders keep the era they have`, e);
            },
        );
        return { found: true, rebuilt };
    }

    /** {@link republishSlot_} for every type this ref names one of — a changed
     *  FILE, which does not say what kind of asset lives at it. */
    private republishSlots_(ref: string): { found: boolean; rebuilt: Promise<void> } {
        const work: Array<Promise<void>> = [];
        let found = false;
        for (const type of this.loaders_.keys()) {
            const slot = this.republishSlot_(type, ref);
            found = slot.found || found;
            work.push(slot.rebuilt);
        }
        return { found, rebuilt: Promise.all(work).then(() => undefined) };
    }

    /** Fire every onInvalidate listener with one generation's ending. Isolates
     *  throws. Shared by {@link invalidate} and {@link applyUpdate}. */
    private fireInvalidate_(event: AssetInvalidation): void {
        for (const listener of this.invalidateListeners_) {
            try {
                listener(event);
            } catch (e) {
                log.warn('asset', 'onInvalidate listener threw', e);
            }
        }
    }

    /**
     * Subscribe to cache invalidations. The listener fires once per
     * successful `invalidate(ref)` call with the original ref (not the
     * resolved path). Returns an unsubscribe function.
     *
     * Typical use: a scene-graph controller or renderer that holds cached
     * handles for assets — subscribe to re-bind / re-load on hot reload
     * so stale GPU handles stop being rendered.
     */
    onInvalidate(listener: InvalidateListener): () => void {
        this.invalidateListeners_.add(listener);
        return () => {
            this.invalidateListeners_.delete(listener);
        };
    }

    /**
     * @internal Live entry counts for the resource census.
     *
     * Cache sizes are not expected to return to baseline — that is what a cache
     * is for. `refCounts` and `handlePaths` are: every load handing one out has a
     * release taking it back. `pendingLoads` and `propagations` should be zero at rest.
     */
    sizes(): {
        textureCached: number;
        pendingLoads: number;
        /** Rebuilds of dependents still running after an invalidation. */
        propagations: number;
        refCounts: number;
        refRows: number;
        genericCaches: number;
        genericCached: number;
        handlePaths: number;
        invalidateListeners: number;
        registrySlots: number;
        trackedRefRows: number;
    } {
        const tex = this.textureCache_.sizes();
        let genericCached = 0;
        let pending = tex.pending;
        for (const cache of this.genericCache_.values()) {
            const s = cache.sizes();
            genericCached += s.cached;
            pending += s.pending;
        }
        return {
            textureCached: tex.cached,
            pendingLoads: pending,
            propagations: this.settling_.size,
            refCounts: this.textureRefs_.size + this.genericRefs_.size,
            refRows: this.textureRefs_.rows + this.genericRefs_.rows,
            genericCaches: this.genericCache_.size,
            genericCached,
            handlePaths: this.handleToPath_.size,
            invalidateListeners: this.invalidateListeners_.size,
            registrySlots: this.registrySlots_.size,
            trackedRefRows: this.refCounter_?.getTotalRefRows() ?? 0,
        };
    }

    /**
     * What is explicitly owned by the whole asset realm.
     *
     * Its life is this instance's. Entity bindings use scene or entity scopes,
     * including runtime entities with no scene, so their resources can end sooner.
     *
     * @internal
     */
    get appScope(): AssetScope {
        return this.appScope_;
    }

    /**
     * What entities own for themselves — runtime entities with no scene and
     * persistent entities that outlived theirs. Ends at the entity's despawn.
     *
     * @internal
     */
    get entityScopes(): EntityAssetScopes {
        return this.entityScopes_;
    }

    /** @internal A standalone bake uses the same acquisition transaction as a graph recipe. */
    async preparePrefab(ref: string, overrides: readonly PrefabOverride[] = []): Promise<PreparedPrefab> {
        const epoch = this.resetEpoch_;
        try {
            const era = await this.prepared_(ctx => this.bakePrefab_(this.resolveLoadPath_(ref),
                ctx as LoadContext & { recorder: DependencyRecorder }, overrides));
            if (epoch !== this.resetEpoch_) {
                era.dependencies.releaseAll();
                throw new Error(`Assets were released while "${ref}" was preparing; it has no owner. Load it again.`);
            }
            return { ...era, ref, release: () => era.dependencies.releaseAll() };
        } catch (error) { throw preparationFailureReason(error); }
    }

    releaseAll(): void {
        if (this.releasing_) return;
        this.releasing_ = true;
        // Pending loads lose ownership even if a user-provided unload throws.
        this.resetEpoch_++;
        this.abandoned_.clear();
        try {
            disposeAll([
                () => {
                    const pending = [...this.preparations_];
                    this.preparations_.clear();
                    disposeAll(pending, recorder => recorder.rollback());
                },
                // Normal receipts first, then every remaining generation.
                () => this.appScope_.releaseAll(),
                () => this.registrySlots_.releaseAll(),
                () => {
                    const handles = new Set<number>();
                    for (const info of this.textureCache_.values()) handles.add(info.handle);
                    this.textureCache_.clearAll();
                    for (const { value } of this.textureRefs_.drain()) handles.add(value);
                    if (handles.size === 0) return;
                    const rm = requireResourceManager();
                    disposeAll([...handles], handle => {
                        evictTextureDimensions(handle);
                        rm.releaseTexture(handle);
                    });
                },
                () => {
                    for (const cache of this.genericCache_.values()) cache.clearAll();
                    this.genericCache_.clear();
                    const generations = this.genericRefs_.drain();
                    disposeAll(generations, ({ key, value }) => this.retire_(key.slice(0, key.indexOf(':')), value));
                },
            ], dispose => dispose());
        } finally {
            const meshLoader = this.getLoader<MeshResult>('mesh');
            if (meshLoader instanceof MeshAssetLoader) for (const handle of this.builtMeshes_.keys()) meshLoader.releaseData(handle);
            this.builtMeshes_.clear();
            this.handleToPath_.clear();
            this.releasing_ = false;
        }
    }

    // =========================================================================
    // Spine Controller
    // =========================================================================

    getTextureLoader(): TextureLoader {
        return this.textureLoader_;
    }

    /**
     * What the textures this realm loaded became on the GPU, and which compressed
     * formats the device samples at all. @experimental
     *
     * The upload half; what the BUILD shipped is the cook's own record. A realm
     * that plays source images still answers `deviceFormats` — the capability a
     * cooked payload would meet here.
     */
    textureFormatReport(): TextureFormatReport {
        return this.textureLoader_.formatReport();
    }

    setAssetRefResolver(resolver: AssetRefResolver): void {
        this.assetRefResolver_ = resolver;
    }

    private readonly assetProblems_ = new Map<string, readonly string[]>();
    private assetProblemListener_: ((asset: string, problems: readonly string[]) => void) | null = null;

    /**
     * What is wrong with an asset that loaded: the parts of it that were left out, each said once. Empty when it is whole (or was never
     * loaded). A material whose texture would not load, or whose value has a shape nothing reads, is here and not in a failed load.
     * @experimental
     */
    getAssetProblems(asset: string): readonly string[] {
        return this.assetProblems_.get(asset) ?? [];
    }

    /** Hear every change to an asset's problems (the editor's diagnostics). One listener; null removes it. @experimental */
    setAssetProblemListener(listener: ((asset: string, problems: readonly string[]) => void) | null): void {
        this.assetProblemListener_ = listener;
    }

    getAssetRefResolver(): AssetRefResolver | null {
        return this.assetRefResolver_;
    }

    /**
     * Attach optional usage monitoring. Scene publication records runtime
     * entity IDs through trackSceneAssetReferences; the shared World binding
     * removes them on despawn and follows the active asset resource. Plugin
     * and runtime factories install it; manually created Assets default to
     * no tracking until a counter is attached.
     */
    setRefCounter(counter: AssetRefCounter): void {
        this.refCounter_ = counter;
    }

    getRefCounter(): AssetRefCounter | null {
        return this.refCounter_;
    }

    /**
     * Resolve any serialized asset ref (UUID or plain path) to a concrete
     * path. Returns null when a UUID ref can't be matched to a known
     * asset. Without a registry/resolver configured, refs pass through
     * unchanged — legacy path-only scenes keep working.
     */
    resolveRef(ref: string): string | null {
        if (isBuiltinAssetRef(ref)) return ref;
        if (this.assetRefResolver_) return this.assetRefResolver_(ref);
        return ref;
    }

    /**
     * The load path a ref resolves to — resolver plus addressable Catalog,
     * the same two steps every typed load performs. This is the key a loader
     * registers a data asset under, so runtime stores keyed by registration
     * path (FSM/BT/timeline/tilemap via `resolveAssetKey`) must look up with
     * THIS: `resolveRef` alone diverges once the Catalog carries mappings.
     */
    resolveLoadPath(ref: string): string {
        return this.resolveLoadPath_(ref);
    }

    /**
     * Canonical path-resolution for all typed load methods.
     * Runs the AssetRefResolver first so `@uuid:...` refs map to their real
     * project path, then applies the addressable Catalog for any further
     * indirection. If the resolver returns null (unknown UUID), we fall back
     * to the Catalog on the original ref — the loader will 404 with a clear
     * error rather than silently succeeding on a nonsense URL.
     *
     * Historically each load method called `this.catalog.resolve(ref)`
     * directly, which completely bypassed the AssetRefResolver. Editors that
     * serialized asset refs as `@uuid:...` could never resolve them at load
     * time — textures silently rendered white. This helper closes that gap.
     */
    private resolveLoadPath_(ref: string): string {
        // Built-in geometry names code, not a file. Every realm's resolver turns a
        // non-URL ref into one (the play realm prefixes an origin), so a ref that
        // has nothing to resolve has to say so before resolution, not after.
        if (isBuiltinAssetRef(ref)) return ref;
        // A `remote`-group asset (per the active addressable manifest) resolves to
        // its CDN url — so a scene @uuid ref to a remote asset loads from, and
        // hot-updates with, the CDN, not just loadGroup'd DLC assets. Gated on a
        // remote root being set, so same-origin realms (editor Play, a build with
        // no CDN) keep their normal resolver + base-prefixing untouched. It is
        // the one step that carries a REVISION, which is why identity stops
        // short of it.
        const remote = this.remoteAssetPath_(ref);
        if (remote != null) return remote;
        // Deliberately NOT assetIdentity_: for a remote-group asset that answers
        // with the ADDRESS, and the package carries the STAGED name. Where the
        // bytes are is the realm's question, so its resolver gets it.
        const resolved = this.assetRefResolver_?.(ref) ?? ref;
        return this.catalog.resolve(resolved);
    }

    /** CDN url of `ref` when it names a `remote`-group asset AND a remote root is
     *  set; null otherwise (caller falls back to the normal resolver). */
    private remoteAssetPath_(ref: string): string | null {
        if (!this.remoteRoot_) return null;
        const model = this.manifestModel_;
        if (!model) return null;
        const key = ref.startsWith(UUID_REF_PREFIX)
            ? ref.slice(UUID_REF_PREFIX.length).toLowerCase()
            : ref;
        const path = model.remoteAssetPath(key) ?? model.remoteAssetPath(ref);
        return path != null ? this.remoteUrlFor_(path) : null;
    }

    /**
     * What a ref MEANS in this realm, with no revision in it.
     *
     * Distinct from {@link resolveLoadPath_}, which goes on to where that asset
     * is served from NOW. Identity is what a slot is keyed by and what two
     * spellings agree on; a locator is what one preparation reads.
     */
    private assetIdentity_(ref: string): string {
        if (isBuiltinMeshRef(ref)) return ref;
        // A manifest names one asset three ways — record key, address, build
        // path — and only it knows they are the same asset. Folding them here is
        // what keeps a uuid ref and a path ref on ONE slot.
        const named = this.manifestModel_?.remoteAssetIdentity(ref);
        if (named != null) return named;
        const resolved = this.assetRefResolver_?.(ref) ?? ref;
        return this.catalog.resolve(resolved);
    }

    // =========================================================================
    // Private
    // =========================================================================

    private registerBuiltinLoaders(): void {
        this.register(this.textureLoader_);
        this.register(this.spineLoader_);
        this.register(new MaterialShaderAssetLoader());
        this.register(new MaterialAssetLoader());
        this.register(new FontAssetLoader());
        // The engine core however it is embedded: the module on the web, the host's
        // bindings on a device. Taking only the module made these two web-only by
        // construction — a packaged game passes `module: null`.
        const core = (): EngineApi | null => this.module_ ?? nativeEngineApi();
        this.register(new MeshAssetLoader(core));
        this.register(new EnvironmentAssetLoader(core));
        this.register(new ProbeVolumeAssetLoader(core));
        this.register(new MeshSdfAssetLoader());
        this.register(new MeshCardsAssetLoader());
        // The audio loader needs the AudioAPI outside load() too (unload /
        // invalidate have no LoadContext), so it shares Assets' lazy accessor.
        this.register(new AudioAssetLoader(() => this.getAudio_()));
        this.register(new AnimClipAssetLoader());
        this.register(new PrefabAssetLoader());
        // A recipe is bound to an exact era, just like a resolved material.
        // Use the same pending cache, generation ledger and dependency graph.
        this.register<PreparedPrefab>({
            type: 'prepared-prefab', extensions: [],
            load: (path, context) => this.bakePrefab_(path, context as LoadContext & { recorder: DependencyRecorder }),
            unload: (prepared) => prepared.release(),
        });
        this.register(new LocaleAssetLoader());
        this.register(new JsonAssetLoader());
        this.register(new SoundEventAssetLoader());
        // …and whatever an optional subsystem brought with it. A loader names
        // its subsystem's parser, so one the core constructs is one every
        // package carries.
        for (const loader of optionalAssetLoaders()) this.register(loader);
    }

    private textureCacheKey_(path: string, flip: boolean): string {
        return textureResidencyKey(path, flip);
    }

    private async loadTyped<T>(type: string, ref: string): Promise<T> {
        try { return (await this.acquireTyped_<T>(type, ref)).value; }
        catch (error) { throw preparationFailureReason(error); }
    }

    private async acquireTyped_<T>(
        type: string, ref: string,
    ): Promise<{ value: T; lease: AssetRefLease<PreparedLoad<unknown>> }> {
        const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;
        if (!loader) {
            throw new Error(`No loader registered for type: ${type}`);
        }
        if (!loader.load) {
            throw new Error(`Loader for "${type}" publishes by name; acquire it through its slot`);
        }
        const load = loader.load.bind(loader);
        const path = this.resolveLoadPath_(ref);
        return this.acquirePrepared_<T>(type, path, ref, (ctx) => load(path, ctx));
    }

    /**
     * One era of one handle-bound asset, under the KEY that identifies it — the
     * path for everything whose identity is a path, and the PAIR for spine,
     * whose skeleton with another atlas is another asset. One ownership
     * algorithm, differing only in what it calls one asset.
     */
    private async acquirePrepared_<T>(
        type: string, key: string, ref: string, prepare: (ctx: LoadContext) => Promise<T>,
    ): Promise<{ value: T; lease: AssetRefLease<PreparedLoad<unknown>> }> {
        this.assertLoading_();
        const epoch = this.resetEpoch_;
        const era = await this.genericCacheFor_(type).getOrLoad(key, () =>
            this.prepared_(async (ctx) => ({ value: await prepare(ctx) as unknown })),
        );
        // BEFORE acquiring, as with textures: a realm that let go while this
        // loaded has drained the ledger this row would go in, so nothing would
        // ever unload it.
        if (epoch !== this.resetEpoch_) {
            this.retire_(type, era);
            throw new Error(
                `Assets were released while "${ref}" was loading; it has no owner. Load it again.`,
            );
        }
        const lease = this.genericRefs_.acquire(`${type}:${key}`, era);
        const result = era.value as T;
        const handle = (result as { handle?: unknown } | null)?.handle;
        if (typeof handle === 'number' && handle !== 0) this.recordHandlePath_(type, handle, key);
        return { value: result, lease };
    }

    /** The cache of current eras for one handle-bound type. A load that lands
     *  after its own deadline was never handed to anyone, so this is the last
     *  place that knows it and what it acquired. */
    private genericCacheFor_(type: string): AsyncCache<PreparedLoad<unknown>> {
        let cache = this.genericCache_.get(type);
        if (!cache) {
            cache = new AsyncCache<PreparedLoad<unknown>>((era) => this.retire_(type, era));
            this.genericCache_.set(type, cache);
        }
        return cache;
    }

    /**
     * What THIS realm publishes for a ref-bound asset — the answer a runtime
     * lookup reads, and the only copy of it.
     *
     * By the ref as spelled or the path it resolves to: a slot answers to both,
     * so a lookup site need not know which spelling a scene serialized.
     *
     * @internal
     */
    resolveRegistryAsset<T>(type: string, ref: string): T | undefined {
        return (this.registrySlots_.published(type, ref)
            ?? this.registrySlots_.published(type, this.assetIdentity_(ref))) as T | undefined;
    }

    /** @internal Changes when a registry type publishes, replaces or withdraws an era. */
    registryAssetVersion(type: string): number {
        return this.registrySlots_.version(type);
    }

    /**
     * What the current era of a ref-bound asset took — the dependency graph as a
     * PROJECTION of acquisitions, never a table anyone maintains.
     *
     * @internal
     */
    dependenciesOf(type: string, ref: string): readonly DependencyReceipt[] {
        const own = this.registrySlots_.dependenciesOf(type, ref);
        if (own.length > 0) return own;
        const byIdentity = this.registrySlots_.dependenciesOf(type, this.assetIdentity_(ref));
        if (byIdentity.length > 0) return byIdentity;
        return this.genericCache_.get(type)?.get(this.resolveLoadPath_(ref))?.edges ?? [];
    }

    /**
     * The asset types a component holds BY HANDLE — the loaders with a `load`
     * door. What a live rebind can migrate: a ref-bound asset's slot swaps
     * under the name a field already holds, so there is nothing to move.
     *
     * @internal
     */
    handleBoundTypes(): string[] {
        const types: string[] = [];
        for (const [type, loader] of this.loaders_) {
            if (loader.load) types.push(type);
        }
        return types;
    }

    /**
     * Every asset of this realm whose CURRENT era took `ref` — the reverse of
     * {@link dependenciesOf}, walked from the eras so there is no table to keep.
     * By canonical identity: a receipt says what the acquisition ASKED for (a
     * `@uuid:` ref, a document-relative path) and a change names a file.
     *
     * @internal
     */
    dependentsOfSource(ref: string): AssetIdentity[] {
        // Both meanings of a file: whoever READ it, and whoever acquired the
        // asset that lives at it.
        return this.dependents_(ref, isInvalidatable);
    }

    /**
     * Every asset of this realm that ACQUIRED this one — the edge to follow once
     * the walk is past the file that changed. A source read is NOT one: those
     * bytes are exactly as their reader read them, and what ended here is this
     * asset's own generation.
     *
     * @internal
     */
    dependentsOfAsset(asset: AssetIdentity): AssetIdentity[] {
        return this.dependents_(asset.path, (e) => e.kind === 'owned' && e.type === asset.type);
    }

    /** Every era with an edge that `names` — the walk both doors share. */
    private dependents_(ref: string, names: (e: DependencyReceipt) => boolean): AssetIdentity[] {
        const canonical = new Map<string, string>();
        const identify = (path: string): string => {
            let known = canonical.get(path);
            if (known === undefined) {
                known = this.resolveLoadPath_(path);
                canonical.set(path, known);
            }
            return known;
        };
        const target = identify(ref);
        const out: AssetIdentity[] = [];
        for (const era of this.eras_()) {
            if (era.edges.some((e) => names(e) && identify(e.path) === target)) {
                out.push({ type: era.type, path: era.path });
            }
        }
        return out;
    }

    /** Every live era of this realm, published under a name or held by handle. */
    private *eras_(): Generator<{ type: string; path: string; edges: readonly DependencyReceipt[] }> {
        for (const era of this.registrySlots_.eras()) {
            yield { type: era.type, path: era.key, edges: era.edges };
        }
        const seen = new Set<PreparedLoad<unknown>>();
        for (const [type, cache] of this.genericCache_) {
            for (const [path, era] of cache.entries()) {
                seen.add(era);
                yield { type, path, edges: era.edges };
            }
        }
        // Invalidating removes residency, not ownership. A failed refresh can
        // keep an outgoing recipe in a graph; its nested dependencies must still
        // lead back to that graph when their sources recover.
        for (const [key, generations] of this.genericRefs_.entries()) {
            const split = key.indexOf(':');
            const type = key.slice(0, split), path = key.slice(split + 1);
            for (const { value: era } of generations) {
                if (seen.has(era)) continue;
                seen.add(era);
                yield { type, path, edges: era.edges };
            }
        }
    }

    /**
     * Everything this realm publishes of one type. What a schedule analysis
     * reads to learn what the graphs THIS app loaded reach for.
     *
     * @internal
     */
    publishedRegistryAssets<T>(type: string): T[] {
        return this.registrySlots_.publishedOf(type) as T[];
    }

    /**
     * The slot table's view of one registry-backed loader — the LoadContext
     * bound in, so the table stays about ownership and knows nothing about how
     * any particular kind of asset is parsed.
     */
    private registryKind_<T>(type: string): RegistryAssetKind<T> | null {
        const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;
        const registry = loader?.registry;
        if (!registry) return null;
        // The locator is resolved HERE, once per era: the slot holds an identity,
        // and where that asset is served from is a property of the revision the
        // preparation runs in.
        return {
            prepare: (identity) => this.prepared_(
                (ctx) => registry.prepare(this.resolveLoadPath_(identity), ctx),
            ),
        };
    }

    /** A generation-bound recipe through the ordinary typed-asset door. */
    private preparePrefabLease_(ref: string): Promise<AssetLease<PreparedPrefab>> {
        return this.acquireTypedLease_<PreparedPrefab>('prepared-prefab', ref);
    }

    private bakePrefab_(path: string, ctx: LoadContext & { recorder: DependencyRecorder },
                        overrides: readonly PrefabOverride[] = []): Promise<PreparedPrefab> {
        return preparePrefabFromSource({
            loadPrefab: async (ref) => (await ctx.acquireAsset<PrefabResult>('prefab', ref)).value,
            preloadSceneAssets: scene => this.preloadSceneAssets_(scene, undefined, undefined, ctx.recorder),
            resolveSceneAssetPaths: (scene, result) => this.resolveSceneAssetPaths(scene, result),
            trackSceneAssetReferences: (scene, entities) => this.trackSceneAssetReferences(scene, entities),
            resolveRef: ref => this.resolveRef(ref),
            entityScopes: this.entityScopes,
        }, path, overrides);
    }

    /**
     * Run one preparation: what the loader takes IS the result's ownership and
     * IS the graph's edges. A transaction, because an acquisition on the way to
     * a value that never arrives has no owner — the thing that would have held
     * it does not exist.
     */
    private async prepared_<T extends object>(
        work: (ctx: LoadContext) => Promise<T>,
    ): Promise<T & Preparation> {
        this.assertLoading_();
        const recorder = new DependencyRecorder();
        this.preparations_.add(recorder);
        try {
            return recorder.commit(await work(this.recordingContext_(recorder)));
        } catch (e) {
            throw recorder.abort(e);
        } finally { this.preparations_.delete(recorder); }
    }

    /** The load context one preparation sees: every door that takes something
     *  reports it, and the plain readers stay plain. */
    private recordingContext_(recorder: DependencyRecorder): LoadContext & { recorder: DependencyRecorder } {
        const base = this.getLoadContext_();
        const epoch = this.resetEpoch_;
        const attempt = async <T>(ref: string, work: () => Promise<T>): Promise<T> => {
            try { this.assertLoading_(epoch); return await work(); }
            catch (error) { recorder.failed(ref, error); throw preparationFailureReason(error); }
        };
        const read = async <T>(ref: string, work: () => Promise<T>): Promise<T> => {
            const result = await attempt(ref, work);
            this.assertLoading_(epoch);
            return result;
        };
        const take = async <T>(ref: string, work: () => Promise<AssetLease<T>>, type?: string): Promise<AssetLease<T>> => {
            // Own first: if teardown crossed this await, rollback must still
            // return the receipt before the obsolete loader sees its value.
            const lease = recorder.own(ref, await attempt(ref, work), type);
            this.assertLoading_(epoch);
            return lease;
        };
        return {
            ...base,
            recorder,
            loadText: path => read(path, () => base.loadText(path)),
            loadBinary: path => read(path, () => base.loadBinary(path)),
            loadTexture: (path, flipY) => read(path, () => base.loadTexture(path, flipY)),
            decodePixels: path => read(path, () => base.decodePixels!(path)),
            acquireTexture: async (path, flipY) =>
                take(path, () => base.acquireTexture(path, flipY), 'texture'),
            acquireAsset: async (type, ref) => take(ref, () => this.acquireTypedLease_(type, ref), type),
            resolveRef: ref => this.resolveRef(ref),
            preparePrefab: async (ref) => take(ref, () => this.preparePrefabLease_(ref), 'prepared-prefab'),
            createOwnedTexture: async (width, height, pixels, flipY) => {
                this.assertLoading_(epoch);
                const lease = await base.createOwnedTexture!(width, height, pixels, flipY);
                recorder.own(`composed:${lease.value.handle}`, lease);
                this.assertLoading_(epoch);
                return lease;
            },
            readSource: async (ref) => {
                // The edge records what was ASKED for; where the build put
                // those bytes is this door's business, as it is for a texture.
                // A loader resolving first records an identity nothing names.
                recorder.read(ref);
                return read(ref, () => base.loadText(this.catalog.getBuildPath(ref)));
            },
        };
    }

    private getLoadContext_(): LoadContext {
        if (this.loadContext_) return this.loadContext_;
        const self = this;
        this.loadContext_ = {
            backend: this.backend,
            catalog: this.catalog,
            resourceManager: requireResourceManager() as CppResourceManager,
            async loadTexture(path: string, flipY?: boolean): Promise<TextureResult> {
                if (flipY === false) {
                    return self.loadTextureRaw(path);
                }
                return self.loadTexture(path);
            },
            async acquireTexture(path: string, flipY?: boolean): Promise<AssetLease<TextureResult>> {
                const { result, lease } = await self.acquireTextureVariant_(path, flipY !== false);
                return self.textureLease_(lease, result);
            },
            noteAssetProblems(asset: string, problems: readonly string[]): void {
                const path = self.resolveLoadPath_(asset);
                const same = (self.assetProblems_.get(path) ?? []).join('\n') === problems.join('\n');
                if (problems.length === 0) self.assetProblems_.delete(path);
                else self.assetProblems_.set(path, [...problems]);
                if (!same) self.assetProblemListener_?.(path, problems);
            },
            noteMaterialTexture(material: string, texture: string): void {
                if (self.meshMaterials_.has(self.resolveLoadPath_(material)) || self.meshMaterials_.has(material)) {
                    self.meshTextures_.add(self.resolveLoadPath_(texture));
                }
            },
            async acquireAsset<T>(type: string, ref: string): Promise<AssetLease<T>> {
                return self.acquireTyped<T>(type, ref);
            },
            async loadText(path: string): Promise<string> {
                return self.backend.fetchText(self.backend.resolveUrl(path));
            },
            async loadBinary(path: string): Promise<ArrayBuffer> {
                return self.backend.fetchBinary(self.backend.resolveUrl(path));
            },
            async decodePixels(path: string) {
                // The platform's one decode path: the runtime-injected pixel
                // decoder when present (wechat / playable), else fetch→bitmap.
                const decoder = self.textureLoader_.pixelDecoder;
                if (decoder) return decoder(path, false);
                return fetchDecodePixels(self.backend.resolveUrl(self.catalog.getBuildPath(path)));
            },
            async createTextureFromPixels(width, height, pixels, flipY) {
                return self.textureLoader_.loadFromPixels(width, height, pixels, flipY, TextureContent.Retained);
            },
            async createOwnedTexture(width, height, pixels, flipY) {
                return self.ownedTextureLease_(
                    await self.textureLoader_.loadFromPixels(width, height, pixels, flipY, TextureContent.Retained),
                );
            },
            getAudio() {
                return self.getAudio_();
            },
            getSpriteAnimation() {
                return self.getSpriteAnimation_();
            },
            getLocalization() {
                return self.getLocalization_();
            },
        };
        return this.loadContext_;
    }
}