@hkdigital/lib-sveltekit 0.1.20 → 0.1.22

package/dist/classes/svelte/image/ImageScene.svelte.d.ts

@@ -1,78 +1,50 @@
-/**
- * @typedef {object} SourceConfig
- * // property ...
- */
-/**
- * @typedef {object} ImageSource
- * @property {string} label
- * @property {ImageLoader} imageLoader
- * @property {ImageMeta} [imageMeta]
- */
 export default class ImageScene {
-    state: string;
-    loaded: boolean;
-    destroy(): void;
     /**
-     * Add image source
-     * - Uses an ImageLoader instance to load image data from network
+     * Define an image to be managed by this scene
      *
-     * @param {object} _
-     * @param {string} _.label
-     * @param {ImageMeta|ImageMeta[]} _.imageMeta
+     * @param {object} params
+     * @param {string} params.label - Unique identifier for the image
+     * @param {ImageMeta|ImageMeta[]} params.imageMeta - Image metadata (single or variants)
      */
     defineImage({ label, imageMeta }: {
         label: string;
         imageMeta: ImageMeta | ImageMeta[];
     }): void;
     /**
-     * Start loading all image sources
+     * Start loading all defined images
      */
     load(): void;
     /**
-     * Get image scene loading progress
+     * Unload all images and free resources
      */
-    get progress(): {
-        totalBytesLoaded: number;
-        totalSize: number;
-        sourcesLoaded: number;
-        numberOfSources: number;
-    };
+    unload(): void;
     /**
-     * Get an image loader
+     * Get the image loader for a specific label
      *
-     * @param {string} label
-     *
-     * @returns {ImageLoader}
+     * @param {string} label - Image identifier
+     * @returns {ImageLoader|null} The image loader or null if not found
      */
-    getImageLoader(label: string): ImageLoader;
+    getImageLoader(label: string): ImageLoader | null;
     /**
-     * Get object URL that can be used as src parameter of an HTML image
-     *
-     * @param {string} label
-     *
-     * @returns {ImageMeta}
+     * Check if the scene is currently loading
      */
-    getImageMeta(label: string): ImageMeta;
+    get loading(): boolean;
     /**
-     * Get object URL that can be used as src parameter of an HTML image
-     *
-     * @param {string} label
-     *
-     * @note the objectURL should be revoked when no longer used
-     *
-     * @returns {string}
+     * Check if all images in the scene are loaded
      */
-    getObjectURL(label: string): string;
+    get loaded(): boolean;
+    /**
+     * Get the current loading progress
+     */
+    get progress(): {
+        bytesLoaded: number;
+        size: number;
+        loaded: boolean;
+    };
     #private;
 }
-export type ImageMeta = import("./typedef.js").ImageMeta;
 /**
- * // property ...
+ * A simple class to preload and manage images for a scene
  */
-export type SourceConfig = object;
-export type ImageSource = {
-    label: string;
-    imageLoader: ImageLoader;
-    imageMeta?: ImageMeta;
-};
-import ImageLoader from './ImageLoader.svelte.js';
+export type ImageMeta = import("../../../config/typedef.js").ImageMeta;
+import { ImageLoader } from './index.js';

package/dist/classes/svelte/image/ImageScene.svelte.js

@@ -1,253 +1,120 @@
-/** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
-
-import * as expect from '../../../util/expect/index.js';
-
-import {
-  LoadingStateMachine,
-  STATE_INITIAL,
-  STATE_LOADING,
-  STATE_UNLOADING,
-  STATE_LOADED,
-  STATE_CANCELLED,
-  STATE_ERROR,
-  LOAD,
-  // CANCEL,
-  ERROR,
-  LOADED,
-  UNLOAD,
-  INITIAL
-} from '../loading-state-machine/index.js';
-
-import ImageLoader from './ImageLoader.svelte.js';
-
-/**
- * @typedef {object} SourceConfig
- * // property ...
- */
-
 /**
- * @typedef {object} ImageSource
- * @property {string} label
- * @property {ImageLoader} imageLoader
- * @property {ImageMeta} [imageMeta]
+ * A simple class to preload and manage images for a scene
+ *
+ * @typedef {import('../../../config/typedef.js').ImageMeta} ImageMeta
  */
+import { ImageLoader } from './index.js';
 
 export default class ImageScene {
-  #state = new LoadingStateMachine();
-
-  // @note this exported state is set by $effect's
-  state = $state(STATE_INITIAL);
-
-  // @note this exported state is set by $effect's
-  loaded = $derived.by(() => {
-    return this.state === STATE_LOADED;
-  });
-
-  /** @type {ImageSource[]} */
-  #imageSources = $state([]);
-
-  #progress = $derived.by(() => {
-    // console.log('update progress');
-
-    let totalSize = 0;
-    let totalBytesLoaded = 0;
-    let sourcesLoaded = 0;
-
-    const sources = this.#imageSources;
-    const numberOfSources = sources.length;
-
-    for (let j = 0; j < numberOfSources; j++) {
-      const source = sources[j];
-      const { imageLoader } = source;
-
-      const { bytesLoaded, size, loaded } = imageLoader.progress;
-
-      totalSize += size;
-      totalBytesLoaded += bytesLoaded;
-
-      if (loaded) {
-        sourcesLoaded++;
-      }
-    } // end for
-
-    return {
-      totalBytesLoaded,
-      totalSize,
-      sourcesLoaded,
-      numberOfSources
-    };
-  });
+  /** @type {Map<string, ImageLoader>} */
+  #loaders = $state.raw(new Map());
 
-  /**
-   * Construct ImageScene
-   */
-  constructor() {
-    const state = this.#state;
-
-    $effect(() => {
-      if (state.current === STATE_LOADING) {
-        // console.log(
-        //   'progress',
-        //   JSON.stringify($state.snapshot(this.#progress))
-        // );
-
-        const { sourcesLoaded, numberOfSources } = this.#progress;
-
-        if (sourcesLoaded === numberOfSources) {
-          // console.log(`All [${numberOfSources}] sources loaded`);
-          this.#state.send(LOADED);
-        }
-      }
-    });
+  /** @type {boolean} */
+  #loading = $state(false);
 
-    $effect(() => {
-      switch (state.current) {
-        case STATE_LOADING:
-          {
-            // console.log('ImageScene:loading');
-            this.#startLoading();
-          }
-          break;
-
-        case STATE_UNLOADING:
-          {
-            // console.log('ImageScene:unloading');
-            // this.#startUnLoading();
-          }
-          break;
-
-        case STATE_LOADED:
-          {
-            // console.log('ImageScene:loaded');
-            // TODO
-            // this.#abortLoading = null;
-          }
-          break;
-
-        case STATE_CANCELLED:
-          {
-            // console.log('ImageScene:cancelled');
-            // TODO
-          }
-          break;
-
-        case STATE_ERROR:
-          {
-            console.log('ImageScene:error', state.error);
-          }
-          break;
-      } // end switch
-
-      this.state = state.current;
-    });
-  }
+  /** @type {boolean} */
+  #loaded = $state(false);
 
-  destroy() {
-    // TODO: disconnect all image sources?
-    // TODO: Unload ImageLoaders?
-  }
+  /** @type {{ bytesLoaded: number, size: number, loaded: boolean }} */
+  #progress = $state({ bytesLoaded: 0, size: 0, loaded: false });
 
   /**
-   * Add image source
-   * - Uses an ImageLoader instance to load image data from network
+   * Define an image to be managed by this scene
    *
-   * @param {object} _
-   * @param {string} _.label
-   * @param {ImageMeta|ImageMeta[]} _.imageMeta
+   * @param {object} params
+   * @param {string} params.label - Unique identifier for the image
+   * @param {ImageMeta|ImageMeta[]} params.imageMeta - Image metadata (single or variants)
    */
   defineImage({ label, imageMeta }) {
-    expect.notEmptyString(label);
-
-    // expect.notEmptyString(url);
-
-    const imageLoader = new ImageLoader({ imageMeta });
-
-    this.#imageSources.push({ label, imageLoader, imageMeta });
+    // Create loader for this image
+    const loader = new ImageLoader({ imageMeta });
+    this.#loaders.set(label, loader);
   }
 
   /**
-   * Start loading all image sources
+   * Start loading all defined images
    */
   load() {
-    this.#state.send(LOAD);
+    if (this.#loading || this.#loaded) return;
 
-    // FIXME: in unit test when moved to startloading it hangs!
+    this.#loading = true;
 
-    for (const { imageLoader } of this.#imageSources) {
-      imageLoader.load();
+    // Start loading all images
+    for (const loader of this.#loaders.values()) {
+      loader.load();
     }
-  }
 
-  async #startLoading() {
-    // console.log('#startLoading');
-    // FIXME: in unit test when moved to startloading it hangs!
-    // for (const { audioLoader } of this.#memorySources) {
-    //   audioLoader.load();
-    // }
-  }
+    // Track overall loading progress
+    $effect(() => {
+      if (this.#loaders.size === 0) return;
 
-  /**
-   * Get Image source
-   *
-   * @param {string} label
-   *
-   * @returns {ImageSource}
-   */
-  #getImageSource(label) {
-    for (const source of this.#imageSources) {
-      if (label === source.label) {
-        return source;
+      let totalBytesLoaded = 0;
+      let totalSize = 0;
+      let allLoaded = true;
+
+      for (const loader of this.#loaders.values()) {
+        const progress = loader.progress;
+
+        totalBytesLoaded += progress.bytesLoaded;
+        totalSize += progress.size || 0;
+
+        if (!progress.loaded) {
+          allLoaded = false;
+        }
       }
-    }
 
-    throw new Error(`Source [${label}] has not been defined`);
+      this.#progress = {
+        bytesLoaded: totalBytesLoaded,
+        size: totalSize,
+        loaded: allLoaded
+      };
+
+      if (allLoaded && this.#loading) {
+        this.#loaded = true;
+      }
+    });
   }
 
   /**
-   * Get image scene loading progress
+   * Unload all images and free resources
    */
-  get progress() {
-    return this.#progress;
+  unload() {
+    for (const loader of this.#loaders.values()) {
+      loader.unload();
+    }
+
+    this.#loading = false;
+    this.#loaded = false;
   }
 
   /**
-   * Get an image loader
-   *
-   * @param {string} label
+   * Get the image loader for a specific label
    *
-   * @returns {ImageLoader}
+   * @param {string} label - Image identifier
+   * @returns {ImageLoader|null} The image loader or null if not found
    */
   getImageLoader(label) {
-    const source = this.#getImageSource(label);
-
-    return source.imageLoader;
+    return this.#loaders.get(label) || null;
   }
 
   /**
-   * Get object URL that can be used as src parameter of an HTML image
-   *
-   * @param {string} label
-   *
-   * @returns {ImageMeta}
+   * Check if the scene is currently loading
    */
-  getImageMeta(label) {
-    const source = this.#getImageSource(label);
-
-    return source.imageMeta;
+  get loading() {
+    return this.#loading;
   }
 
   /**
-   * Get object URL that can be used as src parameter of an HTML image
-   *
-   * @param {string} label
-   *
-   * @note the objectURL should be revoked when no longer used
-   *
-   * @returns {string}
+   * Check if all images in the scene are loaded
    */
-  getObjectURL(label) {
-    const source = this.#getImageSource(label);
+  get loaded() {
+    return this.#loaded;
+  }
 
-    return source.imageLoader.getObjectURL();
+  /**
+   * Get the current loading progress
+   */
+  get progress() {
+    return this.#progress;
   }
 }

package/dist/classes/svelte/image/ImageScene.svelte.js__

@@ -0,0 +1,253 @@
+/** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
+
+import * as expect from '$lib/util/expect/index.js';
+
+import {
+  LoadingStateMachine,
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_UNLOADING,
+  STATE_LOADED,
+  STATE_CANCELLED,
+  STATE_ERROR,
+  LOAD,
+  // CANCEL,
+  ERROR,
+  LOADED,
+  UNLOAD,
+  INITIAL
+} from '$lib/classes/svelte/loading-state-machine/index.js';
+
+import ImageLoader from '$lib/classes/svelte/image/ImageLoader.svelte.js';
+
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+
+/**
+ * @typedef {object} ImageSource
+ * @property {string} label
+ * @property {ImageLoader} imageLoader
+ * @property {ImageMeta} [imageMeta]
+ */
+
+export default class ImageScene {
+  #state = new LoadingStateMachine();
+
+  // @note this exported state is set by $effect's
+  state = $state(STATE_INITIAL);
+
+  // @note this exported state is set by $effect's
+  loaded = $derived.by(() => {
+    return this.state === STATE_LOADED;
+  });
+
+  /** @type {ImageSource[]} */
+  #imageSources = $state([]);
+
+  #progress = $derived.by(() => {
+    // console.log('update progress');
+
+    let totalSize = 0;
+    let totalBytesLoaded = 0;
+    let sourcesLoaded = 0;
+
+    const sources = this.#imageSources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const { imageLoader } = source;
+
+      const { bytesLoaded, size, loaded } = imageLoader.progress;
+
+      totalSize += size;
+      totalBytesLoaded += bytesLoaded;
+
+      if (loaded) {
+        sourcesLoaded++;
+      }
+    } // end for
+
+    return {
+      totalBytesLoaded,
+      totalSize,
+      sourcesLoaded,
+      numberOfSources
+    };
+  });
+
+  /**
+   * Construct ImageScene
+   */
+  constructor() {
+    const state = this.#state;
+
+    $effect(() => {
+      if (state.current === STATE_LOADING) {
+        // console.log(
+        //   'progress',
+        //   JSON.stringify($state.snapshot(this.#progress))
+        // );
+
+        const { sourcesLoaded, numberOfSources } = this.#progress;
+
+        if (sourcesLoaded === numberOfSources) {
+          // console.log(`All [${numberOfSources}] sources loaded`);
+          this.#state.send(LOADED);
+        }
+      }
+    });
+
+    $effect(() => {
+      switch (state.current) {
+        case STATE_LOADING:
+          {
+            // console.log('ImageScene:loading');
+            this.#startLoading();
+          }
+          break;
+
+        case STATE_UNLOADING:
+          {
+            // console.log('ImageScene:unloading');
+            // this.#startUnLoading();
+          }
+          break;
+
+        case STATE_LOADED:
+          {
+            // console.log('ImageScene:loaded');
+            // TODO
+            // this.#abortLoading = null;
+          }
+          break;
+
+        case STATE_CANCELLED:
+          {
+            // console.log('ImageScene:cancelled');
+            // TODO
+          }
+          break;
+
+        case STATE_ERROR:
+          {
+            console.log('ImageScene:error', state.error);
+          }
+          break;
+      } // end switch
+
+      this.state = state.current;
+    });
+  }
+
+  destroy() {
+    // TODO: disconnect all image sources?
+    // TODO: Unload ImageLoaders?
+  }
+
+  /**
+   * Add image source
+   * - Uses an ImageLoader instance to load image data from network
+   *
+   * @param {object} _
+   * @param {string} _.label
+   * @param {ImageMeta|ImageMeta[]} _.imageMeta
+   */
+  defineImage({ label, imageMeta }) {
+    expect.notEmptyString(label);
+
+    // expect.notEmptyString(url);
+
+    const imageLoader = new ImageLoader({ imageMeta });
+
+    this.#imageSources.push({ label, imageLoader, imageMeta });
+  }
+
+  /**
+   * Start loading all image sources
+   */
+  load() {
+    this.#state.send(LOAD);
+
+    // FIXME: in unit test when moved to startloading it hangs!
+
+    for (const { imageLoader } of this.#imageSources) {
+      imageLoader.load();
+    }
+  }
+
+  async #startLoading() {
+    // console.log('#startLoading');
+    // FIXME: in unit test when moved to startloading it hangs!
+    // for (const { audioLoader } of this.#memorySources) {
+    //   audioLoader.load();
+    // }
+  }
+
+  /**
+   * Get Image source
+   *
+   * @param {string} label
+   *
+   * @returns {ImageSource}
+   */
+  #getImageSource(label) {
+    for (const source of this.#imageSources) {
+      if (label === source.label) {
+        return source;
+      }
+    }
+
+    throw new Error(`Source [${label}] has not been defined`);
+  }
+
+  /**
+   * Get image scene loading progress
+   */
+  get progress() {
+    return this.#progress;
+  }
+
+  /**
+   * Get an image loader
+   *
+   * @param {string} label
+   *
+   * @returns {ImageLoader}
+   */
+  getImageLoader(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageLoader;
+  }
+
+  /**
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @param {string} label
+   *
+   * @returns {ImageMeta}
+   */
+  getImageMeta(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageMeta;
+  }
+
+  /**
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @param {string} label
+   *
+   * @note the objectURL should be revoked when no longer used
+   *
+   * @returns {string}
+   */
+  getObjectURL(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageLoader.getObjectURL();
+  }
+}

package/dist/classes/svelte/image/ImageVariantsLoader.svelte.d.ts

@@ -1,8 +1,5 @@
 export default class ImageVariantsLoader {
-    /**
-     * @param {ImageMeta[]} imagesMeta
-     */
-    constructor(imagesMeta: ImageMeta[], { devicePixelRatio }?: {
+    constructor(imagesMeta: any, { devicePixelRatio }?: {
         devicePixelRatio?: number;
     });
     /**
@@ -28,7 +25,11 @@ export default class ImageVariantsLoader {
      * @returns {string|null}
      */
     getObjectURL(): string | null;
-    get progress(): import("../network-loader/typedef.js").LoadingProgress;
+    get progress(): {
+        bytesLoaded: any;
+        size: any;
+        loaded: boolean;
+    };
     /**
      * Get optimal image variant
      *

package/dist/classes/svelte/image/ImageVariantsLoader.svelte.js

@@ -1,11 +1,7 @@
 /** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
 
-// import * as expect from '../../../util/expect/index.js';
-
 import { calculateEffectiveWidth } from '../../../util/image/index.js';
-
 import { untrack } from 'svelte';
-
 import ImageLoader from './ImageLoader.svelte.js';
 
 export default class ImageVariantsLoader {
@@ -21,22 +17,32 @@ export default class ImageVariantsLoader {
   /** @type {ImageLoader|null} */
   #imageLoader = $state(null);
 
-  #progress = $derived.by(() => {
-    if (this.#imageLoader) {
-      return this.#imageLoader.progress;
-    } else {
-      return { bytesLoaded: 0, size: 0, loaded: false };
-    }
-  });
+  /** @type {boolean} */
+  #isObjectUrlCreated = $state(false);
 
-  #loaded = $derived.by(() => this.#progress?.loaded || false);
+  /** @type {boolean} */
+  #variantLoaded = $state(false);
+
+  /** @type {Object} */
+  #baseProgress = $state({ bytesLoaded: 0, size: 0, loaded: false });
 
-  /**
-   * @param {ImageMeta[]} imagesMeta
-   */
   constructor(imagesMeta, { devicePixelRatio = 1 } = {}) {
     this.#devicePixelRatio = devicePixelRatio ?? 1;
     this.#imagesMeta = [...imagesMeta].sort((a, b) => a.width - b.width);
+
+    // Track the imageLoader's progress
+    $effect(() => {
+      if (this.#imageLoader) {
+        // Store the base progress from the loader
+        this.#baseProgress = this.#imageLoader.progress;
+
+        // When the base image is loaded, we can say variant is loaded
+        // if an object URL has been created
+        if (this.#baseProgress.loaded && this.#isObjectUrlCreated) {
+          this.#variantLoaded = true;
+        }
+      }
+    });
   }
 
   /**
@@ -67,7 +73,11 @@ export default class ImageVariantsLoader {
     ) {
       this.#imageVariant = newVariant;
 
-      // Create and start loader here directly when variant changes
+      // Reset our loaded flags when changing variants
+      this.#isObjectUrlCreated = false;
+      this.#variantLoaded = false;
+
+      // Clean up and create a new loader
       if (this.#imageLoader?.initial) {
         this.#imageLoader.unload();
       }
@@ -81,7 +91,7 @@ export default class ImageVariantsLoader {
   }
 
   get loaded() {
-    return this.#loaded;
+    return this.#variantLoaded;
   }
 
   get variant() {
@@ -96,31 +106,38 @@ export default class ImageVariantsLoader {
    * @returns {string|null}
    */
   getObjectURL() {
-    // Example usage:
-    //
-    // $effect(() => {
-    //   if (variantsLoader.loaded) {
-    //     // @ts-ignore
-    //     imageUrl = variantsLoader.getObjectURL();
-    //   }
-
-    //   return () => {
-    //     if (imageUrl) {
-    //       URL.revokeObjectURL(imageUrl);
-    //       imageUrl = null;
-    //     }
-    //   };
-    // });
-
-    const blob = this.#imageLoader?.getBlob();
-
-    const url = blob ? URL.createObjectURL(blob) : null;
+    if (!this.#imageLoader) {
+      return null;
+    }
+
+    const blob = this.#imageLoader.getBlob();
+
+    if (!blob) {
+      return null;
+    }
+
+    // Get the URL
+    const url = URL.createObjectURL(blob);
+
+    // Mark that we've successfully created an object URL
+    this.#isObjectUrlCreated = true;
+
+    // If the underlying loader is also loaded, we can consider
+    // the whole variant loaded
+    if (this.#baseProgress.loaded) {
+      this.#variantLoaded = true;
+    }
 
     return url;
   }
 
   get progress() {
-    return this.#progress;
+    // Only return loaded:true in the progress when we're fully loaded
+    return {
+      bytesLoaded: this.#baseProgress.bytesLoaded,
+      size: this.#baseProgress.size,
+      loaded: this.#variantLoaded
+    };
   }
 
   /**
@@ -141,7 +158,6 @@ export default class ImageVariantsLoader {
     const imagesMeta = this.#imagesMeta;
 
     // Find the smallest image that's larger than our required width
-
     const optimal = imagesMeta.find(
       (current) => current.width >= requiredWidth
     );
@@ -149,4 +165,4 @@ export default class ImageVariantsLoader {
     // Fall back to the largest image if nothing is big enough
     return optimal || imagesMeta[imagesMeta.length - 1];
   }
-} // end class
+}

package/dist/classes/svelte/image/ImageVariantsLoader.svelte.js--responsive-loading-fails-fix-tried__

@@ -0,0 +1,184 @@
+/** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
+
+// import * as expect from '$lib/util/expect/index.js';
+
+import { calculateEffectiveWidth } from '$lib/util/image/index.js';
+
+import { untrack } from 'svelte';
+
+import ImageLoader from './ImageLoader.svelte.js';
+
+export default class ImageVariantsLoader {
+  /** @type {number} */
+  #devicePixelRatio;
+
+  /** @type {ImageMeta[]} */
+  #imagesMeta;
+
+  /** @type {ImageMeta|null} */
+  #imageVariant = $state(null);
+
+  /** @type {ImageLoader|null} */
+  #imageLoader = $state(null);
+
+  /** @type {boolean} */
+  #manuallyCheckedLoaded = $state(false);
+
+  // Create a custom progress object that we control fully
+  #customProgress = $state({
+    bytesLoaded: 0,
+    size: 0,
+    loaded: false
+  });
+
+  #progress = $derived.by(() => {
+    return this.#customProgress;
+  });
+
+  // Derive loaded state from our custom progress
+  #loaded = $derived.by(() => this.#customProgress.loaded);
+
+  /**
+   * @param {ImageMeta[]} imagesMeta
+   */
+  constructor(imagesMeta, { devicePixelRatio = 1 } = {}) {
+    this.#devicePixelRatio = devicePixelRatio ?? 1;
+    this.#imagesMeta = [...imagesMeta].sort((a, b) => a.width - b.width);
+
+    // Track when the imageLoader's progress changes
+    $effect(() => {
+      if (this.#imageLoader) {
+        const loaderProgress = this.#imageLoader.progress;
+
+        // Update our custom progress with the loader's values,
+        // but maintain our own loaded state
+        this.#customProgress = {
+          bytesLoaded: loaderProgress.bytesLoaded,
+          size: loaderProgress.size,
+          loaded: this.#manuallyCheckedLoaded && loaderProgress.loaded
+        };
+      }
+    });
+  }
+
+  /**
+   * Set new optimal image variant or keep current
+   *
+   * @param {object} params
+   * @param {number} [params.containerWidth] Container width
+   * @param {number} [params.containerHeight] Container height
+   * @param {'cover'|'contain'|'fill'} [params.fit='contain'] Fit mode
+   */
+  updateOptimalImageMeta({ containerWidth, containerHeight, fit = 'contain' }) {
+    const baseImage = this.#imagesMeta[0];
+    const imageAspectRatio = baseImage.width / baseImage.height;
+
+    const effectiveWidth = calculateEffectiveWidth({
+      containerWidth,
+      containerHeight,
+      imageAspectRatio,
+      fit
+    });
+
+    const newVariant = this.getOptimalImageMeta(effectiveWidth);
+
+    if (
+      !newVariant ||
+      !this.#imageVariant ||
+      newVariant.width > this.#imageVariant.width
+    ) {
+      this.#imageVariant = newVariant;
+
+      // Reset loaded state when changing variants
+      this.#manuallyCheckedLoaded = false;
+      this.#customProgress = {
+        bytesLoaded: 0,
+        size: 0,
+        loaded: false
+      };
+
+      // Create and start loader here directly when variant changes
+      if (this.#imageLoader?.initial) {
+        this.#imageLoader.unload();
+      }
+
+      this.#imageLoader = new ImageLoader({
+        imageMeta: newVariant
+      });
+
+      this.#imageLoader.load();
+    }
+  }
+
+  get loaded() {
+    return this.#loaded;
+  }
+
+  get variant() {
+    return this.#imageVariant;
+  }
+
+  /**
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @note the objectURL should be revoked when no longer used
+   *
+   * @returns {string|null}
+   */
+  getObjectURL() {
+    // First check if the loader is actually loaded
+    if (!this.#imageLoader?.loaded) {
+      return null;
+    }
+
+    const blob = this.#imageLoader.getBlob();
+
+    if (!blob) {
+      return null;
+    }
+
+    // Successfully got a blob, so we're definitely loaded
+    if (!this.#manuallyCheckedLoaded) {
+      this.#manuallyCheckedLoaded = true;
+
+      // Update our custom progress to indicate we're loaded
+      this.#customProgress = {
+        bytesLoaded: this.#customProgress.bytesLoaded,
+        size: this.#customProgress.size,
+        loaded: true
+      };
+    }
+
+    return URL.createObjectURL(blob);
+  }
+
+  get progress() {
+    return this.#progress;
+  }
+
+  /**
+   * Get optimal image variant
+   *
+   * @param {number} containerWidth
+   *
+   * @returns {ImageMeta|null}
+   */
+  getOptimalImageMeta(containerWidth) {
+    if (!containerWidth) {
+      return null;
+    }
+
+    // Calculate the required width (container * DPR)
+    const requiredWidth = containerWidth * this.#devicePixelRatio;
+
+    const imagesMeta = this.#imagesMeta;
+
+    // Find the smallest image that's larger than our required width
+    const optimal = imagesMeta.find(
+      (current) => current.width >= requiredWidth
+    );
+
+    // Fall back to the largest image if nothing is big enough
+    return optimal || imagesMeta[imagesMeta.length - 1];
+  }
+} // end class

package/dist/util/svelte/index.d.ts

@@ -1,2 +1,3 @@
 export * as observe from "./observe/index.js";
 export * as stateContext from "./state-context/index.js";
+export * as loading from "./loading/loading-tracker.svelte.js";

package/dist/util/svelte/index.js

@@ -1,2 +1,4 @@
 export * as observe from './observe/index.js';
 export * as stateContext from './state-context/index.js';
+
+export * as loading from './loading/loading-tracker.svelte.js';

package/dist/util/svelte/loading/loading-tracker.svelte.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Simple utility for tracking combined loading progress across multiple components
+ *
+ * @typedef {Object} LoadingProgress
+ * @property {number} bytesLoaded - Number of bytes loaded
+ * @property {number} size - Total size in bytes
+ * @property {boolean} loaded - Whether loading is complete
+ */
+/**
+ * Creates a loading tracker that combines progress from multiple sources
+ *
+ * @returns {Object} Loading tracker instance
+ */
+export function createTracker(): any;
+/**
+ * Simple utility for tracking combined loading progress across multiple components
+ */
+export type LoadingProgress = {
+    /**
+     * - Number of bytes loaded
+     */
+    bytesLoaded: number;
+    /**
+     * - Total size in bytes
+     */
+    size: number;
+    /**
+     * - Whether loading is complete
+     */
+    loaded: boolean;
+};

package/dist/util/svelte/loading/loading-tracker.svelte.js

@@ -0,0 +1,108 @@
+/**
+ * Simple utility for tracking combined loading progress across multiple components
+ *
+ * @typedef {Object} LoadingProgress
+ * @property {number} bytesLoaded - Number of bytes loaded
+ * @property {number} size - Total size in bytes
+ * @property {boolean} loaded - Whether loading is complete
+ */
+
+/**
+ * Creates a loading tracker that combines progress from multiple sources
+ *
+ * @returns {Object} Loading tracker instance
+ */
+export function createTracker() {
+  // Store progress for each item by ID
+  const items = new Map();
+
+  // Computed values
+  let totalBytesLoaded = 0;
+  let totalSize = 0;
+  let allLoaded = false;
+  let progressPercent = 0;
+
+  /**
+   * Update the totals based on current items
+   */
+  function updateTotals() {
+    let bytesLoaded = 0;
+    let size = 0;
+    let loaded = items.size > 0;
+
+    // Loop through all items and sum values
+    for (const progress of items.values()) {
+      bytesLoaded += progress.bytesLoaded || 0;
+      size += progress.size || 0;
+
+      if (!progress.loaded) {
+        loaded = false;
+      }
+    }
+
+    // Update state
+    totalBytesLoaded = bytesLoaded;
+    totalSize = size;
+    allLoaded = items.size > 0 ? loaded : false;
+    progressPercent = size > 0 ? Math.round((bytesLoaded / size) * 100) : 0;
+  }
+
+  /**
+   * Track progress for a component
+   *
+   * @param {LoadingProgress} progress - The progress update
+   * @param {string|Symbol} id - The component identifier
+   */
+  function track(progress, id) {
+    if (progress && id) {
+      items.set(id, progress);
+      updateTotals();
+    }
+  }
+
+  /**
+   * Remove an item from tracking
+   *
+   * @param {string|Symbol} id - Item identifier to remove
+   */
+  function remove(id) {
+    if (items.has(id)) {
+      items.delete(id);
+      updateTotals();
+    }
+  }
+
+  /**
+   * Reset the tracker, clearing all items
+   */
+  function reset() {
+    items.clear();
+    updateTotals();
+  }
+
+  // Return the public API
+  return {
+    track,
+    remove,
+    reset,
+
+    // Read-only properties
+    get state() {
+      return {
+        bytesLoaded: totalBytesLoaded,
+        size: totalSize,
+        loaded: allLoaded,
+        percent: progressPercent,
+        itemCount: items.size
+      };
+    },
+
+    get loaded() {
+      return allLoaded;
+    },
+
+    get percent() {
+      return progressPercent;
+    }
+  };
+}

package/dist/widgets/image-box/ImageBox.svelte

@@ -14,10 +14,11 @@
 	 *   overflow?: string,
 	 *   fit?: 'contain' | 'cover' | 'fill',
 	 *   position?: string,
-	 *   imageMeta: import('../../config/typedef.js').ImageMeta | import('../../config/typedef.js').ImageMeta[],
+	 *   imageMeta?: import('../../config/typedef.js').ImageMeta | import('../../config/typedef.js').ImageMeta[],
 	 *   imageLoader?: import('../../classes/svelte/image/index.js').ImageLoader,
 	 *   alt?: string,
-	 *   onProgress?: (progress: import('../../classes/svelte/network-loader/typedef.js').LoadingProgress) => void,
+	 *   id?: string | Symbol,
+	 *   onProgress?: (progress: import('../../classes/svelte/network-loader/typedef.js').LoadingProgress, id?: string | Symbol) => void,
 	 *   [attr: string]: any
 	 * }}
 	 */
@@ -42,6 +43,9 @@
 		// Accessibility
 		alt = '',
 
+		// Component identification
+		id = Symbol('ImageBox'),
+
 		// Events
 		onProgress,
 
@@ -49,9 +53,9 @@
 		...attrs
 	} = $props();
 
-	if (!imageMeta) {
-		throw new Error('Missing [imageMeta]');
-	}
+	// if (!imageMeta) {
+	//  throw new Error('Missing [imageMeta]');
+	// }
 
 	/** @type {HTMLDivElement|undefined} */
 	let containerElem = $state();
@@ -87,11 +91,11 @@
 
 		// Report progress from variants loader
 		if (variantsLoader) {
-			onProgress(variantsLoader.progress);
+			onProgress(variantsLoader.progress, id);
 		}
 		// Report progress from single image loader
 		else if (imageLoader_) {
-			onProgress(imageLoader_.progress);
+			onProgress(imageLoader_.progress, id);
 		}
 	});
 

package/dist/widgets/image-box/ImageBox.svelte.d.ts

@@ -12,10 +12,11 @@ type ImageBox = {
         overflow?: string;
         fit?: "fill" | "contain" | "cover";
         position?: string;
-        imageMeta: ImageMeta | ImageMeta[];
+        imageMeta?: ImageMeta | ImageMeta[];
         imageLoader?: ImageLoader;
         alt?: string;
-        onProgress?: (progress: LoadingProgress) => void;
+        id?: string | Symbol;
+        onProgress?: (progress: LoadingProgress, id?: string | Symbol) => void;
     }>): void;
 };
 declare const ImageBox: import("svelte").Component<{
@@ -29,8 +30,9 @@ declare const ImageBox: import("svelte").Component<{
     overflow?: string;
     fit?: "contain" | "cover" | "fill";
     position?: string;
-    imageMeta: import("../../config/typedef.js").ImageMeta | import("../../config/typedef.js").ImageMeta[];
+    imageMeta?: import("../../config/typedef.js").ImageMeta | import("../../config/typedef.js").ImageMeta[];
     imageLoader?: import("../../classes/svelte/image/index.js").ImageLoader;
     alt?: string;
-    onProgress?: (progress: import("../../classes/svelte/network-loader/typedef.js").LoadingProgress) => void;
+    id?: string | Symbol;
+    onProgress?: (progress: import("../../classes/svelte/network-loader/typedef.js").LoadingProgress, id?: string | Symbol) => void;
 }, {}, "">;

package/dist/widgets/presenter/Presenter.state.svelte.d.ts

@@ -25,6 +25,13 @@ export class PresenterState {
     busy: boolean;
     /** @type {string} */
     currentSlideName: string;
+    /**
+     * Returns a simplified presenter reference with essential methods
+     * for slide components to use
+     *
+     * @returns {PresenterRef} A reference object with presenter methods
+     */
+    getPresenterRef(): PresenterRef;
     /**
      * Mark the slide as loaded, which triggers transitions to begin
      */
@@ -80,4 +87,14 @@ export type LoadController = {
      */
     cancel: () => void;
 };
+export type PresenterRef = {
+    /**
+     * - Navigate to a slide by name
+     */
+    gotoSlide: (name: string) => void;
+    /**
+     * - Get the current slide name
+     */
+    getCurrentSlideName: () => string;
+};
 import { HkPromise } from '../../classes/promise/index.js';

package/dist/widgets/presenter/Presenter.state.svelte.js

@@ -26,6 +26,12 @@ import { HkPromise } from '../../classes/promise/index.js';
  * @property {() => void} cancel - Function to return to the previous slide
  */
 
+/**
+ * @typedef {Object} PresenterRef
+ * @property {(name: string) => void} gotoSlide - Navigate to a slide by name
+ * @property {() => string} getCurrentSlideName - Get the current slide name
+ */
+
 /* -------------------------------------------------------------- Constants */
 
 const Z_BACK = 0;
@@ -96,6 +102,19 @@ export class PresenterState {
     this.#setupLoadingTransitions();
   }
 
+  /**
+   * Returns a simplified presenter reference with essential methods
+   * for slide components to use
+   *
+   * @returns {PresenterRef} A reference object with presenter methods
+   */
+  getPresenterRef() {
+    return {
+      gotoSlide: (name) => this.gotoSlide(name),
+      getCurrentSlideName: () => this.currentSlideName
+    };
+  }
+
   /**
    * Set up reactivity for stage transitions between the before/after states
    * This handles the animation timing for both layers
@@ -358,27 +377,31 @@ export class PresenterState {
 
     // Add controller function to slide props if it has a component
     if (slide.data?.component) {
+      // Get a presenter reference to pass to the slide
+      const presenterRef = this.getPresenterRef();
+
       // Create a copy of the slide to avoid mutating the original
-      const slideWithController = {
+      const slideWithExtras = {
         ...slide,
         data: {
           ...slide.data,
           props: {
             ...(slide.data.props || {}),
-            getLoadingController: () => this.getLoadingController()
+            getLoadingController: () => this.getLoadingController(),
+            presenter: presenterRef // Add presenter reference to props
           }
         }
       };
 
-      // Add next slide to next layer with controller included
-      this.#updateSlide(this.nextLayerLabel, slideWithController);
+      // Add next slide to next layer with controller and presenter included
+      this.#updateSlide(this.nextLayerLabel, slideWithExtras);
 
       // If a timeout is configured, automatically finish loading after delay
       if (this.loadingTimeout > 0) {
         setTimeout(() => {
           // Only auto-finish if the controller wasn't requested
           if (!this.controllerRequested && this.isSlideLoading) {
-            // console.log(
+            // console.debug(
             //   `Slide '${slide.name}' didn't request loading controller, auto-finishing.`
             // );
             this.finishSlideLoading();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-sveltekit",
-	"version": "0.1.20",
+	"version": "0.1.22",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"