@hapticjs/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -304,6 +304,36 @@ declare class WebVibrationAdapter implements HapticAdapter {
     private _pwmVibrate;
 }
 
+/**
+ * iOS Audio workaround adapter.
+ * Uses AudioContext to generate short, low-frequency oscillator tones (20-60 Hz)
+ * that create a subtle physical sensation through device speakers.
+ * This is a fallback for iOS Safari, which does not support the Vibration API.
+ */
+declare class IoSAudioAdapter implements HapticAdapter {
+    readonly name = "ios-audio";
+    readonly supported: boolean;
+    private _audioCtx;
+    private _activeOscillator;
+    private _activeGain;
+    private _cancelled;
+    constructor();
+    capabilities(): AdapterCapabilities;
+    pulse(intensity: number, duration: number): Promise<void>;
+    playSequence(steps: HapticStep[]): Promise<void>;
+    cancel(): void;
+    dispose(): void;
+    private _detectSupport;
+    /** Get or create the AudioContext, resuming if suspended */
+    private _getAudioContext;
+    /** Map intensity (0-1) to frequency in the 20-60 Hz sub-bass range */
+    private _intensityToFrequency;
+    /** Play a single oscillator tone for the given duration */
+    private _playTone;
+    /** Immediately stop the active oscillator if any */
+    private _stopOscillator;
+}
+
 declare class HPLParserError extends Error {
     constructor(message: string);
 }
@@ -357,6 +387,61 @@ interface ValidationResult {
 }
 declare function validateHPL(input: string): ValidationResult;
 
+/** Portable JSON-serializable format for sharing haptic patterns */
+interface HapticPatternExport {
+    version: 1;
+    name: string;
+    description?: string;
+    /** Original HPL string if pattern was created from HPL */
+    hpl?: string;
+    /** Compiled haptic steps */
+    steps: HapticStep[];
+    metadata?: {
+        /** Total duration in milliseconds */
+        duration: number;
+        author?: string;
+        tags?: string[];
+        /** ISO date string */
+        createdAt?: string;
+    };
+}
+/** Options for exporting a pattern */
+interface ExportOptions {
+    name?: string;
+    description?: string;
+    author?: string;
+    tags?: string[];
+}
+/** Input types accepted by exportPattern */
+type ExportInput = HapticPattern | HapticStep[] | string;
+/**
+ * Export a haptic pattern as a portable JSON-serializable object.
+ *
+ * Accepts a HapticPattern, HapticStep[], or HPL string.
+ */
+declare function exportPattern(input: ExportInput, options?: ExportOptions): HapticPatternExport;
+/**
+ * Import a pattern from a HapticPatternExport object or JSON string.
+ * Validates the data and returns a HapticPattern.
+ */
+declare function importPattern(data: HapticPatternExport | string): HapticPattern;
+/**
+ * Serialize a pattern to a pretty-printed JSON string.
+ */
+declare function patternToJSON(input: ExportInput, options?: ExportOptions): string;
+/**
+ * Parse a JSON string into a HapticPattern.
+ */
+declare function patternFromJSON(json: string): HapticPattern;
+/**
+ * Encode a pattern as a data: URL for easy sharing via links.
+ */
+declare function patternToDataURL(input: ExportInput, options?: ExportOptions): string;
+/**
+ * Decode a data: URL back to a HapticPattern.
+ */
+declare function patternFromDataURL(url: string): HapticPattern;
+
 /** Platform detection utilities */
 interface PlatformInfo {
     isWeb: boolean;
@@ -381,4 +466,4 @@ declare function detectPlatform(): PlatformInfo;
  */
 declare const haptic: HapticEngine;
 
-export { type AdapterCapabilities, AdaptiveEngine, type EasingFunction, type FallbackConfig, FallbackManager, type HPLNode, type HPLNodeType, HPLParser, HPLParserError, type HPLToken, type HPLTokenType, HPLTokenizerError, type HapticAdapter, type HapticConfig, HapticEngine, type HapticPattern, type HapticStep, type ImpactStyle, NoopAdapter, type NotificationType, PatternComposer, type PlatformInfo, type SemanticEffect, type ValidationResult, type VisualFallbackStyle, WebVibrationAdapter, compile, detectAdapter, detectPlatform, haptic, optimizeSteps, parseHPL, tokenize, validateHPL };
+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 };

package/dist/index.js

@@ -131,6 +131,124 @@ var WebVibrationAdapter = class {
   }
 };
 
+// src/adapters/ios-audio.adapter.ts
+var IoSAudioAdapter = class {
+  constructor() {
+    this.name = "ios-audio";
+    this._audioCtx = null;
+    this._activeOscillator = null;
+    this._activeGain = null;
+    this._cancelled = false;
+    this.supported = this._detectSupport();
+  }
+  capabilities() {
+    return {
+      maxIntensityLevels: 100,
+      minDuration: 5,
+      maxDuration: 5e3,
+      supportsPattern: true,
+      supportsIntensity: true,
+      dualMotor: false
+    };
+  }
+  async pulse(intensity, duration) {
+    if (!this.supported) return;
+    await this._playTone(intensity, duration);
+  }
+  async playSequence(steps) {
+    if (!this.supported || steps.length === 0) return;
+    this._cancelled = false;
+    for (const step of steps) {
+      if (this._cancelled) break;
+      if (step.type === "vibrate" && step.intensity > 0) {
+        await this._playTone(step.intensity, step.duration);
+      } else {
+        await delay(step.duration);
+      }
+    }
+  }
+  cancel() {
+    this._cancelled = true;
+    this._stopOscillator();
+  }
+  dispose() {
+    this.cancel();
+    if (this._audioCtx) {
+      void this._audioCtx.close();
+      this._audioCtx = null;
+    }
+  }
+  // ─── Internal ──────────────────────────────────────────────
+  _detectSupport() {
+    if (typeof window === "undefined") return false;
+    const hasAudioContext = typeof AudioContext !== "undefined" || typeof window.webkitAudioContext !== "undefined";
+    if (!hasAudioContext) return false;
+    const ua = navigator.userAgent;
+    const isIOS = /iPad|iPhone|iPod/.test(ua) || navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1;
+    return isIOS;
+  }
+  /** Get or create the AudioContext, resuming if suspended */
+  async _getAudioContext() {
+    if (!this._audioCtx) {
+      const Ctor = typeof AudioContext !== "undefined" ? AudioContext : window.webkitAudioContext;
+      this._audioCtx = new Ctor();
+    }
+    if (this._audioCtx.state === "suspended") {
+      await this._audioCtx.resume();
+    }
+    return this._audioCtx;
+  }
+  /** Map intensity (0-1) to frequency in the 20-60 Hz sub-bass range */
+  _intensityToFrequency(intensity) {
+    return 20 + intensity * 40;
+  }
+  /** Play a single oscillator tone for the given duration */
+  async _playTone(intensity, duration) {
+    const ctx = await this._getAudioContext();
+    const oscillator = ctx.createOscillator();
+    const gainNode = ctx.createGain();
+    oscillator.type = "sine";
+    oscillator.frequency.setValueAtTime(
+      this._intensityToFrequency(intensity),
+      ctx.currentTime
+    );
+    gainNode.gain.setValueAtTime(intensity, ctx.currentTime);
+    oscillator.connect(gainNode);
+    gainNode.connect(ctx.destination);
+    this._activeOscillator = oscillator;
+    this._activeGain = gainNode;
+    oscillator.start(ctx.currentTime);
+    oscillator.stop(ctx.currentTime + duration / 1e3);
+    await new Promise((resolve) => {
+      oscillator.onended = () => {
+        oscillator.disconnect();
+        gainNode.disconnect();
+        this._activeOscillator = null;
+        this._activeGain = null;
+        resolve();
+      };
+    });
+  }
+  /** Immediately stop the active oscillator if any */
+  _stopOscillator() {
+    if (this._activeOscillator) {
+      try {
+        this._activeOscillator.stop();
+        this._activeOscillator.disconnect();
+      } catch {
+      }
+      this._activeOscillator = null;
+    }
+    if (this._activeGain) {
+      try {
+        this._activeGain.disconnect();
+      } catch {
+      }
+      this._activeGain = null;
+    }
+  }
+};
+
 // src/utils/platform.ts
 function detectPlatform() {
   const isWeb = typeof window !== "undefined" && typeof document !== "undefined";
@@ -160,6 +278,12 @@ function detectAdapter() {
   if (platform.hasVibrationAPI) {
     return new WebVibrationAdapter();
   }
+  if (platform.isIOS && platform.isWeb) {
+    const iosAdapter = new IoSAudioAdapter();
+    if (iosAdapter.supported) {
+      return iosAdapter;
+    }
+  }
   return new NoopAdapter();
 }
 
@@ -194,13 +318,13 @@ var FallbackManager = class {
   /** Execute fallback feedback for the given steps */
   async execute(steps) {
     if (this.config.type === "none") return;
-    const totalDuration = steps.reduce((sum, s) => sum + s.duration, 0);
+    const totalDuration2 = steps.reduce((sum, s) => sum + s.duration, 0);
     const maxIntensity = Math.max(...steps.filter((s) => s.type === "vibrate").map((s) => s.intensity), 0);
     if (this.config.type === "visual" || this.config.type === "both") {
-      await this._visualFallback(totalDuration, maxIntensity);
+      await this._visualFallback(totalDuration2, maxIntensity);
     }
     if (this.config.type === "audio" || this.config.type === "both") {
-      await this._audioFallback(totalDuration, maxIntensity);
+      await this._audioFallback(totalDuration2, maxIntensity);
     }
   }
   async _visualFallback(duration, intensity) {
@@ -605,7 +729,7 @@ var HapticEngine = class _HapticEngine {
   // ─── Semantic API ──────────────────────────────────────────
   /** Light tap feedback */
   async tap(intensity = 0.6) {
-    await this._playSteps([{ type: "vibrate", duration: 10, intensity }]);
+    await this._playSteps([{ type: "vibrate", duration: 30, intensity }]);
   }
   /** Double tap */
   async doubleTap(intensity = 0.6) {
@@ -785,6 +909,121 @@ function validateHPL(input) {
   return { valid: errors.length === 0, errors };
 }
 
+// src/patterns/sharing.ts
+function totalDuration(steps) {
+  return steps.reduce((sum, s) => sum + s.duration, 0);
+}
+function resolveInput(input) {
+  if (typeof input === "string") {
+    const ast = parseHPL(input);
+    return { steps: compile(ast), hpl: input };
+  }
+  if (Array.isArray(input)) {
+    return { steps: input };
+  }
+  return { steps: input.steps, name: input.name };
+}
+function exportPattern(input, options = {}) {
+  const resolved = resolveInput(input);
+  const steps = resolved.steps;
+  const name = options.name ?? resolved.name ?? "Untitled Pattern";
+  const result = {
+    version: 1,
+    name,
+    steps
+  };
+  if (options.description) {
+    result.description = options.description;
+  }
+  if (resolved.hpl) {
+    result.hpl = resolved.hpl;
+  }
+  const hasMetadataFields = options.author || options.tags;
+  if (hasMetadataFields || steps.length > 0) {
+    result.metadata = {
+      duration: totalDuration(steps),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (options.author) {
+      result.metadata.author = options.author;
+    }
+    if (options.tags) {
+      result.metadata.tags = options.tags;
+    }
+  }
+  return result;
+}
+function validateExport(data) {
+  if (data === null || typeof data !== "object") {
+    throw new Error("Invalid pattern data: expected an object");
+  }
+  const obj = data;
+  if (obj.version !== 1) {
+    throw new Error(
+      `Unsupported pattern version: ${String(obj.version)}. Expected version 1`
+    );
+  }
+  if (typeof obj.name !== "string" || obj.name.length === 0) {
+    throw new Error('Invalid pattern data: "name" must be a non-empty string');
+  }
+  if (!Array.isArray(obj.steps)) {
+    throw new Error('Invalid pattern data: "steps" must be an array');
+  }
+  for (let i = 0; i < obj.steps.length; i++) {
+    const step = obj.steps[i];
+    if (step.type !== "vibrate" && step.type !== "pause") {
+      throw new Error(
+        `Invalid step at index ${i}: "type" must be "vibrate" or "pause"`
+      );
+    }
+    if (typeof step.duration !== "number" || step.duration < 0) {
+      throw new Error(
+        `Invalid step at index ${i}: "duration" must be a non-negative number`
+      );
+    }
+    if (typeof step.intensity !== "number" || step.intensity < 0 || step.intensity > 1) {
+      throw new Error(
+        `Invalid step at index ${i}: "intensity" must be a number between 0 and 1`
+      );
+    }
+  }
+}
+function importPattern(data) {
+  const parsed = typeof data === "string" ? JSON.parse(data) : data;
+  validateExport(parsed);
+  const pattern = {
+    name: parsed.name,
+    steps: parsed.steps.map((s) => ({ ...s }))
+  };
+  if (parsed.metadata) {
+    pattern.metadata = { ...parsed.metadata };
+  }
+  return pattern;
+}
+function patternToJSON(input, options = {}) {
+  const exported = exportPattern(input, options);
+  return JSON.stringify(exported, null, 2);
+}
+function patternFromJSON(json) {
+  return importPattern(json);
+}
+function patternToDataURL(input, options = {}) {
+  const json = patternToJSON(input, options);
+  const encoded = btoa(json);
+  return `data:application/haptic+json;base64,${encoded}`;
+}
+function patternFromDataURL(url) {
+  const prefix = "data:application/haptic+json;base64,";
+  if (!url.startsWith(prefix)) {
+    throw new Error(
+      'Invalid haptic data URL: expected "data:application/haptic+json;base64," prefix'
+    );
+  }
+  const encoded = url.slice(prefix.length);
+  const json = atob(encoded);
+  return patternFromJSON(json);
+}
+
 // src/presets/ui.ts
 var ui = {
   /** Light button tap */
@@ -1176,6 +1415,6 @@ var presets = {
 // src/index.ts
 var haptic = HapticEngine.create();
 
-export { AdaptiveEngine, FallbackManager, HPLParser, HPLParserError, HPLTokenizerError, HapticEngine, NoopAdapter, PatternComposer, WebVibrationAdapter, accessibility, compile, detectAdapter, detectPlatform, gaming, haptic, notifications, optimizeSteps, parseHPL, presets, system, tokenize, ui, validateHPL };
+export { AdaptiveEngine, FallbackManager, HPLParser, HPLParserError, HPLTokenizerError, HapticEngine, IoSAudioAdapter, NoopAdapter, PatternComposer, WebVibrationAdapter, accessibility, compile, detectAdapter, detectPlatform, exportPattern, gaming, haptic, importPattern, notifications, optimizeSteps, parseHPL, patternFromDataURL, patternFromJSON, patternToDataURL, patternToJSON, presets, system, tokenize, ui, validateHPL };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map