/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

/** Asset archive queries and cache management. */
interface AssetNamespace {
  // Loader type constants
  readonly TYPE_MESH:    number;
  readonly TYPE_TEXTURE: number;
  readonly TYPE_TILESET: number;
  readonly TYPE_LOCALE:  number;
  readonly TYPE_JSON:    number;
  readonly TYPE_SCRIPT:  number;

  // Mesh axis input constants (pass as `input` to lock with TYPE_MESH)
  readonly MESH_AXIS_Y_UP:   number;
  readonly MESH_AXIS_Z_UP:   number;
  readonly MESH_AXIS_X_UP:   number;
  readonly MESH_AXIS_Y_DOWN: number;
  readonly MESH_AXIS_Z_DOWN: number;
  readonly MESH_AXIS_X_DOWN: number;

  /**
   * Returns `true` if the given path exists in the asset archive (`dusk.dsk`).
   *
   * @param path - Archive-relative path, e.g. `"init.js"` or `"ui/hud.png"`.
   */
  exists(path: string): boolean;

  /**
   * Locks an entry in the asset cache and returns an `AssetEntry`.
   * The entry begins loading in the background. Call `entry.requireLoaded()`
   * to block until it is ready.
   *
   * The lock is released when the `AssetEntry` is GC'd or `entry.unlock()`
   * is called explicitly.
   *
   * @param path - Archive-relative path.
   * @param type  - Loader type constant (`Asset.TYPE_*`).
   * @param input - Optional loader-specific input constant.
   *                `TYPE_TEXTURE` → `Texture.FORMAT_*`
   *                `TYPE_MESH`    → `Asset.MESH_AXIS_*`
   *
   * @example
   * const entry = Asset.lock('data/map.json');
   * entry.requireLoaded();
   */
  lock(path: string, type: number, input?: number): AssetEntry;

  /**
   * Blocks until the given entry is fully loaded.
   * Returns the entry for chaining.
   * @throws If the load fails.
   *
   * @example
   * const entry = Asset.requireLoaded(Asset.lock('map.json', Asset.TYPE_JSON));
   */
  requireLoaded(entry: AssetEntry): AssetEntry;

  /**
   * Releases the lock on an asset by path.
   * Prefer calling `entry.unlock()` on the `AssetEntry` object directly.
   *
   * @param path - The path originally passed to `lock`.
   */
  unlock(path: string): void;
}

declare var Asset: AssetNamespace;