@thewhateverapp/tile-sdk 0.20.0 → 0.20.2

package/dist/audio/index.d.ts

@@ -0,0 +1,48 @@
+type HowlStatic = any;
+export interface SoundOptions {
+    volume?: number;
+    loop?: boolean;
+    rate?: number;
+    sprite?: Record<string, [number, number]>;
+    onload?: () => void;
+    onloaderror?: (id: number, error: any) => void;
+    onplay?: () => void;
+    onend?: () => void;
+    onstop?: () => void;
+    onpause?: () => void;
+}
+export interface SoundController {
+    play: (spriteId?: string) => void;
+    pause: () => void;
+    stop: () => void;
+    volume: (vol?: number) => number | void;
+    rate: (rate?: number) => number | void;
+    loop: (loop?: boolean) => boolean | void;
+    playing: () => boolean;
+    duration: () => number;
+    state: () => 'unloaded' | 'loading' | 'loaded';
+    unload: () => void;
+}
+/**
+ * Hook for playing sound effects
+ *
+ * @param src - URL to the audio file
+ * @param options - Howler options
+ * @returns Sound controller
+ */
+export declare function useSound(src: string, options?: SoundOptions): SoundController;
+/**
+ * Hook for playing background music with auto-play on mount
+ *
+ * @param src - URL to the music file
+ * @param options - Howler options (loop defaults to true for music)
+ * @returns Sound controller
+ */
+export declare function useMusic(src: string, options?: SoundOptions): SoundController;
+/**
+ * Re-export Howl for advanced use cases
+ * Returns null during SSR, the Howl class after client-side load
+ */
+export declare function getHowl(): Promise<HowlStatic | null>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/audio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AA4BA,KAAK,UAAU,GAAG,GAAG,CAAC;AA6BtB,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAC/C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACxC,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACvC,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,CAAC;IACzC,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/C,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,eAAe,CAoGjF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,eAAe,CAgBjF;AAED;;;GAGG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAI1D"}

package/dist/audio/index.js

@@ -0,0 +1,182 @@
+'use client';
+/**
+ * Audio SDK for tile-sdk
+ *
+ * SSR-safe wrapper around Howler.js with React hooks for easy audio management.
+ * Handles dynamic import, lifecycle management, and provides a clean API.
+ *
+ * @example
+ * ```tsx
+ * import { useSound, useMusic } from '@thewhateverapp/tile-sdk/audio';
+ *
+ * function MyGame() {
+ *   const jumpSound = useSound('/sounds/jump.mp3');
+ *   const bgMusic = useMusic('/music/theme.mp3', { volume: 0.3, loop: true });
+ *
+ *   return (
+ *     <button onClick={() => jumpSound.play()}>
+ *       Jump
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+import { useEffect, useRef, useState } from 'react';
+let Howl = null;
+let howlerLoaded = false;
+let howlerPromise = null;
+/**
+ * Load Howler dynamically (client-side only)
+ */
+async function loadHowler() {
+    if (typeof window === 'undefined') {
+        throw new Error('Howler can only be loaded in the browser');
+    }
+    if (howlerLoaded)
+        return;
+    if (howlerPromise) {
+        return howlerPromise;
+    }
+    howlerPromise = import('howler').then((module) => {
+        Howl = module.Howl;
+        howlerLoaded = true;
+    });
+    return howlerPromise;
+}
+/**
+ * Hook for playing sound effects
+ *
+ * @param src - URL to the audio file
+ * @param options - Howler options
+ * @returns Sound controller
+ */
+export function useSound(src, options = {}) {
+    const [isLoaded, setIsLoaded] = useState(false);
+    const howlRef = useRef(null);
+    useEffect(() => {
+        let cancelled = false;
+        loadHowler().then(() => {
+            if (cancelled || !Howl)
+                return;
+            const howl = new Howl({
+                src: [src],
+                volume: options.volume ?? 1.0,
+                loop: options.loop ?? false,
+                rate: options.rate ?? 1.0,
+                sprite: options.sprite,
+                onload: () => {
+                    setIsLoaded(true);
+                    options.onload?.();
+                },
+                onloaderror: options.onloaderror,
+                onplay: options.onplay,
+                onend: options.onend,
+                onstop: options.onstop,
+                onpause: options.onpause,
+            });
+            howlRef.current = howl;
+        }).catch(err => {
+            console.error('[useSound] Failed to load Howler:', err);
+        });
+        return () => {
+            cancelled = true;
+            if (howlRef.current) {
+                howlRef.current.unload();
+                howlRef.current = null;
+            }
+        };
+    }, [src]);
+    return {
+        play: (spriteId) => {
+            if (howlRef.current) {
+                howlRef.current.play(spriteId);
+            }
+        },
+        pause: () => {
+            if (howlRef.current) {
+                howlRef.current.pause();
+            }
+        },
+        stop: () => {
+            if (howlRef.current) {
+                howlRef.current.stop();
+            }
+        },
+        volume: (vol) => {
+            if (howlRef.current) {
+                if (vol !== undefined) {
+                    howlRef.current.volume(vol);
+                }
+                else {
+                    return howlRef.current.volume();
+                }
+            }
+        },
+        rate: (rate) => {
+            if (howlRef.current) {
+                if (rate !== undefined) {
+                    howlRef.current.rate(rate);
+                }
+                else {
+                    return howlRef.current.rate();
+                }
+            }
+        },
+        loop: (loop) => {
+            if (howlRef.current) {
+                if (loop !== undefined) {
+                    howlRef.current.loop(loop);
+                }
+                else {
+                    return howlRef.current.loop();
+                }
+            }
+        },
+        playing: () => {
+            return howlRef.current ? howlRef.current.playing() : false;
+        },
+        duration: () => {
+            return howlRef.current ? howlRef.current.duration() : 0;
+        },
+        state: () => {
+            return howlRef.current ? howlRef.current.state() : 'unloaded';
+        },
+        unload: () => {
+            if (howlRef.current) {
+                howlRef.current.unload();
+                howlRef.current = null;
+            }
+        },
+    };
+}
+/**
+ * Hook for playing background music with auto-play on mount
+ *
+ * @param src - URL to the music file
+ * @param options - Howler options (loop defaults to true for music)
+ * @returns Sound controller
+ */
+export function useMusic(src, options = {}) {
+    const sound = useSound(src, {
+        loop: true, // Music usually loops
+        ...options,
+    });
+    const hasAutoPlayed = useRef(false);
+    useEffect(() => {
+        if (sound.state() === 'loaded' && !hasAutoPlayed.current) {
+            hasAutoPlayed.current = true;
+            sound.play();
+        }
+    }, [sound.state()]);
+    return sound;
+}
+/**
+ * Re-export Howl for advanced use cases
+ * Returns null during SSR, the Howl class after client-side load
+ */
+export async function getHowl() {
+    if (typeof window === 'undefined')
+        return null;
+    await loadHowler();
+    return Howl;
+}

package/dist/index.d.ts

@@ -12,6 +12,8 @@ OverlaySlot, FullOverlay, GradientOverlay, } from './react/overlay/index.js';
 export type { VideoState, VideoControls, VideoContextValue, VideoPlayerProps, CuePoint, SlideImage, SlideshowState, SlideshowControls, SlideshowContextValue, SlideshowProps, SlotPosition, OverlaySlotProps, FullOverlayProps, GradientOverlayProps, } from './react/overlay/index.js';
 export { confetti } from './react/confetti.js';
 export type { ConfettiOptions } from './react/confetti.js';
+export { useSound, useMusic, getHowl } from './audio/index.js';
+export type { SoundOptions, SoundController } from './audio/index.js';
 export { getTileBridge, TileBridge } from './bridge/TileBridge.js';
 export type { TileMessage, TileConfig, TileTokenData, KeyboardState, VisibilityState, SafeAreaInsets } from './bridge/TileBridge.js';
 export { StateClient } from './state/StateClient.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAEL,WAAW,EACX,aAAa,EACb,QAAQ,EAAE,0BAA0B;AACpC,WAAW,EACX,YAAY,EACZ,gBAAgB,EAEhB,SAAS,EACT,iBAAiB,EACjB,YAAY,EAAE,8BAA8B;AAE5C,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAEV,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EAER,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EAEd,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACnE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGrI,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGtE,cAAc,kBAAkB,CAAC;AAGjC,cAAc,YAAY,CAAC;AAG3B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAEL,WAAW,EACX,aAAa,EACb,QAAQ,EAAE,0BAA0B;AACpC,WAAW,EACX,YAAY,EACZ,gBAAgB,EAEhB,SAAS,EACT,iBAAiB,EACjB,YAAY,EAAE,8BAA8B;AAE5C,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAEV,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EAER,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EAEd,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACnE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGrI,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGtE,cAAc,kBAAkB,CAAC;AAGjC,cAAc,YAAY,CAAC;AAG3B,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -17,6 +17,8 @@ Slideshow, useSlideshowState, useSlideshow, // Alias for useSlideshowState
 OverlaySlot, FullOverlay, GradientOverlay, } from './react/overlay/index.js';
 // Confetti - CSS-based, mobile WebView safe
 export { confetti } from './react/confetti.js';
+// Audio hooks - SSR-safe Howler.js wrappers
+export { useSound, useMusic, getHowl } from './audio/index.js';
 // Bridge for secure communication
 export { getTileBridge, TileBridge } from './bridge/TileBridge.js';
 // State API client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhateverapp/tile-sdk",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "SDK for building interactive tiles on The Whatever App platform",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,6 +13,10 @@
       "types": "./dist/excalibur/index.d.ts",
       "import": "./dist/excalibur/index.js"
     },
+    "./audio": {
+      "types": "./dist/audio/index.d.ts",
+      "import": "./dist/audio/index.js"
+    },
     "./spec": {
       "types": "./dist/spec/index.d.ts",
       "import": "./dist/spec/index.js"
@@ -55,20 +59,26 @@
   "peerDependencies": {
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
-    "excalibur": "^0.29.0"
+    "excalibur": "^0.29.0",
+    "howler": "^2.2.0"
   },
   "peerDependenciesMeta": {
     "excalibur": {
       "optional": true
+    },
+    "howler": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@types/howler": "^2.2.11",
     "@types/matter-js": "^0.19.0",
     "@types/node": "^20.0.0",
     "@types/react": "^18.2.48",
     "@types/react-dom": "^18.2.18",
     "eslint": "^9.39.1",
     "excalibur": "^0.29.3",
+    "howler": "^2.2.4",
     "next": "^14.2.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"