@flighthq/assets 0.1.0

package/dist/assetLibrary.d.ts

@@ -0,0 +1,12 @@
+import type { AssetGroupLoadOptions, AssetLibrary, AssetLoaderAdapter, AssetManifest, AssetType } from '@flighthq/types';
+export declare function acquireAsset<T = unknown>(library: Readonly<AssetLibrary>, id: string): Promise<T>;
+export declare function createAssetLibrary(): AssetLibrary;
+export declare function disposeAssetLibrary(library: Readonly<AssetLibrary>): void;
+export declare function getAsset<T = unknown>(library: Readonly<AssetLibrary>, id: string): T | null;
+export declare function getAssetRefCount(library: Readonly<AssetLibrary>, id: string): number;
+export declare function loadAssetGroup(library: Readonly<AssetLibrary>, name: string, options?: Readonly<AssetGroupLoadOptions>): Promise<void>;
+export declare function loadAssetManifest(library: Readonly<AssetLibrary>, manifest: AssetManifest): void;
+export declare function registerAssetLoader<T>(library: Readonly<AssetLibrary>, type: AssetType, adapter: Readonly<AssetLoaderAdapter<T>>): void;
+export declare function releaseAsset(library: Readonly<AssetLibrary>, id: string): void;
+export declare function releaseAssetGroup(library: Readonly<AssetLibrary>, name: string): void;
+//# sourceMappingURL=assetLibrary.d.ts.map

package/dist/assetLibrary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetLibrary.d.ts","sourceRoot":"","sources":["../src/assetLibrary.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,qBAAqB,EACrB,YAAY,EAEZ,kBAAkB,EAClB,aAAa,EACb,SAAS,EACV,MAAM,iBAAiB,CAAC;AAQzB,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAkCjG;AAKD,wBAAgB,kBAAkB,IAAI,YAAY,CAQjD;AAID,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI,CAYzE;AAID,wBAAgB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAG3F;AAID,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAGpF;AAOD,wBAAsB,cAAc,CAClC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAID,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAYhG;AAKD,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC/B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACvC,IAAI,CAEN;AAKD,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAO9E;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIrF"}

package/dist/assetLibrary.js

@@ -0,0 +1,176 @@
+import { createResourceLoader, disposeResourceLoader, queueResourceLoad, startResourceLoad } from '@flighthq/loader';
+import { connectSignal, emitSignal } from '@flighthq/signals';
+// Increments the reference count for `id` and resolves its loaded value. If the asset is already
+// resident, resolves immediately. If a load is already in flight (a concurrent acquire), the same
+// promise is shared, so exactly one adapter.load runs per id (dedup). Otherwise the descriptor is
+// resolved to its type's adapter and the load begins, storing the value at reference count one.
+// Rejects (an async sentinel, not a throw) when no descriptor is recorded for the id or no adapter is
+// registered for its type — the two misuse cases the library cannot recover from on its own.
+export function acquireAsset(library, id) {
+    const runtime = library.runtime;
+    const descriptor = runtime.descriptors.get(id);
+    if (descriptor === undefined) {
+        return Promise.reject(new Error(`assets: no descriptor for id "${id}" (loadAssetManifest first)`));
+    }
+    const adapter = runtime.adapters.get(descriptor.type);
+    if (adapter === undefined) {
+        return Promise.reject(new Error(`assets: no loader for type "${descriptor.type}" (registerAssetLoader first)`));
+    }
+    const existing = runtime.entries.get(id);
+    if (existing !== undefined) {
+        existing.refcount++;
+        if (existing.resident)
+            return Promise.resolve(existing.value);
+        // A load is in flight — share it so only one adapter.load runs per id.
+        return existing.loadPromise;
+    }
+    const entry = { value: undefined, refcount: 1, loadPromise: null, resident: false };
+    runtime.entries.set(id, entry);
+    const loadPromise = adapter.load(descriptor).then((value) => {
+        if (runtime.entries.get(id) !== entry || entry.refcount <= 0) {
+            // Released before the load settled — free the orphaned resource deterministically.
+            adapter.dispose(value);
+            return value;
+        }
+        entry.value = value;
+        entry.resident = true;
+        entry.loadPromise = null;
+        return value;
+    });
+    entry.loadPromise = loadPromise;
+    return loadPromise;
+}
+// Allocates an empty asset library — an open adapter registry, an empty descriptor map, an empty cache,
+// and an empty group index. Registers no adapters and knows how to load nothing until the caller opts
+// in with registerAssetLoader.
+export function createAssetLibrary() {
+    const runtime = {
+        adapters: new Map(),
+        descriptors: new Map(),
+        entries: new Map(),
+        groups: new Map(),
+    };
+    return { runtime };
+}
+// Disposes every resident asset through its registered adapter and empties the library — adapters,
+// descriptors, cache entries, and groups. Leaves the library reusable but stripped of all state.
+export function disposeAssetLibrary(library) {
+    const runtime = library.runtime;
+    for (const [id, entry] of runtime.entries) {
+        if (!entry.resident)
+            continue;
+        const descriptor = runtime.descriptors.get(id);
+        const adapter = descriptor !== undefined ? runtime.adapters.get(descriptor.type) : undefined;
+        if (adapter !== undefined)
+            adapter.dispose(entry.value);
+    }
+    runtime.adapters.clear();
+    runtime.descriptors.clear();
+    runtime.entries.clear();
+    runtime.groups.clear();
+}
+// Returns the resident value for `id` synchronously, or null if it is not loaded (never acquired, or
+// still loading). Never triggers a load — use acquireAsset for that.
+export function getAsset(library, id) {
+    const entry = library.runtime.entries.get(id);
+    return entry !== undefined && entry.resident ? entry.value : null;
+}
+// Returns the live holder count for `id`: how many acquires have not yet been matched by a release.
+// Zero for an id that was never acquired or has already been freed at reference count zero.
+export function getAssetRefCount(library, id) {
+    const entry = library.runtime.entries.get(id);
+    return entry !== undefined ? entry.refcount : 0;
+}
+// Preloads a named group through @flighthq/loader: every member that is not already resident is
+// scheduled as a loader item (bounded concurrency, aggregate progress via options.progress), and every
+// member is acquired (reference count incremented) so the whole group stays resident until
+// releaseAssetGroup. Resolves once all scheduled loads settle. A group with no recorded members
+// resolves immediately.
+export async function loadAssetGroup(library, name, options) {
+    const runtime = library.runtime;
+    const ids = runtime.groups.get(name);
+    if (ids === undefined || ids.length === 0)
+        return;
+    const loader = createResourceLoader();
+    const progress = options?.progress;
+    if (progress !== undefined) {
+        connectSignal(loader.onProgress, (loaded, total) => {
+            emitSignal(progress, { loaded, total });
+        });
+    }
+    for (const id of ids) {
+        const entry = runtime.entries.get(id);
+        if (entry !== undefined && entry.resident) {
+            // Already loaded — hold a group reference without scheduling a redundant load.
+            void acquireAsset(library, id);
+            continue;
+        }
+        // Route the actual load through the loader for bounded concurrency; acquireAsset dedups and holds
+        // the group's reference.
+        queueResourceLoad(loader, () => acquireAsset(library, id));
+    }
+    await new Promise((resolve) => {
+        connectSignal(loader.onComplete, () => resolve());
+        startResourceLoad(loader);
+    });
+    disposeResourceLoader(loader);
+}
+// Records every descriptor's id → descriptor mapping and its group membership. Does not load anything —
+// acquireAsset and loadAssetGroup perform the loads. Re-recording an id overwrites its descriptor.
+export function loadAssetManifest(library, manifest) {
+    const runtime = library.runtime;
+    for (const descriptor of manifest) {
+        runtime.descriptors.set(descriptor.id, descriptor);
+        if (descriptor.group === undefined)
+            continue;
+        let members = runtime.groups.get(descriptor.group);
+        if (members === undefined) {
+            members = [];
+            runtime.groups.set(descriptor.group, members);
+        }
+        if (!members.includes(descriptor.id))
+            members.push(descriptor.id);
+    }
+}
+// Binds an asset type to how it loads and how it frees. The registry is open and last-write-wins, so a
+// user adds their own (vendor-prefixed) types and can override a prior binding. The library depends on
+// no resource package; the adapter is where a concrete decoder is wired in.
+export function registerAssetLoader(library, type, adapter) {
+    library.runtime.adapters.set(type, adapter);
+}
+// Decrements the reference count for `id`. When it reaches zero the asset is immediately disposed
+// through its registered adapter and dropped from the cache (deterministic free). Releasing an id that
+// is not held — never acquired, or already freed at zero — is a no-op.
+export function releaseAsset(library, id) {
+    const runtime = library.runtime;
+    const entry = runtime.entries.get(id);
+    if (entry === undefined)
+        return;
+    entry.refcount--;
+    if (entry.refcount > 0)
+        return;
+    disposeAssetEntry(runtime, id, entry);
+}
+// Releases the group reference held by loadAssetGroup for each member, mirroring the per-member acquire
+// it performed. A member reaching reference count zero is disposed and dropped. A group with no
+// recorded members is a no-op.
+export function releaseAssetGroup(library, name) {
+    const ids = library.runtime.groups.get(name);
+    if (ids === undefined)
+        return;
+    for (const id of ids)
+        releaseAsset(library, id);
+}
+// Drops the cache entry and, when the asset actually decoded, frees it through its adapter. An entry
+// whose load never settled (released mid-flight) has nothing decoded to free; the in-flight load's own
+// continuation disposes the orphaned value once it resolves.
+function disposeAssetEntry(runtime, id, entry) {
+    runtime.entries.delete(id);
+    if (!entry.resident)
+        return;
+    const descriptor = runtime.descriptors.get(id);
+    const adapter = descriptor !== undefined ? runtime.adapters.get(descriptor.type) : undefined;
+    if (adapter !== undefined)
+        adapter.dispose(entry.value);
+}
+//# sourceMappingURL=assetLibrary.js.map

package/dist/assetLibrary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetLibrary.js","sourceRoot":"","sources":["../src/assetLibrary.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './assetLibrary';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './assetLibrary';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/assets",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/loader": "0.1.0",
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Id-keyed asset library over @flighthq/loader — manifests, group preload, refcounted ownership, and an open per-type loader registry",
+  "sideEffects": false
+}

package/src/assetLibrary.test.ts

@@ -0,0 +1,318 @@
+import { connectSignal, createSignal } from '@flighthq/signals';
+import type { AssetDescriptor, AssetLoadProgress, AssetManifest } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import {
+  acquireAsset,
+  createAssetLibrary,
+  disposeAssetLibrary,
+  getAsset,
+  getAssetRefCount,
+  loadAssetGroup,
+  loadAssetManifest,
+  registerAssetLoader,
+  releaseAsset,
+  releaseAssetGroup,
+} from './assetLibrary';
+
+// A mock loader adapter: counts load calls, records disposed values, and holds each load open until
+// flush() so tests can observe in-flight state (dedup, bounded concurrency). Each load resolves a
+// fresh, stable value object keyed by id, so identity assertions distinguish shared vs. re-loaded.
+function createMockAdapter() {
+  let loadCalls = 0;
+  let inFlight = 0;
+  let peak = 0;
+  const disposed: unknown[] = [];
+  const pending: Array<() => void> = [];
+
+  return {
+    adapter: {
+      load(descriptor: Readonly<AssetDescriptor>): Promise<{ id: string }> {
+        loadCalls++;
+        inFlight++;
+        peak = Math.max(peak, inFlight);
+        return new Promise<{ id: string }>((resolve) => {
+          pending.push(() => {
+            inFlight--;
+            resolve({ id: descriptor.id });
+          });
+        });
+      },
+      dispose(value: { id: string }): void {
+        disposed.push(value);
+      },
+    },
+    disposed,
+    flush(): void {
+      const wave = pending.splice(0);
+      for (const settle of wave) settle();
+    },
+    get inFlight() {
+      return inFlight;
+    },
+    get loadCalls() {
+      return loadCalls;
+    },
+    get peak() {
+      return peak;
+    },
+    get pendingCount() {
+      return pending.length;
+    },
+  };
+}
+
+// Registers `type`, records a one-descriptor manifest for `id`, and returns the mock so a test can
+// acquire and drive the load.
+function libraryWith(id: string, type = 'image') {
+  const library = createAssetLibrary();
+  const mock = createMockAdapter();
+  registerAssetLoader(library, type, mock.adapter);
+  loadAssetManifest(library, [{ id, url: `${id}.bin`, type }]);
+  return { library, mock };
+}
+
+// Runs pending microtasks so loader continuations settle between flush waves.
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe('acquireAsset', () => {
+  it('resolves the adapter loaded value and calls load once', async () => {
+    const { library, mock } = libraryWith('hero');
+    const promise = acquireAsset<{ id: string }>(library, 'hero');
+    expect(mock.loadCalls).toBe(1);
+    mock.flush();
+    const value = await promise;
+    expect(value).toEqual({ id: 'hero' });
+    expect(getAsset(library, 'hero')).toBe(value);
+  });
+
+  it('shares one in-flight load across concurrent acquires (dedup)', async () => {
+    const { library, mock } = libraryWith('hero');
+    const first = acquireAsset<{ id: string }>(library, 'hero');
+    const second = acquireAsset<{ id: string }>(library, 'hero');
+    expect(mock.loadCalls).toBe(1);
+    expect(getAssetRefCount(library, 'hero')).toBe(2);
+    mock.flush();
+    const [a, b] = await Promise.all([first, second]);
+    expect(a).toBe(b);
+    expect(getAsset(library, 'hero')).toBe(a);
+  });
+
+  it('rejects when no descriptor is recorded for the id', async () => {
+    const library = createAssetLibrary();
+    await expect(acquireAsset(library, 'missing')).rejects.toThrow(/no descriptor/);
+  });
+
+  it('rejects when no adapter is registered for the descriptor type', async () => {
+    const library = createAssetLibrary();
+    loadAssetManifest(library, [{ id: 'hero', url: 'hero.bin', type: 'image' }]);
+    await expect(acquireAsset(library, 'hero')).rejects.toThrow(/no loader/);
+  });
+});
+
+describe('createAssetLibrary', () => {
+  it('creates an empty library with no resident assets', () => {
+    const library = createAssetLibrary();
+    expect(getAsset(library, 'hero')).toBeNull();
+    expect(getAssetRefCount(library, 'hero')).toBe(0);
+  });
+});
+
+describe('disposeAssetLibrary', () => {
+  it('disposes every resident asset and empties the library', async () => {
+    const { library, mock } = libraryWith('hero');
+    await (() => {
+      const p = acquireAsset(library, 'hero');
+      mock.flush();
+      return p;
+    })();
+    // A second acquire on the same id shares the resident value (refcount 2, one loaded value).
+    await acquireAsset(library, 'hero');
+    expect(getAssetRefCount(library, 'hero')).toBe(2);
+
+    disposeAssetLibrary(library);
+    expect(mock.disposed).toEqual([{ id: 'hero' }]);
+    expect(getAsset(library, 'hero')).toBeNull();
+    expect(getAssetRefCount(library, 'hero')).toBe(0);
+  });
+});
+
+describe('getAsset', () => {
+  it('returns null before load and the value once resident', async () => {
+    const { library, mock } = libraryWith('hero');
+    expect(getAsset(library, 'hero')).toBeNull();
+    const promise = acquireAsset(library, 'hero');
+    // Still loading — not yet resident.
+    expect(getAsset(library, 'hero')).toBeNull();
+    mock.flush();
+    const value = await promise;
+    expect(getAsset(library, 'hero')).toBe(value);
+  });
+});
+
+describe('getAssetRefCount', () => {
+  it('counts acquires and drops to zero when freed', async () => {
+    const { library, mock } = libraryWith('hero');
+    const promise = acquireAsset(library, 'hero');
+    mock.flush();
+    await promise;
+    await acquireAsset(library, 'hero');
+    expect(getAssetRefCount(library, 'hero')).toBe(2);
+    releaseAsset(library, 'hero');
+    expect(getAssetRefCount(library, 'hero')).toBe(1);
+    releaseAsset(library, 'hero');
+    expect(getAssetRefCount(library, 'hero')).toBe(0);
+  });
+});
+
+describe('loadAssetGroup', () => {
+  it('preloads a group through the loader with bounded concurrency and aggregate progress', async () => {
+    const library = createAssetLibrary();
+    const mock = createMockAdapter();
+    registerAssetLoader(library, 'image', mock.adapter);
+
+    const count = 10;
+    const manifest: AssetManifest = Array.from({ length: count }, (_unused, i) => ({
+      id: `tile-${i}`,
+      url: `tile-${i}.bin`,
+      type: 'image',
+      group: 'level',
+    }));
+    loadAssetManifest(library, manifest);
+
+    const ticks: AssetLoadProgress[] = [];
+    const progress = createSignal<(p: Readonly<AssetLoadProgress>) => void>();
+    connectSignal(progress, (p) => {
+      ticks.push({ loaded: p.loaded, total: p.total });
+    });
+
+    const done = loadAssetGroup(library, 'level', { progress });
+    // The loader dispatches at most its default concurrency (6) at once.
+    expect(mock.peak).toBe(6);
+
+    let settled = false;
+    void done.then(() => {
+      settled = true;
+    });
+    while (!settled) {
+      mock.flush();
+      await tick();
+    }
+    await done;
+
+    expect(mock.loadCalls).toBe(count);
+    expect(mock.peak).toBeLessThanOrEqual(6);
+    for (let i = 0; i < count; i++) {
+      expect(getAsset(library, `tile-${i}`)).toEqual({ id: `tile-${i}` });
+      expect(getAssetRefCount(library, `tile-${i}`)).toBe(1);
+    }
+    expect(ticks[ticks.length - 1]).toEqual({ loaded: count, total: count });
+  });
+
+  it('resolves immediately for an unknown or empty group', async () => {
+    const library = createAssetLibrary();
+    await expect(loadAssetGroup(library, 'nope')).resolves.toBeUndefined();
+  });
+});
+
+describe('loadAssetManifest', () => {
+  it('records descriptors and group membership without loading', async () => {
+    const library = createAssetLibrary();
+    const mock = createMockAdapter();
+    registerAssetLoader(library, 'image', mock.adapter);
+    loadAssetManifest(library, [
+      { id: 'a', url: 'a.bin', type: 'image', group: 'boot' },
+      { id: 'b', url: 'b.bin', type: 'image', group: 'boot' },
+    ]);
+    // Nothing loaded from recording alone.
+    expect(mock.loadCalls).toBe(0);
+    expect(getAsset(library, 'a')).toBeNull();
+    // The recorded descriptor makes acquire resolvable.
+    const promise = acquireAsset(library, 'a');
+    mock.flush();
+    await promise;
+    expect(getAsset(library, 'a')).toEqual({ id: 'a' });
+  });
+});
+
+describe('registerAssetLoader', () => {
+  it('is last-write-wins for a type', async () => {
+    const library = createAssetLibrary();
+    const first = createMockAdapter();
+    const second = createMockAdapter();
+    registerAssetLoader(library, 'image', first.adapter);
+    registerAssetLoader(library, 'image', second.adapter);
+    loadAssetManifest(library, [{ id: 'hero', url: 'hero.bin', type: 'image' }]);
+    const promise = acquireAsset(library, 'hero');
+    second.flush();
+    await promise;
+    expect(first.loadCalls).toBe(0);
+    expect(second.loadCalls).toBe(1);
+  });
+});
+
+describe('releaseAsset', () => {
+  it('disposes and drops the asset at reference count zero', async () => {
+    const { library, mock } = libraryWith('hero');
+    const promise = acquireAsset(library, 'hero');
+    mock.flush();
+    const value = await promise;
+    await acquireAsset(library, 'hero');
+
+    releaseAsset(library, 'hero');
+    // Still held by the second acquire — not disposed.
+    expect(mock.disposed).toEqual([]);
+    expect(getAsset(library, 'hero')).toBe(value);
+
+    releaseAsset(library, 'hero');
+    // Last holder gone — disposed once and dropped.
+    expect(mock.disposed).toEqual([value]);
+    expect(getAsset(library, 'hero')).toBeNull();
+  });
+
+  it('is a no-op when releasing below zero', () => {
+    const { library, mock } = libraryWith('hero');
+    releaseAsset(library, 'hero');
+    releaseAsset(library, 'hero');
+    expect(mock.disposed).toEqual([]);
+    expect(getAssetRefCount(library, 'hero')).toBe(0);
+  });
+});
+
+describe('releaseAssetGroup', () => {
+  it('releases and disposes every group member', async () => {
+    const library = createAssetLibrary();
+    const mock = createMockAdapter();
+    registerAssetLoader(library, 'image', mock.adapter);
+    loadAssetManifest(library, [
+      { id: 'a', url: 'a.bin', type: 'image', group: 'level' },
+      { id: 'b', url: 'b.bin', type: 'image', group: 'level' },
+    ]);
+
+    const done = loadAssetGroup(library, 'level');
+    let settled = false;
+    void done.then(() => {
+      settled = true;
+    });
+    while (!settled) {
+      mock.flush();
+      await tick();
+    }
+    await done;
+
+    expect(getAssetRefCount(library, 'a')).toBe(1);
+    expect(getAssetRefCount(library, 'b')).toBe(1);
+
+    releaseAssetGroup(library, 'level');
+    expect(mock.disposed).toEqual([{ id: 'a' }, { id: 'b' }]);
+    expect(getAsset(library, 'a')).toBeNull();
+    expect(getAsset(library, 'b')).toBeNull();
+  });
+
+  it('is a no-op for an unknown group', () => {
+    const library = createAssetLibrary();
+    expect(() => releaseAssetGroup(library, 'nope')).not.toThrow();
+  });
+});