From a10168476ed7f3fbc3b85f94576a9ecb220a91f7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 18 Mar 2026 20:58:07 +0000
Subject: [PATCH 1/2] Initial plan


From 9913f8da97a6be616632158570faa2b7c381a10f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 18 Mar 2026 21:02:45 +0000
Subject: [PATCH 2/2] feat(asset-loading): return null on cache miss instead of
 throwing

Co-authored-by: stormmuller <17644200+stormmuller@users.noreply.github.com>
---
 src/asset-loading/asset-cache.ts              |  4 ++--
 .../asset-caches/image-cache.test.ts          |  6 ++---
 src/asset-loading/asset-caches/image-cache.ts | 22 +++++++++----------
 3 files changed, 15 insertions(+), 17 deletions(-)

diff --git a/src/asset-loading/asset-cache.ts b/src/asset-loading/asset-cache.ts
index 864c0c45..bb29d5f3 100644
--- a/src/asset-loading/asset-cache.ts
+++ b/src/asset-loading/asset-cache.ts
@@ -12,9 +12,9 @@ export interface AssetCache<T> {
   /**
    * Retrieves an asset from the cache.
    * @param key - The key of the asset to retrieve.
-   * @returns The cached asset.
+   * @returns The cached asset, or null if not found in the cache.
    */
-  get: (key: string) => T;
+  get: (key: string) => T | null;
 
   /**
    * Loads an asset from the specified key and caches it.
diff --git a/src/asset-loading/asset-caches/image-cache.test.ts b/src/asset-loading/asset-caches/image-cache.test.ts
index b2f3b0bd..c95b1743 100644
--- a/src/asset-loading/asset-caches/image-cache.test.ts
+++ b/src/asset-loading/asset-caches/image-cache.test.ts
@@ -12,12 +12,10 @@ describe('ImageCache', () => {
     expect(retrievedImage).toBe(mockImage);
   });
 
-  it('should throw an error if the image is not found in the cache', () => {
+  it('should return null if the image is not found in the cache', () => {
     const imageCache = new ImageCache();
 
-    expect(() => imageCache.get('path/to/nonexistent.png')).toThrow(
-      'Image with path "path/to/nonexistent.png" not found in store.',
-    );
+    expect(imageCache.get('path/to/nonexistent.png')).toBeNull();
   });
 
   it('should load and cache an image', async () => {
diff --git a/src/asset-loading/asset-caches/image-cache.ts b/src/asset-loading/asset-caches/image-cache.ts
index 9655f32c..161f6dc5 100644
--- a/src/asset-loading/asset-caches/image-cache.ts
+++ b/src/asset-loading/asset-caches/image-cache.ts
@@ -9,17 +9,10 @@ export class ImageCache implements AssetCache<HTMLImageElement> {
   /**
    * Retrieves an image from the cache.
    * @param path - The path of the image to retrieve.
-   * @returns The cached image element.
-   * @throws Will throw an error if the image is not found in the cache.
+   * @returns The cached image element, or null if not found in the cache.
    */
-  public get(path: string): HTMLImageElement {
-    const image = this.assets.get(path);
-
-    if (!image) {
-      throw new Error(`Image with path "${path}" not found in store.`);
-    }
-
-    return image;
+  public get(path: string): HTMLImageElement | null {
+    return this.assets.get(path) ?? null;
   }
 
   /**
@@ -53,12 +46,19 @@ export class ImageCache implements AssetCache<HTMLImageElement> {
    * Retrieves an image from the cache if it exists, otherwise loads and caches it.
    * @param path - The path of the image to retrieve or load.
    * @returns A promise that resolves to the image element.
+   * @throws Will throw an error if the image fails to load.
    */
   public async getOrLoad(path: string): Promise<HTMLImageElement> {
     if (!this.assets.has(path)) {
       await this.load(path);
     }
 
-    return this.get(path);
+    const image = this.get(path);
+
+    if (image === null) {
+      throw new Error(`Image with path "${path}" not found in store.`);
+    }
+
+    return image;
   }
 }