waveframe 0.2.1 → 0.3.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "waveframe",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A high-performance, customizable React audio player with SoundCloud-style waveforms and built-in audio analysis.",
   "type": "module",
-  "main": "./dist/waveframe.umd.js",
-  "module": "./dist/waveframe.es.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "homepage": "https://gradippp.github.io/waveframe",
   "bugs": {
@@ -13,10 +13,10 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/waveframe.es.js",
-      "require": "./dist/waveframe.umd.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     },
-    "./style.css": "./dist/waveframe.css"
+    "./style.css": "./dist/index.css"
   },
   "files": [
     "dist"
@@ -65,12 +65,12 @@
     "react-dom": "^19.2.6",
     "tailwindcss": "^4.3.0",
     "tsc-alias": "^1.8.17",
+    "tsup": "^8.5.1",
     "typedoc": "^0.28.19",
     "typedoc-material-theme": "^1.4.1",
     "typedoc-plugin-extras": "^4.0.1",
     "typescript": "^6.0.3",
     "vite": "^8.0.11",
-    "vite-plugin-dts": "^5.0.0",
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
@@ -80,7 +80,7 @@
   "scripts": {
     "dev": "vite",
     "build": "pnpm run build:lib && pnpm run build:app",
-    "build:lib": "tsc && vite build",
+    "build:lib": "tsup && node scripts/prepend-use-client.js",
     "build:app": "tsc && cross-env BUILD_MODE=app vite build",
     "preview": "vite preview",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",

package/dist/src/App.d.ts

@@ -1,2 +0,0 @@
-declare function App(): import("react/jsx-runtime").JSX.Element;
-export default App;

package/dist/src/__tests__/WaveframePlayer.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/atoms/CodeBlock.d.ts

@@ -1,9 +0,0 @@
-import { default as React } from 'react';
-interface CodeBlockProps {
-    code: string;
-    highlightFn: (code: string) => string[];
-    onCopy: () => void;
-    copied: boolean;
-}
-export declare const CodeBlock: React.FC<CodeBlockProps>;
-export {};

package/dist/src/components/WaveframePlayer.d.ts

@@ -1,83 +0,0 @@
-import { default as React } from 'react';
-import { WaveframeTheme } from '../types.js';
-import { WaveframeEngine } from '../core/WaveframeEngine.js';
-/**
- * Props for the WaveframePlayer component
- */
-export interface WaveframePlayerProps {
-    /**
-     * The audio source to play. Can be a URL string or a Blob/File object.
-     */
-    media?: string | Blob;
-    /**
-     * Optional pre-generated peaks for the waveform (0-1 range).
-     * If omitted or empty, the player will automatically analyze the media.
-     */
-    peaks?: number[];
-    /**
-     * The artwork source to display. Can be a URL string or a Blob/File object.
-     */
-    artwork?: string | Blob;
-    /**
-     * The title of the track
-     */
-    title?: string;
-    /**
-     * The artist of the track
-     */
-    artist?: string;
-    /**
-     * The base color of the waveform bars
-     * @default "#e5e7eb" (light) or "#374151" (dark)
-     */
-    waveColor?: string;
-    /**
-     * The color of the played progress part of the waveform
-     * @default theme.primary or "#3b82f6"
-     */
-    progressColor?: string;
-    /**
-     * The height of the waveform in pixels
-     * @default 80
-     */
-    height?: number;
-    /**
-     * Additional CSS classes for the container
-     */
-    className?: string;
-    /**
-     * Inline styles for the container
-     */
-    style?: React.CSSProperties;
-    /**
-     * The number of bars to render. Use 'auto' to fit the container width.
-     * @default "auto"
-     */
-    resolution?: number | 'auto';
-    /**
-     * The width of each bar in pixels (if resolution is 'auto')
-     * @default 2
-     */
-    barWidth?: number;
-    /**
-     * The gap between bars in pixels (if resolution is 'auto')
-     * @default 1
-     */
-    barGap?: number;
-    /**
-     * Custom theme configuration
-     */
-    theme?: WaveframeTheme;
-    /**
-     * Optional WaveframeEngine instance for external control.
-     * If provided, the player will sync with this engine instead of creating its own.
-     */
-    engine?: WaveframeEngine;
-}
-/**
- * The standard "all-in-one" Waveframe player component.
- *
- * This component features a SoundCloud-inspired layout with a prominent
- * play/pause button positioned next to the track metadata.
- */
-export declare const WaveframePlayer: React.FC<WaveframePlayerProps>;

package/dist/src/core/PeakAnalyzer.d.ts

@@ -1,41 +0,0 @@
-/**
- * A specialized class for decoding audio data and generating waveform peaks.
- *
- * It leverages the Web Audio API (`AudioContext`) to process audio buffers
- * and extract amplitude data for visualization.
- */
-export declare class PeakAnalyzer {
-    private audioCtx;
-    /**
-     * Initializes the analyzer. AudioContext creation is deferred to the first use
-     * to comply with browser autoplay and resource management policies.
-     */
-    constructor();
-    /**
-     * Lazily creates or returns the existing AudioContext.
-     */
-    private getContext;
-    /**
-     * Processes media (URL or Blob) and generates a set of normalized peaks.
-     *
-     * @param media The URL string or Blob object to analyze.
-     * @param samples The number of peaks (bars) to generate. Defaults to 512.
-     * @returns A promise resolving to an array of normalized peak values (0 to 1).
-     *
-     * @example
-     * ```typescript
-     * const analyzer = new PeakAnalyzer();
-     *
-     * // Analyze from URL
-     * const peaksFromUrl = await analyzer.generatePeaks('https://example.com/audio.mp3');
-     *
-     * // Analyze from Blob
-     * const peaksFromBlob = await analyzer.generatePeaks(myAudioBlob);
-     * ```
-     */
-    generatePeaks(media: string | Blob, samples?: number): Promise<number[]>;
-    /**
-     * Closes the AudioContext and releases system audio resources.
-     */
-    dispose(): void;
-}

package/dist/src/core/PlayerCore.d.ts

@@ -1,92 +0,0 @@
-/**
- * Represents the low-level playback state of the audio element.
- */
-export type PlayerState = {
-    /** Whether the audio is currently playing */
-    isPlaying: boolean;
-    /** The current playback time in seconds */
-    currentTime: number;
-    /** The total duration of the track in seconds */
-    duration: number;
-    /** The current volume level (0 to 1) */
-    volume: number;
-    /** Whether the audio is currently muted */
-    muted: boolean;
-};
-/**
- * A callback function that receives the latest PlayerState.
- */
-export type PlayerListener = (state: PlayerState) => void;
-/**
- * The internal core class responsible for managing the HTMLAudioElement.
- *
- * It handles raw playback logic, volume control, and synchronizes the
- * internal `PlayerState` with DOM events from the underlying `Audio` instance.
- */
-export declare class PlayerCore {
-    private audio;
-    private listeners;
-    private _state;
-    /**
-     * Initializes a new PlayerCore instance and sets up event listeners on a new Audio object.
-     */
-    constructor();
-    /**
-     * Subscribes to various HTMLMediaElement events to keep the internal state in sync.
-     */
-    private initListeners;
-    /**
-     * Updates the internal state and notifies subscribers.
-     */
-    private updateState;
-    /**
-     * Triggers all registered listener callbacks.
-     */
-    private notify;
-    /**
-     * Registers a listener for state updates.
-     * @param listener The callback function.
-     * @returns An unsubscribe function.
-     */
-    subscribe(listener: PlayerListener): () => boolean;
-    /**
-     * Returns the current playback state.
-     */
-    get state(): PlayerState;
-    /**
-     * Updates the source URL of the underlying audio element.
-     * @param url The audio source URL.
-     */
-    setSource(url: string): void;
-    /**
-     * Starts playback. Returns a promise that resolves when playback begins.
-     */
-    play(): Promise<void>;
-    /**
-     * Pauses playback.
-     */
-    pause(): void;
-    /**
-     * Toggles between play and pause states.
-     */
-    togglePlay(): void;
-    /**
-     * Seeks to a specific time.
-     * @param time Time in seconds.
-     */
-    seek(time: number): void;
-    /**
-     * Sets the volume level.
-     * @param volume Level from 0 to 1.
-     */
-    setVolume(volume: number): void;
-    /**
-     * Mutes or unmutes the audio element.
-     * @param muted Mute status.
-     */
-    setMuted(muted: boolean): void;
-    /**
-     * Cleans up the audio element and removes all listeners.
-     */
-    dispose(): void;
-}

package/dist/src/core/WaveframeEngine.d.ts

@@ -1,122 +0,0 @@
-import { PlayerState } from './PlayerCore.js';
-/**
- * Represents the complete state of the Waveframe engine, combining playback and analysis.
- */
-export type EngineState = PlayerState & {
-    /** The current set of generated or provided waveform peaks (0-1 range) */
-    peaks: number[];
-    /** Whether an audio analysis process is currently in progress */
-    isAnalyzing: boolean;
-    /** Any error message encountered during playback or analysis */
-    error: string | null;
-};
-/**
- * A callback function that receives the latest EngineState.
- */
-export type EngineListener = (state: EngineState) => void;
-/**
- * The orchestrator class for Waveframe.
- *
- * It manages the lifecycle of audio playback and waveform analysis, providing a unified
- * store-like interface that can be easily consumed by React or other frameworks.
- *
- * @example
- * ```typescript
- * const engine = new WaveframeEngine();
- *
- * // Load from URL (automatic analysis if peaks omitted)
- * engine.load('https://example.com/audio.mp3');
- *
- * // Load from Blob with pre-computed peaks
- * engine.load(myBlob, [0.1, 0.5, 0.8]);
- *
- * // Subscription
- * const unsubscribe = engine.subscribe((state) => {
- *   console.log('Current time:', state.currentTime);
- * });
- * ```
- */
-export declare class WaveframeEngine {
-    private player;
-    private analyzer;
-    private listeners;
-    private _state;
-    private _media;
-    private _objectUrl;
-    /**
-     * Creates a new instance of the WaveframeEngine.
-     * Initializes internal PlayerCore and PeakAnalyzer.
-     */
-    constructor();
-    /**
-     * Internal method to update the state and notify all subscribers.
-     */
-    private updateState;
-    /**
-     * Notifies all registered listeners of a state change.
-     */
-    private notify;
-    /**
-     * Registers a listener to be called whenever the engine state changes.
-     * @param listener The callback function.
-     * @returns An unsubscribe function.
-     */
-    subscribe(listener: EngineListener): () => boolean;
-    /**
-     * Returns a snapshot of the current engine state.
-     * Useful for `useSyncExternalStore`.
-     */
-    getSnapshot(): EngineState;
-    /**
-     * Revokes any existing Object URLs to prevent memory leaks.
-     */
-    private revokeOldSource;
-    /**
-     * Loads media (URL or Blob) into the player.
-     *
-     * If a string is passed, it's treated as a URL and used directly for playback.
-     * If a Blob is passed, an Object URL is created for playback.
-     *
-     * If `peaks` are not provided, it automatically triggers an analysis.
-     *
-     * @param media The audio source (URL string or Blob/File object).
-     * @param peaks Optional pre-generated peaks for the waveform.
-     */
-    load(media: string | Blob, peaks?: number[]): void;
-    /**
-     * Analyzes the current media to generate waveform peaks.
-     * @param samples The number of peaks to generate. Defaults to 512.
-     */
-    analyze(samples?: number): Promise<void>;
-    /**
-     * Toggles playback between playing and paused.
-     */
-    togglePlay(): void;
-    /**
-     * Starts audio playback.
-     */
-    play(): void;
-    /**
-     * Pauses audio playback.
-     */
-    pause(): void;
-    /**
-     * Seeks to a specific position in the track.
-     * @param percentage The seek position as a decimal (0 to 1).
-     */
-    seek(percentage: number): void;
-    /**
-     * Sets the playback volume.
-     * @param volume The volume level (0 to 1).
-     */
-    setVolume(volume: number): void;
-    /**
-     * Mutes or unmutes the audio.
-     * @param muted Whether the audio should be muted.
-     */
-    setMuted(muted: boolean): void;
-    /**
-     * Disposes of the engine, pausing playback and clearing all listeners and resources.
-     */
-    dispose(): void;
-}

package/dist/src/hooks/usePersistentSettings.d.ts

@@ -1 +0,0 @@
-export declare const usePersistentSettings: (key: string, defaultValue: any) => any[];

package/dist/src/hooks/useResampledPeaks.d.ts

@@ -1 +0,0 @@
-export declare const useResampledPeaks: (peaks: number[], targetCount: number) => number[];

package/dist/src/hooks/useResizeObserver.d.ts

@@ -1 +0,0 @@
-export declare const useResizeObserver: (ref: React.RefObject<HTMLElement | null>) => number;

package/dist/src/hooks/useWaveframe.d.ts

@@ -1,51 +0,0 @@
-import { WaveframeEngine, EngineState } from '../core/WaveframeEngine.js';
-/**
- * Configuration options for the `useWaveframe` hook.
- */
-export interface UseWaveframeOptions {
-    /** Optional pre-computed peaks to skip automatic analysis */
-    peaks?: number[];
-    /** Optional external engine instance for shared playback across components */
-    engine?: WaveframeEngine;
-}
-/**
- * A headless hook that provides full control over the Waveframe engine.
- *
- * It manages the engine's lifecycle, loads the provided media, and returns
- * the current state along with playback controls.
- *
- * @param media The audio source (URL string or Blob/File object).
- * @param options Additional configuration and an optional external engine.
- *
- * @example
- * ```tsx
- * const { state, togglePlay, seek } = useWaveframe('https://example.com/audio.mp3');
- *
- * return (
- *   <div>
- *     <button onClick={togglePlay}>{state.isPlaying ? 'Pause' : 'Play'}</button>
- *     <div onClick={(e) => seek(0.5)}>Seek to Middle</div>
- *   </div>
- * );
- * ```
- */
-export declare const useWaveframe: (media: string | Blob | undefined, options?: UseWaveframeOptions) => {
-    /** The current reactive state of the engine */
-    state: EngineState;
-    /** The raw WaveframeEngine instance for advanced usage */
-    engine: WaveframeEngine;
-    /** Toggles playback between playing and paused */
-    togglePlay: () => void;
-    /** Starts audio playback */
-    play: () => void;
-    /** Pauses audio playback */
-    pause: () => void;
-    /** Seeks to a specific percentage (0-1) */
-    seek: (percentage: number) => void;
-    /** Sets the playback volume (0-1) */
-    setVolume: (v: number) => void;
-    /** Mutes or unmutes the audio */
-    setMuted: (m: boolean) => void;
-    /** Manually triggers a re-analysis of the current media */
-    analyze: (samples?: number) => Promise<void>;
-};

package/dist/src/hooks/useWaveframeStore.d.ts

@@ -1,27 +0,0 @@
-import { WaveframeEngine, EngineState } from '../core/WaveframeEngine.js';
-/**
- * A React hook that synchronizes a WaveframeEngine's state with a React component.
- *
- * It uses `useSyncExternalStore` for high-performance updates, ensuring that
- * the component only re-renders when the engine's state snapshot actually changes.
- *
- * @param engine The WaveframeEngine instance to subscribe to.
- * @returns The current EngineState (isPlaying, currentTime, peaks, etc.).
- *
- * @example
- * ```tsx
- * const MyPlayer = ({ engine }: { engine: WaveframeEngine }) => {
- *   const { isPlaying, currentTime, duration } = useWaveframeStore(engine);
- *
- *   return (
- *     <div>
- *       <button onClick={() => engine.togglePlay()}>
- *         {isPlaying ? 'Pause' : 'Play'}
- *       </button>
- *       <p>{currentTime.toFixed(2)} / {duration.toFixed(2)}</p>
- *     </div>
- *   );
- * };
- * ```
- */
-export declare const useWaveframeStore: (engine: WaveframeEngine) => EngineState;

package/dist/src/index.d.ts

@@ -1,7 +0,0 @@
-export * from './components/WaveframePlayer.js';
-export * from './core/WaveframeEngine.js';
-export * from './core/PlayerCore.js';
-export * from './core/PeakAnalyzer.js';
-export * from './hooks/useWaveframeStore.js';
-export * from './types.js';
-export * from './utils.js';

package/dist/src/molecules/ArtworkOverlay.d.ts

@@ -1,20 +0,0 @@
-import { default as React } from 'react';
-/**
- * Props for the ArtworkOverlay component.
- */
-interface ArtworkOverlayProps {
-    /** The URL or Object URL of the artwork image */
-    artworkUrl?: string;
-    /** The title of the track (used for alt text) */
-    title?: string;
-    /** Whether the artwork is currently being processed or the audio is analyzing */
-    isLoading?: boolean;
-}
-/**
- * A purely visual component for displaying track artwork.
- *
- * It handles loading states with a blur effect and provides a consistent
- * container for the track image.
- */
-export declare const ArtworkOverlay: React.FC<ArtworkOverlayProps>;
-export {};

package/dist/src/organisms/SettingsPanel.d.ts

@@ -1,29 +0,0 @@
-import { default as React } from 'react';
-import { WaveframeTheme, TrackInfo, WaveformConfig } from '../types.js';
-interface SettingsPanelProps {
-    theme: WaveframeTheme;
-    trackInfo: TrackInfo;
-    config: WaveformConfig;
-    scale: number;
-    engineState: {
-        isPlaying: boolean;
-        volume: number;
-        muted: boolean;
-        isAnalyzing: boolean;
-    };
-    onAnalyze: () => void;
-    onThemeChange: (theme: Partial<WaveframeTheme>) => void;
-    onTrackChange: (track: Partial<TrackInfo>) => void;
-    onConfigChange: (config: Partial<WaveformConfig>) => void;
-    onScaleChange: (scale: number) => void;
-    onTogglePreset: (type: 'light' | 'dark') => void;
-    onClearPeaks: () => void;
-    onFileUpload: (e: React.ChangeEvent<HTMLInputElement>) => void;
-    onArtworkUpload: (e: React.ChangeEvent<HTMLInputElement>) => void;
-    onReset: () => void;
-    onTogglePlay: () => void;
-    onSetVolume: (v: number) => void;
-    onSetMuted: (m: boolean) => void;
-}
-export declare const SettingsPanel: React.FC<SettingsPanelProps>;
-export {};

package/dist/src/organisms/Waveform.d.ts

@@ -1,15 +0,0 @@
-import { default as React } from 'react';
-interface WaveformProps {
-    peaks: number[];
-    currentTime: number;
-    duration: number;
-    waveColor: string;
-    progressColor: string;
-    height: number;
-    onSeek: (percentage: number) => void;
-    resolution?: number | 'auto';
-    barWidth?: number;
-    barGap?: number;
-}
-export declare const Waveform: React.FC<WaveformProps>;
-export {};

package/dist/src/types/index.d.ts

@@ -1,75 +0,0 @@
-/**
- * Defines the core color palette for the Waveframe component.
- *
- * @example
- * ```tsx
- * const darkTheme: WaveframeTheme = {
- *   bg: '#111827',
- *   primary: '#ec4899',
- *   text: '#f9fafb',
- *   border: '#1f2937'
- * };
- * ```
- */
-export interface WaveframeTheme {
-    /** The main background color of the player */
-    bg: string;
-    /** The primary accent color (used for play button and progress) */
-    primary: string;
-    /** The color of the text elements (title, artist, time) */
-    text: string;
-    /** The color of borders and dividers */
-    border: string;
-}
-/**
- * Metadata associated with an audio track.
- *
- * @example
- * ```tsx
- * const track: TrackInfo = {
- *   title: 'Electronic Sunset',
- *   artist: 'Digital Nomad',
- *   artwork: 'https://example.com/art.jpg', // or a Blob object
- *   audioUrl: 'https://example.com/audio.mp3'
- * };
- * ```
- */
-export interface TrackInfo {
-    /** The title of the track */
-    title: string;
-    /** The artist of the track */
-    artist: string;
-    /** The artwork source (URL string or Blob/File object) */
-    artwork: string | Blob;
-    /** The URL to the actual audio file */
-    audioUrl: string;
-}
-/**
- * Defines the resolution of the waveform.
- * - `number`: A fixed number of bars to render.
- * - `'auto'`: Compute the number of bars dynamically based on the container width.
- */
-export type Resolution = number | 'auto';
-/**
- * Configuration options for how the waveform is rendered visually.
- *
- * @example
- * ```tsx
- * const config: WaveformConfig = {
- *   resolution: 'auto',
- *   barWidth: 2,
- *   barGap: 1,
- *   height: 100
- * };
- * ```
- */
-export interface WaveformConfig {
-    /** The number of bars to render, or 'auto' to compute based on container width */
-    resolution: Resolution;
-    /** The width of each individual bar in pixels */
-    barWidth: number;
-    /** The spacing between each bar in pixels */
-    barGap: number;
-    /** The total height of the waveform in pixels */
-    height: number;
-}