@hapticjs/core 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { accessibility, gaming, notifications, presets, system, ui } from './presets/index.js';
+export { accessibility, emotions, gaming, notifications, presets, system, ui } from './presets/index.js';
 
 /** A single step in a haptic sequence */
 interface HapticStep {
@@ -267,6 +267,270 @@ declare class FallbackManager {
  */
 declare function detectAdapter(): HapticAdapter;
 
+/** Options for SoundEngine construction */
+interface SoundEngineOptions {
+    enabled?: boolean;
+    volume?: number;
+    muted?: boolean;
+}
+/** Options for the click sound */
+interface ClickOptions {
+    pitch?: 'low' | 'mid' | 'high';
+    volume?: number;
+}
+/** Options for the generic tone player */
+interface ToneOptions {
+    waveform?: OscillatorType;
+    volume?: number;
+    decay?: boolean;
+}
+/**
+ * Lightweight audio feedback engine using Web Audio API.
+ * Produces tiny UI sounds synced with haptics — all procedurally generated.
+ */
+declare class SoundEngine {
+    private ctx;
+    private masterVolume;
+    private _muted;
+    private _enabled;
+    constructor(options?: SoundEngineOptions);
+    /** Short click sound */
+    click(options?: ClickOptions): Promise<void>;
+    /** Ultra-short tick sound */
+    tick(): Promise<void>;
+    /** Bubbly pop sound — quick frequency sweep high to low */
+    pop(): Promise<void>;
+    /** Swipe/swoosh sound — noise with quick fade */
+    whoosh(): Promise<void>;
+    /** Musical chime */
+    chime(note?: 'C4' | 'E4' | 'G4' | 'C5'): Promise<void>;
+    /** Low buzzer/error tone — two descending tones */
+    error(): Promise<void>;
+    /** Ascending two-tone success sound */
+    success(): Promise<void>;
+    /** Subtle tap sound */
+    tap(): Promise<void>;
+    /** Toggle sound — ascending for on, descending for off */
+    toggle(on: boolean): Promise<void>;
+    /** Generic tone player */
+    playTone(frequency: number, duration: number, options?: ToneOptions): Promise<void>;
+    /** Set master volume (0-1) */
+    setVolume(volume: number): void;
+    /** Mute all sounds */
+    mute(): void;
+    /** Unmute sounds */
+    unmute(): void;
+    /** Whether sounds are currently muted */
+    get muted(): boolean;
+    /** Current master volume */
+    get volume(): number;
+    /** Whether the engine is enabled */
+    get enabled(): boolean;
+    /** Close AudioContext and release resources */
+    dispose(): void;
+    /** Lazily create and return AudioContext, handling autoplay policy */
+    private _getContext;
+    /** Compute effective volume from master + per-sound volume */
+    private _effectiveVolume;
+    /** Schedule a tone at a specific AudioContext time */
+    private _scheduleTone;
+}
+
+/** Options for VisualEngine construction */
+interface VisualEngineOptions {
+    enabled?: boolean;
+    target?: HTMLElement;
+    intensity?: number;
+}
+interface FlashOptions {
+    color?: string;
+    duration?: number;
+    opacity?: number;
+}
+interface ShakeOptions {
+    intensity?: number;
+    duration?: number;
+}
+interface PulseOptions {
+    scale?: number;
+    duration?: number;
+}
+interface RippleOptions {
+    color?: string;
+    size?: number;
+    duration?: number;
+}
+interface GlowOptions {
+    color?: string;
+    duration?: number;
+    size?: number;
+}
+interface BounceOptions$1 {
+    height?: number;
+    duration?: number;
+}
+interface JelloOptions {
+    intensity?: number;
+    duration?: number;
+}
+interface RubberOptions {
+    scaleX?: number;
+    scaleY?: number;
+    duration?: number;
+}
+interface HighlightOptions {
+    color?: string;
+    duration?: number;
+}
+/**
+ * CSS-based visual feedback effects that complement haptic patterns.
+ * Works everywhere including desktop/iOS where vibration is unavailable.
+ */
+declare class VisualEngine {
+    private _enabled;
+    private _target;
+    private _intensity;
+    private _styleInjected;
+    private _cleanups;
+    constructor(options?: VisualEngineOptions);
+    /** Quick screen flash overlay */
+    flash(options?: FlashOptions): void;
+    /** CSS shake animation on target */
+    shake(options?: ShakeOptions): void;
+    /** Scale pulse animation */
+    pulse(options?: PulseOptions): void;
+    /** Material Design style ripple at coordinates */
+    ripple(x: number, y: number, options?: RippleOptions): void;
+    /** Box shadow glow effect */
+    glow(options?: GlowOptions): void;
+    /** Bounce animation on target */
+    bounce(options?: BounceOptions$1): void;
+    /** Jello/wobble animation */
+    jello(options?: JelloOptions): void;
+    /** Rubber band scale effect */
+    rubber(options?: RubberOptions): void;
+    /** Brief background color highlight */
+    highlight(options?: HighlightOptions): void;
+    /** Change the target element for animations */
+    setTarget(element: HTMLElement): void;
+    /** Whether the engine is enabled */
+    get enabled(): boolean;
+    /** Current intensity multiplier */
+    get intensity(): number;
+    /** Remove all active animations and clean up */
+    dispose(): void;
+    private _canRun;
+    private _getTarget;
+    /** Inject a <style> tag for keyframes on first use */
+    private _injectStyles;
+    /** Ensure a @keyframes rule exists in our style tag */
+    private _ensureKeyframes;
+    /** Apply a CSS animation to an element and clean up after */
+    private _applyAnimation;
+    private _removeCleanup;
+}
+
+/** Multi-sensory theme preset — configures haptic, sound, and visual behavior */
+interface ThemePreset {
+    name: string;
+    hapticIntensity: number;
+    soundEnabled: boolean;
+    soundVolume: number;
+    visualEnabled: boolean;
+    visualStyle: 'flash' | 'ripple' | 'shake' | 'glow' | 'pulse';
+    colors: {
+        primary: string;
+        success: string;
+        error: string;
+        warning: string;
+    };
+}
+/** Built-in theme presets */
+declare const themes: Record<string, ThemePreset>;
+/**
+ * Manages multi-sensory themes that configure haptic, sound, and visual behavior.
+ */
+declare class ThemeManager {
+    private _current;
+    private _registry;
+    constructor();
+    /** Apply a theme by name or provide a custom preset */
+    setTheme(name: string | ThemePreset): void;
+    /** Get the current theme preset */
+    getTheme(): ThemePreset;
+    /** Current theme name */
+    get current(): string;
+    /** List all available theme names */
+    listThemes(): string[];
+    /** Register a custom theme preset */
+    registerTheme(preset: ThemePreset): void;
+}
+
+/** Options for the SensoryEngine */
+interface SensoryEngineOptions {
+    haptic?: Partial<HapticConfig>;
+    sound?: {
+        enabled?: boolean;
+        volume?: number;
+        muted?: boolean;
+    };
+    visual?: {
+        enabled?: boolean;
+        target?: HTMLElement;
+        intensity?: number;
+    };
+    theme?: string | ThemePreset;
+}
+/**
+ * Higher-level engine that combines haptic + sound + visual feedback.
+ * Ties HapticEngine, SoundEngine, VisualEngine, and ThemeManager together.
+ *
+ * Usage:
+ *   const engine = SensoryEngine.create();
+ *   engine.tap();
+ *   engine.success();
+ *   engine.setTheme('gaming');
+ */
+declare class SensoryEngine {
+    private _haptic;
+    private _sound;
+    private _visual;
+    private _themes;
+    constructor(options?: SensoryEngineOptions);
+    /** Factory method */
+    static create(options?: SensoryEngineOptions): SensoryEngine;
+    /** Tap: vibrate + click sound + pulse visual */
+    tap(): Promise<void>;
+    /** Success: haptic success + success sound + green glow */
+    success(): Promise<void>;
+    /** Error: haptic error + error sound + red flash */
+    error(): Promise<void>;
+    /** Warning: haptic warning + warning sound + yellow flash */
+    warning(): Promise<void>;
+    /** Selection: haptic selection + tick sound + subtle pulse */
+    selection(): Promise<void>;
+    /** Toggle: haptic toggle + toggle sound + pulse */
+    toggle(on: boolean): Promise<void>;
+    /** Play a haptic pattern (sound/visual auto-mapped from theme) */
+    play(pattern: string | HapticPattern | HapticStep[]): Promise<void>;
+    /** Apply a theme by name or preset */
+    setTheme(name: string | ThemePreset): void;
+    /** Access the underlying HapticEngine */
+    get haptic(): HapticEngine;
+    /** Access the SoundEngine */
+    get sound(): SoundEngine;
+    /** Access the VisualEngine */
+    get visual(): VisualEngine;
+    /** Access the ThemeManager */
+    get themes(): ThemeManager;
+    /** Configure all engines */
+    configure(options: SensoryEngineOptions): void;
+    /** Clean up all engines */
+    dispose(): void;
+    /** Run the appropriate visual effect based on theme style */
+    private _runVisual;
+}
+
 /**
  * No-op adapter — used in SSR, Node, or when no haptic hardware is available.
  * Silently accepts all calls without doing anything.
@@ -436,6 +700,155 @@ declare function patternToDataURL(input: ExportInput, options?: ExportOptions):
  */
 declare function patternFromDataURL(url: string): HapticPattern;
 
+/** A single recorded tap event */
+interface RecordedTap {
+    /** Timestamp in ms relative to recording start */
+    time: number;
+    /** Intensity from 0.0 to 1.0 */
+    intensity: number;
+}
+/** Callback invoked on each tap during recording */
+type TapCallback = (tap: RecordedTap, index: number) => void;
+/**
+ * Records tap rhythms and converts them to HPL pattern strings or HapticSteps.
+ *
+ * Usage:
+ *   const recorder = new PatternRecorder();
+ *   recorder.start();
+ *   recorder.tap();        // user taps...
+ *   recorder.tap(0.9);     // heavy tap
+ *   recorder.stop();
+ *   console.log(recorder.toHPL()); // '##..@@'
+ */
+declare class PatternRecorder {
+    private taps;
+    private recording;
+    private startTime;
+    private stopTime;
+    private tapCallbacks;
+    private nowFn;
+    constructor(options?: {
+        now?: () => number;
+    });
+    /** Whether the recorder is currently recording */
+    get isRecording(): boolean;
+    /** Total duration of the recording in ms */
+    get duration(): number;
+    /** Number of taps recorded */
+    get tapCount(): number;
+    /** Begin recording. Records timestamps of tap events. */
+    start(): void;
+    /** Register a tap at current time. */
+    tap(intensity?: number): void;
+    /** Stop recording, return the recorded taps. */
+    stop(): RecordedTap[];
+    /** Register a callback for each tap (for visual feedback during recording). */
+    onTap(callback: TapCallback): void;
+    /** Reset the recorder. */
+    clear(): void;
+    /**
+     * Snap taps to a grid for cleaner patterns.
+     * @param gridMs Grid size in ms (default 50ms)
+     */
+    quantize(gridMs?: number): void;
+    /**
+     * Convert recorded taps to an HPL string.
+     *
+     * Maps gaps between taps to `.` characters (each 50ms),
+     * and tap intensities to `~` (light), `#` (medium), `@` (heavy).
+     */
+    toHPL(): string;
+    /** Convert recorded taps to HapticStep[]. */
+    toSteps(): HapticStep[];
+    /** Convert recorded taps to a HapticPattern. */
+    toPattern(name?: string): HapticPattern;
+}
+
+interface SpringOptions {
+    /** Spring stiffness 0.5-1.0 */
+    stiffness?: number;
+    /** Damping factor 0.1-0.9 */
+    damping?: number;
+    /** Total duration in ms */
+    duration?: number;
+}
+interface BounceOptions {
+    /** Initial height 0.5-1.0 */
+    height?: number;
+    /** Bounciness factor 0.3-0.9 */
+    bounciness?: number;
+    /** Number of bounces */
+    bounces?: number;
+}
+interface FrictionOptions {
+    /** Surface roughness 0.1-1.0 */
+    roughness?: number;
+    /** Sliding speed 0.1-1.0 */
+    speed?: number;
+    /** Total duration in ms */
+    duration?: number;
+}
+interface ImpactOptions {
+    /** Object mass 0.1-1.0 */
+    mass?: number;
+    /** Surface hardness 0.1-1.0 */
+    hardness?: number;
+}
+interface GravityOptions {
+    /** Fall distance 0.3-1.0 */
+    distance?: number;
+    /** Total duration in ms */
+    duration?: number;
+}
+interface ElasticOptions {
+    /** Stretch amount 0.3-1.0 */
+    stretch?: number;
+    /** Snap-back speed 0.3-1.0 */
+    snapSpeed?: number;
+}
+interface WaveOptions {
+    /** Wave amplitude 0.3-1.0 */
+    amplitude?: number;
+    /** Wave frequency 0.5-2.0 */
+    frequency?: number;
+    /** Number of full cycles */
+    cycles?: number;
+}
+interface PendulumOptions {
+    /** Swing energy 0.3-1.0 */
+    energy?: number;
+    /** Number of swings */
+    swings?: number;
+}
+/** Bouncy spring oscillation — starts heavy, bounces with decreasing intensity */
+declare function spring(options?: SpringOptions): HapticPattern;
+/** Ball bouncing — each bounce is shorter and lighter */
+declare function bounce(options?: BounceOptions): HapticPattern;
+/** Rough surface sliding — continuous but slightly irregular vibration */
+declare function friction(options?: FrictionOptions): HapticPattern;
+/** Collision with surface — sharp initial hit followed by resonance */
+declare function impact(options?: ImpactOptions): HapticPattern;
+/** Falling sensation — accelerating intensity */
+declare function gravity(options?: GravityOptions): HapticPattern;
+/** Rubber band snap — stretch and snap back */
+declare function elastic(options?: ElasticOptions): HapticPattern;
+/** Ocean wave motion — smooth sine-wave-like intensity */
+declare function wave(options?: WaveOptions): HapticPattern;
+/** Swinging motion — intensity peaks at ends, quiet in middle */
+declare function pendulum(options?: PendulumOptions): HapticPattern;
+
+/** All physics-based haptic pattern generators */
+declare const physics: {
+    readonly spring: typeof spring;
+    readonly bounce: typeof bounce;
+    readonly friction: typeof friction;
+    readonly impact: typeof impact;
+    readonly gravity: typeof gravity;
+    readonly elastic: typeof elastic;
+    readonly wave: typeof wave;
+    readonly pendulum: typeof pendulum;
+};
+
 /** Platform detection utilities */
 interface PlatformInfo {
     isWeb: boolean;
@@ -460,4 +873,4 @@ declare function detectPlatform(): PlatformInfo;
  */
 declare const haptic: HapticEngine;
 
-export { type AdapterCapabilities, AdaptiveEngine, type EasingFunction, type ExportOptions, type FallbackConfig, FallbackManager, type HPLNode, type HPLNodeType, HPLParser, HPLParserError, type HPLToken, type HPLTokenType, HPLTokenizerError, type HapticAdapter, type HapticConfig, HapticEngine, type HapticPattern, type HapticPatternExport, type HapticStep, type ImpactStyle, IoSAudioAdapter, NoopAdapter, type NotificationType, PatternComposer, type PlatformInfo, type SemanticEffect, type ValidationResult, type VisualFallbackStyle, WebVibrationAdapter, compile, detectAdapter, detectPlatform, exportPattern, haptic, importPattern, optimizeSteps, parseHPL, patternFromDataURL, patternFromJSON, patternToDataURL, patternToJSON, tokenize, validateHPL };
+export { type AdapterCapabilities, AdaptiveEngine, type BounceOptions, type ClickOptions, type EasingFunction, type ElasticOptions, type ExportOptions, type FallbackConfig, FallbackManager, type FlashOptions, type FrictionOptions, type GlowOptions, type GravityOptions, type HPLNode, type HPLNodeType, HPLParser, HPLParserError, type HPLToken, type HPLTokenType, HPLTokenizerError, type HapticAdapter, type HapticConfig, HapticEngine, type HapticPattern, type HapticPatternExport, type HapticStep, type HighlightOptions, type ImpactOptions, type ImpactStyle, IoSAudioAdapter, type JelloOptions, NoopAdapter, type NotificationType, PatternComposer, PatternRecorder, type PendulumOptions, type PlatformInfo, type PulseOptions, type RippleOptions, type RubberOptions, type SemanticEffect, SensoryEngine, type SensoryEngineOptions, type ShakeOptions, SoundEngine, type SoundEngineOptions, type SpringOptions, ThemeManager, type ThemePreset, type ToneOptions, type ValidationResult, type BounceOptions$1 as VisualBounceOptions, VisualEngine, type VisualEngineOptions, type VisualFallbackStyle, type WaveOptions, WebVibrationAdapter, bounce, compile, detectAdapter, detectPlatform, elastic, exportPattern, friction, gravity, haptic, impact, importPattern, optimizeSteps, parseHPL, patternFromDataURL, patternFromJSON, patternToDataURL, patternToJSON, pendulum, physics, spring, themes, tokenize, validateHPL, wave };