@hapticjs/core 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thirumalesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @hapticjs/core
+
+Universal Haptics Engine for JavaScript & TypeScript.
+
+```bash
+npm install @hapticjs/core
+```
+
+## Quick Start
+
+```typescript
+import { haptic } from '@hapticjs/core';
+
+// Semantic effects
+haptic.tap();
+haptic.success();
+haptic.error();
+
+// Haptic Pattern Language
+haptic.play('~~..##..@@');
+
+// Fluent composer
+haptic.compose()
+  .tap(0.5)
+  .pause(100)
+  .buzz(200)
+  .play();
+```
+
+## Haptic Pattern Language (HPL)
+
+| Char | Effect | Duration | Intensity |
+|------|--------|----------|-----------|
+| `~` | Light vibration | 50ms | 0.3 |
+| `#` | Medium vibration | 50ms | 0.6 |
+| `@` | Heavy vibration | 50ms | 1.0 |
+| `.` | Pause | 50ms | - |
+| `\|` | Sharp tap | 10ms | 1.0 |
+| `-` | Sustain | 50ms | - |
+
+Groups & repeats: `[~.]x3` repeats 3 times.
+
+## 43 Built-in Presets
+
+```typescript
+import { presets } from '@hapticjs/core';
+
+haptic.play(presets.gaming.explosion);
+haptic.play(presets.ui.pullToRefresh);
+haptic.play(presets.notifications.success);
+```
+
+Categories: UI (12), Notifications (7), Gaming (10), Accessibility (7), System (7).
+
+## Pattern Sharing
+
+```typescript
+import { exportPattern, importPattern, patternToDataURL } from '@hapticjs/core';
+
+const exported = exportPattern('~~..##', { name: 'My Pattern' });
+const url = patternToDataURL('~~..##', { name: 'My Pattern' });
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -133,6 +133,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";
@@ -162,6 +280,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();
 }
 
@@ -196,13 +320,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) {
@@ -607,7 +731,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) {
@@ -787,6 +911,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 */
@@ -1184,6 +1423,7 @@ exports.HPLParser = HPLParser;
 exports.HPLParserError = HPLParserError;
 exports.HPLTokenizerError = HPLTokenizerError;
 exports.HapticEngine = HapticEngine;
+exports.IoSAudioAdapter = IoSAudioAdapter;
 exports.NoopAdapter = NoopAdapter;
 exports.PatternComposer = PatternComposer;
 exports.WebVibrationAdapter = WebVibrationAdapter;
@@ -1191,11 +1431,17 @@ exports.accessibility = accessibility;
 exports.compile = compile;
 exports.detectAdapter = detectAdapter;
 exports.detectPlatform = detectPlatform;
+exports.exportPattern = exportPattern;
 exports.gaming = gaming;
 exports.haptic = haptic;
+exports.importPattern = importPattern;
 exports.notifications = notifications;
 exports.optimizeSteps = optimizeSteps;
 exports.parseHPL = parseHPL;
+exports.patternFromDataURL = patternFromDataURL;
+exports.patternFromJSON = patternFromJSON;
+exports.patternToDataURL = patternToDataURL;
+exports.patternToJSON = patternToJSON;
 exports.presets = presets;
 exports.system = system;
 exports.tokenize = tokenize;