web-haptic-engine 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1047 @@
+//#region src/core/easings.ts
+const easings = {
+	linear: (t) => t,
+	easeIn: (t) => t * t,
+	easeOut: (t) => t * (2 - t),
+	easeInOut: (t) => t < .5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
+	bounce: (t) => {
+		if (t < 1 / 2.75) return 7.5625 * t * t;
+		if (t < 2 / 2.75) return 7.5625 * (t -= 1.5 / 2.75) * t + .75;
+		if (t < 2.5 / 2.75) return 7.5625 * (t -= 2.25 / 2.75) * t + .9375;
+		return 7.5625 * (t -= 2.625 / 2.75) * t + .984375;
+	},
+	spring: (t) => 1 - Math.cos(t * 4.5 * Math.PI) * Math.exp(-t * 6)
+};
+//#endregion
+//#region src/core/presets.ts
+const presets = {
+	success: {
+		description: "Ascending double-tap",
+		pattern: [{
+			duration: 30,
+			intensity: .5
+		}, {
+			delay: 65,
+			duration: 45,
+			intensity: 1
+		}],
+		iosTicks: 2,
+		iosTickGap: 80,
+		impulse: "confirm"
+	},
+	warning: {
+		description: "Two hesitant taps",
+		pattern: [{
+			duration: 40,
+			intensity: .7
+		}, {
+			delay: 120,
+			duration: 35,
+			intensity: .5
+		}],
+		iosTicks: 2,
+		iosTickGap: 140,
+		impulse: "harsh"
+	},
+	error: {
+		description: "Three rapid harsh taps",
+		pattern: [
+			{
+				duration: 45,
+				intensity: .9
+			},
+			{
+				delay: 50,
+				duration: 45,
+				intensity: .9
+			},
+			{
+				delay: 50,
+				duration: 45,
+				intensity: .9
+			}
+		],
+		iosTicks: 3,
+		iosTickGap: 65,
+		impulse: "harsh"
+	},
+	confirm: {
+		description: "Strong double-tap confirm",
+		pattern: [{
+			duration: 35,
+			intensity: .9
+		}, {
+			delay: 100,
+			duration: 50,
+			intensity: 1
+		}],
+		iosTicks: 2,
+		iosTickGap: 110,
+		impulse: "confirm"
+	},
+	reject: {
+		description: "Harsh staccato triple",
+		pattern: [
+			{
+				duration: 30,
+				intensity: 1
+			},
+			{
+				delay: 30,
+				duration: 30,
+				intensity: 1
+			},
+			{
+				delay: 30,
+				duration: 50,
+				intensity: 1
+			}
+		],
+		iosTicks: 3,
+		iosTickGap: 45,
+		impulse: "harsh"
+	},
+	light: {
+		description: "Single light tap",
+		pattern: [{
+			duration: 12,
+			intensity: .35
+		}],
+		iosTicks: 1,
+		impulse: "tick"
+	},
+	medium: {
+		description: "Moderate tap",
+		pattern: [{
+			duration: 28,
+			intensity: .65
+		}],
+		iosTicks: 1,
+		impulse: "tap"
+	},
+	heavy: {
+		description: "Strong tap",
+		pattern: [{
+			duration: 40,
+			intensity: 1
+		}],
+		iosTicks: 2,
+		iosTickGap: 30,
+		impulse: "thud"
+	},
+	soft: {
+		description: "Cushioned tap",
+		pattern: [{
+			duration: 45,
+			intensity: .45
+		}],
+		iosTicks: 1,
+		impulse: "tap"
+	},
+	rigid: {
+		description: "Hard crisp snap",
+		pattern: [{
+			duration: 8,
+			intensity: 1
+		}],
+		iosTicks: 1,
+		impulse: "snap"
+	},
+	selection: {
+		description: "Subtle tick",
+		pattern: [{
+			duration: 6,
+			intensity: .25
+		}],
+		iosTicks: 1,
+		impulse: "tick"
+	},
+	tick: {
+		description: "Crisp tick",
+		pattern: [{
+			duration: 10,
+			intensity: .5
+		}],
+		iosTicks: 1,
+		impulse: "click"
+	},
+	click: {
+		description: "Ultra-short click",
+		pattern: [{
+			duration: 5,
+			intensity: .8
+		}],
+		iosTicks: 1,
+		impulse: "click"
+	},
+	snap: {
+		description: "Sharp snap",
+		pattern: [{
+			duration: 6,
+			intensity: 1
+		}],
+		iosTicks: 1,
+		impulse: "snap"
+	},
+	nudge: {
+		description: "Two quick taps",
+		pattern: [{
+			duration: 60,
+			intensity: .7
+		}, {
+			delay: 70,
+			duration: 40,
+			intensity: .3
+		}],
+		iosTicks: 2,
+		iosTickGap: 90,
+		impulse: "tap"
+	},
+	buzz: {
+		description: "Sustained vibration",
+		pattern: [{
+			duration: 800,
+			intensity: 1
+		}],
+		iosTicks: 8,
+		iosTickGap: 50,
+		impulse: "buzz"
+	},
+	heartbeat: {
+		description: "Heartbeat rhythm",
+		pattern: [
+			{
+				duration: 35,
+				intensity: .8
+			},
+			{
+				delay: 80,
+				duration: 25,
+				intensity: .5
+			},
+			{
+				delay: 300,
+				duration: 35,
+				intensity: .8
+			},
+			{
+				delay: 80,
+				duration: 25,
+				intensity: .5
+			}
+		],
+		iosTicks: 4,
+		iosTickGap: 0,
+		impulse: "thud"
+	},
+	spring: {
+		description: "Bouncy pulses",
+		pattern: [
+			{
+				duration: 40,
+				intensity: 1
+			},
+			{
+				delay: 50,
+				duration: 30,
+				intensity: .7
+			},
+			{
+				delay: 45,
+				duration: 20,
+				intensity: .45
+			},
+			{
+				delay: 40,
+				duration: 12,
+				intensity: .25
+			}
+		],
+		iosTicks: 4,
+		iosTickGap: 55,
+		impulse: "tap",
+		easing: "bounce"
+	},
+	rampUp: {
+		description: "Escalating",
+		pattern: [
+			{
+				duration: 12,
+				intensity: .2
+			},
+			{
+				delay: 50,
+				duration: 18,
+				intensity: .4
+			},
+			{
+				delay: 45,
+				duration: 25,
+				intensity: .65
+			},
+			{
+				delay: 40,
+				duration: 35,
+				intensity: 1
+			}
+		],
+		iosTicks: 4,
+		iosTickGap: 60,
+		impulse: "tap",
+		easing: "easeIn"
+	},
+	rampDown: {
+		description: "Decreasing",
+		pattern: [
+			{
+				duration: 35,
+				intensity: 1
+			},
+			{
+				delay: 45,
+				duration: 25,
+				intensity: .6
+			},
+			{
+				delay: 50,
+				duration: 15,
+				intensity: .3
+			},
+			{
+				delay: 55,
+				duration: 8,
+				intensity: .15
+			}
+		],
+		iosTicks: 3,
+		iosTickGap: 65,
+		impulse: "tap",
+		easing: "easeOut"
+	},
+	thud: {
+		description: "Heavy impact",
+		pattern: [{
+			duration: 50,
+			intensity: 1
+		}, {
+			delay: 40,
+			duration: 25,
+			intensity: .35
+		}],
+		iosTicks: 2,
+		iosTickGap: 50,
+		impulse: "thud"
+	},
+	trill: {
+		description: "Rapid flutter",
+		pattern: [
+			{
+				duration: 15,
+				intensity: .8
+			},
+			{
+				delay: 25,
+				duration: 15,
+				intensity: .8
+			},
+			{
+				delay: 25,
+				duration: 15,
+				intensity: .8
+			},
+			{
+				delay: 25,
+				duration: 15,
+				intensity: .8
+			},
+			{
+				delay: 25,
+				duration: 15,
+				intensity: .8
+			}
+		],
+		iosTicks: 5,
+		iosTickGap: 35,
+		impulse: "click"
+	},
+	pulse: {
+		description: "Rhythmic pulse",
+		pattern: [
+			{
+				duration: 30,
+				intensity: .6
+			},
+			{
+				delay: 150,
+				duration: 30,
+				intensity: .6
+			},
+			{
+				delay: 150,
+				duration: 30,
+				intensity: .6
+			}
+		],
+		iosTicks: 3,
+		iosTickGap: 180,
+		impulse: "tap"
+	}
+};
+//#endregion
+//#region src/core/constants.ts
+/** Maximum duration for a single vibration segment (ms). */
+const MAX_SEG_MS = 1e3;
+//#endregion
+//#region src/audio/impulse-library.ts
+var ImpulseLibrary = class {
+	buffers = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		this.ctx = ctx;
+		this.build();
+	}
+	build() {
+		const sr = this.ctx.sampleRate;
+		this.mk("tick", sr, .008, (t) => {
+			const e = Math.exp(-t * 600);
+			return Math.sin(2 * Math.PI * 320 * t) * e + Math.sin(2 * Math.PI * 800 * t) * e * .15;
+		});
+		this.mk("tap", sr, .02, (t) => {
+			const e = Math.exp(-t * 250);
+			return Math.sin(2 * Math.PI * 220 * t) * e + (t < .001 ? Math.sin(2 * Math.PI * 800 * t) * (1 - t / .001) * .4 : 0) + Math.sin(2 * Math.PI * 110 * t) * e * .3;
+		});
+		this.mk("thud", sr, .035, (t) => {
+			const e = Math.exp(-t * 150);
+			return Math.sin(2 * Math.PI * 160 * t) * e + Math.sin(2 * Math.PI * 80 * t) * e * .5 + (t < .002 ? Math.sin(2 * Math.PI * 600 * t) * (1 - t / .002) * .3 : 0);
+		});
+		this.mk("click", sr, .005, (t) => {
+			const e = Math.exp(-t * 1200);
+			return Math.sin(2 * Math.PI * 400 * t) * e + Math.sin(2 * Math.PI * 1200 * t) * e * .1;
+		});
+		this.mk("snap", sr, .01, (t) => {
+			const e = Math.exp(-t * 500);
+			return Math.sin(2 * Math.PI * 500 * t) * e + Math.sin(2 * Math.PI * 1380 * t) * e * .2;
+		});
+		this.mk("buzz", sr, .06, (t) => {
+			const e = Math.exp(-t * 40);
+			let s = 0;
+			for (let h = 1; h <= 5; h++) s += Math.sin(2 * Math.PI * 200 * h * t) / h;
+			return s * e * .4;
+		});
+		this.mk("confirm", sr, .025, (t) => {
+			const e = Math.exp(-t * 200);
+			return (Math.sin(2 * Math.PI * 280 * t) * .6 + Math.sin(2 * Math.PI * 420 * t) * .4) * e;
+		});
+		this.mk("harsh", sr, .03, (t) => {
+			const f = 180, e = Math.exp(-t * 160);
+			let s = 0;
+			for (let h = 1; h <= 6; h++) s += Math.sin(2 * Math.PI * f * h * t) * (h % 2 === 0 ? .8 : 1) / h;
+			return (s + Math.sin(2 * Math.PI * f * 1.07 * t) * e * .3) * e * .35;
+		});
+	}
+	/** Synthesize a named impulse buffer: peak-normalize samples from fn(t). */
+	mk(name, sr, dur, fn) {
+		const len = Math.ceil(sr * dur), buf = this.ctx.createBuffer(1, len, sr), d = buf.getChannelData(0);
+		let pk = 0;
+		for (let i = 0; i < len; i++) {
+			d[i] = fn(i / sr);
+			pk = Math.max(pk, Math.abs(d[i]));
+		}
+		if (pk > 0) for (let i = 0; i < len; i++) d[i] /= pk;
+		this.buffers.set(name, buf);
+	}
+	get(name) {
+		return this.buffers.get(name);
+	}
+};
+//#endregion
+//#region src/audio/audio-layer.ts
+var AudioImpulseLayer = class {
+	ctx = null;
+	lib = null;
+	mg;
+	unlocked = false;
+	constructor(gain = .6) {
+		this.mg = gain;
+	}
+	/** Play a silent buffer to unlock the AudioContext (call from user gesture). */
+	unlock() {
+		if (this.unlocked) return;
+		try {
+			const ctx = this.ensureCtx();
+			const b = ctx.createBuffer(1, 1, ctx.sampleRate);
+			const s = ctx.createBufferSource();
+			s.buffer = b;
+			s.connect(ctx.destination);
+			s.start(0);
+			if (ctx.state === "suspended") ctx.resume();
+			this.unlocked = true;
+		} catch {}
+	}
+	ensureCtx() {
+		if (!this.ctx) {
+			this.ctx = new AudioContext();
+			this.lib = new ImpulseLibrary(this.ctx);
+		}
+		if (this.ctx.state === "suspended") this.ctx.resume();
+		return this.ctx;
+	}
+	/** Play a single impulse at the given intensity. */
+	fire(type, intensity) {
+		try {
+			const ctx = this.ensureCtx();
+			if (!this.lib) return;
+			const buf = this.lib.get(type);
+			if (!buf) return;
+			const src = ctx.createBufferSource();
+			const gain = ctx.createGain();
+			src.buffer = buf;
+			gain.gain.value = intensity * this.mg;
+			src.connect(gain);
+			gain.connect(ctx.destination);
+			src.start(0);
+		} catch {}
+	}
+	/** Play a sequence of impulses matching a Vibration[] pattern. */
+	fireSequence(vibs, type, intensity, ef) {
+		let elapsed = 0;
+		const count = vibs.length;
+		for (let i = 0; i < count; i++) {
+			const v = vibs[i];
+			const delay = elapsed + (v.delay ?? 0);
+			const si = v.intensity ?? intensity;
+			const pr = count > 1 ? i / (count - 1) : 1;
+			const ei = ef ? si * Math.max(.1, ef(pr)) : si;
+			if (delay <= 0) this.fire(type, ei);
+			else setTimeout(() => this.fire(type, ei), delay);
+			elapsed = delay + v.duration;
+		}
+	}
+	setGain(g) {
+		this.mg = Math.max(0, Math.min(1, g));
+	}
+	destroy() {
+		this.ctx?.close();
+		this.ctx = null;
+		this.lib = null;
+	}
+};
+//#endregion
+//#region src/interactions/drag-haptics.ts
+var DragHaptics = class {
+	engine;
+	opts;
+	curX = 0;
+	curY = 0;
+	lastFireX = 0;
+	lastFireY = 0;
+	lastFireT = 0;
+	active = false;
+	tickCount = 0;
+	cleanup = [];
+	/** Set during a touch sequence to prevent mouse handlers from double-firing. */
+	touchActive = false;
+	constructor(engine, options = {}) {
+		this.engine = engine;
+		this.opts = {
+			fireDist: options.fireDist ?? 18,
+			impulse: options.impulse ?? "tick",
+			intensity: options.intensity ?? .6,
+			onTick: options.onTick
+		};
+	}
+	/** Attach drag-haptic listeners to an element. Returns an unbind function. */
+	bind(element) {
+		const startDrag = (x, y) => {
+			this.curX = this.lastFireX = x;
+			this.curY = this.lastFireY = y;
+			this.lastFireT = performance.now();
+			this.active = true;
+			this.tickCount = 0;
+			this.engine.fireDragTickIfVibration(this.opts.intensity, 0);
+			this.engine.fireImpulse(this.opts.impulse, this.opts.intensity);
+			this.tickCount++;
+			this.opts.onTick?.(0, this.tickCount);
+		};
+		const moveDrag = (x, y) => {
+			if (!this.active) return;
+			this.curX = x;
+			this.curY = y;
+			const dist = this.distFromLastFire();
+			const elapsed = performance.now() - this.lastFireT;
+			if (dist >= this.opts.fireDist || dist >= 2 && elapsed >= 80) {
+				const dt = elapsed / 1e3;
+				const velocity = dt > .001 ? dist / dt : 0;
+				this.engine.fireDragTickIfVibration(this.opts.intensity, velocity);
+				this.engine.fireImpulse(this.opts.impulse, this.opts.intensity);
+				this.lastFireX = this.curX;
+				this.lastFireY = this.curY;
+				this.lastFireT = performance.now();
+				this.tickCount++;
+				this.opts.onTick?.(velocity, this.tickCount);
+			}
+		};
+		const endDrag = () => {
+			if (!this.active) return;
+			this.active = false;
+			this.engine.trigger("selection", { intensity: this.opts.intensity });
+		};
+		const onTouchStart = (e) => {
+			this.touchActive = true;
+			const t = e.touches[0];
+			startDrag(t.clientX, t.clientY);
+		};
+		const onTouchMove = (e) => {
+			const t = e.touches[0];
+			moveDrag(t.clientX, t.clientY);
+		};
+		const onTouchEnd = () => {
+			endDrag();
+			setTimeout(() => {
+				this.touchActive = false;
+			}, 400);
+		};
+		const onTouchCancel = () => {
+			this.active = false;
+			this.touchActive = false;
+		};
+		const onMouseDown = (e) => {
+			if (this.touchActive) return;
+			if (e.button !== 0) return;
+			startDrag(e.clientX, e.clientY);
+		};
+		const onMouseMove = (e) => {
+			if (this.touchActive) return;
+			moveDrag(e.clientX, e.clientY);
+		};
+		const onMouseUp = () => {
+			if (this.touchActive) return;
+			endDrag();
+		};
+		element.addEventListener("touchstart", onTouchStart, { passive: true });
+		element.addEventListener("touchmove", onTouchMove, { passive: true });
+		element.addEventListener("touchend", onTouchEnd, { passive: true });
+		element.addEventListener("touchcancel", onTouchCancel, { passive: true });
+		element.addEventListener("mousedown", onMouseDown);
+		window.addEventListener("mousemove", onMouseMove);
+		window.addEventListener("mouseup", onMouseUp);
+		const unbind = () => {
+			element.removeEventListener("touchstart", onTouchStart);
+			element.removeEventListener("touchmove", onTouchMove);
+			element.removeEventListener("touchend", onTouchEnd);
+			element.removeEventListener("touchcancel", onTouchCancel);
+			element.removeEventListener("mousedown", onMouseDown);
+			window.removeEventListener("mousemove", onMouseMove);
+			window.removeEventListener("mouseup", onMouseUp);
+			this.active = false;
+		};
+		this.cleanup.push(unbind);
+		return unbind;
+	}
+	distFromLastFire() {
+		const dx = this.curX - this.lastFireX;
+		const dy = this.curY - this.lastFireY;
+		return Math.sqrt(dx * dx + dy * dy);
+	}
+	/** Unbind all elements and stop tracking. */
+	destroyAll() {
+		this.active = false;
+		this.cleanup.forEach((fn) => fn());
+		this.cleanup = [];
+	}
+};
+//#endregion
+//#region src/platform/android.ts
+function buildAndroidPattern(vibs, di, ef) {
+	const flat = [];
+	const count = vibs.length;
+	for (let idx = 0; idx < count; idx++) {
+		const v = vibs[idx];
+		let intensity = Math.max(0, Math.min(1, v.intensity ?? di));
+		if (ef && count > 1) intensity *= Math.max(.1, ef(idx / (count - 1)));
+		const sc = Math.max(1, Math.round(Math.min(v.duration, MAX_SEG_MS) * Math.max(.15, intensity)));
+		if (v.delay && v.delay > 0) if (!flat.length) flat.push(0, v.delay);
+		else if (flat.length % 2 === 0) flat[flat.length - 1] += v.delay;
+		else flat.push(v.delay);
+		if (flat.length > 0 && flat.length % 2 === 1) flat.push(0);
+		flat.push(sc);
+	}
+	return flat;
+}
+//#endregion
+//#region src/platform/detection.ts
+const hasVib = () => typeof navigator !== "undefined" && typeof navigator.vibrate === "function";
+const isIOS = () => {
+	if (typeof document === "undefined") return false;
+	if (hasVib()) return false;
+	if (!("ontouchstart" in window) && !navigator.maxTouchPoints) return false;
+	try {
+		const el = document.createElement("input");
+		el.type = "checkbox";
+		el.setAttribute("switch", "");
+		return el.getAttribute("switch") !== null;
+	} catch {
+		return false;
+	}
+};
+const detectPlatform = () => {
+	if (typeof window === "undefined") return "none";
+	if (hasVib()) return "vibration";
+	if (isIOS()) return "ios-switch";
+	return "none";
+};
+const supportsIOSHaptics = typeof document !== "undefined" ? isIOS() : false;
+//#endregion
+//#region src/platform/ios.ts
+var IOSSwitchPool = class {
+	labels = [];
+	nextIndex = 0;
+	constructor() {
+		for (let i = 0; i < 6; i++) {
+			const id = `__hp${i}_${Date.now()}`;
+			const label = document.createElement("label");
+			label.setAttribute("for", id);
+			label.style.position = "fixed";
+			label.style.top = "0";
+			label.style.left = "0";
+			label.style.width = "1px";
+			label.style.height = "1px";
+			label.style.overflow = "hidden";
+			label.style.opacity = "0.01";
+			label.style.pointerEvents = "none";
+			label.style.userSelect = "none";
+			label.setAttribute("aria-hidden", "true");
+			const input = document.createElement("input");
+			input.type = "checkbox";
+			input.setAttribute("switch", "");
+			input.id = id;
+			input.tabIndex = -1;
+			input.style.all = "initial";
+			input.style.appearance = "auto";
+			label.appendChild(input);
+			document.body.appendChild(label);
+			this.labels.push(label);
+		}
+	}
+	/** Toggle the next switch in the pool to fire a single Taptic tick. */
+	fire() {
+		const label = this.labels[this.nextIndex];
+		this.nextIndex = (this.nextIndex + 1) % this.labels.length;
+		label.click();
+	}
+	destroy() {
+		for (const l of this.labels) l.remove();
+		this.labels = [];
+	}
+};
+function iosPlan(vibs, pr, di) {
+	if (pr?.iosTicks !== void 0) {
+		const bt = pr.iosTicks, sc = Math.max(1, Math.round(bt * Math.max(.25, di)));
+		const gap = pr.iosTickGap ?? 55;
+		if (gap === 0 && vibs.length > 1) {
+			const gs = [];
+			for (let i = 1; i < vibs.length && gs.length < sc - 1; i++) gs.push((vibs[i].delay ?? 0) + vibs[i - 1].duration);
+			return {
+				ticks: Math.min(sc, gs.length + 1),
+				gaps: gs
+			};
+		}
+		return {
+			ticks: sc,
+			gaps: Array(Math.max(0, sc - 1)).fill(gap)
+		};
+	}
+	let t = 0;
+	const gs = [];
+	for (const v of vibs) if ((v.intensity ?? di) >= .12) {
+		if (t > 0) gs.push((v.delay ?? 0) + (vibs[t - 1]?.duration ?? 0));
+		t++;
+	}
+	const sc = Math.max(1, Math.round(t * Math.max(.25, di)));
+	return {
+		ticks: sc,
+		gaps: gs.slice(0, Math.max(0, sc - 1))
+	};
+}
+//#endregion
+//#region src/haptic-engine.ts
+var HapticEngine = class HapticEngine {
+	platform;
+	iosPool = null;
+	audio = null;
+	useAudio;
+	throttleMs;
+	enabled = true;
+	lastTriggerTime = 0;
+	activeAbort = null;
+	/** True if the device supports Android-style navigator.vibrate(). */
+	static supportsVibration = hasVib();
+	/** True if the device supports iOS switch-checkbox haptics. */
+	static supportsIOSHaptics = supportsIOSHaptics;
+	/** True if any form of haptic feedback is available. */
+	static isSupported = HapticEngine.supportsVibration || HapticEngine.supportsIOSHaptics;
+	constructor(options = {}) {
+		this.throttleMs = options.throttleMs ?? 25;
+		this.useAudio = options.audioLayer ?? true;
+		this.platform = detectPlatform();
+		if (this.platform === "ios-switch") this.iosPool = new IOSSwitchPool();
+		this.audio = new AudioImpulseLayer(options.audioGain ?? .6);
+		if (typeof document !== "undefined") {
+			const unlock = () => {
+				this.audio?.unlock();
+			};
+			document.addEventListener("touchstart", unlock, {
+				once: true,
+				passive: true,
+				capture: true
+			});
+			document.addEventListener("click", unlock, {
+				once: true,
+				capture: true
+			});
+		}
+	}
+	/**
+	* Fire a haptic + audio pattern. Input can be a preset name, duration (ms),
+	* Vibration[], number[] (alternating on/off), or a HapticPreset object.
+	*/
+	async trigger(input, options) {
+		if (!this.enabled) return;
+		const now = performance.now();
+		if (now - this.lastTriggerTime < this.throttleMs) return;
+		this.lastTriggerTime = now;
+		this.cancel();
+		const r = this.resolveInput(input);
+		if (r.vibrations.length === 0) return;
+		const di = options?.intensity ?? .5;
+		const ef = r.preset?.easing ? easings[r.preset.easing] : void 0;
+		const sa = options?.audio ?? this.useAudio;
+		this.audio?.unlock();
+		if (sa && this.audio && r.preset?.impulse) this.audio.fireSequence(r.vibrations, r.preset.impulse, di, ef);
+		switch (this.platform) {
+			case "vibration":
+				await this.fireAndroid(r.vibrations, di, ef);
+				break;
+			case "ios-switch":
+				await this.fireIOS(r.vibrations, r.preset, di);
+				break;
+		}
+	}
+	/** Play an audio impulse. Set force=true to bypass the audio-enabled toggle. */
+	fireImpulse(type, intensity, force) {
+		if ((force || this.useAudio) && this.audio) {
+			this.audio.unlock();
+			this.audio.fire(type, intensity);
+		}
+	}
+	/** Fire a single platform haptic tick (short vibrate or single iOS switch toggle). */
+	fireHapticTick(intensity) {
+		if (this.platform === "vibration") try {
+			navigator.vibrate(Math.max(1, Math.round(10 * intensity)));
+		} catch {}
+		else if (this.platform === "ios-switch" && this.iosPool) try {
+			this.iosPool.fire();
+		} catch {}
+	}
+	/**
+	* Fire a drag-optimized haptic tick. Skips cancel()/vibrate(0) overhead.
+	* Android: velocity scales pulse duration (12-25ms) and count (1-3 taps).
+	* iOS: single switch toggle (requires user activation to produce Taptic).
+	*/
+	fireDragTick(intensity, velocity) {
+		const taps = Math.max(1, Math.min(3, Math.ceil(velocity / 400)));
+		if (this.platform === "vibration") {
+			const dur = Math.max(12, Math.min(25, Math.round(15 * intensity + velocity / 200)));
+			if (taps === 1) try {
+				navigator.vibrate(dur);
+			} catch {}
+			else {
+				const pat = [];
+				for (let i = 0; i < taps; i++) {
+					if (i > 0) pat.push(6);
+					pat.push(dur);
+				}
+				try {
+					navigator.vibrate(pat);
+				} catch {}
+			}
+		} else if (this.platform === "ios-switch" && this.iosPool) try {
+			this.iosPool.fire();
+		} catch {}
+	}
+	/** Fire a drag tick only on Android (vibration platform). No-op on iOS. */
+	fireDragTickIfVibration(intensity, velocity) {
+		if (this.platform !== "vibration") return;
+		this.fireDragTick(intensity, velocity);
+	}
+	/** Play a sequence of preset steps with optional delays and repeats. */
+	async sequence(steps, options) {
+		const repeat = options?.repeat ?? 1, repeatGap = options?.repeatGap ?? 200;
+		const ac = new AbortController();
+		this.activeAbort = ac;
+		for (let rep = 0; rep < repeat; rep++) {
+			if (ac.signal.aborted) return;
+			for (const step of steps) {
+				if (ac.signal.aborted) return;
+				if (step.delay && step.delay > 0) {
+					await this.sleep(step.delay, ac.signal);
+					if (ac.signal.aborted) return;
+				}
+				this.lastTriggerTime = 0;
+				await this.trigger(step.preset, { intensity: step.intensity });
+			}
+			if (rep < repeat - 1 && repeatGap > 0) await this.sleep(repeatGap, ac.signal);
+		}
+	}
+	/** Create a DragHaptics instance bound to this engine. */
+	drag(options) {
+		return new DragHaptics(this, options);
+	}
+	/** Cancel any in-progress pattern or vibration. */
+	cancel() {
+		this.activeAbort?.abort();
+		this.activeAbort = null;
+		if (this.platform === "vibration" && hasVib()) navigator.vibrate(0);
+	}
+	setEnabled(e) {
+		this.enabled = e;
+		if (!e) this.cancel();
+	}
+	get isEnabled() {
+		return this.enabled;
+	}
+	setAudioLayer(e) {
+		this.useAudio = e;
+	}
+	setAudioGain(g) {
+		this.audio?.setGain(g);
+	}
+	setThrottle(ms) {
+		this.throttleMs = Math.max(0, ms);
+	}
+	registerPreset(name, preset) {
+		presets[name] = preset;
+	}
+	/** Clean up all resources (audio context, iOS DOM elements). */
+	destroy() {
+		this.cancel();
+		this.iosPool?.destroy();
+		this.iosPool = null;
+		this.audio?.destroy();
+		this.audio = null;
+	}
+	/** Resolve any HapticInput into a Vibration[] and optional preset metadata. */
+	resolveInput(input) {
+		if (input == null) return {
+			vibrations: presets.medium.pattern,
+			preset: presets.medium
+		};
+		if (typeof input === "string") {
+			const p = presets[input];
+			if (!p) {
+				console.warn(`[haptics] Unknown: "${input}"`);
+				return {
+					vibrations: [],
+					preset: null
+				};
+			}
+			return {
+				vibrations: p.pattern,
+				preset: p
+			};
+		}
+		if (typeof input === "number") return {
+			vibrations: [{ duration: input }],
+			preset: null
+		};
+		if (typeof input === "object" && !Array.isArray(input) && "pattern" in input) return {
+			vibrations: input.pattern,
+			preset: input
+		};
+		if (Array.isArray(input)) {
+			if (!input.length) return {
+				vibrations: [],
+				preset: null
+			};
+			if (typeof input[0] === "number") {
+				const r = [];
+				let pd = 0;
+				for (let i = 0; i < input.length; i++) if (i % 2 === 0) {
+					r.push({
+						duration: input[i],
+						...pd > 0 ? { delay: pd } : {}
+					});
+					pd = 0;
+				} else pd = input[i];
+				return {
+					vibrations: r,
+					preset: null
+				};
+			}
+			return {
+				vibrations: input,
+				preset: null
+			};
+		}
+		return {
+			vibrations: [],
+			preset: null
+		};
+	}
+	/** Android: convert Vibration[] to flat pattern and vibrate for its duration. */
+	async fireAndroid(vibs, di, ef) {
+		const pat = buildAndroidPattern(vibs, di, ef);
+		if (!pat.length) return;
+		navigator.vibrate(pat);
+		const total = pat.reduce((s, v) => s + v, 0);
+		if (total > 0) {
+			const ac = new AbortController();
+			this.activeAbort = ac;
+			await this.sleep(total, ac.signal);
+		}
+	}
+	/** iOS: fire switch-checkbox toggles with gaps between them. */
+	async fireIOS(vibs, pr, di) {
+		if (!this.iosPool) return;
+		const plan = iosPlan(vibs, pr, di);
+		if (plan.ticks <= 0) return;
+		const ac = new AbortController();
+		this.activeAbort = ac;
+		for (let i = 0; i < plan.ticks; i++) {
+			if (ac.signal.aborted) return;
+			this.iosPool.fire();
+			if (i < plan.ticks - 1) {
+				const gap = plan.gaps[i] ?? 55;
+				if (gap > 0) {
+					await this.sleep(gap, ac.signal);
+					if (ac.signal.aborted) return;
+				}
+			}
+		}
+	}
+	/** Cancellable setTimeout wrapped in a Promise. */
+	sleep(ms, signal) {
+		return new Promise((resolve) => {
+			if (signal.aborted) {
+				resolve();
+				return;
+			}
+			const t = setTimeout(resolve, ms);
+			signal.addEventListener("abort", () => {
+				clearTimeout(t);
+				resolve();
+			}, { once: true });
+		});
+	}
+};
+let _default = null;
+/** Get or create the shared default engine instance. */
+function getDefaultEngine(opts) {
+	if (!_default) _default = new HapticEngine(opts);
+	return _default;
+}
+/** Fire a one-shot haptic using the default engine. */
+async function haptic(input, options) {
+	return getDefaultEngine().trigger(input, options);
+}
+//#endregion
+export { DragHaptics, HapticEngine, easings, getDefaultEngine, haptic, presets };