@hkdigital/lib-core 0.4.27 → 0.4.28

package/dist/network/loaders/audio/AudioScene.svelte.d.ts

@@ -8,36 +8,23 @@
  * @property {AudioLoader} audioLoader
  * @property {SourceConfig} [config]
  */
-export default class AudioScene {
-    state: string;
-    loaded: boolean;
+export default class AudioScene extends SceneBase {
     muted: boolean;
     targetGain: number;
     /**
-   * Get audio scene loading progress
-   */
-    get progress(): {
-        totalBytesLoaded: number;
-        totalSize: number;
-        sourcesLoaded: number;
-        numberOfSources: number;
-    };
-    /**
-     * Get audio scene abort progress
-     */
-    get abortProgress(): {
-        sourcesAborted: number;
-        numberOfSources: number;
-    };
-    /**
-     * Start loading all audio sources
+     * Get the array of memory sources managed by this scene
+     *
+     * @returns {MemorySource[]}
      */
-    load(): void;
+    get sources(): MemorySource[];
     /**
-     * Abort loading all audio sources
+     * Extract the audio loader from a source object
+     *
+     * @param {MemorySource} source
+     *
+     * @returns {AudioLoader}
      */
-    abort(): void;
-    destroy(): void;
+    getLoaderFromSource(source: MemorySource): AudioLoader;
     /**
      * Add in-memory audio source
      * - Uses an AudioLoader instance to load audio data from network
@@ -67,18 +54,33 @@ export default class AudioScene {
      */
     setAudioContext(audioContext?: AudioContext): void;
     /**
-     * Set target gain
+     * Set target gain (volume level) for all audio in this scene
+     * - Currently applies immediately, but "target" allows for future
+     *   smooth transitions using Web Audio API's gain scheduling
+     * - Range: 0.0 (silence) to 1.0 (original) to 1.0+ (amplified)
      *
-     * @param {number} value
+     * @param {number} value - Target gain value (0.0 to 1.0+)
      */
     setTargetGain(value: number): void;
     /**
-     * Get the scene gain
+     * Get the current target gain (volume level)
      *
-     * @returns {number} value
+     * @returns {number} Target gain value (0.0 to 1.0+)
      */
     getTargetGain(): number;
+    /**
+     * Mute all audio in this scene
+     * - Saves current volume level for restoration
+     * - Sets target gain to 0 (silence)
+     * - Safe to call multiple times
+     */
     mute(): void;
+    /**
+     * Unmute all audio in this scene
+     * - Restores volume level from before muting
+     * - Safe to call multiple times
+     * - No effect if scene is not currently muted
+     */
     unmute(): void;
     #private;
 }
@@ -91,4 +93,5 @@ export type MemorySource = {
     audioLoader: AudioLoader;
     config?: SourceConfig;
 };
+import SceneBase from '../base/SceneBase.svelte.js';
 import AudioLoader from './AudioLoader.svelte.js';

package/dist/network/loaders/audio/AudioScene.svelte.js

@@ -1,20 +1,6 @@
 import * as expect from '../../../util/expect.js';
 
-import { LoadingStateMachine } from '../../../state/machines.js';
-
-import {
-	STATE_INITIAL,
-	STATE_LOADING,
-	STATE_LOADED,
-	STATE_ABORTING,
-	STATE_ABORTED,
-	STATE_ERROR,
-	LOAD,
-	LOADED,
-	ABORT,
-	ABORTED
-} from '../../../state/machines.js';
-
+import SceneBase from '../base/SceneBase.svelte.js';
 import AudioLoader from './AudioLoader.svelte.js';
 
 /**
@@ -29,15 +15,7 @@ import AudioLoader from './AudioLoader.svelte.js';
  * @property {SourceConfig} [config]
  */
 
-export default class AudioScene {
-	#state = new LoadingStateMachine();
-
-	// @note this exported state is set by onenter
-	state = $state(STATE_INITIAL);
-
-	loaded = $derived.by(() => {
-		return this.state === STATE_LOADED;
-	});
+export default class AudioScene extends SceneBase {
 
 	#targetGain = $state(1);
 
@@ -56,143 +34,35 @@ export default class AudioScene {
 	/** @type {MemorySource[]} */
 	#memorySources = $state([]);
 
-	#progress = $derived.by(() => {
-		// console.log('update progress');
-
-		let totalSize = 0;
-		let totalBytesLoaded = 0;
-		let sourcesLoaded = 0;
-
-		const sources = this.#memorySources;
-		const numberOfSources = sources.length;
-
-		for (let j = 0; j < numberOfSources; j++) {
-			const source = sources[j];
-			const { audioLoader } = source;
-
-			const { bytesLoaded, size, loaded } = audioLoader.progress;
-
-			totalSize += size;
-			totalBytesLoaded += bytesLoaded;
-
-			if (loaded) {
-				sourcesLoaded++;
-			}
-		} // end for
-
-		return {
-			totalBytesLoaded,
-			totalSize,
-			sourcesLoaded,
-			numberOfSources
-		};
-	});
-
-	#abortProgress = $derived.by(() => {
-		let sourcesAborted = 0;
-		const sources = this.#memorySources;
-		const numberOfSources = sources.length;
-
-		for (let j = 0; j < numberOfSources; j++) {
-			const source = sources[j];
-			const { audioLoader } = source;
-			const loaderState = audioLoader.state;
-
-			if (loaderState === STATE_ABORTED || loaderState === STATE_ERROR) {
-				sourcesAborted++;
-			}
-		} // end for
-
-		return {
-			sourcesAborted,
-			numberOfSources
-		};
-	});
 
 	/**
 	 * Construct AudioScene
 	 */
 	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.debug(`AudioScene: ${numberOfSources} sources loaded`);
-					this.#state.send(LOADED);
-				}
-			}
-		});
-
-		$effect(() => {
-			if (state.current === STATE_ABORTING) {
-				const { sourcesAborted, numberOfSources } = this.#abortProgress;
-
-				if (sourcesAborted === numberOfSources) {
-					// console.debug(`AudioScene: ${numberOfSources} sources aborted`);
-					this.#state.send(ABORTED);
-				}
-			}
-		});
-
-		state.onenter = ( currentState ) => {
-      // console.log('onenter', currentState );
-
-			if(currentState === STATE_LOADING )
-			{
-				// console.log('AudioScene:loading');
-				this.#startLoading();
-			}
-			else if(currentState === STATE_ABORTING )
-			{
-				// console.log('AudioScene:aborting');
-				this.#startAbort();
-			}
-
-			this.state = state.current;
-		};
+		super();
 	}
 
-	/* ==== Common loader interface */
+	/* ==== SceneBase implementation */
 
 	/**
-   * Get audio scene loading progress
-   */
-  get progress() {
-    return this.#progress;
-  }
-
-	/**
-	 * Get audio scene abort progress
-	 */
-	get abortProgress() {
-		return this.#abortProgress;
-	}
-
-	/**
-	 * Start loading all audio sources
+	 * Get the array of memory sources managed by this scene
+	 *
+	 * @returns {MemorySource[]}
 	 */
-	load() {
-		this.#state.send(LOAD);
+	get sources() {
+		return this.#memorySources;
 	}
 
 	/**
-	 * Abort loading all audio sources
+	 * Extract the audio loader from a source object
+	 *
+	 * @param {MemorySource} source
+	 *
+	 * @returns {AudioLoader}
 	 */
-	abort() {
-		this.#state.send(ABORT);
-	}
-
-	destroy() {
-		// TODO: disconnect all audio sources?
-		// TODO: Unload AUdioLoaders?
+	// eslint-disable-next-line no-unused-vars
+	getLoaderFromSource(source) {
+		return source.audioLoader;
 	}
 
 	/* ==== Source definitions */
@@ -260,28 +130,16 @@ export default class AudioScene {
 		this.#audioContext = audioContext;
 	}
 
-	async #startLoading() {
-		// console.log('#startLoading');
-
-		for (const { audioLoader } of this.#memorySources) {
-		  audioLoader.load();
-		}
-	}
-
-	#startAbort() {
-		// console.log('#startAbort');
-
-		for (const { audioLoader } of this.#memorySources) {
-			audioLoader.abort();
-		}
-	}
 
 	/* ==== Audio specific */
 
 	/**
-	 * Set target gain
+	 * Set target gain (volume level) for all audio in this scene
+	 * - Currently applies immediately, but "target" allows for future 
+	 *   smooth transitions using Web Audio API's gain scheduling
+	 * - Range: 0.0 (silence) to 1.0 (original) to 1.0+ (amplified)
 	 *
-	 * @param {number} value
+	 * @param {number} value - Target gain value (0.0 to 1.0+)
 	 */
 	setTargetGain( value ) {
 		this.#targetGain = value;
@@ -291,15 +149,21 @@ export default class AudioScene {
 	}
 
 	/**
-	 * Get the scene gain
+	 * Get the current target gain (volume level)
 	 *
-	 * @returns {number} value
+	 * @returns {number} Target gain value (0.0 to 1.0+)
 	 */
 	getTargetGain()
 	{
 		return this.#targetGain;
 	}
 
+	/**
+	 * Mute all audio in this scene
+	 * - Saves current volume level for restoration
+	 * - Sets target gain to 0 (silence)
+	 * - Safe to call multiple times
+	 */
 	mute() {
 		if( this.muted )
 		{
@@ -310,6 +174,12 @@ export default class AudioScene {
 		this.setTargetGain(0);
 	}
 
+	/**
+	 * Unmute all audio in this scene
+	 * - Restores volume level from before muting
+	 * - Safe to call multiple times
+	 * - No effect if scene is not currently muted
+	 */
 	unmute() {
 		if( !this.muted )
 		{

package/dist/network/loaders/audio/README.md

@@ -0,0 +1,195 @@
+# Audio Loaders
+
+Audio loading and scene management for web applications using the Web Audio API.
+
+## Overview
+
+The audio loading system consists of two main components:
+
+- **AudioLoader** - Loads individual audio files from network sources
+- **AudioScene** - Manages collections of audio sources with centralized playback control
+
+## AudioScene
+
+`AudioScene` extends `SceneBase` to provide audio-specific functionality including volume control, muting, and Web Audio API integration.
+
+### Key Features
+
+- **Scene-wide volume control** via gain nodes
+- **Mute/unmute functionality** with volume restoration
+- **Web Audio API integration** for precise audio control
+- **Multiple audio source management** with unified loading states
+- **Audio context management** with automatic creation or custom injection
+
+### Audio Context Usage
+
+AudioScene uses the Web Audio API's `AudioContext` for advanced audio processing:
+
+```javascript
+const audioScene = new AudioScene();
+
+// Option 1: Use automatic context creation (default)
+audioScene.load(); // Creates AudioContext internally
+
+// Option 2: Provide your own context for integration
+const customContext = new AudioContext();
+audioScene.setAudioContext(customContext);
+```
+
+### Volume Control (Target Gain)
+
+The scene uses a "target gain" system based on Web Audio API's gain scheduling:
+
+- **Target Gain**: The desired volume level that the audio system transitions towards
+  - `0.0` = silence (muted)
+  - `1.0` = original volume  
+  - `> 1.0` = amplified (use carefully to avoid distortion)
+
+**Why "Target"?**
+The Web Audio API allows smooth transitions between gain values over time. When you set a target gain, the audio system can gradually transition from the current level to the target level, preventing audio pops and clicks.
+
+```javascript
+// Set immediate volume change to 50%
+audioScene.setTargetGain(0.5);
+
+// Future: Could support smooth transitions
+// gainNode.gain.setTargetAtTime(0.5, audioContext.currentTime, 0.3);
+
+// Get current target volume
+const volume = audioScene.getTargetGain(); // 0.5
+
+// Mute (remembers previous volume)
+audioScene.mute();
+
+// Restore previous volume
+audioScene.unmute();
+```
+
+The current implementation sets gain immediately, but the "target" naming prepares for potential smooth volume transitions in future versions.
+
+### Audio Source Management
+
+Define audio sources before loading:
+
+```javascript
+// Add audio sources
+audioScene.defineMemorySource({
+  label: 'background-music',
+  url: '/audio/bg-music.mp3'
+});
+
+audioScene.defineMemorySource({
+  label: 'sound-effect',
+  url: '/audio/beep.wav'
+});
+
+// Load all sources
+audioScene.load();
+
+// Wait for loading completion
+await waitForState(() => audioScene.loaded);
+```
+
+### Playback
+
+Get playable audio sources after loading:
+
+```javascript
+// Get a source node for one-time playback
+const sourceNode = await audioScene.getSourceNode('sound-effect');
+
+// Play immediately
+sourceNode.start();
+
+// Play with delay
+sourceNode.start(audioContext.currentTime + 0.5);
+
+// Cleanup is automatic when playback ends
+```
+
+### Web Audio API Architecture
+
+```
+AudioSources → GainNode → AudioContext.destination → Speakers
+                  ↑
+            Volume Control
+```
+
+Each audio source connects through a gain node that provides scene-wide volume control before reaching the audio output.
+
+### State Management
+
+AudioScene inherits state management from SceneBase:
+
+- `STATE_INITIAL` - Scene created, sources defined
+- `STATE_LOADING` - Audio files downloading
+- `STATE_LOADED` - All sources ready for playback
+- `STATE_ABORTING` - Canceling downloads
+- `STATE_ABORTED` - Downloads canceled
+
+### Preloading with Progress and Abort
+
+AudioScene supports convenient preloading with automatic progress tracking:
+
+```javascript
+// Basic preload - returns promise and abort function
+const { promise, abort } = audioScene.preload();
+
+// Preload with options
+const { promise, abort } = audioScene.preload({
+  timeoutMs: 5000,  // Timeout after 5 seconds
+  onProgress: (progress) => {
+    console.log(`Loading: ${progress.sourcesLoaded}/${progress.numberOfSources}`);
+    console.log(`Bytes: ${progress.totalBytesLoaded}/${progress.totalSize}`);
+  }
+});
+
+// Wait for completion
+try {
+  const loadedScene = await promise;
+  console.log('All audio loaded successfully!');
+} catch (error) {
+  console.error('Preload failed:', error.message);
+}
+
+// Can abort anytime
+document.getElementById('cancelBtn').onclick = () => abort();
+```
+
+**Preload Features:**
+- **Promise-based**: Returns `{ promise, abort }` object
+- **Progress tracking**: Optional callback with loading progress
+- **Timeout support**: Configurable timeout with automatic abort
+- **Manual abort**: Call `abort()` function to cancel loading
+- **Error handling**: Promise rejects on timeout, abort, or loading errors
+
+### Progress Tracking
+
+Monitor loading progress across all sources:
+
+```javascript
+const progress = audioScene.progress;
+console.log(`${progress.sourcesLoaded}/${progress.numberOfSources} loaded`);
+console.log(`${progress.totalBytesLoaded}/${progress.totalSize} bytes`);
+```
+
+## Best Practices
+
+1. **Audio Context Lifecycle**: Create AudioContext in response to user interaction to avoid browser autoplay restrictions
+
+2. **Memory Management**: Audio sources are loaded into memory - consider file sizes for mobile devices
+
+3. **Source Node Usage**: Each `getSourceNode()` call creates a new playable instance - don't reuse source nodes
+
+4. **Volume Levels**: Keep target gain ≤ 1.0 to avoid audio clipping and distortion
+
+5. **Error Handling**: Check scene state before attempting playback
+
+```javascript
+if (audioScene.loaded) {
+  const source = await audioScene.getSourceNode('audio-label');
+  source.start();
+} else {
+  console.warn('Audio scene not ready for playback');
+}
+```

package/dist/network/loaders/base/SceneBase.svelte.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Base class for scene loaders that manage collections of media sources
+ */
+export default class SceneBase {
+    state: string;
+    loaded: boolean;
+    /**
+     * Get the array of sources managed by this scene
+     *
+     * @returns {Array} Array of source objects
+     */
+    get sources(): any[];
+    /**
+     * Extract the loader from a source object
+     *
+     * @param {*} source
+     *
+     * @returns {*} Loader object with progress and state properties
+     */
+    getLoaderFromSource(source: any): any;
+    /**
+     * Get scene loading progress
+     */
+    get progress(): {
+        totalBytesLoaded: number;
+        totalSize: number;
+        sourcesLoaded: number;
+        numberOfSources: number;
+    };
+    /**
+     * Get scene abort progress
+     */
+    get abortProgress(): {
+        sourcesAborted: number;
+        numberOfSources: number;
+    };
+    /**
+     * Start loading all sources
+     */
+    load(): void;
+    /**
+     * Abort loading all sources
+     */
+    abort(): void;
+    /**
+     * Preload all sources with progress tracking and abort capability
+     * - Starts loading and waits for completion
+     * - Supports timeout and progress callbacks
+     * - Returns object with promise and abort function
+     *
+     * @param {object} [options]
+     * @param {number} [options.timeoutMs=10000] - Timeout in milliseconds
+     * @param {Function} [options.onProgress] - Progress callback function
+     *
+     * @returns {object} Object with promise and abort function
+     * @returns {Promise<SceneBase>} returns.promise - Promise that resolves when loaded
+     * @returns {Function} returns.abort - Function to abort preloading
+     */
+    preload({ timeoutMs, onProgress }?: {
+        timeoutMs?: number;
+        onProgress?: Function;
+    }): object;
+    destroy(): void;
+    #private;
+}

package/dist/network/loaders/base/SceneBase.svelte.js

@@ -0,0 +1,283 @@
+import { LoadingStateMachine } from '../../../state/machines.js';
+
+import {
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_LOADED,
+  STATE_ABORTING,
+  STATE_ABORTED,
+  STATE_ERROR,
+  LOAD,
+  LOADED,
+  ABORT,
+  ABORTED
+} from '../../../state/machines.js';
+
+import { waitForState } from '../../../util/svelte.js';
+
+/**
+ * Base class for scene loaders that manage collections of media sources
+ */
+export default class SceneBase {
+  #state = new LoadingStateMachine();
+
+  // @note this exported state is set by onenter
+  state = $state(STATE_INITIAL);
+
+  loaded = $derived.by(() => {
+    return this.state === STATE_LOADED;
+  });
+
+  #progress = $derived.by(() => {
+    let totalSize = 0;
+    let totalBytesLoaded = 0;
+    let sourcesLoaded = 0;
+
+    const sources = this.sources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const loader = this.getLoaderFromSource(source);
+
+      const { bytesLoaded, size, loaded } = loader.progress;
+
+      totalSize += size;
+      totalBytesLoaded += bytesLoaded;
+
+      if (loaded) {
+        sourcesLoaded++;
+      }
+    }
+
+    return {
+      totalBytesLoaded,
+      totalSize,
+      sourcesLoaded,
+      numberOfSources
+    };
+  });
+
+  #abortProgress = $derived.by(() => {
+    let sourcesAborted = 0;
+    const sources = this.sources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const loader = this.getLoaderFromSource(source);
+      const loaderState = loader.state;
+
+      if (loaderState === STATE_ABORTED || loaderState === STATE_ERROR) {
+        sourcesAborted++;
+      }
+    }
+
+    return {
+      sourcesAborted,
+      numberOfSources
+    };
+  });
+
+  /**
+   * Construct SceneBase
+   */
+  constructor() {
+    const state = this.#state;
+
+    $effect(() => {
+      if (state.current === STATE_LOADING) {
+        const { sourcesLoaded, numberOfSources } = this.#progress;
+
+        if (sourcesLoaded === numberOfSources) {
+          this.#state.send(LOADED);
+        }
+      }
+    });
+
+    $effect(() => {
+      if (state.current === STATE_ABORTING) {
+        const { sourcesAborted, numberOfSources } = this.#abortProgress;
+
+        if (sourcesAborted === numberOfSources) {
+          this.#state.send(ABORTED);
+        }
+      }
+    });
+
+    state.onenter = (currentState) => {
+      if (currentState === STATE_LOADING) {
+        this.#startLoading();
+      } else if (currentState === STATE_ABORTING) {
+        this.#startAbort();
+      }
+
+      this.state = currentState;
+    };
+  }
+
+  /* ==== Abstract methods - must be implemented by subclasses */
+
+  /**
+   * Get the array of sources managed by this scene
+   *
+   * @returns {Array} Array of source objects
+   */
+  get sources() {
+    throw new Error('Subclass must implement sources getter');
+  }
+
+  /**
+   * Extract the loader from a source object
+   *
+   * @param {*} source
+   *
+   * @returns {*} Loader object with progress and state properties
+   */
+  // eslint-disable-next-line no-unused-vars
+  getLoaderFromSource(source) {
+    throw new Error('Subclass must implement getLoaderFromSource method');
+  }
+
+  /* ==== Common loader interface */
+
+  /**
+   * Get scene loading progress
+   */
+  get progress() {
+    return this.#progress;
+  }
+
+  /**
+   * Get scene abort progress
+   */
+  get abortProgress() {
+    return this.#abortProgress;
+  }
+
+  /**
+   * Start loading all sources
+   */
+  load() {
+    this.#state.send(LOAD);
+  }
+
+  /**
+   * Abort loading all sources
+   */
+  abort() {
+    this.#state.send(ABORT);
+  }
+
+  /**
+   * Preload all sources with progress tracking and abort capability
+   * - Starts loading and waits for completion
+   * - Supports timeout and progress callbacks
+   * - Returns object with promise and abort function
+   *
+   * @param {object} [options]
+   * @param {number} [options.timeoutMs=10000] - Timeout in milliseconds
+   * @param {Function} [options.onProgress] - Progress callback function
+   *
+   * @returns {object} Object with promise and abort function
+   * @returns {Promise<SceneBase>} returns.promise - Promise that resolves when loaded
+   * @returns {Function} returns.abort - Function to abort preloading
+   */
+  preload({ timeoutMs = 10000, onProgress } = {}) {
+    let timeoutId = null;
+    let progressIntervalId = null;
+    let isAborted = false;
+
+    const abort = () => {
+      if (isAborted) return;
+      isAborted = true;
+
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+
+      if (progressIntervalId) {
+        clearInterval(progressIntervalId);
+        progressIntervalId = null;
+      }
+
+      this.abort();
+    };
+
+    const promise = new Promise((resolve, reject) => {
+      // Set up progress tracking with polling
+      if (onProgress) {
+        progressIntervalId = setInterval(() => {
+          if (!isAborted) {
+            onProgress(this.progress);
+          }
+        }, 50); // Poll every 50ms
+      }
+
+      // Set up timeout
+      if (timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          abort();
+          reject(new Error(`Preload timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+
+      // Start loading
+      this.load();
+
+      // Wait for completion with extended timeout
+      const waitTimeout = Math.max(timeoutMs + 1000, 2000);
+      waitForState(() => {
+        return this.loaded ||
+               this.state === STATE_ABORTED ||
+               this.state === STATE_ERROR;
+      }, waitTimeout)
+        .then(() => {
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+          }
+
+          if (progressIntervalId) {
+            clearInterval(progressIntervalId);
+            progressIntervalId = null;
+          }
+
+          if (isAborted || this.state === STATE_ABORTED) {
+            reject(new Error('Preload was aborted'));
+          } else if (this.state === STATE_ERROR) {
+            reject(new Error('Preload failed due to error'));
+          } else if (this.loaded) {
+            resolve(this);
+          } else {
+            reject(new Error(`Preload failed: unexpected state ${this.state}`));
+          }
+        })
+        .catch(reject);
+    });
+
+    return { promise, abort };
+  }
+
+  destroy() {
+    // TODO: disconnect all sources?
+    // TODO: Unload loaders?
+  }
+
+  /* ==== Internal methods */
+
+  #startLoading() {
+    for (const source of this.sources) {
+      const loader = this.getLoaderFromSource(source);
+      loader.load();
+    }
+  }
+
+  #startAbort() {
+    for (const source of this.sources) {
+      const loader = this.getLoaderFromSource(source);
+      loader.abort();
+    }
+  }
+}

package/dist/network/loaders/image/ImageScene.svelte.d.ts

@@ -7,34 +7,21 @@
  * @property {string} label
  * @property {ImageLoader} imageLoader
  */
-export default class ImageScene {
-    state: string;
-    loaded: boolean;
+export default class ImageScene extends SceneBase {
     /**
-     * Get image scene loading progress
-     */
-    get progress(): {
-        totalBytesLoaded: number;
-        totalSize: number;
-        sourcesLoaded: number;
-        numberOfSources: number;
-    };
-    /**
-     * Get image scene abort progress
-     */
-    get abortProgress(): {
-        sourcesAborted: number;
-        numberOfSources: number;
-    };
-    /**
-     * Start loading all image sources
+     * Get the array of image sources managed by this scene
+     *
+     * @returns {ImageSceneSource[]}
      */
-    load(): void;
+    get sources(): ImageSceneSource[];
     /**
-     * Abort loading all image sources
+     * Extract the image loader from a source object
+     *
+     * @param {ImageSceneSource} source
+     *
+     * @returns {ImageLoader}
      */
-    abort(): void;
-    destroy(): void;
+    getLoaderFromSource(source: ImageSceneSource): ImageLoader;
     /**
      * Add image source
      * - Uses an ImageLoader instance to load image data from network
@@ -84,4 +71,5 @@ export type ImageSceneSource = {
     label: string;
     imageLoader: ImageLoader;
 };
+import SceneBase from '../base/SceneBase.svelte.js';
 import ImageLoader from './ImageLoader.svelte.js';

package/dist/network/loaders/image/ImageScene.svelte.js

@@ -2,21 +2,7 @@
 
 import * as expect from '../../../util/expect.js';
 
-import { LoadingStateMachine } from '../../../state/machines.js';
-
-import {
-  STATE_INITIAL,
-  STATE_LOADING,
-  STATE_LOADED,
-  STATE_ABORTING,
-  STATE_ABORTED,
-  STATE_ERROR,
-  LOAD,
-  LOADED,
-  ABORT,
-  ABORTED
-} from '../../../state/machines.js';
-
+import SceneBase from '../base/SceneBase.svelte.js';
 import ImageLoader from './ImageLoader.svelte.js';
 
 /**
@@ -30,152 +16,40 @@ import ImageLoader from './ImageLoader.svelte.js';
  * @property {ImageLoader} imageLoader
  */
 
-export default class ImageScene {
-  #state = new LoadingStateMachine();
-
-  // @note this exported state is set by onenter
-  state = $state(STATE_INITIAL);
-
-  loaded = $derived.by(() => {
-    return this.state === STATE_LOADED;
-  });
+export default class ImageScene extends SceneBase {
 
   /** @type {ImageSceneSource[]} */
   #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
-    };
-  });
-
-  #abortProgress = $derived.by(() => {
-    let sourcesAborted = 0;
-    const sources = this.#imageSources;
-    const numberOfSources = sources.length;
-
-    for (let j = 0; j < numberOfSources; j++) {
-      const source = sources[j];
-      const { imageLoader } = source;
-      const loaderState = imageLoader.state;
-
-      if (loaderState === STATE_ABORTED || loaderState === STATE_ERROR) {
-        sourcesAborted++;
-      }
-    } // end for
-
-    return {
-      sourcesAborted,
-      numberOfSources
-    };
-  });
-
-  #sourcesLoaded = $derived( this.#progress.sourcesLoaded );
-  #numberOfSources = $derived( this.#progress.numberOfSources );
 
   /**
    * Construct ImageScene
    */
   constructor() {
-    const state = this.#state;
-
-    $effect( () => {
-      if (state.current === STATE_LOADING) {
-        if (this.#sourcesLoaded === this.#numberOfSources) {
-          // console.log(`All [${this.#numberOfSources}] sources loaded`);
-          this.#state.send(LOADED);
-        }
-      }
-    } );
-
-    $effect(() => {
-      if (state.current === STATE_ABORTING) {
-        const { sourcesAborted, numberOfSources } = this.#abortProgress;
-
-        if (sourcesAborted === numberOfSources) {
-          // console.debug(`ImageScene: ${numberOfSources} sources aborted`);
-          this.#state.send(ABORTED);
-        }
-      }
-    });
-
-    state.onenter = ( currentState ) => {
-      // console.log('onenter', currentState );
-
-      if(currentState === STATE_LOADING )
-      {
-        // console.log('ImageScene:loading');
-        this.#startLoading();
-      }
-      else if(currentState === STATE_ABORTING )
-      {
-        // console.log('ImageScene:aborting');
-        this.#startAbort();
-      }
-
-      this.state = currentState;
-    };
-  }
-
-  /* ==== Common loader interface */
-
-  /**
-   * Get image scene loading progress
-   */
-  get progress() {
-    return this.#progress;
+    super();
   }
 
-  /**
-   * Get image scene abort progress
-   */
-  get abortProgress() {
-    return this.#abortProgress;
-  }
+  /* ==== SceneBase implementation */
 
   /**
-   * Start loading all image sources
+   * Get the array of image sources managed by this scene
+   *
+   * @returns {ImageSceneSource[]}
    */
-  load() {
-    this.#state.send(LOAD);
+  get sources() {
+    return this.#imageSources;
   }
 
   /**
-   * Abort loading all image sources
+   * Extract the image loader from a source object
+   *
+   * @param {ImageSceneSource} source
+   *
+   * @returns {ImageLoader}
    */
-  abort() {
-    this.#state.send(ABORT);
-  }
-
-  destroy() {
-    // TODO: disconnect all image sources?
-    // TODO: Unload ImageLoaders?
+  // eslint-disable-next-line no-unused-vars
+  getLoaderFromSource(source) {
+    return source.imageLoader;
   }
 
   /* ==== Source definitions */
@@ -241,18 +115,6 @@ export default class ImageScene {
     return source.imageLoader.getObjectURL();
   }
 
-  async #startLoading() {
-    for (const { imageLoader } of this.#imageSources) {
-      imageLoader.load();
-    }
-  }
-
-  #startAbort() {
-    for (const { imageLoader } of this.#imageSources) {
-      imageLoader.abort();
-    }
-  }
-
   /* ==== Internals */
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.4.27",
+	"version": "0.4.28",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"