@hapticjs/core 0.3.0 → 0.4.0

package/dist/index.js

@@ -2620,9 +2620,737 @@ var physics = {
   pendulum
 };
 
+// src/middleware/middleware.ts
+var MiddlewareManager = class {
+  constructor() {
+    this.middleware = [];
+  }
+  /** Register a middleware */
+  use(middleware) {
+    this.middleware.push(middleware);
+  }
+  /** Remove a middleware by name */
+  remove(name) {
+    this.middleware = this.middleware.filter((m) => m.name !== name);
+  }
+  /** Run all middleware in order */
+  process(steps) {
+    let result = steps;
+    for (const m of this.middleware) {
+      result = m.process(result);
+    }
+    return result;
+  }
+  /** Remove all middleware */
+  clear() {
+    this.middleware = [];
+  }
+  /** List registered middleware names */
+  list() {
+    return this.middleware.map((m) => m.name);
+  }
+};
+function intensityScaler(scale) {
+  return {
+    name: "intensityScaler",
+    process: (steps) => steps.map((s) => ({
+      ...s,
+      intensity: Math.min(1, Math.max(0, s.intensity * scale))
+    }))
+  };
+}
+function durationScaler(scale) {
+  return {
+    name: "durationScaler",
+    process: (steps) => steps.map((s) => ({
+      ...s,
+      duration: Math.max(20, Math.round(s.duration * scale))
+    }))
+  };
+}
+function intensityClamper(min, max) {
+  return {
+    name: "intensityClamper",
+    process: (steps) => steps.map((s) => ({
+      ...s,
+      intensity: Math.min(max, Math.max(min, s.intensity))
+    }))
+  };
+}
+function patternRepeater(times) {
+  return {
+    name: "patternRepeater",
+    process: (steps) => {
+      const result = [];
+      for (let i = 0; i < times; i++) {
+        result.push(...steps.map((s) => ({ ...s })));
+      }
+      return result;
+    }
+  };
+}
+function reverser() {
+  return {
+    name: "reverser",
+    process: (steps) => [...steps].reverse()
+  };
+}
+function accessibilityBooster() {
+  return {
+    name: "accessibilityBooster",
+    process: (steps) => steps.map((s) => ({
+      ...s,
+      intensity: Math.min(1, s.intensity * 1.3),
+      duration: Math.max(20, Math.round(s.duration * 1.2))
+    }))
+  };
+}
+
+// src/profiles/intensity-profiles.ts
+var profiles = {
+  off: {
+    name: "off",
+    hapticScale: 0,
+    durationScale: 0,
+    soundEnabled: false,
+    soundVolume: 0,
+    visualEnabled: false
+  },
+  subtle: {
+    name: "subtle",
+    hapticScale: 0.5,
+    durationScale: 0.7,
+    soundEnabled: true,
+    soundVolume: 0.1,
+    visualEnabled: true
+  },
+  normal: {
+    name: "normal",
+    hapticScale: 1,
+    durationScale: 1,
+    soundEnabled: true,
+    soundVolume: 0.3,
+    visualEnabled: true
+  },
+  strong: {
+    name: "strong",
+    hapticScale: 1.3,
+    durationScale: 1.2,
+    soundEnabled: true,
+    soundVolume: 0.5,
+    visualEnabled: true
+  },
+  intense: {
+    name: "intense",
+    hapticScale: 1.8,
+    durationScale: 1.5,
+    soundEnabled: true,
+    soundVolume: 0.7,
+    visualEnabled: true
+  },
+  accessible: {
+    name: "accessible",
+    hapticScale: 1.5,
+    durationScale: 1.3,
+    soundEnabled: true,
+    soundVolume: 0.6,
+    visualEnabled: true
+  }
+};
+var ProfileManager = class {
+  constructor() {
+    this.registry = /* @__PURE__ */ new Map();
+    for (const [name, profile] of Object.entries(profiles)) {
+      this.registry.set(name, profile);
+    }
+    this.currentProfile = profiles.normal;
+  }
+  /** Apply a profile by name or custom profile object */
+  setProfile(name) {
+    if (typeof name === "string") {
+      const profile = this.registry.get(name);
+      if (!profile) {
+        throw new Error(`Unknown profile: "${name}"`);
+      }
+      this.currentProfile = profile;
+    } else {
+      this.registry.set(name.name, name);
+      this.currentProfile = name;
+    }
+  }
+  /** Get the current profile */
+  getProfile() {
+    return this.currentProfile;
+  }
+  /** List available profile names */
+  listProfiles() {
+    return Array.from(this.registry.keys());
+  }
+  /** Register a custom profile */
+  registerProfile(profile) {
+    this.registry.set(profile.name, profile);
+  }
+  /** Convert current profile to a HapticMiddleware (intensity + duration scaling) */
+  toMiddleware() {
+    const profile = this.currentProfile;
+    const iScaler = intensityScaler(profile.hapticScale);
+    const dScaler = durationScaler(profile.durationScale);
+    return {
+      name: `profile:${profile.name}`,
+      process: (steps) => dScaler.process(iScaler.process(steps))
+    };
+  }
+  /** Current profile name */
+  get current() {
+    return this.currentProfile.name;
+  }
+};
+
+// src/experiment/ab-testing.ts
+var HapticExperiment = class {
+  constructor(name, variants) {
+    this.assignments = /* @__PURE__ */ new Map();
+    this.tracking = [];
+    this._name = name;
+    this.variants = variants;
+    this.variantNames = Object.keys(variants);
+    if (this.variantNames.length === 0) {
+      throw new Error("Experiment must have at least one variant");
+    }
+  }
+  /** Experiment name */
+  get name() {
+    return this._name;
+  }
+  /**
+   * Randomly assign a variant (consistent for same userId via simple hash).
+   * If no userId is provided, generates a random assignment.
+   */
+  assign(userId) {
+    const id = userId ?? `anon-${Math.random().toString(36).slice(2)}`;
+    const existing = this.assignments.get(id);
+    if (existing) return existing;
+    const hash = this._hash(id);
+    const index = hash % this.variantNames.length;
+    const variant = this.variantNames[index];
+    this.assignments.set(id, variant);
+    return variant;
+  }
+  /** Get the assigned variant pattern for a user */
+  getVariant(userId) {
+    const id = userId ?? void 0;
+    if (!id) return void 0;
+    const variant = this.assignments.get(id);
+    if (!variant) return void 0;
+    return this.variants[variant];
+  }
+  /** Track an event for a user */
+  track(userId, event, value) {
+    const variant = this.assignments.get(userId);
+    if (!variant) return;
+    this.tracking.push({
+      userId,
+      variant,
+      event,
+      value,
+      timestamp: Date.now()
+    });
+  }
+  /** Get aggregated results per variant */
+  getResults() {
+    const results = {};
+    for (const name of this.variantNames) {
+      results[name] = { assignments: 0, events: {} };
+    }
+    for (const variant of this.assignments.values()) {
+      if (results[variant]) {
+        results[variant].assignments++;
+      }
+    }
+    for (const entry of this.tracking) {
+      if (results[entry.variant]) {
+        const events = results[entry.variant].events;
+        events[entry.event] = (events[entry.event] ?? 0) + 1;
+      }
+    }
+    return results;
+  }
+  /** Clear all tracking data and assignments */
+  reset() {
+    this.assignments.clear();
+    this.tracking = [];
+  }
+  /** Simple string hash for deterministic variant assignment */
+  _hash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+};
+
+// src/rhythm/rhythm-sync.ts
+var RhythmSync = class {
+  constructor(options = {}) {
+    // reserved for pattern-based rhythm
+    this._isPlaying = false;
+    this._beatCount = 0;
+    this._intervalId = null;
+    this._callbacks = [];
+    this._tapTimestamps = [];
+    this._audioElement = null;
+    this._syncEngine = null;
+    this._syncEffect = "tap";
+    this._bpm = Math.min(300, Math.max(60, options.bpm ?? 120));
+    this._intensity = Math.min(1, Math.max(0, options.intensity ?? 0.7));
+    this._pattern = options.pattern ?? "";
+  }
+  // ─── BPM Control ─────────────────────────────────────────
+  /** Set beats per minute (clamped to 60-300) */
+  setBPM(bpm) {
+    this._bpm = Math.min(300, Math.max(60, bpm));
+    if (this._isPlaying) {
+      this._stopInterval();
+      this._startInterval();
+    }
+  }
+  /**
+   * Store an audio element reference for sync.
+   * Since Web Audio API's AnalyserNode isn't reliably available in all
+   * environments, use tapTempo() for BPM detection instead.
+   */
+  detectBPM(audioElement) {
+    this._audioElement = audioElement;
+  }
+  /**
+   * Tap tempo — call repeatedly to set BPM from tap intervals.
+   * Calculates average BPM from the last 4-8 taps.
+   * Returns the current estimated BPM.
+   */
+  tapTempo() {
+    const now = Date.now();
+    this._tapTimestamps.push(now);
+    if (this._tapTimestamps.length > 8) {
+      this._tapTimestamps = this._tapTimestamps.slice(-8);
+    }
+    if (this._tapTimestamps.length < 2) {
+      return this._bpm;
+    }
+    const timestamps = this._tapTimestamps.slice(-8);
+    const intervals = [];
+    for (let i = 1; i < timestamps.length; i++) {
+      intervals.push(timestamps[i] - timestamps[i - 1]);
+    }
+    const avgInterval = intervals.reduce((sum, v) => sum + v, 0) / intervals.length;
+    if (avgInterval > 0) {
+      const estimatedBPM = Math.round(6e4 / avgInterval);
+      this._bpm = Math.min(300, Math.max(60, estimatedBPM));
+    }
+    return this._bpm;
+  }
+  // ─── Playback ────────────────────────────────────────────
+  /** Start emitting beats at the current BPM */
+  start(callback) {
+    if (this._isPlaying) return;
+    if (callback) {
+      this._callbacks.push(callback);
+    }
+    this._isPlaying = true;
+    this._beatCount = 0;
+    this._startInterval();
+  }
+  /** Stop the rhythm */
+  stop() {
+    this._isPlaying = false;
+    this._stopInterval();
+  }
+  /** Register a beat callback */
+  onBeat(callback) {
+    this._callbacks.push(callback);
+  }
+  // ─── Haptic Sync ────────────────────────────────────────
+  /**
+   * Auto-trigger a haptic effect on each beat.
+   * Calls engine.tap() by default, or the specified semantic method.
+   */
+  syncHaptic(engine, effect = "tap") {
+    this._syncEngine = engine;
+    this._syncEffect = effect;
+  }
+  // ─── Getters ─────────────────────────────────────────────
+  /** Current BPM */
+  get bpm() {
+    return this._bpm;
+  }
+  /** Whether rhythm is active */
+  get isPlaying() {
+    return this._isPlaying;
+  }
+  /** Total beats since start */
+  get beatCount() {
+    return this._beatCount;
+  }
+  /** Current pattern string */
+  get pattern() {
+    return this._pattern;
+  }
+  /** The attached audio element, if any */
+  get audioElement() {
+    return this._audioElement;
+  }
+  // ─── Lifecycle ───────────────────────────────────────────
+  /** Clean up intervals and callbacks */
+  dispose() {
+    this.stop();
+    this._callbacks = [];
+    this._tapTimestamps = [];
+    this._syncEngine = null;
+    this._audioElement = null;
+  }
+  // ─── Internal ────────────────────────────────────────────
+  _startInterval() {
+    const intervalMs = 6e4 / this._bpm;
+    this._intervalId = setInterval(() => {
+      this._beatCount++;
+      const beat = this._beatCount;
+      for (const cb of this._callbacks) {
+        cb(beat);
+      }
+      if (this._syncEngine) {
+        const engine = this._syncEngine;
+        if (typeof engine[this._syncEffect] === "function") {
+          engine[this._syncEffect](this._intensity);
+        } else if (typeof engine.tap === "function") {
+          engine.tap(this._intensity);
+        }
+      }
+    }, intervalMs);
+  }
+  _stopInterval() {
+    if (this._intervalId !== null) {
+      clearInterval(this._intervalId);
+      this._intervalId = null;
+    }
+  }
+};
+
+// src/motion/motion-detector.ts
+var MotionDetector = class {
+  constructor(options = {}) {
+    this._isListening = false;
+    this._callbacks = {
+      shake: [],
+      tilt: [],
+      rotation: [],
+      flip: []
+    };
+    this._lastOrientation = null;
+    this._lastFlipState = null;
+    this._boundMotionHandler = null;
+    this._boundOrientationHandler = null;
+    this._shakeThreshold = options.shakeThreshold ?? 15;
+    this._tiltThreshold = options.tiltThreshold ?? 10;
+  }
+  // ─── Detection ───────────────────────────────────────────
+  /** Whether DeviceMotion API is available */
+  get isSupported() {
+    if (typeof window === "undefined") return false;
+    return "DeviceMotionEvent" in window;
+  }
+  /** Whether currently listening for motion events */
+  get isListening() {
+    return this._isListening;
+  }
+  // ─── Permission ──────────────────────────────────────────
+  /**
+   * Request permission for motion events (required on iOS 13+).
+   * Returns true if permission was granted.
+   */
+  async requestPermission() {
+    if (typeof window === "undefined") return false;
+    const DeviceMotionEventRef = window.DeviceMotionEvent;
+    if (DeviceMotionEventRef && typeof DeviceMotionEventRef.requestPermission === "function") {
+      try {
+        const result = await DeviceMotionEventRef.requestPermission();
+        return result === "granted";
+      } catch {
+        return false;
+      }
+    }
+    return this.isSupported;
+  }
+  // ─── Lifecycle ───────────────────────────────────────────
+  /** Begin listening to device motion and orientation events */
+  start() {
+    if (this._isListening) return;
+    if (typeof window === "undefined") return;
+    this._boundMotionHandler = this._handleMotion.bind(this);
+    this._boundOrientationHandler = this._handleOrientation.bind(this);
+    window.addEventListener("devicemotion", this._boundMotionHandler);
+    window.addEventListener("deviceorientation", this._boundOrientationHandler);
+    this._isListening = true;
+  }
+  /** Stop listening to motion events */
+  stop() {
+    if (!this._isListening) return;
+    if (typeof window === "undefined") return;
+    if (this._boundMotionHandler) {
+      window.removeEventListener("devicemotion", this._boundMotionHandler);
+    }
+    if (this._boundOrientationHandler) {
+      window.removeEventListener("deviceorientation", this._boundOrientationHandler);
+    }
+    this._isListening = false;
+    this._lastOrientation = null;
+    this._lastFlipState = null;
+  }
+  // ─── Callbacks ───────────────────────────────────────────
+  /** Register callback for shake events. Intensity is 0-1 based on acceleration. */
+  onShake(callback) {
+    this._callbacks.shake.push(callback);
+  }
+  /** Register callback for tilt changes. Direction x/y are -1 to 1. */
+  onTilt(callback) {
+    this._callbacks.tilt.push(callback);
+  }
+  /** Register callback for rotation. Angle in degrees. */
+  onRotation(callback) {
+    this._callbacks.rotation.push(callback);
+  }
+  /** Register callback for device flip (face-down/up toggle). */
+  onFlip(callback) {
+    this._callbacks.flip.push(callback);
+  }
+  // ─── Cleanup ─────────────────────────────────────────────
+  /** Remove all listeners and callbacks */
+  dispose() {
+    this.stop();
+    this._callbacks = { shake: [], tilt: [], rotation: [], flip: [] };
+  }
+  // ─── Internal ────────────────────────────────────────────
+  _handleMotion(event) {
+    const accel = event.accelerationIncludingGravity;
+    if (!accel) return;
+    const { x, y, z } = accel;
+    if (x == null || y == null || z == null) return;
+    const magnitude = Math.sqrt(x * x + y * y + z * z) - 9.81;
+    if (magnitude > this._shakeThreshold) {
+      const intensity = Math.min(
+        1,
+        (magnitude - this._shakeThreshold) / this._shakeThreshold
+      );
+      for (const cb of this._callbacks.shake) {
+        cb(intensity);
+      }
+    }
+  }
+  _handleOrientation(event) {
+    const { alpha, beta, gamma } = event;
+    if (beta == null || gamma == null) return;
+    if (this._lastOrientation) {
+      const deltaBeta = Math.abs(beta - this._lastOrientation.beta);
+      const deltaGamma = Math.abs(gamma - this._lastOrientation.gamma);
+      if (deltaBeta > this._tiltThreshold || deltaGamma > this._tiltThreshold) {
+        const tiltX = Math.max(-1, Math.min(1, gamma / 90));
+        const tiltY = Math.max(-1, Math.min(1, beta / 180));
+        for (const cb of this._callbacks.tilt) {
+          cb({ x: tiltX, y: tiltY });
+        }
+      }
+    }
+    this._lastOrientation = { beta, gamma };
+    if (alpha != null) {
+      for (const cb of this._callbacks.rotation) {
+        cb(alpha);
+      }
+    }
+    const isFaceDown = Math.abs(beta) > 140;
+    if (this._lastFlipState !== null && isFaceDown !== this._lastFlipState) {
+      for (const cb of this._callbacks.flip) {
+        cb();
+      }
+    }
+    this._lastFlipState = isFaceDown;
+  }
+};
+
+// src/accessibility/haptic-a11y.ts
+var HapticA11y = class {
+  constructor(engine, options = {}) {
+    this._isAttached = false;
+    this._root = null;
+    this._observer = null;
+    this._focusChangeCallback = null;
+    this._formErrorCallback = null;
+    // Bound handlers for cleanup
+    this._handleFocusIn = null;
+    this._handleFocusOut = null;
+    this._handleInvalid = null;
+    this._handleClick = null;
+    this.engine = engine;
+    this.options = {
+      focusChange: options.focusChange ?? true,
+      formErrors: options.formErrors ?? true,
+      navigation: options.navigation ?? true,
+      announcements: options.announcements ?? true
+    };
+  }
+  /** Whether currently attached and listening */
+  get isAttached() {
+    return this._isAttached;
+  }
+  // ─── Attach / Detach ─────────────────────────────────────
+  /**
+   * Attach to a root element and begin listening for interactions.
+   * Defaults to document.body if no root is provided.
+   */
+  attach(root) {
+    if (this._isAttached) return;
+    if (typeof document === "undefined") return;
+    this._root = root ?? document.body;
+    if (!this._root) return;
+    this._bindHandlers();
+    this._attachListeners();
+    this._startObserver();
+    this._isAttached = true;
+  }
+  /** Remove all listeners and stop observing */
+  detach() {
+    if (!this._isAttached) return;
+    this._removeListeners();
+    this._stopObserver();
+    this._isAttached = false;
+    this._root = null;
+  }
+  // ─── Custom Handlers ─────────────────────────────────────
+  /** Set a custom handler for focus changes */
+  onFocusChange(callback) {
+    this._focusChangeCallback = callback ?? null;
+  }
+  /** Set a custom handler for form errors */
+  onFormError(callback) {
+    this._formErrorCallback = callback ?? null;
+  }
+  // ─── Cleanup ─────────────────────────────────────────────
+  /** Clean up all listeners, observers, and callbacks */
+  dispose() {
+    this.detach();
+    this._focusChangeCallback = null;
+    this._formErrorCallback = null;
+  }
+  // ─── Internal ────────────────────────────────────────────
+  _bindHandlers() {
+    this._handleFocusIn = (e) => {
+      if (!this.options.focusChange) return;
+      if (this._focusChangeCallback) {
+        this._focusChangeCallback(e);
+        return;
+      }
+      this._safeCall(() => this.engine.selection());
+    };
+    this._handleFocusOut = (_e) => {
+    };
+    this._handleInvalid = (e) => {
+      if (!this.options.formErrors) return;
+      if (this._formErrorCallback) {
+        this._formErrorCallback(e);
+        return;
+      }
+      this._safeCall(() => this.engine.error());
+    };
+    this._handleClick = (e) => {
+      const target = e.target;
+      if (!target) return;
+      const tagName = target.tagName?.toLowerCase();
+      if (tagName === "button" || target.getAttribute?.("role") === "button") {
+        this._safeCall(() => this.engine.tap());
+        return;
+      }
+      if (tagName === "a" && this.options.navigation) {
+        this._safeCall(() => this.engine.selection());
+        return;
+      }
+      if (tagName === "input") {
+        const inputType = target.type?.toLowerCase();
+        if (inputType === "checkbox" || inputType === "radio") {
+          const checked = target.checked;
+          this._safeCall(() => this.engine.toggle(checked));
+        }
+      }
+    };
+  }
+  _attachListeners() {
+    if (!this._root) return;
+    this._root.addEventListener("focusin", this._handleFocusIn, true);
+    this._root.addEventListener("focusout", this._handleFocusOut, true);
+    this._root.addEventListener("invalid", this._handleInvalid, true);
+    this._root.addEventListener("click", this._handleClick, true);
+  }
+  _removeListeners() {
+    if (!this._root) return;
+    this._root.removeEventListener("focusin", this._handleFocusIn, true);
+    this._root.removeEventListener("focusout", this._handleFocusOut, true);
+    this._root.removeEventListener("invalid", this._handleInvalid, true);
+    this._root.removeEventListener("click", this._handleClick, true);
+  }
+  _startObserver() {
+    if (typeof MutationObserver === "undefined") return;
+    if (!this.options.announcements) return;
+    this._observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of mutation.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          const el = node;
+          const role = el.getAttribute?.("role");
+          const ariaLive = el.getAttribute?.("aria-live");
+          if (role === "alert" || role === "alertdialog") {
+            this._safeCall(() => this.engine.warning());
+          } else if (role === "status" || ariaLive === "polite" || ariaLive === "assertive") {
+            this._safeCall(() => this.engine.selection());
+          }
+          if (role === "dialog" || el.tagName?.toLowerCase() === "dialog") {
+            this._safeCall(() => this.engine.toggle(true));
+          }
+        }
+        for (const node of mutation.removedNodes) {
+          if (node.nodeType !== 1) continue;
+          const el = node;
+          const role = el.getAttribute?.("role");
+          if (role === "dialog" || el.tagName?.toLowerCase() === "dialog") {
+            this._safeCall(() => this.engine.toggle(false));
+          }
+        }
+      }
+    });
+    this._observer.observe(this._root, {
+      childList: true,
+      subtree: true
+    });
+  }
+  _stopObserver() {
+    if (this._observer) {
+      this._observer.disconnect();
+      this._observer = null;
+    }
+  }
+  _safeCall(fn) {
+    try {
+      const result = fn();
+      if (result && typeof result.catch === "function") {
+        result.catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+};
+
 // src/index.ts
 var haptic = HapticEngine.create();
 
-export { AdaptiveEngine, FallbackManager, HPLParser, HPLParserError, HPLTokenizerError, HapticEngine, IoSAudioAdapter, NoopAdapter, PatternComposer, PatternRecorder, SensoryEngine, SoundEngine, ThemeManager, VisualEngine, WebVibrationAdapter, accessibility, bounce, compile, detectAdapter, detectPlatform, elastic, emotions, exportPattern, friction, gaming, gravity, haptic, impact, importPattern, notifications, optimizeSteps, parseHPL, patternFromDataURL, patternFromJSON, patternToDataURL, patternToJSON, pendulum, physics, presets, spring, system, themes, tokenize, ui, validateHPL, wave };
+export { AdaptiveEngine, FallbackManager, HPLParser, HPLParserError, HPLTokenizerError, HapticA11y, HapticEngine, HapticExperiment, IoSAudioAdapter, MiddlewareManager, MotionDetector, NoopAdapter, PatternComposer, PatternRecorder, ProfileManager, RhythmSync, SensoryEngine, SoundEngine, ThemeManager, VisualEngine, WebVibrationAdapter, accessibility, accessibilityBooster, bounce, compile, detectAdapter, detectPlatform, durationScaler, elastic, emotions, exportPattern, friction, gaming, gravity, haptic, impact, importPattern, intensityClamper, intensityScaler, notifications, optimizeSteps, parseHPL, patternFromDataURL, patternFromJSON, patternRepeater, patternToDataURL, patternToJSON, pendulum, physics, presets, profiles, reverser, spring, system, themes, tokenize, ui, validateHPL, wave };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map