@flighthq/haptics 0.3.1-next.975.01aea94 → 0.4.0-edge.1908.751021c

package/dist/haptics.d.ts

@@ -1,10 +1,15 @@
+import type { BackendExplanation } from '@flighthq/types/contract';
 import type { HapticImpactStyle, HapticNotificationType, HapticsBackend, HapticsCapabilities } from '@flighthq/types/contract';
 export declare function cancelDeviceVibration(): boolean;
 export declare function createWebHapticsBackend(): HapticsBackend;
+export declare function explainHapticsBackend(): BackendExplanation;
 export declare function getHapticsBackend(): HapticsBackend;
 export declare function getHapticsCapabilities(out: HapticsCapabilities): HapticsCapabilities;
+export declare function installHapticsHostBackend(backend: HapticsBackend): void;
 export declare function isHapticsSupported(): boolean;
+export declare function observeHapticsHostResult(operation: string, succeeded: boolean): void;
 export declare function prepareHaptics(): void;
+export declare function resetHapticsBackendForTest(): void;
 export declare function setHapticsBackend(backend: HapticsBackend | null): void;
 export declare function triggerHapticImpact(style: HapticImpactStyle, intensity?: number): boolean;
 export declare function triggerHapticNotification(type: HapticNotificationType): boolean;

package/dist/haptics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"haptics.d.ts","sourceRoot":"","sources":["../src/haptics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAGlC,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAKD,wBAAgB,uBAAuB,IAAI,cAAc,CA8CxD;AAGD,wBAAgB,iBAAiB,IAAI,cAAc,CAGlD;AAGD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAEpF;AAGD,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAID,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAGD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAEtE;AAID,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAIzF;AAID,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAE/E;AAGD,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAGD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAGzE;AAOD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAC3B,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAC9B,MAAM,SAAK,GACV,OAAO,CAOT"}
+{"version":3,"file":"haptics.d.ts","sourceRoot":"","sources":["../src/haptics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAKD,wBAAgB,uBAAuB,IAAI,cAAc,CA2CxD;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAa1D;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAEpF;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAMvE;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAKpF;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAE/E;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAGzE;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAC3B,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAC9B,MAAM,SAAK,GACV,OAAO,CAOT"}

package/dist/haptics.js

@@ -1,4 +1,3 @@
-// Cancels any in-progress device vibration. Returns false when haptics are unavailable.
 export function cancelDeviceVibration() {
     return getHapticsBackend().cancel();
 }
@@ -8,7 +7,7 @@ export function cancelDeviceVibration() {
 export function createWebHapticsBackend() {
     return {
         cancel() {
-            return webVibrate(0);
+            return _webVibrate(0, 'cancel');
         },
         capabilities(out) {
             const supported = typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function';
@@ -22,93 +21,101 @@ export function createWebHapticsBackend() {
         impact(style, intensity) {
             const base = style === 'heavy' || style === 'rigid' ? 30 : style === 'medium' ? 20 : style === 'soft' ? 25 : 10;
             const ms = intensity !== undefined ? Math.round(base * Math.max(0, Math.min(1, intensity))) : base;
-            return webVibrate(ms);
+            return _webVibrate(ms, 'impact');
         },
         isSupported() {
             return typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function';
         },
         notification(type) {
             const pattern = type === 'error' ? [20, 60, 20] : type === 'warning' ? [20, 60, 20, 60] : [15, 50, 15];
-            return webVibrate(pattern);
-        },
-        prepare() {
-            // No-op on web; native backends may pre-allocate feedback generators to reduce latency.
+            return _webVibrate(pattern, 'notification');
         },
+        prepare() { },
         selection() {
-            return webVibrate(5);
+            return _webVibrate(5, 'selection');
         },
         vibrate(durationMs) {
-            return webVibrate(durationMs);
+            return _webVibrate(durationMs, 'vibrate');
         },
         vibratePattern(pattern) {
             if (pattern.length === 0)
                 return false;
-            return webVibrate(pattern);
+            return _webVibrate(pattern, 'vibratePattern');
         },
         vibrateWaveform(timings, _amplitudes, repeat) {
-            // Web backend ignores amplitudes; falls back to vibratePattern. repeat is unsupported on web.
             if (timings.length === 0)
                 return false;
             void repeat;
-            return webVibrate(timings);
+            return _webVibrate(timings, 'vibrateWaveform');
         },
     };
 }
-// The active haptics backend, or a lazily-created web default. There is always a backend.
+export function explainHapticsBackend() {
+    if (_custom !== null) {
+        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
+    }
+    if (_host !== null) {
+        return {
+            conflict: _hostConflict,
+            layer: 'host',
+            operation: _hostObservation !== null ? _hostObservation.operation : null,
+            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
+        };
+    }
+    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
+}
 export function getHapticsBackend() {
-    if (_backend === null)
-        _backend = createWebHapticsBackend();
-    return _backend;
+    return _custom ?? _host ?? _sentinel;
 }
-// Fills out with the capabilities of the active HapticsBackend. Returns the same out object.
 export function getHapticsCapabilities(out) {
     return getHapticsBackend().capabilities(out);
 }
-// Returns true if the active backend reports that haptics are available on the current device.
+export function installHapticsHostBackend(backend) {
+    if (_host !== null) {
+        if (_host !== backend)
+            _hostConflict = true;
+        return;
+    }
+    _host = backend;
+}
 export function isHapticsSupported() {
     return getHapticsBackend().isSupported();
 }
-// Warm-up hint to reduce first-trigger latency (mirrors UIFeedbackGenerator.prepare). No-op on
-// backends that do not support pre-allocation. Always safe to call.
+export function observeHapticsHostResult(operation, succeeded) {
+    _hostObservation = {
+        operation,
+        viability: succeeded ? 'available' : 'runtime-api-unavailable',
+    };
+}
 export function prepareHaptics() {
     getHapticsBackend().prepare?.();
 }
-// Installs a native host haptics backend; pass null to fall back to the web default.
+export function resetHapticsBackendForTest() {
+    _custom = null;
+    _host = null;
+    _hostConflict = false;
+    _hostObservation = null;
+}
 export function setHapticsBackend(backend) {
-    _backend = backend;
+    _custom = backend;
 }
-// Triggers a physical impact at the given style, with optional continuous intensity (0..1).
-// Intensity defaults to 1 when omitted. Returns false when haptics are unavailable.
 export function triggerHapticImpact(style, intensity) {
-    // Resolve the documented default here so every backend receives a concrete intensity; a native
-    // backend must not have to reinterpret `undefined` as full strength on its own.
     return getHapticsBackend().impact(style, intensity ?? 1);
 }
-// Triggers a semantic notification cue ('success' | 'warning' | 'error').
-// Returns false when haptics are unavailable.
 export function triggerHapticNotification(type) {
     return getHapticsBackend().notification(type);
 }
-// Triggers a light selection tick. Returns false when haptics are unavailable.
 export function triggerHapticSelection() {
     return getHapticsBackend().selection();
 }
-// Vibrates the device for the given duration in milliseconds. Returns false when unavailable or denied.
 export function vibrateDevice(durationMs) {
     return getHapticsBackend().vibrate(durationMs);
 }
-// Vibrates the device using a pattern array [onMs, offMs, onMs, ...] matching the Web Vibration API.
-// Returns false on empty pattern or when haptics are unavailable.
 export function vibrateDevicePattern(pattern) {
     if (pattern.length === 0)
         return false;
     return getHapticsBackend().vibratePattern(pattern);
 }
-// Vibrates using an amplitude-aware waveform (maps to Android VibrationEffect.createWaveform).
-// timings and amplitudes must have equal length; amplitudes are 0..255 (per Android convention).
-// repeat is the index into timings at which to loop, or -1 (default) for no repeat.
-// Backends that lack native waveform support fall back to vibratePattern(timings).
-// Returns false on empty timings or when haptics are unavailable.
 export function vibrateDeviceWaveform(timings, amplitudes, repeat = -1) {
     const backend = getHapticsBackend();
     if (timings.length === 0)
@@ -118,15 +125,54 @@ export function vibrateDeviceWaveform(timings, amplitudes, repeat = -1) {
     }
     return backend.vibratePattern(timings);
 }
-let _backend = null;
-function webVibrate(pattern) {
+let _custom = null;
+let _host = null;
+let _hostConflict = false;
+let _hostObservation = null;
+const _sentinel = {
+    cancel() {
+        return false;
+    },
+    capabilities(out) {
+        out.amplitudeControl = false;
+        out.customEvents = false;
+        out.intensity = false;
+        out.patterns = false;
+        out.supported = false;
+        return out;
+    },
+    impact() {
+        return false;
+    },
+    isSupported() {
+        return false;
+    },
+    notification() {
+        return false;
+    },
+    prepare() { },
+    selection() {
+        return false;
+    },
+    vibrate() {
+        return false;
+    },
+    vibratePattern() {
+        return false;
+    },
+};
+function _webVibrate(pattern, operation) {
     if (typeof navigator === 'undefined' || !('vibrate' in navigator) || typeof navigator.vibrate !== 'function') {
+        observeHapticsHostResult(operation, false);
         return false;
     }
     try {
-        return navigator.vibrate(pattern);
+        const result = navigator.vibrate(pattern);
+        observeHapticsHostResult(operation, result);
+        return result;
     }
     catch {
+        observeHapticsHostResult(operation, false);
         return false;
     }
 }

package/dist/haptics.js.map

@@ -1 +1 @@
-{"version":3,"file":"haptics.js","sourceRoot":"","sources":["../src/haptics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"haptics.js","sourceRoot":"","sources":["../src/haptics.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { cancelDeviceVibration, getHapticsCapabilities, isHapticsSupported, prepareHaptics, triggerHapticImpact, triggerHapticNotification, triggerHapticSelection, vibrateDevice, vibrateDevicePattern, vibrateDeviceWaveform, } from './contract';
+export { explainHapticsBackend, cancelDeviceVibration, getHapticsCapabilities, isHapticsSupported, prepareHaptics, triggerHapticImpact, triggerHapticNotification, triggerHapticSelection, vibrateDevice, vibrateDevicePattern, vibrateDeviceWaveform, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { cancelDeviceVibration, getHapticsCapabilities, isHapticsSupported, prepareHaptics, triggerHapticImpact, triggerHapticNotification, triggerHapticSelection, vibrateDevice, vibrateDevicePattern, vibrateDeviceWaveform, } from './contract';
+export { explainHapticsBackend, cancelDeviceVibration, getHapticsCapabilities, isHapticsSupported, prepareHaptics, triggerHapticImpact, triggerHapticNotification, triggerHapticSelection, vibrateDevice, vibrateDevicePattern, vibrateDeviceWaveform, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/haptics",
-  "version": "0.3.1-next.975.01aea94",
+  "version": "0.4.0-edge.1908.751021c",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.1-next.975.01aea94"
+    "@flighthq/types": "0.4.0-edge.1908.751021c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/haptics.test.ts

@@ -19,6 +19,10 @@ import {
   vibrateDevice,
   vibrateDevicePattern,
   vibrateDeviceWaveform,
+  explainHapticsBackend,
+  installHapticsHostBackend,
+  observeHapticsHostResult,
+  resetHapticsBackendForTest,
 } from './haptics';
 
 function makeCapabilities(overrides: Partial<HapticsCapabilities> = {}): HapticsCapabilities {
@@ -155,6 +159,34 @@ describe('createWebHapticsBackend', () => {
   });
 });
 
+describe('explainHapticsBackend', () => {
+  afterEach(() => resetHapticsBackendForTest());
+
+  it('reports host-not-enabled when no backend is installed', () => {
+    resetHapticsBackendForTest();
+    const explanation = explainHapticsBackend();
+    expect(explanation.layer).toBe('host-not-enabled');
+    expect(explanation.conflict).toBe(false);
+    expect(explanation.viability).toBe('unobserved');
+  });
+
+  it('reports custom layer when a custom backend is set', () => {
+    setHapticsBackend(fakeBackend());
+    expect(explainHapticsBackend().layer).toBe('custom');
+  });
+
+  it('reports host layer when a host backend is installed', () => {
+    installHapticsHostBackend(fakeBackend());
+    expect(explainHapticsBackend().layer).toBe('host');
+  });
+
+  it('reports conflict when two different host backends are installed', () => {
+    installHapticsHostBackend(fakeBackend());
+    installHapticsHostBackend(fakeBackend());
+    expect(explainHapticsBackend().conflict).toBe(true);
+  });
+});
+
 describe('getHapticsBackend', () => {
   it('falls back to a web backend', () => {
     expect(getHapticsBackend()).not.toBeNull();
@@ -188,6 +220,25 @@ describe('getHapticsCapabilities', () => {
   });
 });
 
+describe('installHapticsHostBackend', () => {
+  afterEach(() => resetHapticsBackendForTest());
+
+  it('installs a host backend that getHapticsBackend returns', () => {
+    const backend = fakeBackend();
+    installHapticsHostBackend(backend);
+    expect(getHapticsBackend()).toBe(backend);
+  });
+
+  it('is first-host-wins: a second different backend sets conflict', () => {
+    const first = fakeBackend();
+    const second = fakeBackend();
+    installHapticsHostBackend(first);
+    installHapticsHostBackend(second);
+    expect(getHapticsBackend()).toBe(first);
+    expect(explainHapticsBackend().conflict).toBe(true);
+  });
+});
+
 describe('isHapticsSupported', () => {
   it('returns true from fake backend', () => {
     setHapticsBackend(fakeBackend());
@@ -199,6 +250,24 @@ describe('isHapticsSupported', () => {
   });
 });
 
+describe('observeHapticsHostResult', () => {
+  afterEach(() => resetHapticsBackendForTest());
+
+  it('records a successful observation', () => {
+    installHapticsHostBackend(fakeBackend());
+    observeHapticsHostResult('cancel', true);
+    const explanation = explainHapticsBackend();
+    expect(explanation.operation).toBe('cancel');
+    expect(explanation.viability).toBe('available');
+  });
+
+  it('records a failed observation', () => {
+    installHapticsHostBackend(fakeBackend());
+    observeHapticsHostResult('cancel', false);
+    expect(explainHapticsBackend().viability).toBe('runtime-api-unavailable');
+  });
+});
+
 describe('prepareHaptics', () => {
   it('calls prepare on backends that provide it', () => {
     const backend = fakeBackend();
@@ -216,6 +285,18 @@ describe('prepareHaptics', () => {
   });
 });
 
+describe('resetHapticsBackendForTest', () => {
+  it('clears all backend slots', () => {
+    setHapticsBackend(fakeBackend());
+    installHapticsHostBackend(fakeBackend());
+    observeHapticsHostResult('cancel', true);
+    resetHapticsBackendForTest();
+    expect(explainHapticsBackend().layer).toBe('host-not-enabled');
+    expect(explainHapticsBackend().conflict).toBe(false);
+    expect(explainHapticsBackend().viability).toBe('unobserved');
+  });
+});
+
 describe('setHapticsBackend', () => {
   it('clears back to the web fallback when passed null', () => {
     setHapticsBackend(fakeBackend());