@scandit/web-datacapture-core 8.2.1 → 8.3.0

package/build/js/private/ViewControls+related.js

@@ -1 +1 @@
-import {a as a$1}from'../chunks/chunk-4J3Y5IIL.js';import {d as d$1}from'../chunks/chunk-NT5WI2PS.js';import {b}from'../chunks/chunk-A225YZFY.js';import {a}from'../chunks/chunk-XR65N6EG.js';import {f as f$1,g}from'../chunks/chunk-3D2HNEVH.js';var S=(t=>(t.Idle="idle",t.Pressed="pressed",t))(S||{}),d=class{constructor(e,t){this.state="idle";this.isHover=false;this.controlTypeToAriaLabelMap={"camera-fov":"Switch camera field of view",camera:"Switch camera",torch:"Toggle torch"};this.control=e,this.domHost=t,this.onTouchStartListener=this.onTouchStart.bind(this),this.onMouseEnterListener=this.onMouseEnter.bind(this),this.onMouseLeaveListener=this.onMouseLeave.bind(this),this.onClickListener=this.onClick.bind(this),this.setup();}get frameSource(){var e,t;return (t=(e=this.control.view)==null?void 0:e.getContext())==null?void 0:t.frameSource}get context(){var e;return (e=this.control.view)==null?void 0:e.getContext()}async install(){this.button||this.setup();let e=await this.canShow();return e?(this.updateButtonBackground(this.button,this.getImageFromState()),this.show()):this.hide(),e}remove(e=false){e&&this.button?(this.button.removeEventListener("mouseenter",this.onMouseEnterListener),this.button.removeEventListener("mouseleave",this.onMouseLeaveListener),this.button.removeEventListener("touchstart",this.onTouchStartListener),this.button.removeEventListener("click",this.onClickListener),this.button.remove(),this.isHover=false,this.button=void 0):this.hide();}hide(){this.button&&(this.button.style.display="none");}show(){this.button&&(this.button.style.display="block");}setupButton(){let e=document.createElement("button");e.type="button",e.style.display="none",e.className=`scandit-control-widget scandit-control-widget-${this.control.type}`,this.updateButtonBackground(e,this.getImageFromState()),this.domHost.append(e),e.addEventListener("mouseenter",this.onMouseEnterListener),e.addEventListener("mouseleave",this.onMouseLeaveListener),b.isDesktopDevice()||e.addEventListener("touchstart",this.onTouchStartListener),e.addEventListener("click",this.onClickListener),e.setAttribute("aria-pressed",String(this.state==="pressed"));let t=this.control.type,i=this.controlTypeToAriaLabelMap[t];return e.setAttribute("aria-label",i),this.button=e,this.button}setup(){this.setupButton();}onTouchStart(){var e,t;(e=this.button)==null||e.removeEventListener("mouseenter",this.onMouseEnterListener),(t=this.button)==null||t.removeEventListener("mouseleave",this.onMouseLeaveListener);}onMouseEnter(){this.isHover=true,this.updateButtonBackground(this.button,this.getImageFromState());}onMouseLeave(){this.isHover=false,this.updateButtonBackground(this.button,this.getImageFromState());}onClick(){var e;this.state=this.state==="pressed"?"idle":"pressed",this.buttonClicked(),this.updateButtonBackground(this.button,this.getImageFromState()),(e=this.button)==null||e.setAttribute("aria-pressed",String(this.state==="pressed"));}updateButtonBackground(e,t){t!=null&&e!=null&&(e.style.backgroundImage=`url(${JSON.stringify(t)})`);}},v=class extends d{constructor(e,t){super(e,t);}async buttonClicked(){await this.frameSource.setDesiredTorchState(this.retrieveTorchState()==="on"?"off":"on");}async canShow(){return this.isTorchAvailable()}getImageFromState(){return this.retrieveTorchState()==="on"?this.isHover?this.control.torchOnPressedImage:this.control.torchOnImage:this.isHover?this.control.torchOffPressedImage:this.control.torchOffImage}setup(){if(this.control.torchOffImage==null||this.control.torchOnImage==null){a.log(a.Level.Warn,"TorchSwitchControl icon is not set or is empty, the control will not be rendered.");return}super.setup();}async isTorchAvailable(){return f$1(this.frameSource)?this.frameSource.isTorchAvailable():false}retrieveTorchState(){return f$1(this.frameSource)?this.frameSource.getDesiredTorchState():"off"}},f=class extends d{constructor(e,t){super(e,t);}async canShow(){return (await a$1.getAll()).length>1}getImageFromState(){return this.isHover?this.control.pressedImage:this.control.idleImage}async buttonClicked(){if(this.isTransitioning)return;let e=await this.getNextDeviceCamera();e&&await this.switchCameras(e);}setup(){if(this.control.idleImage==null){a.log(a.Level.Warn,"CameraSwitchControl idle icon is not set or is empty, the control will not be rendered.");return}super.setup();}async getNextDeviceCamera(){var a;let e=await a$1.getAll(false,true),t=this.frameSource?this.frameSource:null,i=t==null?void 0:t.deviceId,r=e.findIndex(n=>n.deviceId===i);return r>-1?(a=e[r+1])!=null?a:e[0]:e.length>0?e[0]:null}async switchCameras(e){var a,n,l;this.isTransitioning=true;let t=(a=this.context)==null?void 0:a.frameSource,i,r;t!=null&&(i=new g(t.settings),r=t.desiredState),await(t==null?void 0:t.switchToDesiredState("off")),i!=null&&await e.applySettings(i),await((n=this.context)==null?void 0:n.setFrameSource(e)),await((l=this.context)==null?void 0:l.frameSource).switchToDesiredState(r!=null?r:"on"),this.isTransitioning=false;}},C=class extends d{constructor(e,t){super(e,t);}async install(){let e=await super.install();return e&&await this.setInitialCamera(),e}async canShow(){return !b.isIOSDeviceWithExtendedCameraAccess()||!f$1(this.frameSource)?false:d$1.isIOSBackDualWideCameraLabel(this.frameSource.label)||d$1.isIOSBackCameraLabel(this.frameSource.label)||d$1.isIOSUltraWideBackCameraLabel(this.frameSource.label)}getImageFromState(){return this.isUltraWideBackCamera()?this.isHover?this.control.cameraFOVUltraWidePressedImage:this.control.cameraFOVUltraWideImage:this.isHover?this.control.cameraFOVWidePressedImage:this.control.cameraFOVWideImage}async buttonClicked(){if(this.isTransitioning)return;let e=await this.getAlternativeCamera();e&&await this.switchCameras(e);}setup(){if(this.control.cameraFOVUltraWideImage==null||this.control.cameraFOVWideImage==null){a.log(a.Level.Warn,"CameraFOVSwitchControl icon is not set or is empty, the control will not be rendered.");return}super.setup();}async setInitialCamera(){var e,t;if(!this.isTransitioning&&!d$1.isIOSBackCameraLabel((t=(e=this.frameSource)==null?void 0:e.label)!=null?t:"")){let r=(await a$1.getAll()).find(a=>d$1.isIOSBackCameraLabel(a.label));r&&await this.switchCameras(r);}}isUltraWideBackCamera(){return f$1(this.frameSource)?d$1.isIOSUltraWideBackCameraLabel(this.frameSource.label):false}async getAlternativeCamera(){return (await a$1.getAll()).find(t=>this.isUltraWideBackCamera()?d$1.isIOSBackCameraLabel(t.label):d$1.isIOSUltraWideBackCameraLabel(t.label))}async switchCameras(e){var a,n,l;this.isTransitioning=true;let t=(a=this.context)==null?void 0:a.frameSource,i,r;t!=null&&(i=new g(t.settings),r=t.desiredState),await(t==null?void 0:t.switchToDesiredState("off")),i!=null&&await e.applySettings(i),await((n=this.context)==null?void 0:n.setFrameSource(e)),await((l=this.context)==null?void 0:l.frameSource).switchToDesiredState(r!=null?r:"on"),this.isTransitioning=false;}};export{S as ButtonState,f as CameraSwitchControlWidget,C as PrivateCameraFOVSwitchControlWidget,v as PrivateTorchControlWidget};
+import {a as a$1}from'../chunks/chunk-RY2EW3RR.js';import {d as d$1}from'../chunks/chunk-YUZDO2PC.js';import {b}from'../chunks/chunk-YONR3EGV.js';import {a}from'../chunks/chunk-XR65N6EG.js';import {f as f$1,g}from'../chunks/chunk-3D2HNEVH.js';var S=(t=>(t.Idle="idle",t.Pressed="pressed",t))(S||{}),d=class{constructor(e,t){this.state="idle";this.isHover=false;this.controlTypeToAriaLabelMap={"camera-fov":"Switch camera field of view",camera:"Switch camera",torch:"Toggle torch"};this.control=e,this.domHost=t,this.onTouchStartListener=this.onTouchStart.bind(this),this.onMouseEnterListener=this.onMouseEnter.bind(this),this.onMouseLeaveListener=this.onMouseLeave.bind(this),this.onClickListener=this.onClick.bind(this),this.setup();}get frameSource(){var e,t;return (t=(e=this.control.view)==null?void 0:e.getContext())==null?void 0:t.frameSource}get context(){var e;return (e=this.control.view)==null?void 0:e.getContext()}async install(){this.button||this.setup();let e=await this.canShow();return e?(this.updateButtonBackground(this.button,this.getImageFromState()),this.show()):this.hide(),e}remove(e=false){e&&this.button?(this.button.removeEventListener("mouseenter",this.onMouseEnterListener),this.button.removeEventListener("mouseleave",this.onMouseLeaveListener),this.button.removeEventListener("touchstart",this.onTouchStartListener),this.button.removeEventListener("click",this.onClickListener),this.button.remove(),this.isHover=false,this.button=void 0):this.hide();}hide(){this.button&&(this.button.style.display="none");}show(){this.button&&(this.button.style.display="block");}setupButton(){let e=document.createElement("button");e.type="button",e.style.display="none",e.className=`scandit-control-widget scandit-control-widget-${this.control.type}`,this.updateButtonBackground(e,this.getImageFromState()),this.domHost.append(e),e.addEventListener("mouseenter",this.onMouseEnterListener),e.addEventListener("mouseleave",this.onMouseLeaveListener),b.isDesktopDevice()||e.addEventListener("touchstart",this.onTouchStartListener),e.addEventListener("click",this.onClickListener),e.setAttribute("aria-pressed",String(this.state==="pressed"));let t=this.control.type,i=this.controlTypeToAriaLabelMap[t];return e.setAttribute("aria-label",i),this.button=e,this.button}setup(){this.setupButton();}onTouchStart(){var e,t;(e=this.button)==null||e.removeEventListener("mouseenter",this.onMouseEnterListener),(t=this.button)==null||t.removeEventListener("mouseleave",this.onMouseLeaveListener);}onMouseEnter(){this.isHover=true,this.updateButtonBackground(this.button,this.getImageFromState());}onMouseLeave(){this.isHover=false,this.updateButtonBackground(this.button,this.getImageFromState());}onClick(){var e;this.state=this.state==="pressed"?"idle":"pressed",this.buttonClicked(),this.updateButtonBackground(this.button,this.getImageFromState()),(e=this.button)==null||e.setAttribute("aria-pressed",String(this.state==="pressed"));}updateButtonBackground(e,t){t!=null&&e!=null&&(e.style.backgroundImage=`url(${JSON.stringify(t)})`);}},v=class extends d{constructor(e,t){super(e,t);}async buttonClicked(){await this.frameSource.setDesiredTorchState(this.retrieveTorchState()==="on"?"off":"on");}async canShow(){return this.isTorchAvailable()}getImageFromState(){return this.retrieveTorchState()==="on"?this.isHover?this.control.torchOnPressedImage:this.control.torchOnImage:this.isHover?this.control.torchOffPressedImage:this.control.torchOffImage}setup(){if(this.control.torchOffImage==null||this.control.torchOnImage==null){a.log(a.Level.Warn,"TorchSwitchControl icon is not set or is empty, the control will not be rendered.");return}super.setup();}async isTorchAvailable(){return f$1(this.frameSource)?this.frameSource.isTorchAvailable():false}retrieveTorchState(){return f$1(this.frameSource)?this.frameSource.getDesiredTorchState():"off"}},f=class extends d{constructor(e,t){super(e,t);}async canShow(){return (await a$1.getAll()).length>1}getImageFromState(){return this.isHover?this.control.pressedImage:this.control.idleImage}async buttonClicked(){if(this.isTransitioning)return;let e=await this.getNextDeviceCamera();e&&await this.switchCameras(e);}setup(){if(this.control.idleImage==null){a.log(a.Level.Warn,"CameraSwitchControl idle icon is not set or is empty, the control will not be rendered.");return}super.setup();}async getNextDeviceCamera(){var a;let e=await a$1.getAll(false,true),t=this.frameSource?this.frameSource:null,i=t==null?void 0:t.deviceId,r=e.findIndex(n=>n.deviceId===i);return r>-1?(a=e[r+1])!=null?a:e[0]:e.length>0?e[0]:null}async switchCameras(e){var a,n,l;this.isTransitioning=true;let t=(a=this.context)==null?void 0:a.frameSource,i,r;t!=null&&(i=new g(t.settings),r=t.desiredState),await(t==null?void 0:t.switchToDesiredState("off")),i!=null&&await e.applySettings(i),await((n=this.context)==null?void 0:n.setFrameSource(e)),await((l=this.context)==null?void 0:l.frameSource).switchToDesiredState(r!=null?r:"on"),this.isTransitioning=false;}},C=class extends d{constructor(e,t){super(e,t);}async install(){let e=await super.install();return e&&await this.setInitialCamera(),e}async canShow(){return !b.isIOSDeviceWithExtendedCameraAccess()||!f$1(this.frameSource)?false:d$1.isIOSBackDualWideCameraLabel(this.frameSource.label)||d$1.isIOSBackCameraLabel(this.frameSource.label)||d$1.isIOSUltraWideBackCameraLabel(this.frameSource.label)}getImageFromState(){return this.isUltraWideBackCamera()?this.isHover?this.control.cameraFOVUltraWidePressedImage:this.control.cameraFOVUltraWideImage:this.isHover?this.control.cameraFOVWidePressedImage:this.control.cameraFOVWideImage}async buttonClicked(){if(this.isTransitioning)return;let e=await this.getAlternativeCamera();e&&await this.switchCameras(e);}setup(){if(this.control.cameraFOVUltraWideImage==null||this.control.cameraFOVWideImage==null){a.log(a.Level.Warn,"CameraFOVSwitchControl icon is not set or is empty, the control will not be rendered.");return}super.setup();}async setInitialCamera(){var e,t;if(!this.isTransitioning&&!d$1.isIOSBackCameraLabel((t=(e=this.frameSource)==null?void 0:e.label)!=null?t:"")){let r=(await a$1.getAll()).find(a=>d$1.isIOSBackCameraLabel(a.label));r&&await this.switchCameras(r);}}isUltraWideBackCamera(){return f$1(this.frameSource)?d$1.isIOSUltraWideBackCameraLabel(this.frameSource.label):false}async getAlternativeCamera(){return (await a$1.getAll()).find(t=>this.isUltraWideBackCamera()?d$1.isIOSBackCameraLabel(t.label):d$1.isIOSUltraWideBackCameraLabel(t.label))}async switchCameras(e){var a,n,l;this.isTransitioning=true;let t=(a=this.context)==null?void 0:a.frameSource,i,r;t!=null&&(i=new g(t.settings),r=t.desiredState),await(t==null?void 0:t.switchToDesiredState("off")),i!=null&&await e.applySettings(i),await((n=this.context)==null?void 0:n.setFrameSource(e)),await((l=this.context)==null?void 0:l.frameSource).switchToDesiredState(r!=null?r:"on"),this.isTransitioning=false;}};export{S as ButtonState,f as CameraSwitchControlWidget,C as PrivateCameraFOVSwitchControlWidget,v as PrivateTorchControlWidget};

package/build/js/private/ViewControls_related.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="emscripten" />
-import { g as FrameSource } from '../Camera-DhGjpcjv.js';
-import { y as DataCaptureView, C as Control, p as DataCaptureContext } from '../DataCaptureContext-Dvdr7st4.js';
+import { g as FrameSource } from '../Camera-Cc__1Nc-.js';
+import { C as Control, f as DataCaptureContext, p as DataCaptureView } from '../DataCaptureContext-BcSpF9Dt.js';
 import { CameraFOVSwitchControl } from '../controls/CameraFOVSwitchControl.js';
 import { CameraSwitchControl } from '../controls/CameraSwitchControl.js';
 import { TorchSwitchControl } from '../controls/TorchSwitchControl.js';
@@ -29,9 +29,11 @@ import './CustomLocationsView.js';
 import './View.js';
 import './AnchorPositions.js';
 import './nativeHandle.js';
+import './AdditionalLayerPosition.js';
 import '../license/OpenSourceSoftwareLicenseInfo.js';
 import '../logger.js';
 import './FrameReaders/ColorType.js';
+import './BatteryInterface.js';
 import '../LoadingStatus.js';
 import './djinni-types/index.js';
 import './HtmlElementState.js';

package/build/js/private/ViewStyles.js

@@ -1 +1 @@
-export{a as getDataCaptureViewStyles}from'../chunks/chunk-UOQFOEG6.js';
+export{a as getDataCaptureViewStyles}from'../chunks/chunk-A5G2NHT2.js';

package/build/js/private/ViewsRegistry.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="emscripten" />
-import { y as DataCaptureView } from '../DataCaptureContext-Dvdr7st4.js';
-import '../Camera-DhGjpcjv.js';
+import { p as DataCaptureView } from '../DataCaptureContext-BcSpF9Dt.js';
+import '../Camera-Cc__1Nc-.js';
 import '../commons/Rect.js';
 import './Serializable.js';
 import '../commons/Point.js';
@@ -26,9 +26,11 @@ import './CustomLocationsView.js';
 import './View.js';
 import './AnchorPositions.js';
 import './nativeHandle.js';
+import './AdditionalLayerPosition.js';
 import '../license/OpenSourceSoftwareLicenseInfo.js';
 import '../logger.js';
 import './FrameReaders/ColorType.js';
+import './BatteryInterface.js';
 import '../LoadingStatus.js';
 import './djinni-types/index.js';
 import './HtmlElementState.js';

package/build/js/private/customHowler/AudioCache.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="emscripten" />
+/**
+ * Audio buffer cache manager
+ * Avoids re-loading and re-decoding the same audio files
+ *
+ * Benefits:
+ * - Multiple Howl instances for the same sound share one AudioBuffer
+ * - Avoids redundant network requests and CPU-intensive decoding
+ * - Particularly important for frequently played sounds (like beeps)
+ *
+ * @private
+ */
+declare class AudioCache {
+    private cache;
+    /**
+     * Get a cached audio buffer promise
+     * @param src Audio source URL (data URI or file path)
+     * @returns Promise<AudioBuffer> if cached, undefined otherwise
+     */
+    get(src: string): Promise<AudioBuffer> | undefined;
+    /**
+     * Cache an audio buffer promise
+     * @param src Audio source URL
+     * @param promise Promise that resolves to decoded AudioBuffer
+     */
+    set(src: string, promise: Promise<AudioBuffer>): void;
+    /**
+     * Clear all cached buffers (useful for cleanup or testing)
+     */
+    clear(): void;
+    /**
+     * Get cache size (for monitoring)
+     */
+    size(): number;
+}
+
+export { AudioCache };

package/build/js/private/customHowler/AudioCache.js

@@ -0,0 +1 @@
+export{a as AudioCache}from'../../chunks/chunk-NYYGU4ZV.js';

package/build/js/private/customHowler/Howl.d.ts

@@ -0,0 +1,189 @@
+/// <reference types="emscripten" />
+/**
+ * Type definitions for customHowler audio system
+ * @private
+ */
+interface HowlOptions {
+    src: string | string[];
+    /**
+     * Force use of HTML5 audio element instead of Web Audio API.
+     * Useful for testing or specific use cases where HTML5 is preferred.
+     * Default: auto-detect (use Web Audio API everywhere for non-blocking playback)
+     * Note: HTML5 audio blocks the main thread and should be avoided.
+     */
+    html5?: boolean;
+}
+/**
+ * Lightweight Howl implementation using Web Audio API
+ *
+ * ## Features
+ *
+ * - **Web Audio API** (Desktop): Off-main-thread audio processing (smooth UI rendering)
+ * - **HTML5 Audio** (iOS): Reliable playback on iOS devices (avoids pitch shifting)
+ * - **HTML5 Sound pooling**: Maintains a pool of audio elements for efficient concurrent playback
+ * - **Caching**: Decoded AudioBuffers cached globally (efficient repeated playback)
+ * - **Overlapping playback**: Multiple source nodes allow simultaneous sounds
+ * - **Tree-shakable**: Side-effect free, lazy initialization
+ * - **Auto-unlock**: Automatically unlocks audio on first user interaction
+ * - **Auto-detect**: Automatically uses HTML5 on iOS, Web Audio API on desktop
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const beep = new Howl({ src: 'beep.mp3' });
+ * beep.play(); // First call unlocks audio, subsequent calls play immediately
+ * beep.play(); // Overlapping playback supported
+ * ```
+ *
+ * ## Performance Notes
+ *
+ * **Desktop (Web Audio API):**
+ * - Each play() call creates a new AudioBufferSourceNode (allows overlapping)
+ * - AudioBuffer is decoded once and shared (efficient repeated playback)
+ * - Audio runs on separate thread (doesn't block UI)
+ *
+ * **iOS (HTML5 Audio):**
+ * - Uses HTML5 audio pool for efficient concurrent playback
+ * - Main thread may block briefly during playback (unavoidable on iOS)
+ * - Reliable pitch and sample rate (avoids Web Audio API issues)
+ *
+ * ## Overlapping Playback
+ *
+ * Each call to play() creates a new AudioBufferSourceNode, allowing the same
+ * sound to play multiple times simultaneously (useful for rapid scanning feedback).
+ * The decoded AudioBuffer is shared, only the source nodes are created per play.
+ */
+declare class Howl {
+    /** Audio source URL (data URI, file path, or URL) */
+    private src;
+    /** Use HTML5 audio element (true) or Web Audio API (false) */
+    private html5;
+    /** Decoded audio buffer (cached after first load) - for Web Audio API only */
+    private audioBuffer;
+    /** Loading promise (prevents duplicate loads) */
+    private loadPromise;
+    /** Pool of HTML5 Sound objects (similar to Howler.js) */
+    private soundPool;
+    private soundPoolSize;
+    /** Track inactive (available) sounds for O(1) lookup instead of O(n) find */
+    private inactiveSounds;
+    constructor(options: HowlOptions);
+    /**
+     * Load and decode the audio file
+     *
+     * ## Caching Strategy
+     *
+     * This method implements three levels of caching:
+     *
+     * 1. **Instance cache**: Check if this Howl instance has already loaded the audio
+     * 2. **Instance promise cache**: Check if this Howl instance is currently loading
+     * 3. **Global cache**: Check if any Howl instance has loaded this URL
+     *
+     * Benefits:
+     * - Multiple Howl instances for the same sound share one AudioBuffer
+     * - Prevents duplicate network requests
+     * - Avoids redundant CPU-intensive audio decoding
+     * - Important for rapid scanning where same sound plays frequently
+     *
+     * ## Loading Process
+     *
+     * 1. Fetch audio file (supports data URIs, relative paths, full URLs)
+     * 2. Convert to ArrayBuffer
+     * 3. Decode using AudioContext.decodeAudioData() (async, CPU-intensive)
+     * 4. Cache the decoded AudioBuffer
+     *
+     * Note: decodeAudioData() runs in a separate thread and doesn't block the main thread
+     *
+     * @returns Promise<AudioBuffer> - Decoded audio ready for playback
+     */
+    private load;
+    /**
+     * Get or create a sound from the pool
+     * Follows Howler.js pattern: pool of Sound objects with state tracking
+     * Uses Set for O(1) lookup of inactive sounds instead of O(n) array find
+     * @private
+     */
+    private getSoundFromPool;
+    /**
+     * Verify audio buffer contains actual data (debugging helper, no-op in production)
+     * @private
+     */
+    private verifyAudioBuffer;
+    /**
+     * Handle playback errors for Web Audio API
+     * @private
+     */
+    private handlePlaybackError;
+    /**
+     * Prepare AudioContext for playback
+     * @private
+     */
+    private prepareAudioContext;
+    /**
+     * Play sound using HTML5 Sound pool (Howler.js style)
+     * Follows Howler.js pattern of Sound objects with state tracking
+     *
+     * ## Non-blocking Playback
+     *
+     * On iOS, the HTML5 audio play() call can block the main thread. To prevent
+     * this from blocking overlay rendering during continuous scanning, we defer
+     * the play() call to the next animation frame using requestAnimationFrame.
+     * This keeps the current frame free for UI rendering.
+     *
+     * @private
+     */
+    private playHTML5;
+    /**
+     * Play the sound.
+     *
+     * This method is the public API - call it to play the sound.
+     * It's non-blocking (fire-and-forget) and supports overlapping playback.
+     *
+     * ## Behavior
+     *
+     * - Creates a new AudioBufferSourceNode for each call (allows overlapping)
+     * - Reuses cached AudioBuffer (efficient repeated playback)
+     * - Auto-unlocks audio on first play (if not already unlocked)
+     * - Uses iOS MediaStreamDestination workaround when needed
+     *
+     * ## Example
+     *
+     * ```typescript
+     * const beep = new Howl({ src: 'beep.mp3' });
+     * beep.play(); // First play
+     * beep.play(); // Overlapping play (both sounds play simultaneously)
+     * ```
+     */
+    play(): void;
+    /**
+     * Internal async play method
+     *
+     * ## Playback Flow
+     *
+     * 1. **Unlock check**: Ensure audio is unlocked (iOS requirement)
+     * 2. **Load**: Load and decode audio if not already cached
+     * 3. **Create source**: Create new AudioBufferSourceNode for this playback
+     * 4. **Setup audio graph**: Source → Gain → Destination
+     * 5. **Start playback**: Call source.start(0) to play immediately
+     * 6. **Cleanup**: Disconnect source after playback completes
+     *
+     * ## Platform-specific playback
+     *
+     * **Desktop:**
+     * - Uses Web Audio API with standard AudioContext destination
+     *
+     * **iOS:**
+     * - Uses HTML5 <audio> elements for reliable playback
+     * - Avoids Web Audio API pitch shifting issues on real devices
+     *
+     * ## Performance Notes
+     *
+     * - AudioBuffer loading/decoding happens once (cached)
+     * - Each play() creates only a lightweight source node
+     * - Gain node allows future volume control (currently 1.0)
+     * - Source disconnects automatically after playback to free memory
+     */
+    private playAsync;
+}
+
+export { Howl, type HowlOptions };

package/build/js/private/customHowler/Howl.js

@@ -0,0 +1 @@
+export{a as Howl}from'../../chunks/chunk-EEWGHHL4.js';

package/build/js/private/customHowler/HowlRegistry.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="emscripten" />
+/**
+ * Register a Howl instance in the global registry
+ * @private
+ */
+declare function registerHowlInstance(howl: any): void;
+/**
+ * Unregister a Howl instance from the global registry
+ * @private
+ */
+declare function unregisterHowlInstance(howl: any): void;
+/**
+ * Get all active Howl instances (for internal cleanup)
+ * @private
+ */
+declare function getActiveHowlInstances(): any[];
+
+export { getActiveHowlInstances, registerHowlInstance, unregisterHowlInstance };

package/build/js/private/customHowler/HowlRegistry.js

@@ -0,0 +1 @@
+export{c as getActiveHowlInstances,a as registerHowlInstance,b as unregisterHowlInstance}from'../../chunks/chunk-ZAXZRQYF.js';

package/build/js/private/customHowler/Html5Sound.d.ts

@@ -0,0 +1,52 @@
+/// <reference types="emscripten" />
+/**
+ * Wrapper for HTML5 audio element with state tracking (similar to Howler.js Sound)
+ * Tracks paused, ended, and seek position independently from element state
+ * @private
+ */
+declare class Html5Sound {
+    node: HTMLAudioElement;
+    _paused: boolean;
+    _ended: boolean;
+    _seek: number;
+    private onEndedHandler;
+    private onPauseHandler;
+    private onPlayHandler;
+    private onInactive?;
+    constructor(src: string, onInactive?: (sound: Html5Sound) => void);
+    /**
+     * Handle natural playback completion
+     * @private
+     */
+    private onEnded;
+    /**
+     * Track pause events
+     * @private
+     */
+    private onPause;
+    /**
+     * Track play events
+     * @private
+     */
+    private onPlay;
+    /**
+     * Start playback from the beginning, deferred to the next animation frame.
+     * Deferring avoids blocking the main thread (critical for smooth overlay
+     * rendering during continuous scanning on iOS).
+     */
+    play(): void;
+    /**
+     * Pause playback and preserve current position
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to beginning
+     */
+    stop(): void;
+    /**
+     * Clean up event listeners (for disposal)
+     */
+    dispose(): void;
+}
+
+export { Html5Sound };

package/build/js/private/customHowler/Html5Sound.js

@@ -0,0 +1 @@
+export{a as Html5Sound}from'../../chunks/chunk-AAPD5YU3.js';

package/build/js/private/customHowler/UnlockManager.d.ts

@@ -0,0 +1,39 @@
+/// <reference types="emscripten" />
+/**
+ * Manages audio unlock state and event listeners
+ * Handles setup of user interaction listeners for iOS audio unlock
+ * @private
+ */
+declare class UnlockManager {
+    private setupComplete;
+    private handler;
+    private readonly events;
+    private readonly doc;
+    /**
+     * Constructor - accepts optional document for dependency injection
+     * @param doc - Document object (defaults to global document for browser, undefined for tests)
+     */
+    constructor(doc?: Document);
+    /**
+     * Check if unlock setup is complete
+     */
+    isSetupComplete(): boolean;
+    /**
+     * Mark setup as complete
+     */
+    markSetupComplete(): void;
+    /**
+     * Setup unlock handlers and add event listeners
+     */
+    setup(handler: EventListener): void;
+    /**
+     * Reset unlock state (called during disposal/reset)
+     */
+    reset(): void;
+    /**
+     * Remove all event listeners
+     */
+    private removeListeners;
+}
+
+export { UnlockManager };

package/build/js/private/customHowler/UnlockManager.js

@@ -0,0 +1 @@
+export{a as UnlockManager}from'../../chunks/chunk-LV6LGCDC.js';

package/build/js/private/customHowler/WebAudioContextManager.d.ts

@@ -0,0 +1,161 @@
+/// <reference types="emscripten" />
+import { AudioCache } from './AudioCache.js';
+
+declare function getAudioCacheInstance(): AudioCache;
+/**
+ * Global Web Audio Context manager
+ * Manages a single AudioContext instance for efficient audio playback
+ *
+ * ## iOS Safari Audio Workaround
+ *
+ * iOS Safari has a known issue where Web Audio API playback may not produce
+ * sound on real devices (works fine in simulator). The workaround routes audio
+ * through a MediaStreamDestination connected to an HTML5 Audio element:
+ *
+ * ```
+ * AudioBufferSourceNode → GainNode → MediaStreamDestination → HTML5 <audio> → Speakers
+ * ```
+ *
+ * This tricks iOS Safari into treating the audio as a "live stream" (like a video
+ * conference), which it allows to play reliably. The HTML5 audio element stays
+ * playing continuously, acting as a bridge between Web Audio and the actual speakers.
+ *
+ * ## Why This Works
+ *
+ * - iOS Safari blocks standard Web Audio destination output (silently fails)
+ * - MediaStreams are treated differently (needed for WebRTC/conferencing)
+ * - By routing through MediaStream, iOS allows the audio to reach speakers
+ * - Web Audio API still runs off main thread (smooth UI rendering)
+ *
+ * ## References
+ *
+ * - Community workaround: https://www.reddit.com/r/webdev/comments/1ldjqa1/comment/mymw7v3/
+ * - Used for background audio, PWAs, and continuous scanning scenarios
+ */
+declare class WebAudioContextManager {
+    private audioContext;
+    private isUnlocked;
+    private unlockPromise;
+    private unlockAttempts;
+    private readonly MAX_UNLOCK_ATTEMPTS;
+    private lastKnownSampleRate;
+    /** iOS-specific: MediaStreamDestination for routing audio */
+    private mediaStreamDestination;
+    /** iOS-specific: HTML5 audio element that plays the MediaStream */
+    private streamAudioElement;
+    private handlerStreamAudioElementError;
+    private handlerStreamAudioElementPause;
+    /**
+     * Get the AudioContext (must be created via unlock first on iOS)
+     *
+     * ## Sample Rate: Native Hardware Rate
+     *
+     * We let the browser use its native sample rate to prevent pitch shifting:
+     *
+     * **The Problem with Forcing 44.1kHz:**
+     * - iOS may ignore the sampleRate parameter in AudioContext constructor
+     * - This creates a mismatch between requested (44.1kHz) and actual sample rate
+     * - When AudioContext uses different rate than what we requested, audio plays at wrong pitch
+     * - This happens especially on iOS with dynamic audio routing
+     *
+     * **The Solution:**
+     * - Let the browser choose its native sample rate (no sampleRate parameter)
+     * - Detect the actual sample rate and remember it
+     * - If sample rate changes during session, recreate context to match
+     * - Web Audio API automatically resamples audio buffers to match
+     * - Sound quality remains identical (transparent resampling)
+     *
+     * **Why This Works:**
+     * - AudioContext will use the hardware's preferred rate
+     * - No mismatch between requested and actual rates
+     * - Prevents pitch shifting caused by rate mismatches
+     * - More stable across different iOS devices and configurations
+     */
+    getContext(): AudioContext;
+    /**
+     * Get the audio destination node.
+     *
+     * On iOS: Returns MediaStreamDestination routed through HTML5 Audio element
+     * On other platforms: Returns the standard AudioContext destination
+     *
+     * ## iOS MediaStreamDestination Workaround
+     *
+     * Why we need this:
+     * - iOS Safari silently blocks Web Audio API output on real devices
+     * - The AudioContext reports "running" and source.start() succeeds
+     * - But no sound reaches the speakers (works fine in iOS Simulator)
+     *
+     * The solution:
+     * 1. Create a MediaStreamDestination node from the AudioContext
+     * 2. Create an HTML5 <audio> element
+     * 3. Connect the audio element to the MediaStream via srcObject
+     * 4. Start playing the audio element (it plays continuously as a live stream)
+     * 5. Route all audio through this destination instead of context.destination
+     *
+     * Result:
+     * - iOS Safari treats this as a "live stream" (like WebRTC)
+     * - Live streams are allowed to play reliably on iOS
+     * - The <audio> element acts as a bridge to the speakers
+     * - Individual sounds play through the stream as they're triggered
+     *
+     * ## Lifecycle & Resource Management
+     *
+     * The stream audio element plays continuously for the page lifetime. This is
+     * intentional because:
+     * - Recreating it requires a user gesture on iOS (can't do on-demand)
+     * - Resource usage is minimal when no audio is playing through it
+     * - Stopping and restarting could fail due to iOS autoplay restrictions
+     *
+     * The element can be cleaned up by calling dispose() if needed, but this will
+     * require a new user gesture to re-enable audio on iOS.
+     *
+     * Error handling: If the stream stops or errors unexpectedly, it automatically
+     * attempts to restart to maintain audio functionality.
+     *
+     * @returns AudioDestinationNode (desktop) or MediaStreamAudioDestinationNode (iOS)
+     */
+    getDestination(): AudioDestinationNode | MediaStreamAudioDestinationNode;
+    onStreamAudioElementError(): void;
+    onStreamAudioElementPause(): void;
+    /**
+     * Create AudioContext (must be called synchronously during a user gesture on iOS)
+     */
+    private createContext;
+    /**
+     * Unlock audio playback on iOS/mobile during user gesture.
+     *
+     * ## iOS Safari Requirements
+     *
+     * iOS Safari requires explicit user interaction before audio can play:
+     *
+     * 1. **AudioContext must be created during a user gesture**
+     *    - Creating it later (async) will result in silent playback
+     *    - Must happen in synchronous event handler (touchstart, click, etc.)
+     *
+     * 2. **AudioContext.resume() must be called during a user gesture**
+     *    - Even if state is "running", calling resume() during gesture is required
+     *    - Must be initiated synchronously (can complete asynchronously)
+     *
+     * 3. **Actual audio playback must occur during the unlock**
+     *    - Just creating and resuming context isn't enough
+     *    - Must play a buffer (even silent) to truly unlock audio
+     *
+     * ## Implementation Flow
+     *
+     * 1. User taps screen (event handler runs synchronously)
+     * 2. Create AudioContext synchronously
+     * 3. Call context.resume() synchronously (completes async)
+     * 4. This async method plays a silent scratch buffer
+     * 5. On iOS, this creates MediaStreamDestination on first call
+     * 6. Mark as unlocked after successful playback
+     *
+     * @returns Promise that resolves when unlock is complete
+     */
+    unlock(): Promise<void>;
+    /**
+     * Get the unlock status
+     */
+    get unlocked(): boolean;
+}
+
+export { WebAudioContextManager, getAudioCacheInstance };

package/build/js/private/customHowler/WebAudioContextManager.js

@@ -0,0 +1 @@
+export{c as WebAudioContextManager,a as createAudioContext,b as getAudioCacheInstance}from'../../chunks/chunk-Y3TODCJD.js';

package/build/js/private/customHowler/debug.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="emscripten" />
+/**
+ * Debug logging wrapper - only logs when DEBUG is enabled
+ *
+ * Used for diagnostic information that helps troubleshoot audio issues.
+ * These logs are verbose and should not appear in production.
+ *
+ * ## Build-Time Configuration
+ *
+ * Enable debug logging by building with:
+ * ```bash
+ * DEBUG_AUDIO=true npm run build
+ * ```
+ *
+ * ## Debug Symbols
+ *
+ * - 🎧 Unlock event listener setup
+ * - 👆 User interaction detection
+ * - 🎵 AudioContext creation
+ * - 🔓 Unlock process (context resume, scratch buffer playback)
+ * - 🔊 Audio playback state, buffer data, and routing details
+ * - ✅ Success indicators
+ * - ⚠️ Warnings for potential issues
+ * - ❌ Error indicators
+ */
+declare const debugLog: CallableFunction | undefined;
+
+export { debugLog };

package/build/js/private/customHowler/debug.js

@@ -0,0 +1 @@
+export{a as debugLog}from'../../chunks/chunk-SJIN27Q5.js';

package/build/js/private/customHowler/index.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="emscripten" />
+export { Howl, HowlOptions } from './Howl.js';

package/build/js/private/customHowler/index.js

@@ -0,0 +1 @@
+export{a as disposeGlobalAudioContext,c as ensureUnlockSetup,b as resetGlobalAudioContext}from'../../chunks/chunk-6AQGNP4S.js';export{a as Howl}from'../../chunks/chunk-EEWGHHL4.js';