@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/asset/AssetManager.js

@@ -1,1045 +1,1411 @@
-import { assert } from "../../core/assert.js";
-import { array_push_if_unique } from "../../core/collection/array/array_push_if_unique.js";
-import { array_remove_first } from "../../core/collection/array/array_remove_first.js";
-import BinaryHeap from "../../core/collection/heap/BinaryHeap.js";
-import { HashMap } from "../../core/collection/map/HashMap.js";
-import { ObservedMap } from "../../core/collection/map/ObservedMap.js";
-import { Deque } from "../../core/collection/queue/Deque.js";
-import { HashSet } from "../../core/collection/set/HashSet.js";
-import { noop } from "../../core/function/noop.js";
-import ConcurrentExecutor from "../../core/process/executor/ConcurrentExecutor.js";
-import Task from "../../core/process/task/Task.js";
-import { TaskSignal } from "../../core/process/task/TaskSignal.js";
-import { AssetDescription } from "./AssetDescription.js";
-import { AssetLoadState } from "./AssetLoadState.js";
-import { AssetRequest, AssetRequestFlags } from "./AssetRequest.js";
-import { AssetRequestScope } from "./AssetRequestScope.js";
-import { CrossOriginConfig } from "./CORS/CrossOriginConfig.js";
-import { AssetLoader } from "./loaders/AssetLoader.js";
-import { PendingAsset } from "./PendingAsset.js";
-import { extractAssetListFromManager } from "./preloader/extractAssetListFromManager.js";
-
-
-class Response {
-    /**
-     *
-     * @param {Asset} asset
-     * @param {AssetRequest} request
-     */
-    constructor(asset, request) {
-        this.asset = asset;
-        this.request = request;
-    }
-}
-
-/**
- * Used by the priority queue, so the priority is inverted as the BinaryHeap returns elements in ascending score order (from lowest)
- * @param {PendingAsset} pending_asset
- * @returns {number}
- */
-function get_pending_asset_priority_score(pending_asset) {
-    return -pending_asset.priority;
-}
-
-
-// TODO handle 429 HTTP error gracefully
-
-/**
- * Handles loading/generating assets
- * @template CTX
- * @class
- */
-export class AssetManager {
-    /**
-     *
-     * @type {HashMap<AssetDescription, Asset>}
-     * @private
-     */
-    assets = new HashMap({
-        capacity: 1024
-    });
-
-    /**
-     *
-     * @type {ObservedMap<AssetDescription, PendingAsset>}
-     */
-    request_map = new ObservedMap(new HashMap());
-
-    /**
-     * Waiting queue for assets that haven't yet been scheduled (passed to relevant loader)
-     * @type {BinaryHeap<PendingAsset>}
-     * @private
-     */
-    #pending_asset_wait_queue = new BinaryHeap(get_pending_asset_priority_score);
-    /**
-     * Assets currently being processed by #loaders
-     * @type {Set<PendingAsset>}
-     * @private
-     */
-    #pending_asset_active_load_set = new Set();
-
-    /**
-     * Maximum number of requests that can be handled at the same time
-     * Since most of the requests are handled over the network, this can help you control network concurrency,
-     * this can be useful to keep some network slots available for high-priority requests such as UI related ones
-     * TODO currently nested asset requests are not recognized, so if nesting level exceeds concurrency - it will lead to a deadlock
-     * @type {number}
-     */
-    load_concurrency = Infinity;
-
-    /**
-     * Registered asset loaders
-     * @private
-     * @type {Object<AssetLoader>}
-     */
-    #loaders = {};
-
-    /**
-     * After an asset is loaded, a chain of transforms can be applied to it, these are registered here
-     * Transformers are executed in the order in which they are added
-     * Identified by asset "type" string
-     * @type {Object<AssetTransformer[]>}
-     * @private
-     */
-    #transformers = {};
-
-    /**
-     * Named links to specific assets. Useful to later re-mapping assets and having meaningful names for them
-     * @type {Map<string, AssetDescription>}
-     * @private
-     * @see resolveAlias
-     * @see assignAlias
-     * @see promiseByAlias
-     */
-    #aliases = new Map();
-
-    /**
-     * This will be added to asset path for actual network resolution
-     * @type {string}
-     * @private
-     */
-    rootPath = '';
-
-    /**
-     *
-     * @type {CrossOriginConfig}
-     */
-    crossOriginConfig = new CrossOriginConfig();
-
-    /**
-     *
-     * @type {HashSet<AssetDescription>}
-     * @private
-     */
-    #failures = new HashSet();
-
-    /**
-     * Queue of responses that are waiting to be dispatched
-     * @type {Deque<Response>}
-     * @private
-     */
-    #response_queue = new Deque();
-
-    /**
-     *
-     * @type {Task}
-     * @private
-     */
-    #response_processor = new Task({
-        name: "Asset Manager Response processor",
-        cycleFunction: () => {
-            if (this.#response_queue.isEmpty()) {
-                return TaskSignal.Yield;
-            }
-
-            const response = this.#response_queue.removeFirst();
-
-            this.#process_response(response);
-
-            return TaskSignal.Continue;
-        }
-    });
-
-    /**
-     *
-     * @type {boolean}
-     * @private
-     */
-    #is_running = false;
-
-    /**
-     *
-     * @type {CTX|null}
-     * @private
-     */
-    #context = null;
-
-    /**
-     *
-     * @type {ConcurrentExecutor|null}
-     */
-    #executor = null;
-
-    /**
-     *
-     * @param {CTX} context
-     * @param {ConcurrentExecutor} executor
-     * @constructor
-     */
-    constructor({
-                    context,
-                    executor = new ConcurrentExecutor()
-                } = {}) {
-
-        this.#context = context;
-        this.#executor = executor;
-
-    }
-
-    startup() {
-        if (this.#is_running) {
-            return;
-        }
-
-        this.#executor.run(this.#response_processor);
-
-        this.#is_running = true;
-    }
-
-    /**
-     *
-     * @param {number} [immediate] should be let pending work finish, or abort it and shut down immediately? Defaults to false (wait)
-     * @return {Promise<void>}
-     */
-    async shutdown(immediate = false) {
-        if (!this.#is_running) {
-            return;
-        }
-
-        if (!immediate) {
-            // wait until all responses have been processed
-            await Promise.allSettled([Task.promise(this.#response_processor)]);
-        }
-
-        this.#executor.removeTask(this.#response_processor);
-
-        this.#is_running = false;
-    }
-
-    /**
-     * Remove asset if it is loaded, does nothing otherwise
-     * @param {String} path
-     * @param {String} type
-     * @returns {boolean} true if asset was removed, else otherwise
-     */
-    remove(path, type) {
-
-        const assetDescription = new AssetDescription(path, type);
-
-        return this.assets.delete(assetDescription);
-    }
-
-    /**
-     * Clear out all loaded assets
-     */
-    clear() {
-        this.assets.clear();
-    }
-
-    dumpLoadedAssetList() {
-        return JSON.stringify(extractAssetListFromManager(this), 3, 3);
-    }
-
-    /**
-     * @param {String} path
-     * @param {String} type
-     * @param {AssetRequestScope} [scope]
-     * @param {boolean} [skip_queue] if true will skip the queue and dispatch request immediately
-     * @returns {Promise<Asset>}
-     */
-    promise(path, type, { scope, skip_queue = false } = {}) {
-        return new Promise((resolve, reject) => {
-            this.get({
-                path,
-                type,
-                callback: resolve,
-                failure: reject,
-                scope
-            });
-        });
-    }
-
-    /**
-     * @template T
-     * @param {String} path
-     * @param {String} type
-     * @param {function(asset:Asset<T>)} [callback] success callback
-     * @param {function(reason:*)} [failure]
-     * @param {function(loaded:number, total:number)} [progress]
-     * @param {boolean} [skip_queue]
-     * @param {AssetRequestScope} [scope]
-     */
-    get({
-            path,
-            type,
-            callback = noop,
-            failure = console.error,
-            progress = noop,
-            skip_queue = false,
-            scope = null
-        }) {
-
-        if (typeof path !== "string") {
-            throw new TypeError(`Path must be string. instead was '${typeof path}'`);
-        }
-
-        if (typeof type !== "string") {
-            throw new TypeError(`type must be a string, instead was '${typeof type}'`);
-        }
-
-        assert.isFunction(callback, 'success');
-        assert.isFunction(failure, 'failure');
-        assert.isFunction(progress, 'progress');
-
-        const assetDescription = new AssetDescription(path, type);
-
-        const asset = this.assets.get(assetDescription);
-
-        if (asset !== undefined) {
-
-            // already exists, dispatch callback immediately
-            callback(asset);
-
-        } else {
-
-            //create request object
-            const assetRequest = new AssetRequest(callback, failure, progress);
-
-            assetRequest.scope = scope;
-            assetRequest.writeFlag(AssetRequestFlags.SkipQueue, skip_queue);
-
-            //submit request
-            this.submitRequest(assetDescription, assetRequest);
-
-        }
-    }
-
-    /**
-     * Checks if an asset is currently being loaded.
-     * Useful for avoiding redundant requests.
-     *
-     * @param {string} path
-     * @param {string} type
-     * @return {boolean}
-     */
-    isPending(path, type) {
-        const assetDescription = new AssetDescription(path, type);
-        return this.request_map.has(assetDescription);
-    }
-
-
-    /**
-     *
-     * @param {string} path
-     * @param {string} type
-     * @returns {boolean}
-     * @see isPending
-     */
-    isFailed(path, type) {
-        const ad = new AssetDescription(path, type);
-
-        return this.#failures.has(ad);
-    }
-
-    /**
-     * Checks if an asset is loaded.
-     * If the asset is loaded, calls to {@link tryGet} are guaranteed to succeed.
-     *
-     * @param {string} path
-     * @param {string} type
-     * @return {boolean}
-     */
-    isLoaded(path, type) {
-        const ad = new AssetDescription(path, type);
-
-        return this.assets.has(ad);
-    }
-
-    /**
-     * Same as {@link insert}, but will register the asset as pending until loader function resolves.
-     *
-     * NOTE: {@link AssetTransformer}s are not applied to the asset
-     *
-     * NOTE: any subsequent normal requests such as {@link get} will be routed to the same loader
-     *
-     * @template T
-     * @param {string} path
-     * @param {string} type
-     * @param {function(progress?:function(current:number, total:number)):Promise<Asset<T>>} loader
-     * @returns {Promise<Asset<T>>} loaded asset
-     * @see insert
-     * @example
-     *   manager.insertAsync('path/to/asset', 'my-type', async (progress) => {
-     *       const asset = await loadAssetFromNetwork('path/to/asset', 'type', progress);
-     *       return asset;
-     *   });
-     *
-     */
-    insertAsync(path, type, loader) {
-
-        const asset_descriptor = new AssetDescription(path, type);
-
-        if (this.request_map.get(asset_descriptor)) {
-            throw new Error(`Asset with path '${path}' and type '${type}' is already pending`);
-        }
-
-        const pending = new PendingAsset(asset_descriptor);
-
-        this.request_map.set(asset_descriptor, pending);
-
-        /**
-         *
-         * @param {number} current
-         * @param {number} total
-         */
-        const progress = (current, total) => {
-            pending.progress.setValue(current);
-            pending.progress.setUpperLimit(total);
-        };
-
-        const asset_promise = loader(progress);
-
-        const cleanup = () => {
-            const existing = this.request_map.get(asset_descriptor);
-
-            if (existing !== pending) {
-                // looks like another resolution is pending, this completely invalidates current insersion request
-                // Likely reason is that something else was inserted later on
-                return false;
-            }
-
-            this.request_map.delete(asset_descriptor);
-            return true;
-        }
-
-        return asset_promise.then(asset => {
-            const existing = this.request_map.get(asset_descriptor);
-
-            if (existing !== pending) {
-                // looks like another resolution is pending, this completely invalidates current insersion request
-                // Likely reason is that something else was inserted later on
-                throw new Error(`Race condition. Asset with path '${path}' and type '${type}' was already resolved somewhere else.`);
-            }
-
-            this.insert(path, type, asset);
-
-            return asset;
-        }, error => {
-            cleanup();
-
-            //rethrow
-            throw error;
-        });
-    }
-
-    /**
-     * Manually add a fully resolved resource
-     * NOTE: {@link AssetTransformer}s are not applied to the asset
-     *
-     * @template T
-     * @param {string} path
-     * @param {string} type
-     * @param {Asset<T>} asset
-     */
-    insert(path, type, asset) {
-        assert.isString(path, 'path');
-        assert.isString(type, 'type');
-        assert.isObject(asset, 'asset');
-
-        const asset_descritptor = new AssetDescription(path, type);
-
-        const existing_resource = this.assets.get(asset_descritptor);
-
-        if (existing_resource !== undefined && existing_resource !== asset) {
-            console.warn(`Another asset under ${asset_descritptor} already exists and will be replaced`);
-        }
-
-        // clear failures
-        this.#failures.delete(asset_descritptor);
-
-        // check for assets in-flight
-        const pending = this.request_map.get(asset_descritptor);
-        if (pending !== undefined) {
-            // TODO check 'active' flight sets as well
-            // console.warn(`Asset with path '${path}' and type '${type}' is already pending, this operation will squash the asset in-flight`);
-
-            this.request_map.delete(asset_descritptor);
-
-            const requests = pending.requests;
-            const request_count = requests.length;
-
-            for (let i = 0; i < request_count; i++) {
-                const request = requests[i];
-                this.#schedule_response(asset, request);
-            }
-        }
-
-        this.assets.set(asset_descritptor, asset);
-    }
-
-    /**
-     *
-     * @param {Response} response
-     * @private
-     */
-    #process_response(response) {
-
-        try {
-            response.request.successCallback(response.asset);
-        } catch (e) {
-            console.error("Failed to execute asset success callback", e);
-        }
-    }
-
-    /**
-     *
-     * @param {Asset} asset
-     * @param {AssetRequest} request
-     * @private
-     */
-    #schedule_response(asset, request) {
-        // technically you can schedule responses just fine, but commonly the user forgets to call 'startup' and so nothing happens which is perceived as a bug.
-        assert.equal(this.#is_running, true, 'AssetManager must be running to schedule responses');
-
-        this.#response_queue.add(new Response(asset, request));
-    }
-
-    /**
-     *
-     * @param {PendingAsset} asset
-     * @private
-     */
-    #schedule_load(asset) {
-        if (this.#pending_asset_active_load_set.size < this.load_concurrency) {
-            this.#dispatch_pending_asset(asset);
-        } else {
-            this.#pending_asset_wait_queue.push(asset);
-        }
-    }
-
-    /**
-     * Force load of the asset
-     * @param {PendingAsset} asset
-     * @private
-     */
-    #force_load(asset) {
-        // check if the asset is already being loaded
-        if (this.#pending_asset_active_load_set.has(asset)) {
-            return;
-        }
-
-        // remove from queue
-        this.#pending_asset_wait_queue.delete(asset);
-
-        // dispatch
-        this.#dispatch_pending_asset(asset);
-
-    }
-
-    /**
-     * Asset has been loaded successfully, failed, or aborted
-     * @param {PendingAsset} pending_asset
-     * @private
-     */
-    #handle_asset_resolved(pending_asset) {
-        // console.log(`Asset resolved ${pending_asset.description}`); // DEBUG
-
-        const active_set = this.#pending_asset_active_load_set;
-
-        this.request_map.delete(pending_asset.description);
-        active_set.delete(pending_asset);
-
-        const queue = this.#pending_asset_wait_queue;
-
-        // schedule more if possible
-        while (!queue.isEmpty() && active_set.size < this.load_concurrency) {
-            const load = queue.pop();
-
-            this.#dispatch_pending_asset(load);
-        }
-    }
-
-    /**
-     * Dispatch load request to relevant loader
-     * @param {PendingAsset} pendingAsset
-     * @private
-     */
-    #dispatch_pending_asset(pendingAsset) {
-        // console.log(`Asset load dispatched ${pendingAsset.description}`); // DEBUG
-
-        const requests = pendingAsset.requests;
-        const assetDescription = pendingAsset.description;
-        const type = assetDescription.type;
-        const path = assetDescription.path;
-
-        const loader = this.#loaders[type];
-
-        if (loader === undefined) {
-            let reported_error = false;
-            // no loader
-            for (let i = 0; i < requests.length; i++) {
-                const assetRequest = requests[i];
-
-                if (typeof assetRequest.failureCallback === "function") {
-                    assetRequest.failureCallback(`no loader exists for asset type '${type}', valid types are: ${Object.keys(this.#loaders).join(', ')}`);
-                } else {
-                    //uncaught
-                    if (!reported_error) {
-                        console.error("Uncaught asset load failure: No loader for asset type", type);
-                        reported_error = true;
-                    }
-                }
-            }
-
-            this.#handle_asset_resolved(pendingAsset);
-
-            return;
-        }
-
-        // mark as being loaded
-        this.#pending_asset_active_load_set.add(pendingAsset);
-
-        const assets = this.assets;
-        const failures = this.#failures;
-
-
-        /**
-         *
-         * @param {Asset} loaded_asset
-         */
-        const success = async (loaded_asset) => {
-            if (pendingAsset.state === AssetLoadState.Succeeded) {
-                // incorrect state
-                console.warn(`Asset already resolved, duplicate success invocation. Ignored. AD:${assetDescription}`);
-                return;
-            }
-
-            if (pendingAsset.state === AssetLoadState.Failed) {
-                // incorrect state
-                console.error(`Asset already failed. Unexpected resolution signal. AD:${assetDescription}`);
-            }
-
-            pendingAsset.state = AssetLoadState.Succeeded;
-
-            let asset = loaded_asset;
-
-            // apply the transform chain
-            const transformers = this.#transformers[type];
-            if (transformers !== undefined) {
-                const transformer_count = transformers.length;
-                for (let i = 0; i < transformer_count; i++) {
-                    const transformer = transformers[i];
-
-                    const transformed_asset = await transformer.transform(asset, assetDescription);
-
-                    if (typeof transformed_asset !== "object") {
-                        console.error('Transformer produced invalid result. Ignoring result.', transformer, assetDescription);
-                    } else {
-                        asset = transformed_asset;
-                    }
-                }
-            }
-
-            // link asset description
-            asset.description = assetDescription;
-
-            // clear possible failure
-            this.#failures.delete(assetDescription);
-
-            // register asset
-            assets.set(assetDescription, asset);
-
-            // clear callbacks etc.
-            this.#handle_asset_resolved(pendingAsset);
-
-
-            // process callbacks
-            for (let i = 0; i < requests.length; i++) {
-                const request = requests[i];
-                this.#schedule_response(asset, request);
-            }
-
-        }
-
-        const failure = (error) => {
-            if (pendingAsset.state === AssetLoadState.Failed) {
-                console.warn(`Asset already failed, this is a redundant invocation. AD: ${assetDescription}`);
-                return;
-            }
-
-            if (pendingAsset.state === AssetLoadState.Succeeded) {
-                // incorrect state
-                console.error(`Asset already resolved. Unexpected failure signal. AD:${assetDescription}`);
-            }
-
-            pendingAsset.state = AssetLoadState.Failed;
-
-            for (let i = 0; i < requests.length; i++) {
-                const request = requests[i];
-                try {
-                    request.failureCallback(error);
-                } catch (e) {
-                    console.error("Failed to execute asset failure callback", e);
-                }
-            }
-
-            //clear callbacks etc.
-            this.#handle_asset_resolved(pendingAsset);
-
-            // record failure
-            failures.add(assetDescription);
-        }
-
-        function progress(current, total) {
-            requests.forEach(function (request) {
-                if (typeof request.pogressCallback !== "function") {
-                    //progress callback is not a function, ignore
-                    return;
-                }
-
-                try {
-                    request.pogressCallback(current, total);
-                } catch (e) {
-                    console.error("Failed to execute asset progress callback", e);
-                }
-            });
-
-            pendingAsset.progress.setValue(current);
-            pendingAsset.progress.setUpperLimit(total);
-        }
-
-        // collect scopes
-        const scopes = [];
-
-        for (let i = 0; i < requests.length; i++) {
-            const request = requests[i];
-            const request_scope = request.scope;
-
-            if (request_scope !== null) {
-                array_push_if_unique(scopes, request_scope)
-            }
-        }
-
-        let scope;
-        if (scopes.length > 0) {
-            scope = AssetRequestScope.from(scopes);
-        } else {
-            scope = AssetRequestScope.GLOBAL;
-        }
-
-
-        const full_path = this.rootPath + path;
-
-        // console.log(`Request type: ${type}, path: ${path}, scope: ${scope}`);
-
-        try {
-
-
-            const result = loader.load(scope, full_path, success, failure, progress);
-
-            if (result instanceof Promise) {
-                // allow promise responses
-                result.catch(failure);
-            }
-
-        } catch (e) {
-            console.error(`Loader failed on invocation. path=${path}, type=${type}`, 'Loader exception: ', e);
-            failure(e);
-        }
-    }
-
-    /**
-     *
-     * @param {AssetDescription} assetDescription
-     * @param {AssetRequest} request
-     * @private
-     */
-    submitRequest(assetDescription, request) {
-        const requestMap = this.request_map;
-
-        let shouldSchedule = false;
-        let pendingAsset = requestMap.get(assetDescription);
-
-        if (pendingAsset === undefined) {
-            pendingAsset = new PendingAsset(assetDescription);
-            requestMap.set(assetDescription, pendingAsset);
-
-            shouldSchedule = true;
-        }
-
-        pendingAsset.requests.push(request);
-
-        if (shouldSchedule) {
-            // not loading yet, lets create a load container and schedule it
-            this.#schedule_load(pendingAsset);
-        } else {
-            // update priority queue if necessary
-            this.#pending_asset_wait_queue.updateElementScore(pendingAsset);
-        }
-
-
-        if (request.getFlag(AssetRequestFlags.SkipQueue)) {
-            this.#force_load(pendingAsset);
-        }
-    }
-
-
-    /**
-     *
-     * @param {string} type
-     * @return {boolean}
-     */
-    hasLoaderForType(type) {
-        return this.getLoaderByType(type) !== undefined;
-    }
-
-    /**
-     *
-     * @param {string} type
-     * @returns {AssetLoader|undefined}
-     */
-    getLoaderByType(type) {
-        assert.isString(type, 'type');
-
-        return this.#loaders[type];
-    }
-
-    /**
-     *
-     * @param {string} type
-     * @return {AssetDescription[]}
-     * @private
-     */
-    #getLoadedAssetDescriptorsByType(type) {
-        const loaded_assets = Array.from(this.assets.keys());
-        return loaded_assets.filter(t => t.type === type);
-    }
-
-    /**
-     * Transformer will be applied to all assets of the given type in order of registration.
-     *
-     * Does not apply retroactively, assets that were already loaded will not be transformed.
-     *
-     * @template T
-     * @param {string} type
-     * @param {AssetTransformer<T>} transformer
-     * @returns {void}
-     * @see removeTransformer
-     */
-    registerTransformer(type, transformer) {
-        let transformers = this.#transformers[type];
-
-        if (transformers === undefined) {
-            transformers = [];
-
-            this.#transformers[type] = transformers;
-        }
-
-        transformers.push(transformer);
-
-        // check for loaded assets
-        const matching_assets = this.#getLoadedAssetDescriptorsByType(type);
-
-        if (matching_assets.length > 0) {
-            console.warn(`Following assets of matching type '${type}' are already loaded and transform is not applied to them:\n\t${matching_assets.join('\n\t')}`);
-        }
-
-    }
-
-    /**
-     * @template T
-     * @param {string} type
-     * @param {AssetTransformer<T>} transformer
-     * @returns {boolean} true if removed, false if not found
-     * @see registerTransformer
-     */
-    unregisterTransformer(type, transformer) {
-
-        const transformers = this.#transformers[type];
-
-        if (transformers === undefined) {
-            // not found
-            return false;
-        }
-
-        if (!array_remove_first(transformers, transformer)) {
-            // not found
-            return false;
-        }
-
-        // check for loaded assets
-        const matching_assets = this.#getLoadedAssetDescriptorsByType(type);
-
-        if (matching_assets.length > 0) {
-            console.warn(`Following assets of matching type '${type}' are already loaded and transform was probably already applied to them:\n\t${matching_assets.join('\n\t')}`);
-        }
-
-        return true;
-    }
-
-    /**
-     * Will register loader only if none exists for this type
-     * @template T
-     * @param {string} type
-     * @param {AssetLoader<T>} loader
-     * @returns {Promise<boolean>} true if registered, false otherwise
-     */
-    async tryRegisterLoader(type, loader) {
-        if (this.hasLoaderForType(type)) {
-            return false;
-        }
-
-        await this.registerLoader(type, loader);
-
-        return true;
-    }
-
-    /**
-     * @template T
-     * @param {string} type
-     * @param {AssetLoader<T>} loader
-     * @throws {Error} if a loader is already registered for the given type
-     */
-    async registerLoader(type, loader) {
-        assert.isString(type, 'type');
-
-        const existing_loader = this.getLoaderByType(type);
-
-        if (existing_loader !== undefined) {
-            if (existing_loader === loader) {
-                // all is well, already registered
-                return existing_loader;
-            } else if (Object.getPrototypeOf(existing_loader) === Object.getPrototypeOf(loader)) {
-                console.warn(`Another instance of this loader is already registered for type '${type}'. Ignoring.`);
-                return existing_loader;
-            } else {
-                throw new Error(`Loader for type '${type}' is already registered`);
-            }
-        }
-
-
-        let _loader = loader;
-
-        if (typeof _loader === "function") {
-
-            _loader = new AssetLoader();
-            _loader.load = loader;
-
-            console.warn(`function-based loaders are deprecated (${type})`);
-
-        } else {
-
-            await _loader.link(this, this.#context);
-
-        }
-
-        this.#loaders[type] = _loader;
-
-        return _loader;
-    }
-
-    /**
-     *
-     * @param {string} type
-     */
-    async unregisterLoader(type) {
-        const loader = this.getLoaderByType(type);
-
-        if (loader === undefined) {
-            // asset loader is not registered, nothing to do
-            return;
-
-        }
-
-        // first remove the loader from registry so no further asset requests can be made
-        delete this.#loaders[type];
-
-        // TODO address all pending requests, possibly waiting for all of them to finalize
-
-        // finally unlink the loader
-        await loader.unlink();
-    }
-
-    /**
-     * Retrieve an asset if it is loaded, returns null if the asset is not loaded.
-     * Does not trigger loading if the asset is not loaded.
-     * @template T
-     * @param {String} path
-     * @param {String} type
-     * @returns {Asset<T>|null}
-     */
-    tryGet(path, type) {
-        const assetDescription = new AssetDescription(path, type);
-
-        const asset = this.assets.get(assetDescription);
-
-        if (asset !== undefined) {
-            return asset;
-        } else {
-            return null;
-        }
-    }
-
-    /**
-     * @template T
-     * @param {string} alias
-     * @return {Promise<Asset<T>>}
-     */
-    promiseByAlias(alias) {
-        assert.isString(alias, 'alias');
-
-        // resolve alias
-        const assetDescription = this.#aliases.get(alias);
-
-        if (assetDescription === undefined) {
-            return new Promise.reject(`Alias '${alias}' not found`);
-        }
-
-        return this.promise(assetDescription.path, assetDescription.path);
-    }
-
-    /**
-     *
-     * @param {string} alias
-     * @return {AssetDescription|undefined}
-     */
-    resolveAlias(alias) {
-
-        // todo consider cloning result to protect against mutation
-
-        return this.#aliases.get(alias);
-
-    }
-
-    /**
-     *
-     * @param {string} alias
-     * @param {string} path
-     * @param {string} type
-     */
-    assignAlias(alias, path, type) {
-        assert.isString(alias, 'alias');
-        assert.isString(path, 'path');
-        assert.isString(type, 'type');
-
-        const assetDescription = new AssetDescription(path, type);
-
-        this.#aliases.set(alias, assetDescription);
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-AssetManager.prototype.isAssetManager = true;
+import { assert } from "../../core/assert.js";
+import { array_push_if_unique } from "../../core/collection/array/array_push_if_unique.js";
+import { array_remove_first } from "../../core/collection/array/array_remove_first.js";
+import BinaryHeap from "../../core/collection/heap/BinaryHeap.js";
+import { HashMap } from "../../core/collection/map/HashMap.js";
+import { ObservedMap } from "../../core/collection/map/ObservedMap.js";
+import { Deque } from "../../core/collection/queue/Deque.js";
+import { HashSet } from "../../core/collection/set/HashSet.js";
+import { noop } from "../../core/function/noop.js";
+import ConcurrentExecutor from "../../core/process/executor/ConcurrentExecutor.js";
+import Task from "../../core/process/task/Task.js";
+import { TaskSignal } from "../../core/process/task/TaskSignal.js";
+import { AssetDescription } from "./AssetDescription.js";
+import { AssetLoadState } from "./AssetLoadState.js";
+import { AssetRequest, AssetRequestFlags } from "./AssetRequest.js";
+import { AssetRequestScope } from "./AssetRequestScope.js";
+import { CrossOriginConfig } from "./CORS/CrossOriginConfig.js";
+import { AssetLoader } from "./loaders/AssetLoader.js";
+import { PendingAsset } from "./PendingAsset.js";
+import { extractAssetListFromManager } from "./preloader/extractAssetListFromManager.js";
+
+
+class Response {
+    /**
+     *
+     * @param {AssetRequest} request
+     * @param {Asset|*} value loaded asset when success is true, error otherwise
+     * @param {boolean} success
+     * @param {AssetDescription} description
+     */
+    constructor(request, value, success, description) {
+        this.request = request;
+        this.value = value;
+        this.success = success;
+        this.description = description;
+    }
+}
+
+/**
+ * Used by the priority queue, so the priority is inverted as the BinaryHeap returns elements in ascending score order (from lowest)
+ * @param {PendingAsset} pending_asset
+ * @returns {number}
+ */
+function get_pending_asset_priority_score(pending_asset) {
+    return -pending_asset.priority;
+}
+
+
+// TODO handle 429 HTTP error gracefully
+
+/**
+ * Handles loading/generating assets
+ * @template CTX
+ * @class
+ */
+export class AssetManager {
+    /**
+     *
+     * @type {HashMap<AssetDescription, Asset>}
+     * @private
+     */
+    assets = new HashMap({
+        capacity: 1024
+    });
+
+    /**
+     *
+     * @type {ObservedMap<AssetDescription, PendingAsset>}
+     */
+    request_map = new ObservedMap(new HashMap());
+
+    /**
+     * Waiting queue for assets that haven't yet been scheduled (passed to relevant loader)
+     * @type {BinaryHeap<PendingAsset>}
+     * @private
+     */
+    #pending_asset_wait_queue = new BinaryHeap(get_pending_asset_priority_score);
+    /**
+     * Assets currently being processed by #loaders
+     * @type {Set<PendingAsset>}
+     * @private
+     */
+    #pending_asset_active_load_set = new Set();
+
+    /**
+     * Dispatch scopes of loads that are currently in flight. A request whose scope chain reaches
+     * one of these was made by a loader as part of that load (a nested request).
+     * @type {Map<AssetRequestScope, PendingAsset>}
+     * @private
+     */
+    #active_load_scopes = new Map();
+
+    /**
+     * Maximum number of top-level requests that can be handled at the same time.
+     * Since most of the requests are handled over the network, this can help you control network concurrency,
+     * this can be useful to keep some network slots available for high-priority requests such as UI related ones.
+     * Nested requests (made by a loader while servicing another load) are dispatched immediately and never wait
+     * on this limit: their parent occupies a slot until they resolve, so queueing them would deadlock.
+     * @type {number}
+     */
+    load_concurrency = Infinity;
+
+    /**
+     * Registered asset loaders
+     * @private
+     * @type {Object<AssetLoader>}
+     */
+    #loaders = {};
+
+    /**
+     * After an asset is loaded, a chain of transforms can be applied to it, these are registered here
+     * Transformers are executed in the order in which they are added
+     * Identified by asset "type" string
+     * @type {Object<AssetTransformer[]>}
+     * @private
+     */
+    #transformers = {};
+
+    /**
+     * Named links to specific assets. Useful to later re-mapping assets and having meaningful names for them
+     * @type {Map<string, AssetDescription>}
+     * @private
+     * @see resolveAlias
+     * @see assignAlias
+     * @see promiseByAlias
+     */
+    #aliases = new Map();
+
+    /**
+     * This will be added to asset path for actual network resolution.
+     * Paths exchanged with the manager ({@link get}, {@link promise}, cache keys) are never prefixed;
+     * loaders apply the prefix at the fetch boundary via {@link resolveNetworkPath}.
+     * @type {string}
+     * @private
+     */
+    rootPath = '';
+
+    /**
+     *
+     * @type {CrossOriginConfig}
+     */
+    crossOriginConfig = new CrossOriginConfig();
+
+    /**
+     * Descriptions of assets whose most recent load attempt failed.
+     * Purely advisory (see {@link isFailed}); a new {@link get} for a failed asset will retry the load.
+     * @type {HashSet<AssetDescription>}
+     * @private
+     */
+    #failures = new HashSet();
+
+    /**
+     * Queue of responses that are waiting to be dispatched
+     * @type {Deque<Response>}
+     * @private
+     */
+    #response_queue = new Deque();
+
+    /**
+     * Resolvers of {@link shutdown} calls that are waiting for outstanding work to finish
+     * @type {function[]}
+     * @private
+     */
+    #drain_waiters = [];
+
+    /**
+     * Delivers queued responses. Ends as soon as the queue is drained and is re-scheduled by
+     * {@link #wake_response_processor} when a new response is enqueued, so an idle manager keeps
+     * no task on the executor and the executor itself can go fully idle.
+     * @type {Task}
+     * @private
+     */
+    #response_processor = new Task({
+        name: "Asset Manager Response processor",
+        cycleFunction: () => {
+            if (this.#response_queue.isEmpty()) {
+                this.#flush_drain_waiters();
+
+                return TaskSignal.EndSuccess;
+            }
+
+            const response = this.#response_queue.removeFirst();
+
+            this.#process_response(response);
+
+            return TaskSignal.Continue;
+        }
+    });
+
+    /**
+     * True when a wake of {@link #response_processor} is already sitting on the microtask queue
+     * @type {boolean}
+     * @private
+     */
+    #wake_queued = false;
+
+    /**
+     * Deferred half of {@link #wake_response_processor}. By the time the microtask fires the world
+     * may have changed (manager shut down, queue already drained, processor already scheduled), so
+     * every condition is re-checked here.
+     */
+    #wake = () => {
+        this.#wake_queued = false;
+
+        if (!this.#is_running) {
+            // shut down before the wake fired; #abort_outstanding has already delivered the queue
+            return;
+        }
+
+        if (this.#response_queue.isEmpty()) {
+            // queue was drained before the wake fired
+            return;
+        }
+
+        if (this.#executor.contains(this.#response_processor)) {
+            // processor is already scheduled and will drain the queue
+            return;
+        }
+
+        this.#executor.run(this.#response_processor);
+    };
+
+    /**
+     * Schedules {@link #response_processor} to run. Deferred via the microtask queue: responses are
+     * enqueued from inside {@link #settle} (e.g. by {@link insert} or a loader callback), and
+     * {@link ConcurrentExecutor#run} executes a time slice synchronously — waking the processor
+     * directly would deliver requester callbacks synchronously to whoever caused the settle.
+     * @private
+     */
+    #wake_response_processor() {
+        if (this.#wake_queued) {
+            return;
+        }
+
+        this.#wake_queued = true;
+
+        queueMicrotask(this.#wake);
+    }
+
+    /**
+     *
+     * @type {boolean}
+     * @private
+     */
+    #is_running = false;
+
+    /**
+     *
+     * @type {CTX|null}
+     * @private
+     */
+    #context = null;
+
+    /**
+     *
+     * @type {ConcurrentExecutor|null}
+     */
+    #executor = null;
+
+    /**
+     *
+     * @param {CTX} context
+     * @param {ConcurrentExecutor} executor
+     * @constructor
+     */
+    constructor({
+                    context,
+                    executor = new ConcurrentExecutor()
+                } = {}) {
+
+        this.#context = context;
+        this.#executor = executor;
+
+    }
+
+    startup() {
+        if (this.#is_running) {
+            return;
+        }
+
+        this.#is_running = true;
+
+        // deliver anything that was enqueued before startup
+        if (!this.#response_queue.isEmpty()) {
+            this.#wake_response_processor();
+        }
+    }
+
+    /**
+     *
+     * @param {boolean} [immediate] should we let pending work finish, or shut down immediately?
+     * Defaults to false (wait until all in-flight requests are resolved and all responses are delivered).
+     * When true, outstanding requests are failed and all responses are delivered before the method returns.
+     * @return {Promise<void>}
+     */
+    async shutdown(immediate = false) {
+        if (!this.#is_running) {
+            return;
+        }
+
+        if (!immediate) {
+            await this.#drain();
+        } else {
+            this.#abort_outstanding();
+        }
+
+        this.#executor.removeTask(this.#response_processor);
+
+        this.#is_running = false;
+    }
+
+    /**
+     * Fail every outstanding request and deliver all queued responses synchronously.
+     * In-flight loaders keep running, but their late resolutions will be dropped by the claim guard.
+     * @private
+     */
+    #abort_outstanding() {
+        // empty the wait queue first, otherwise settling an active load would pop and dispatch queued ones
+        const queue = this.#pending_asset_wait_queue;
+
+        while (!queue.isEmpty()) {
+            queue.pop();
+        }
+
+        /**
+         * @type {PendingAsset[]}
+         */
+        const outstanding = [];
+
+        this.request_map.forEach(pending => outstanding.push(pending));
+
+        if (outstanding.length > 0) {
+            const error = new Error('AssetManager was shut down before the asset resolved');
+
+            for (let i = 0; i < outstanding.length; i++) {
+                const pending = outstanding[i];
+
+                pending.resolution_claimed = true;
+                this.#settle(pending, AssetLoadState.Failed, error);
+            }
+        }
+
+        // the response processor is about to be removed, deliver everything now
+        while (!this.#response_queue.isEmpty()) {
+            this.#process_response(this.#response_queue.removeFirst());
+        }
+
+        // a graceful shutdown() may still be waiting on the drain
+        this.#flush_drain_waiters();
+    }
+
+    /**
+     * Resolves once there are no in-flight requests and no undelivered responses.
+     * @returns {Promise<void>}
+     * @private
+     */
+    #drain() {
+        if (this.#response_queue.isEmpty() && this.request_map.size === 0) {
+            return Promise.resolve();
+        }
+
+        return new Promise(resolve => this.#drain_waiters.push(resolve));
+    }
+
+    /**
+     * @private
+     */
+    #flush_drain_waiters() {
+        if (this.#drain_waiters.length === 0) {
+            return;
+        }
+
+        if (!this.#response_queue.isEmpty() || this.request_map.size > 0) {
+            // still busy
+            return;
+        }
+
+        const waiters = this.#drain_waiters;
+        this.#drain_waiters = [];
+
+        for (let i = 0; i < waiters.length; i++) {
+            waiters[i]();
+        }
+    }
+
+    /**
+     * Resolves a caller-facing asset path to the path used for actual network retrieval.
+     * Loaders that fetch over the network should apply this at the fetch boundary; paths passed to
+     * {@link get}/{@link promise} (including nested requests made by loaders) always stay un-prefixed,
+     * so they are keyed consistently in the cache.
+     * @param {string} path
+     * @returns {string}
+     */
+    resolveNetworkPath(path) {
+        return this.rootPath + path;
+    }
+
+    /**
+     * Remove asset if it is loaded, does nothing otherwise
+     * @param {String} path
+     * @param {String} type
+     * @returns {boolean} true if asset was removed, else otherwise
+     */
+    remove(path, type) {
+
+        const assetDescription = new AssetDescription(path, type);
+
+        return this.assets.delete(assetDescription);
+    }
+
+    /**
+     * Clear out all loaded assets
+     */
+    clear() {
+        this.assets.clear();
+    }
+
+    dumpLoadedAssetList() {
+        return JSON.stringify(extractAssetListFromManager(this), null, 3);
+    }
+
+    /**
+     * @param {String} path
+     * @param {String} type
+     * @param {AssetRequestScope} [scope]
+     * @param {boolean} [skip_queue] if true will skip the queue and dispatch request immediately
+     * @param {function(loaded:number, total:number)} [progress]
+     * @returns {Promise<Asset>}
+     */
+    promise(path, type, { scope, skip_queue = false, progress } = {}) {
+        return new Promise((resolve, reject) => {
+            this.get({
+                path,
+                type,
+                callback: resolve,
+                failure: reject,
+                progress,
+                skip_queue,
+                scope
+            });
+        });
+    }
+
+    /**
+     * @template T
+     * @param {String} path
+     * @param {String} type
+     * @param {function(asset:Asset<T>)} [callback] success callback
+     * @param {function(reason:*)} [failure]
+     * @param {function(loaded:number, total:number)} [progress]
+     * @param {boolean} [skip_queue]
+     * @param {AssetRequestScope} [scope]
+     */
+    get({
+            path,
+            type,
+            callback = noop,
+            failure = console.error,
+            progress = noop,
+            skip_queue = false,
+            scope = null
+        }) {
+
+        if (typeof path !== "string") {
+            throw new TypeError(`Path must be string. instead was '${typeof path}'`);
+        }
+
+        if (typeof type !== "string") {
+            throw new TypeError(`type must be a string, instead was '${typeof type}'`);
+        }
+
+        assert.isFunction(callback, 'success');
+        assert.isFunction(failure, 'failure');
+        assert.isFunction(progress, 'progress');
+
+        const assetDescription = new AssetDescription(path, type);
+
+        // requests made from inside an active load are recorded as dependencies of that load
+        const parent_pending = this.#find_enclosing_load(scope);
+
+        if (parent_pending !== null) {
+            parent_pending.addChild(assetDescription);
+        }
+
+        const asset = this.assets.get(assetDescription);
+
+        if (asset !== undefined) {
+
+            // already exists, dispatch callback immediately
+            callback(asset);
+
+            return;
+        }
+
+        // a request for an asset that is an ancestor of this request can never resolve
+        const cycle = this.#find_request_cycle(scope, assetDescription);
+
+        if (cycle !== null) {
+            const request = new AssetRequest(callback, failure, progress);
+
+            this.#schedule_response(request, new Error(`Cyclic asset request: ${cycle}`), false, assetDescription);
+
+            return;
+        }
+
+        //create request object
+        const assetRequest = new AssetRequest(callback, failure, progress);
+
+        assetRequest.scope = scope;
+        assetRequest.writeFlag(AssetRequestFlags.SkipQueue, skip_queue);
+
+        //submit request
+        this.submitRequest(assetDescription, assetRequest, parent_pending);
+    }
+
+    /**
+     * Checks if an asset is currently being loaded.
+     * Useful for avoiding redundant requests.
+     *
+     * @param {string} path
+     * @param {string} type
+     * @return {boolean}
+     */
+    isPending(path, type) {
+        const assetDescription = new AssetDescription(path, type);
+        return this.request_map.has(assetDescription);
+    }
+
+
+    /**
+     * Whether the most recent load attempt for the asset failed.
+     * Advisory only: a new {@link get} will still retry the load.
+     * @param {string} path
+     * @param {string} type
+     * @returns {boolean}
+     * @see isPending
+     */
+    isFailed(path, type) {
+        const ad = new AssetDescription(path, type);
+
+        return this.#failures.has(ad);
+    }
+
+    /**
+     * Checks if an asset is loaded.
+     * If the asset is loaded, calls to {@link tryGet} are guaranteed to succeed.
+     *
+     * @param {string} path
+     * @param {string} type
+     * @return {boolean}
+     */
+    isLoaded(path, type) {
+        const ad = new AssetDescription(path, type);
+
+        return this.assets.has(ad);
+    }
+
+    /**
+     * Same as {@link insert}, but will register the asset as pending until loader function resolves.
+     *
+     * NOTE: {@link AssetTransformer}s are not applied to the asset
+     *
+     * NOTE: any subsequent normal requests such as {@link get} will be routed to the same loader
+     *
+     * @template T
+     * @param {string} path
+     * @param {string} type
+     * @param {function(progress?:function(current:number, total:number)):Promise<Asset<T>>} loader
+     * @returns {Promise<Asset<T>>} loaded asset
+     * @see insert
+     * @example
+     *   manager.insertAsync('path/to/asset', 'my-type', async (progress) => {
+     *       const asset = await loadAssetFromNetwork('path/to/asset', 'type', progress);
+     *       return asset;
+     *   });
+     *
+     */
+    insertAsync(path, type, loader) {
+
+        const asset_descriptor = new AssetDescription(path, type);
+
+        if (this.request_map.get(asset_descriptor)) {
+            throw new Error(`Asset with path '${path}' and type '${type}' is already pending`);
+        }
+
+        const pending = new PendingAsset(asset_descriptor);
+
+        // resolution comes from the supplied loader function, there is nothing for the manager to dispatch
+        pending.dispatchable = false;
+
+        this.request_map.set(asset_descriptor, pending);
+
+        /**
+         *
+         * @param {number} current
+         * @param {number} total
+         */
+        const progress = (current, total) => {
+            pending.progress.setValue(current);
+            pending.progress.setUpperLimit(total);
+        };
+
+        let asset_promise;
+
+        try {
+            asset_promise = loader(progress);
+        } catch (e) {
+            this.request_map.delete(asset_descriptor);
+
+            // the deleted entry may have been the last outstanding work
+            this.#flush_drain_waiters();
+
+            throw e;
+        }
+
+        return asset_promise.then(asset => {
+            const existing = this.request_map.get(asset_descriptor);
+
+            if (existing !== pending) {
+                // looks like another resolution is pending, this completely invalidates current insersion request
+                // Likely reason is that something else was inserted later on
+                throw new Error(`Race condition. Asset with path '${path}' and type '${type}' was already resolved somewhere else.`);
+            }
+
+            this.insert(path, type, asset);
+
+            return asset;
+        }, error => {
+            const existing = this.request_map.get(asset_descriptor);
+
+            if (existing === pending) {
+                // deliver the failure to any requests that attached while the insertion was pending
+                pending.resolution_claimed = true;
+                this.#settle(pending, AssetLoadState.Failed, error);
+            }
+
+            //rethrow
+            throw error;
+        });
+    }
+
+    /**
+     * Manually add a fully resolved resource.
+     * If a load for the same description is in flight, it is squashed: the inserted asset wins,
+     * all accumulated requests are answered with it exactly once, and the loader's late resolution is dropped.
+     *
+     * NOTE: {@link AssetTransformer}s are not applied to the asset
+     *
+     * @template T
+     * @param {string} path
+     * @param {string} type
+     * @param {Asset<T>} asset
+     */
+    insert(path, type, asset) {
+        assert.isString(path, 'path');
+        assert.isString(type, 'type');
+        assert.isObject(asset, 'asset');
+
+        const asset_descriptor = new AssetDescription(path, type);
+
+        const existing_resource = this.assets.get(asset_descriptor);
+
+        if (existing_resource !== undefined && existing_resource !== asset) {
+            console.warn(`Another asset under ${asset_descriptor} already exists and will be replaced`);
+        }
+
+        // check for assets in-flight
+        const pending = this.request_map.get(asset_descriptor);
+
+        if (pending !== undefined) {
+            // squash the load in-flight: block the loader from claiming the resolution later
+            pending.resolution_claimed = true;
+
+            // if the load is still waiting in the queue there is no point dispatching it anymore
+            this.#pending_asset_wait_queue.delete(pending);
+
+            this.#settle(pending, AssetLoadState.Succeeded, asset);
+        } else {
+            // link asset description
+            asset.description = asset_descriptor;
+
+            // clear failures
+            this.#failures.delete(asset_descriptor);
+
+            this.assets.set(asset_descriptor, asset);
+        }
+    }
+
+    /**
+     *
+     * @param {Response} response
+     * @private
+     */
+    #process_response(response) {
+        const request = response.request;
+
+        if (response.success) {
+
+            try {
+                request.successCallback(response.value);
+            } catch (e) {
+                console.error(`Asset success callback raised an exception. AD:${response.description}`, e);
+            }
+
+        } else {
+
+            const failureCallback = request.failureCallback;
+
+            if (typeof failureCallback === "function") {
+                try {
+                    failureCallback(response.value);
+                } catch (e) {
+                    console.error(`Asset failure callback raised an exception. AD:${response.description}`, e);
+                }
+            } else {
+                //uncaught
+                console.error(`Uncaught asset load failure. AD:${response.description}`, response.value);
+            }
+
+        }
+    }
+
+    /**
+     *
+     * @param {AssetRequest} request
+     * @param {Asset|*} value
+     * @param {boolean} success
+     * @param {AssetDescription} description
+     * @private
+     */
+    #schedule_response(request, value, success, description) {
+        // technically you can schedule responses just fine, but commonly the user forgets to call 'startup' and so nothing happens which is perceived as a bug.
+        assert.equal(this.#is_running, true, 'AssetManager must be running to schedule responses');
+
+        this.#response_queue.add(new Response(request, value, success, description));
+
+        this.#wake_response_processor();
+    }
+
+    /**
+     *
+     * @param {PendingAsset} asset
+     * @private
+     */
+    #schedule_load(asset) {
+        if (this.#pending_asset_active_load_set.size < this.load_concurrency) {
+            this.#dispatch_pending_asset(asset);
+        } else {
+            asset.state = AssetLoadState.Queued;
+
+            this.#pending_asset_wait_queue.push(asset);
+        }
+    }
+
+    /**
+     * Force load of the asset
+     * @param {PendingAsset} asset
+     * @private
+     */
+    #force_load(asset) {
+        // externally resolved pending assets (see insertAsync) have no loader run to expedite
+        if (!asset.dispatchable) {
+            return;
+        }
+
+        // check if the asset is already being loaded
+        if (this.#pending_asset_active_load_set.has(asset)) {
+            return;
+        }
+
+        // remove from queue
+        this.#pending_asset_wait_queue.delete(asset);
+
+        // dispatch
+        this.#dispatch_pending_asset(asset);
+
+    }
+
+    /**
+     * Bookkeeping for a pending asset that reached a terminal state: de-register it everywhere
+     * and pull more work from the wait queue.
+     * @param {PendingAsset} pending_asset
+     * @private
+     */
+    #handle_asset_resolved(pending_asset) {
+        const active_set = this.#pending_asset_active_load_set;
+
+        // the map entry may already belong to a different pending asset (the load was squashed
+        // by an insert and a new request batch started since); only remove our own registration
+        if (this.request_map.get(pending_asset.description) === pending_asset) {
+            this.request_map.delete(pending_asset.description);
+        }
+
+        active_set.delete(pending_asset);
+
+        const dispatch_scope = pending_asset.dispatch_scope;
+
+        if (dispatch_scope !== null) {
+            this.#active_load_scopes.delete(dispatch_scope);
+        }
+
+        const queue = this.#pending_asset_wait_queue;
+
+        // schedule more if possible
+        while (!queue.isEmpty() && active_set.size < this.load_concurrency) {
+            const load = queue.pop();
+
+            this.#dispatch_pending_asset(load);
+        }
+    }
+
+    /**
+     * Single termination point for a pending asset. Exactly one resolution wins; the rest are dropped.
+     * All bookkeeping happens here, in a fixed order, before any requester callback is delivered.
+     * @param {PendingAsset} pendingAsset
+     * @param {AssetLoadState} state {@link AssetLoadState.Succeeded} or {@link AssetLoadState.Failed}
+     * @param {Asset|*} value loaded asset when succeeded, error otherwise
+     * @returns {boolean} false if the pending asset was already resolved and this resolution lost
+     * @private
+     */
+    #settle(pendingAsset, state, value) {
+        const current_state = pendingAsset.state;
+
+        if (current_state === AssetLoadState.Succeeded || current_state === AssetLoadState.Failed) {
+            console.warn(`Asset already resolved, late resolution dropped. AD:${pendingAsset.description}`);
+            return false;
+        }
+
+        pendingAsset.state = state;
+
+        const assetDescription = pendingAsset.description;
+
+        if (state === AssetLoadState.Succeeded) {
+            // link asset description
+            value.description = assetDescription;
+
+            // record dependencies gathered from nested requests made during the load
+            if (pendingAsset.children.length > 0) {
+                value.dependencies = pendingAsset.children;
+            }
+
+            // clear possible failure
+            this.#failures.delete(assetDescription);
+
+            // register asset
+            this.assets.set(assetDescription, value);
+        } else {
+            // record failure
+            this.#failures.add(assetDescription);
+        }
+
+        this.#handle_asset_resolved(pendingAsset);
+
+        // deliver responses
+        const requests = pendingAsset.requests;
+        const success = state === AssetLoadState.Succeeded;
+
+        for (let i = 0; i < requests.length; i++) {
+            this.#schedule_response(requests[i], value, success, assetDescription);
+        }
+
+        if (requests.length === 0) {
+            // nothing was scheduled for delivery (e.g. an insertAsync pending with no requesters),
+            // so the response processor will not run; this settle may have been the last outstanding work
+            this.#flush_drain_waiters();
+        }
+
+        return true;
+    }
+
+    /**
+     * Finalize a successful load: apply the transform chain, then settle.
+     * A broken transform chain fails the request instead of hanging it.
+     * @param {PendingAsset} pendingAsset
+     * @param {Asset} loaded_asset
+     * @returns {Promise<void>}
+     * @private
+     */
+    async #finalize_success(pendingAsset, loaded_asset) {
+        const assetDescription = pendingAsset.description;
+
+        let asset = loaded_asset;
+
+        try {
+            // apply the transform chain
+            const transformers = this.#transformers[assetDescription.type];
+
+            if (transformers !== undefined) {
+                const transformer_count = transformers.length;
+
+                for (let i = 0; i < transformer_count; i++) {
+                    const transformer = transformers[i];
+
+                    const transformed_asset = await transformer.transform(asset, assetDescription);
+
+                    if (typeof transformed_asset !== "object" || transformed_asset === null) {
+                        console.error('Transformer produced invalid result. Ignoring result.', transformer, assetDescription);
+                    } else {
+                        asset = transformed_asset;
+                    }
+                }
+            }
+        } catch (e) {
+            this.#settle(pendingAsset, AssetLoadState.Failed, e);
+
+            return;
+        }
+
+        this.#settle(pendingAsset, AssetLoadState.Succeeded, asset);
+    }
+
+    /**
+     * Returns the in-flight load that the given request scope belongs to, or null if the scope
+     * does not descend from any active load (i.e. the request is top-level).
+     * @param {AssetRequestScope|null} scope
+     * @returns {PendingAsset|null}
+     * @private
+     */
+    #find_enclosing_load(scope) {
+        if (scope === null || this.#active_load_scopes.size === 0) {
+            return null;
+        }
+
+        const active = this.#active_load_scopes;
+
+        const visited = new Set();
+        const stack = [scope];
+
+        while (stack.length > 0) {
+            const s = stack.pop();
+
+            if (visited.has(s)) {
+                continue;
+            }
+
+            visited.add(s);
+
+            const pending = active.get(s);
+
+            if (pending !== undefined) {
+                return pending;
+            }
+
+            const sources = s.sources;
+            for (let i = 0; i < sources.length; i++) {
+                stack.push(sources[i]);
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Detects a request for an asset that is itself an ancestor of the request (load cycle).
+     * @param {AssetRequestScope|null} scope
+     * @param {AssetDescription} description
+     * @returns {string|null} human-readable chain from the requested asset down to the requester, or null when there is no cycle
+     * @private
+     */
+    #find_request_cycle(scope, description) {
+        if (scope === null || this.#active_load_scopes.size === 0) {
+            return null;
+        }
+
+        const visited = new Set();
+
+        /**
+         *
+         * @param {AssetRequestScope} s
+         * @returns {AssetDescription[]|null}
+         */
+        function find(s) {
+            if (visited.has(s)) {
+                return null;
+            }
+
+            visited.add(s);
+
+            if (s.description !== null && s.description.equals(description)) {
+                return [s.description];
+            }
+
+            const sources = s.sources;
+            for (let i = 0; i < sources.length; i++) {
+                const chain = find(sources[i]);
+
+                if (chain !== null) {
+                    if (s.description !== null) {
+                        chain.push(s.description);
+                    }
+
+                    return chain;
+                }
+            }
+
+            return null;
+        }
+
+        // `find` builds the chain ancestor-first: [offender, ..., immediate parent]
+        const chain = find(scope);
+
+        if (chain === null) {
+            return null;
+        }
+
+        chain.push(description);
+
+        return chain.join(' -> ');
+    }
+
+    /**
+     * Dispatch load request to relevant loader
+     * @param {PendingAsset} pendingAsset
+     * @private
+     */
+    #dispatch_pending_asset(pendingAsset) {
+        const requests = pendingAsset.requests;
+        const assetDescription = pendingAsset.description;
+        const type = assetDescription.type;
+        const path = assetDescription.path;
+
+        pendingAsset.state = AssetLoadState.Loading;
+
+        const loader = this.#loaders[type];
+
+        if (loader === undefined) {
+            // no loader
+            this.#settle(
+                pendingAsset,
+                AssetLoadState.Failed,
+                new Error(`no loader exists for asset type '${type}', valid types are: ${Object.keys(this.#loaders).join(', ')}`)
+            );
+
+            return;
+        }
+
+        // mark as being loaded
+        this.#pending_asset_active_load_set.add(pendingAsset);
+
+        // build the dispatch scope; it identifies this load for requests made by the loader (nested requests)
+        const scope = new AssetRequestScope();
+
+        scope.description = assetDescription;
+
+        for (let i = 0; i < requests.length; i++) {
+            const request_scope = requests[i].scope;
+
+            if (request_scope !== null) {
+                array_push_if_unique(scope.sources, request_scope);
+            }
+        }
+
+        pendingAsset.dispatch_scope = scope;
+        this.#active_load_scopes.set(scope, pendingAsset);
+
+        /**
+         *
+         * @param {Asset} loaded_asset
+         */
+        const success = (loaded_asset) => {
+            if (pendingAsset.resolution_claimed) {
+                console.warn(`Asset resolution already claimed, success invocation ignored. AD:${assetDescription}`);
+                return;
+            }
+
+            pendingAsset.resolution_claimed = true;
+
+            this.#finalize_success(pendingAsset, loaded_asset);
+        }
+
+        const failure = (error) => {
+            if (pendingAsset.resolution_claimed) {
+                console.warn(`Asset resolution already claimed, failure invocation ignored. AD:${assetDescription}`);
+                return;
+            }
+
+            pendingAsset.resolution_claimed = true;
+
+            this.#settle(pendingAsset, AssetLoadState.Failed, error);
+        }
+
+        function progress(current, total) {
+            const request_count = requests.length;
+
+            for (let i = 0; i < request_count; i++) {
+                const progressCallback = requests[i].progressCallback;
+
+                if (typeof progressCallback !== "function") {
+                    //progress callback is not a function, ignore
+                    continue;
+                }
+
+                try {
+                    progressCallback(current, total);
+                } catch (e) {
+                    console.error("Failed to execute asset progress callback", e);
+                }
+            }
+
+            pendingAsset.progress.setValue(current);
+            pendingAsset.progress.setUpperLimit(total);
+        }
+
+        try {
+
+            const result = loader.load(scope, path, success, failure, progress);
+
+            if (result instanceof Promise) {
+                // allow promise responses
+                result.catch(failure);
+            }
+
+        } catch (e) {
+            console.error(`Loader failed on invocation. path=${path}, type=${type}`, 'Loader exception: ', e);
+            failure(e);
+        }
+    }
+
+    /**
+     *
+     * @param {AssetDescription} assetDescription
+     * @param {AssetRequest} request
+     * @param {PendingAsset|null} [parent_pending] the in-flight load this request was made from, if any
+     * @private
+     */
+    submitRequest(assetDescription, request, parent_pending = null) {
+        const requestMap = this.request_map;
+
+        let pendingAsset = requestMap.get(assetDescription);
+
+        const is_new = pendingAsset === undefined;
+
+        if (is_new) {
+            pendingAsset = new PendingAsset(assetDescription);
+            requestMap.set(assetDescription, pendingAsset);
+        }
+
+        pendingAsset.requests.push(request);
+
+        // a nested request must not wait behind the concurrency limit: its parent occupies a
+        // slot until this request resolves, so queueing it could deadlock
+        const expedite = parent_pending !== null || request.getFlag(AssetRequestFlags.SkipQueue);
+
+        if (is_new) {
+
+            if (expedite) {
+                this.#force_load(pendingAsset);
+            } else {
+                this.#schedule_load(pendingAsset);
+            }
+
+        } else {
+            // update priority queue if necessary
+            this.#pending_asset_wait_queue.updateElementScore(pendingAsset);
+
+            if (expedite) {
+                this.#force_load(pendingAsset);
+            }
+        }
+    }
+
+
+    /**
+     *
+     * @param {string} type
+     * @return {boolean}
+     */
+    hasLoaderForType(type) {
+        return this.getLoaderByType(type) !== undefined;
+    }
+
+    /**
+     *
+     * @param {string} type
+     * @returns {AssetLoader|undefined}
+     */
+    getLoaderByType(type) {
+        assert.isString(type, 'type');
+
+        return this.#loaders[type];
+    }
+
+    /**
+     *
+     * @param {string} type
+     * @return {AssetDescription[]}
+     * @private
+     */
+    #getLoadedAssetDescriptorsByType(type) {
+        const loaded_assets = Array.from(this.assets.keys());
+        return loaded_assets.filter(t => t.type === type);
+    }
+
+    /**
+     * Transformer will be applied to all assets of the given type in order of registration.
+     *
+     * Does not apply retroactively, assets that were already loaded will not be transformed.
+     *
+     * @template T
+     * @param {string} type
+     * @param {AssetTransformer<T>} transformer
+     * @returns {void}
+     * @see removeTransformer
+     */
+    registerTransformer(type, transformer) {
+        let transformers = this.#transformers[type];
+
+        if (transformers === undefined) {
+            transformers = [];
+
+            this.#transformers[type] = transformers;
+        }
+
+        transformers.push(transformer);
+
+        // check for loaded assets
+        const matching_assets = this.#getLoadedAssetDescriptorsByType(type);
+
+        if (matching_assets.length > 0) {
+            console.warn(`Following assets of matching type '${type}' are already loaded and transform is not applied to them:\n\t${matching_assets.join('\n\t')}`);
+        }
+
+    }
+
+    /**
+     * @template T
+     * @param {string} type
+     * @param {AssetTransformer<T>} transformer
+     * @returns {boolean} true if removed, false if not found
+     * @see registerTransformer
+     */
+    unregisterTransformer(type, transformer) {
+
+        const transformers = this.#transformers[type];
+
+        if (transformers === undefined) {
+            // not found
+            return false;
+        }
+
+        if (!array_remove_first(transformers, transformer)) {
+            // not found
+            return false;
+        }
+
+        // check for loaded assets
+        const matching_assets = this.#getLoadedAssetDescriptorsByType(type);
+
+        if (matching_assets.length > 0) {
+            console.warn(`Following assets of matching type '${type}' are already loaded and transform was probably already applied to them:\n\t${matching_assets.join('\n\t')}`);
+        }
+
+        return true;
+    }
+
+    /**
+     * Will register loader only if none exists for this type
+     * @template T
+     * @param {string} type
+     * @param {AssetLoader<T>} loader
+     * @returns {Promise<boolean>} true if registered, false otherwise
+     */
+    async tryRegisterLoader(type, loader) {
+        if (this.hasLoaderForType(type)) {
+            return false;
+        }
+
+        await this.registerLoader(type, loader);
+
+        return true;
+    }
+
+    /**
+     * @template T
+     * @param {string} type
+     * @param {AssetLoader<T>} loader
+     * @throws {Error} if a loader is already registered for the given type
+     */
+    async registerLoader(type, loader) {
+        assert.isString(type, 'type');
+
+        const existing_loader = this.getLoaderByType(type);
+
+        if (existing_loader !== undefined) {
+            if (existing_loader === loader) {
+                // all is well, already registered
+                return existing_loader;
+            } else if (Object.getPrototypeOf(existing_loader) === Object.getPrototypeOf(loader)) {
+                console.warn(`Another instance of this loader is already registered for type '${type}'. Ignoring.`);
+                return existing_loader;
+            } else {
+                throw new Error(`Loader for type '${type}' is already registered`);
+            }
+        }
+
+
+        let _loader = loader;
+
+        if (typeof _loader === "function") {
+
+            // legacy function-based loader with signature (path, success, failure, progress):
+            // adapt to the AssetLoader contract, resolving the network path on its behalf
+            _loader = new AssetLoader();
+            _loader.load = (scope, path, success, failure, progress) => loader(this.resolveNetworkPath(path), success, failure, progress);
+
+            console.warn(`function-based loaders are deprecated (${type})`);
+
+        }
+
+        await _loader.link(this, this.#context);
+
+        this.#loaders[type] = _loader;
+
+        return _loader;
+    }
+
+    /**
+     *
+     * @param {string} type
+     */
+    async unregisterLoader(type) {
+        const loader = this.getLoaderByType(type);
+
+        if (loader === undefined) {
+            // asset loader is not registered, nothing to do
+            return;
+
+        }
+
+        // first remove the loader from registry so no further asset requests can be made
+        delete this.#loaders[type];
+
+        // TODO address all pending requests, possibly waiting for all of them to finalize
+
+        // finally unlink the loader
+        await loader.unlink();
+    }
+
+    /**
+     * Retrieve an asset if it is loaded, returns null if the asset is not loaded.
+     * Does not trigger loading if the asset is not loaded.
+     * @template T
+     * @param {String} path
+     * @param {String} type
+     * @returns {Asset<T>|null}
+     */
+    tryGet(path, type) {
+        const assetDescription = new AssetDescription(path, type);
+
+        const asset = this.assets.get(assetDescription);
+
+        if (asset !== undefined) {
+            return asset;
+        } else {
+            return null;
+        }
+    }
+
+    /**
+     * @template T
+     * @param {string} alias
+     * @return {Promise<Asset<T>>}
+     */
+    promiseByAlias(alias) {
+        assert.isString(alias, 'alias');
+
+        // resolve alias
+        const assetDescription = this.#aliases.get(alias);
+
+        if (assetDescription === undefined) {
+            return Promise.reject(new Error(`Alias '${alias}' not found`));
+        }
+
+        return this.promise(assetDescription.path, assetDescription.type);
+    }
+
+    /**
+     *
+     * @param {string} alias
+     * @return {AssetDescription|undefined}
+     */
+    resolveAlias(alias) {
+
+        // todo consider cloning result to protect against mutation
+
+        return this.#aliases.get(alias);
+
+    }
+
+    /**
+     *
+     * @param {string} alias
+     * @param {string} path
+     * @param {string} type
+     */
+    assignAlias(alias, path, type) {
+        assert.isString(alias, 'alias');
+        assert.isString(path, 'path');
+        assert.isString(type, 'type');
+
+        const assetDescription = new AssetDescription(path, type);
+
+        this.#aliases.set(alias, assetDescription);
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+AssetManager.prototype.isAssetManager = true;