macslap 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,247 @@
+# macslap
+
+> Run any function when your MacBook gets slapped. 🖐️💻
+
+A Node.js package that reads the Apple Silicon accelerometer (Bosch BMI286 IMU) via IOKit HID to detect physical taps, slaps, and hits on your MacBook. Register any callback — deploy code, trigger webhooks, control music, or whatever you want.
+
+## Requirements
+
+- Apple Silicon MacBook (M1 Pro, M2, M3, M4+)
+- macOS 14+ (Sonoma)
+- Node.js 16+
+- **Must run with `sudo`** (IOKit HID requires root)
+
+Check if your Mac supports it:
+
+```bash
+ioreg -l -w0 | grep -A5 AppleSPUHIDDevice
+```
+
+## Install
+
+```bash
+npm install macslap
+```
+
+## Quick Start
+
+```js
+const { onSlap } = require('macslap');
+
+onSlap((event) => {
+  console.log(`Slapped! Force: ${event.force.toFixed(3)}g`);
+  console.log(`Type: ${event.type}`); // "tap", "slap", "hit", or "punch"
+});
+```
+
+```bash
+sudo node my-script.js
+```
+
+## API
+
+### Simple API
+
+```js
+const { onSlap, onTap, onHit, onPunch, onForce, isSupported } = require('macslap');
+
+// Any impact
+onSlap((event) => { /* ... */ });
+
+// Gentle taps only (< 0.15g)
+onTap((event) => { /* ... */ });
+
+// Hard hits (0.5 - 1.0g)
+onHit((event) => { /* ... */ });
+
+// Very hard impacts (> 1.0g)
+onPunch((event) => { /* ... */ });
+
+// Custom force range
+onForce(0.1, 0.3, (event) => { /* ... */ });
+
+// Check hardware support
+if (isSupported()) { /* good to go */ }
+```
+
+All functions return an **unsubscribe** function:
+
+```js
+const unsub = onSlap((event) => { /* ... */ });
+// Later:
+unsub(); // stop listening
+```
+
+### Options
+
+```js
+onSlap(callback, {
+  cooldown: 750,    // ms between events (default: 750)
+  threshold: 0.05,  // min force in g to trigger (default: 0.05)
+});
+```
+
+### Event Object
+
+```js
+{
+  x: -0.012,        // X-axis acceleration in g
+  y: 0.003,         // Y-axis acceleration in g
+  z: -1.024,        // Z-axis acceleration in g
+  force: 0.234,     // magnitude of impact in g
+  type: "slap",     // "tap" | "slap" | "hit" | "punch"
+  timestamp: 1711500000000
+}
+```
+
+### Force Classification
+
+| Type | Force Range | Description |
+|------|-------------|-------------|
+| `tap` | < 0.15g | Gentle touch, light tap |
+| `slap` | 0.15 - 0.5g | Normal slap |
+| `hit` | 0.5 - 1.0g | Hard hit |
+| `punch` | > 1.0g | Full send |
+
+### Advanced API: SlapDetector
+
+For more control, use the `SlapDetector` class directly:
+
+```js
+const { SlapDetector } = require('macslap');
+
+const detector = new SlapDetector({
+  threshold: 0.02,  // ultra sensitive
+  cooldown: 300,
+});
+
+// Event emitter pattern
+detector.on('slap', (event) => { /* any impact */ });
+detector.on('tap', (event) => { /* gentle */ });
+detector.on('hit', (event) => { /* hard */ });
+detector.on('ready', () => console.log('Listening...'));
+
+// Conditional handlers
+detector.when('punch', (event) => {
+  console.log('That was violent');
+});
+
+// Custom conditions
+detector.when(
+  (event) => event.force > 0.3 && event.x > 0,
+  (event) => console.log('Slapped from the right!')
+);
+
+// Read raw values
+const reading = detector.read();
+// { x, y, z, running, calibrated }
+
+detector.start();
+
+// Later:
+detector.stop();
+```
+
+## Examples
+
+### Deploy on Slap
+
+```js
+const { onSlap } = require('macslap');
+const { exec } = require('child_process');
+
+onSlap((event) => {
+  console.log('🚀 SHIPPING IT');
+  exec('git push origin main');
+});
+```
+
+### Webhook Trigger
+
+```js
+const { onSlap } = require('macslap');
+
+onSlap(async (event) => {
+  await fetch('https://your-webhook.com', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      event: 'slapped',
+      force: event.force,
+      timestamp: new Date().toISOString(),
+    }),
+  });
+});
+```
+
+### Tamper Detection
+
+```js
+const { SlapDetector } = require('macslap');
+
+const detector = new SlapDetector({
+  threshold: 0.02, // ultra sensitive
+  cooldown: 2000,
+});
+
+detector.on('slap', (event) => {
+  console.log('🚨 SOMEONE TOUCHED YOUR LAPTOP');
+  // Take photo, send notification, sound alarm, etc.
+});
+
+detector.start();
+```
+
+### Music Control with Tap Patterns
+
+```js
+const { SlapDetector } = require('macslap');
+const { exec } = require('child_process');
+
+const detector = new SlapDetector({ threshold: 0.03, cooldown: 300 });
+let taps = [], timer;
+
+detector.on('slap', () => {
+  taps.push(Date.now());
+  clearTimeout(timer);
+  timer = setTimeout(() => {
+    const count = taps.length;
+    taps = [];
+    if (count === 1) exec(`osascript -e 'tell app "Spotify" to playpause'`);
+    if (count === 2) exec(`osascript -e 'tell app "Spotify" to next track'`);
+    if (count === 3) exec(`osascript -e 'tell app "Spotify" to previous track'`);
+  }, 500);
+});
+
+detector.start();
+```
+
+## How It Works
+
+The package uses a native C++ addon (compiled via `node-gyp`) that:
+
+1. Opens the `AppleSPUHIDDevice` in the IOKit registry (vendor usage page `0xFF00`, usage `3`)
+2. Registers an async HID input report callback at ~100Hz
+3. Parses 22-byte reports: X/Y/Z as int32 LE at byte offsets 6, 10, 14 (divided by 65536 for g values)
+4. Computes a rolling baseline and detects deviations (slaps)
+5. Fires events back to JavaScript via N-API thread-safe functions
+
+## Troubleshooting
+
+**"Accelerometer not found"**
+- Run with `sudo`: `sudo node script.js`
+- Check hardware: `ioreg -l -w0 | grep AppleSPUHIDDevice`
+- M1 (base) may not work — M1 Pro, M2+ confirmed
+
+**"Failed to load native module"**
+- Make sure Xcode Command Line Tools are installed: `xcode-select --install`
+- Rebuild: `npm rebuild`
+- Check Node.js version: needs 16+
+
+**Triggers during typing**
+- Increase threshold: `{ threshold: 0.1 }` or higher
+- Increase cooldown: `{ cooldown: 1500 }`
+
+## License
+
+MIT

package/binding.gyp

@@ -0,0 +1,32 @@
+{
+  "targets": [
+    {
+      "target_name": "macslap_native",
+      "sources": ["src/accelerometer.mm"],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
+      "conditions": [
+        [
+          "OS=='mac'",
+          {
+            "xcode_settings": {
+              "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+              "CLANG_CXX_LIBRARY": "libc++",
+              "MACOSX_DEPLOYMENT_TARGET": "14.0",
+              "OTHER_CFLAGS": ["-ObjC++"]
+            },
+            "link_settings": {
+              "libraries": [
+                "-framework IOKit",
+                "-framework CoreFoundation",
+                "-framework Foundation"
+              ]
+            }
+          }
+        ]
+      ]
+    }
+  ]
+}

package/examples/basic.js

@@ -0,0 +1,37 @@
+/**
+ * Basic macslap example
+ *
+ * Run with: sudo node examples/basic.js
+ */
+
+const { onSlap, onTap, onHit, onPunch, isSupported } = require("../lib");
+
+// Check hardware first
+if (!isSupported()) {
+  console.error("❌ Apple Silicon accelerometer not found.");
+  console.error("   Requirements: M1 Pro or M2+ MacBook, macOS 14+, sudo");
+  process.exit(1);
+}
+
+console.log("🖐️  macslap is listening... Give your MacBook a slap!\n");
+console.log("   Tap    = gentle touch (< 0.15g)");
+console.log("   Slap   = normal slap  (0.15 - 0.5g)");
+console.log("   Hit    = hard hit     (0.5 - 1.0g)");
+console.log("   Punch  = full send    (> 1.0g)");
+console.log("\n   Press Ctrl+C to stop.\n");
+
+// Listen for all events
+onSlap((event) => {
+  const emoji = {
+    tap: "👆",
+    slap: "🖐️",
+    hit: "👊",
+    punch: "💥",
+  };
+
+  console.log(
+    `${emoji[event.type] || "❓"} ${event.type.toUpperCase()} ` +
+      `| force: ${event.force.toFixed(3)}g ` +
+      `| x: ${event.x.toFixed(3)} y: ${event.y.toFixed(3)} z: ${event.z.toFixed(3)}`
+  );
+});

package/examples/deploy-slap.js

@@ -0,0 +1,44 @@
+/**
+ * Deploy on Slap - Push code by slapping your MacBook
+ *
+ * Run with: sudo node examples/deploy-slap.js
+ */
+
+const { onSlap, onHit, isSupported } = require("../lib");
+const { exec } = require("child_process");
+
+if (!isSupported()) {
+  console.error("❌ Accelerometer not found. Need M1 Pro+ MacBook with sudo.");
+  process.exit(1);
+}
+
+console.log("🚀 Deploy-on-Slap is armed!\n");
+console.log("   Slap  → git push origin main");
+console.log("   Hit   → git push origin main --force");
+console.log("\n   Press Ctrl+C to disarm.\n");
+
+let deploying = false;
+
+onSlap((event) => {
+  if (deploying) {
+    console.log("⏳ Already deploying, chill...");
+    return;
+  }
+
+  const force = event.type === "hit" || event.type === "punch";
+  const cmd = force
+    ? "git push origin main --force"
+    : "git push origin main";
+
+  console.log(`\n🖐️  SLAP DETECTED (${event.force.toFixed(3)}g) → ${cmd}`);
+  deploying = true;
+
+  exec(cmd, (error, stdout, stderr) => {
+    deploying = false;
+    if (error) {
+      console.log(`❌ Deploy failed: ${stderr || error.message}`);
+    } else {
+      console.log(`✅ Deployed! ${stdout}`);
+    }
+  });
+});

package/examples/music-control.js

@@ -0,0 +1,82 @@
+/**
+ * Music Controller - Control Spotify/Apple Music with slap gestures
+ *
+ * Run with: sudo node examples/music-control.js
+ */
+
+const { SlapDetector, isSupported } = require("../lib");
+const { exec } = require("child_process");
+
+if (!isSupported()) {
+  console.error("❌ Accelerometer not found.");
+  process.exit(1);
+}
+
+// AppleScript commands for media control
+const media = {
+  playPause: `osascript -e 'tell application "System Events" to key code 49 using {}'`,
+  // Use media keys
+  toggle: `osascript -e 'tell application "Spotify" to playpause'`,
+  next: `osascript -e 'tell application "Spotify" to next track'`,
+  prev: `osascript -e 'tell application "Spotify" to previous track'`,
+  volUp: `osascript -e 'set volume output volume ((output volume of (get volume settings)) + 10)'`,
+  volDown: `osascript -e 'set volume output volume ((output volume of (get volume settings)) - 10)'`,
+};
+
+const detector = new SlapDetector({
+  threshold: 0.03,
+  cooldown: 300, // Short cooldown to detect patterns
+});
+
+let tapTimes = [];
+let patternTimer = null;
+
+function executePattern(count) {
+  switch (count) {
+    case 1:
+      console.log("⏯️  Single tap → Play/Pause");
+      exec(media.toggle);
+      break;
+    case 2:
+      console.log("⏭️  Double tap → Next Track");
+      exec(media.next);
+      break;
+    case 3:
+      console.log("⏮️  Triple tap → Previous Track");
+      exec(media.prev);
+      break;
+    default:
+      console.log(`🔢 ${count} taps — no action mapped`);
+  }
+}
+
+detector.on("slap", (event) => {
+  tapTimes.push(Date.now());
+
+  // Clear previous timer
+  if (patternTimer) clearTimeout(patternTimer);
+
+  // Wait 500ms after last tap to evaluate the pattern
+  patternTimer = setTimeout(() => {
+    const count = tapTimes.length;
+    tapTimes = [];
+    executePattern(count);
+  }, 500);
+});
+
+// Hard hits for volume
+detector.when("hit", (event) => {
+  console.log("🔊 Hard hit → Volume Up");
+  exec(media.volUp);
+});
+
+detector.on("ready", () => {
+  console.log("🎵 Music Controller is active!\n");
+  console.log("   1 tap  → Play/Pause");
+  console.log("   2 taps → Next Track");
+  console.log("   3 taps → Previous Track");
+  console.log("   Hard hit → Volume Up");
+  console.log("\n   (Uses Spotify — edit the script for Apple Music)\n");
+});
+
+detector.start();

package/examples/tamper-detect.js

@@ -0,0 +1,49 @@
+/**
+ * Tamper Detection - Alert when someone touches your MacBook
+ *
+ * Run with: sudo node examples/tamper-detect.js
+ */
+
+const { SlapDetector, isSupported } = require("../lib");
+
+if (!isSupported()) {
+  console.error("❌ Accelerometer not found.");
+  process.exit(1);
+}
+
+const detector = new SlapDetector({
+  threshold: 0.02, // Very sensitive - detect even light touches
+  cooldown: 2000,  // 2s between alerts
+});
+
+let slapCount = 0;
+const startTime = Date.now();
+
+detector.on("slap", (event) => {
+  slapCount++;
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(0);
+
+  console.log(
+    `\n🚨 TAMPER DETECTED #${slapCount} ` +
+      `[${elapsed}s since armed] ` +
+      `force: ${event.force.toFixed(4)}g`
+  );
+
+  // You could add here:
+  // - Take a webcam photo with `imagesnap`
+  // - Send a push notification
+  // - Play an alarm sound
+  // - Send a webhook to your phone
+  // - Log to a file
+
+  console.log("   → Add your alert logic here (webhook, photo, alarm, etc.)");
+});
+
+detector.on("ready", () => {
+  console.log("🔒 Tamper detection ARMED\n");
+  console.log("   Sensitivity: ultra (0.02g threshold)");
+  console.log("   Any touch, bump, or movement will trigger an alert.");
+  console.log("\n   Press Ctrl+C to disarm.\n");
+});
+
+detector.start();

package/examples/webhook.js

@@ -0,0 +1,44 @@
+/**
+ * Webhook on Slap - Send HTTP requests when your MacBook gets slapped
+ *
+ * Run with: sudo node examples/webhook.js
+ */
+
+const { onSlap, isSupported } = require("../lib");
+
+if (!isSupported()) {
+  console.error("❌ Accelerometer not found.");
+  process.exit(1);
+}
+
+// Configure your webhook URL
+const WEBHOOK_URL =
+  process.env.WEBHOOK_URL || "https://httpbin.org/post";
+
+console.log("🌐 Webhook-on-Slap is active!\n");
+console.log(`   Target: ${WEBHOOK_URL}`);
+console.log("   Every slap sends a POST request.\n");
+
+onSlap(async (event) => {
+  const payload = {
+    event: "macbook_slapped",
+    force: event.force,
+    type: event.type,
+    acceleration: { x: event.x, y: event.y, z: event.z },
+    timestamp: new Date().toISOString(),
+    machine: require("os").hostname(),
+  };
+
+  console.log(`🖐️  ${event.type.toUpperCase()} (${event.force.toFixed(3)}g) → POST ${WEBHOOK_URL}`);
+
+  try {
+    const res = await fetch(WEBHOOK_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    console.log(`   ✅ ${res.status} ${res.statusText}`);
+  } catch (err) {
+    console.log(`   ❌ Failed: ${err.message}`);
+  }
+});

package/lib/index.d.ts

@@ -0,0 +1,99 @@
+declare module "macslap" {
+  import { EventEmitter } from "events";
+
+  /** Accelerometer event data */
+  interface SlapEvent {
+    /** X-axis acceleration in g */
+    x: number;
+    /** Y-axis acceleration in g */
+    y: number;
+    /** Z-axis acceleration in g */
+    z: number;
+    /** Magnitude of force (deviation from baseline) in g */
+    force: number;
+    /** Event classification */
+    type: "tap" | "slap" | "hit" | "punch";
+    /** Unix timestamp in ms */
+    timestamp: number;
+  }
+
+  /** Raw accelerometer reading */
+  interface AccelReading {
+    x: number;
+    y: number;
+    z: number;
+    running: boolean;
+    calibrated: boolean;
+  }
+
+  /** Options for slap detection */
+  interface SlapOptions {
+    /** Cooldown between events in ms (default: 750) */
+    cooldown?: number;
+    /** Minimum force threshold in g (default: 0.05) */
+    threshold?: number;
+  }
+
+  /** Callback for slap events */
+  type SlapCallback = (event: SlapEvent) => void;
+
+  /** Unsubscribe function */
+  type Unsubscribe = () => void;
+
+  // ---- Simple API ----
+
+  /** Listen for any slap/tap/hit event */
+  export function onSlap(callback: SlapCallback, options?: SlapOptions): Unsubscribe;
+
+  /** Listen for gentle taps (force < 0.15g) */
+  export function onTap(callback: SlapCallback, options?: SlapOptions): Unsubscribe;
+
+  /** Listen for hard hits (force 0.5-1.0g) */
+  export function onHit(callback: SlapCallback, options?: SlapOptions): Unsubscribe;
+
+  /** Listen for very hard impacts (force > 1.0g) */
+  export function onPunch(callback: SlapCallback, options?: SlapOptions): Unsubscribe;
+
+  /** Listen for a custom force range */
+  export function onForce(
+    min: number,
+    max: number,
+    callback: SlapCallback,
+    options?: SlapOptions
+  ): Unsubscribe;
+
+  /** Check if the Apple Silicon accelerometer is available */
+  export function isSupported(): boolean;
+
+  // ---- Advanced API ----
+
+  export class SlapDetector extends EventEmitter {
+    constructor(options?: SlapOptions);
+
+    /** Start listening for slaps */
+    start(): this;
+
+    /** Stop listening */
+    stop(): this;
+
+    /** Read current raw accelerometer values */
+    read(): AccelReading;
+
+    /** Register handler for a named intensity or custom condition */
+    when(
+      condition: "tap" | "slap" | "hit" | "punch" | ((event: SlapEvent) => boolean),
+      callback: SlapCallback
+    ): Unsubscribe;
+
+    /** Check hardware support */
+    static isSupported(): boolean;
+
+    on(event: "slap", listener: SlapCallback): this;
+    on(event: "tap", listener: SlapCallback): this;
+    on(event: "hit", listener: SlapCallback): this;
+    on(event: "punch", listener: SlapCallback): this;
+    on(event: "ready", listener: () => void): this;
+    on(event: "stop", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+  }
+}

package/lib/index.js

@@ -0,0 +1,287 @@
+/**
+ * macslap - Detect physical slaps on Apple Silicon MacBooks
+ *
+ * Run any function when your MacBook gets slapped.
+ *
+ * Usage:
+ *   const { onSlap, onTap, onHit } = require('macslap');
+ *
+ *   onSlap((event) => {
+ *     console.log(`Slapped with force: ${event.force}`);
+ *   });
+ */
+
+const EventEmitter = require("events");
+const path = require("path");
+
+let native;
+try {
+  native = require("../build/Release/macslap_native.node");
+} catch (e) {
+  try {
+    native = require("../build/Debug/macslap_native.node");
+  } catch (e2) {
+    throw new Error(
+      "macslap: Failed to load native module. " +
+        "Make sure you're on an Apple Silicon Mac (M1+) and ran npm install.\n" +
+        "This package requires macOS 14+ and must be run with sudo.\n" +
+        `Original error: ${e.message}`
+    );
+  }
+}
+
+// ============================================================
+// SlapDetector - Core class
+// ============================================================
+
+class SlapDetector extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this._running = false;
+    this._cooldown = options.cooldown ?? 750; // ms between events
+    this._threshold = options.threshold ?? 0.05; // min force in g
+    this._lastEventTime = 0;
+    this._handlers = new Map(); // force-range -> [callbacks]
+  }
+
+  /**
+   * Start listening for slaps
+   */
+  start() {
+    if (this._running) return this;
+
+    if (!SlapDetector.isSupported()) {
+      throw new Error(
+        "macslap: Apple Silicon accelerometer not found.\n" +
+          "Requirements:\n" +
+          "  - Apple Silicon Mac (M1 Pro or M2+)\n" +
+          "  - macOS 14+ (Sonoma)\n" +
+          "  - Run with sudo\n" +
+          "Check with: ioreg -l -w0 | grep -A5 AppleSPUHIDDevice"
+      );
+    }
+
+    this._running = true;
+
+    native.start(
+      (event) => {
+        const now = Date.now();
+        if (now - this._lastEventTime < this._cooldown) return;
+        this._lastEventTime = now;
+
+        // Classify the event
+        const classified = this._classify(event);
+
+        // Emit typed events
+        this.emit("slap", classified);
+        this.emit(classified.type, classified);
+
+        // Fire registered handlers
+        this._fireHandlers(classified);
+      },
+      { threshold: this._threshold }
+    );
+
+    this.emit("ready");
+    return this;
+  }
+
+  /**
+   * Stop listening
+   */
+  stop() {
+    if (!this._running) return this;
+    native.stop();
+    this._running = false;
+    this.emit("stop");
+    return this;
+  }
+
+  /**
+   * Read current accelerometer values
+   */
+  read() {
+    return native.read();
+  }
+
+  /**
+   * Register a handler for a specific force range
+   */
+  when(condition, callback) {
+    if (typeof condition === "function") {
+      // Custom condition function
+      const id = Symbol("handler");
+      this._handlers.set(id, { condition, callback });
+      return () => this._handlers.delete(id);
+    }
+
+    if (typeof condition === "string") {
+      // Named intensity: "tap", "slap", "punch"
+      const ranges = {
+        tap: [0, 0.15],
+        slap: [0.15, 0.5],
+        hit: [0.5, 1.0],
+        punch: [1.0, Infinity],
+      };
+      const range = ranges[condition];
+      if (!range)
+        throw new Error(`Unknown intensity: ${condition}. Use: tap, slap, hit, punch`);
+
+      const id = Symbol("handler");
+      this._handlers.set(id, {
+        condition: (evt) => evt.force >= range[0] && evt.force < range[1],
+        callback,
+      });
+      return () => this._handlers.delete(id);
+    }
+
+    throw new Error("condition must be a string or function");
+  }
+
+  /**
+   * Classify event by force
+   */
+  _classify(event) {
+    let type;
+    if (event.force < 0.15) type = "tap";
+    else if (event.force < 0.5) type = "slap";
+    else if (event.force < 1.0) type = "hit";
+    else type = "punch";
+
+    return {
+      ...event,
+      type,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Fire matching handlers
+   */
+  _fireHandlers(event) {
+    for (const [, handler] of this._handlers) {
+      try {
+        if (handler.condition(event)) {
+          handler.callback(event);
+        }
+      } catch (err) {
+        this.emit("error", err);
+      }
+    }
+  }
+
+  /**
+   * Check if hardware is supported
+   */
+  static isSupported() {
+    try {
+      return native.isSupported();
+    } catch {
+      return false;
+    }
+  }
+}
+
+// ============================================================
+// Convenience functions (the simple API)
+// ============================================================
+
+// Shared singleton detector
+let _sharedDetector = null;
+
+function getShared(options = {}) {
+  if (!_sharedDetector) {
+    _sharedDetector = new SlapDetector(options);
+    _sharedDetector.start();
+
+    // Clean up on process exit
+    const cleanup = () => {
+      if (_sharedDetector) {
+        _sharedDetector.stop();
+        _sharedDetector = null;
+      }
+    };
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => {
+      cleanup();
+      process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+      cleanup();
+      process.exit(0);
+    });
+  }
+  return _sharedDetector;
+}
+
+/**
+ * onSlap(callback, options?) - Run a function when the MacBook is slapped
+ *
+ * @param {Function} callback - Called with { x, y, z, force, type, timestamp }
+ * @param {Object} options - { cooldown, threshold }
+ * @returns {Function} unsubscribe function
+ */
+function onSlap(callback, options = {}) {
+  const detector = getShared(options);
+  detector.on("slap", callback);
+  return () => detector.off("slap", callback);
+}
+
+/**
+ * onTap(callback, options?) - Run a function on gentle taps (force < 0.15g)
+ */
+function onTap(callback, options = {}) {
+  const detector = getShared(options);
+  detector.on("tap", callback);
+  return () => detector.off("tap", callback);
+}
+
+/**
+ * onHit(callback, options?) - Run a function on hard hits (force > 0.5g)
+ */
+function onHit(callback, options = {}) {
+  const detector = getShared(options);
+  detector.on("hit", callback);
+  return () => detector.off("hit", callback);
+}
+
+/**
+ * onPunch(callback, options?) - Run a function on very hard impacts (force > 1.0g)
+ */
+function onPunch(callback, options = {}) {
+  const detector = getShared(options);
+  detector.on("punch", callback);
+  return () => detector.off("punch", callback);
+}
+
+/**
+ * onForce(min, max, callback, options?) - Run a function for a custom force range
+ */
+function onForce(min, max, callback, options = {}) {
+  const detector = getShared(options);
+  return detector.when((evt) => evt.force >= min && evt.force < max, callback);
+}
+
+/**
+ * isSupported() - Check if hardware is available
+ */
+function isSupported() {
+  return SlapDetector.isSupported();
+}
+
+// ============================================================
+// Exports
+// ============================================================
+
+module.exports = {
+  // Simple API
+  onSlap,
+  onTap,
+  onHit,
+  onPunch,
+  onForce,
+  isSupported,
+
+  // Advanced API
+  SlapDetector,
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "macslap",
+  "version": "1.0.0",
+  "description": "Detect physical slaps/taps on Apple Silicon MacBooks via the accelerometer. Run any function on slap.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "install": "node-gyp rebuild",
+    "build": "node-gyp rebuild",
+    "test": "node examples/basic.js"
+  },
+  "keywords": [
+    "macbook",
+    "slap",
+    "accelerometer",
+    "apple-silicon",
+    "iokit",
+    "hid",
+    "gesture",
+    "tap",
+    "motion",
+    "sensor",
+    "m1",
+    "m2",
+    "m3",
+    "m4",
+    "macos"
+  ],
+  "author": "",
+  "license": "MIT",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "node-addon-api": "^7.1.0",
+    "node-gyp": "^10.0.0"
+  },
+  "gypfile": true,
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/src/accelerometer.mm

@@ -0,0 +1,365 @@
+/**
+ * macslap - Native accelerometer bindings for Apple Silicon MacBooks
+ *
+ * Reads the Bosch BMI286 IMU via IOKit HID (AppleSPUHIDDevice).
+ * The sensor lives at vendor usage page 0xFF00, usage 3.
+ * Data arrives as 22-byte HID reports at ~100Hz.
+ * X/Y/Z are int32 LE at byte offsets 6, 10, 14. Divide by 65536 for g.
+ *
+ * Requires sudo for IOKit HID access.
+ */
+
+#include <napi.h>
+#include <IOKit/hid/IOHIDManager.h>
+#include <IOKit/hid/IOHIDDevice.h>
+#include <CoreFoundation/CoreFoundation.h>
+#include <cmath>
+#include <mutex>
+#include <atomic>
+#include <thread>
+#include <functional>
+
+// Sensor constants
+static const uint32_t kVendorUsagePage = 0xFF00;
+static const uint32_t kAccelUsage = 3;
+static const size_t kReportSize = 22;
+static const double kScaleFactor = 65536.0;
+
+// State
+static IOHIDDeviceRef g_device = nullptr;
+static CFRunLoopRef g_runLoop = nullptr;
+static std::thread g_sensorThread;
+static std::atomic<bool> g_running{false};
+static uint8_t g_reportBuffer[kReportSize];
+
+// Callback data
+static Napi::ThreadSafeFunction g_tsfn;
+static std::mutex g_mutex;
+
+// Last known acceleration
+static std::atomic<double> g_lastX{0.0};
+static std::atomic<double> g_lastY{0.0};
+static std::atomic<double> g_lastZ{0.0};
+
+// Vibration detection state
+static double g_baselineX = 0.0;
+static double g_baselineY = 0.0;
+static double g_baselineZ = 0.0;
+static bool g_baselineSet = false;
+static int g_calibrationSamples = 0;
+static const int kCalibrationCount = 50; // ~0.5s at 100Hz
+static double g_sumX = 0.0, g_sumY = 0.0, g_sumZ = 0.0;
+
+struct SlapEvent {
+  double x, y, z;
+  double force; // magnitude of deviation from baseline
+  double timestamp;
+};
+
+/**
+ * HID input report callback - fires at ~100Hz
+ */
+static void hidReportCallback(
+    void *context,
+    IOReturn result,
+    void *sender,
+    IOHIDReportType type,
+    uint32_t reportID,
+    uint8_t *report,
+    CFIndex reportLength) {
+
+  if (reportLength < (CFIndex)kReportSize) return;
+
+  // Parse x/y/z from report (int32 LE at offsets 6, 10, 14)
+  int32_t rawX, rawY, rawZ;
+  memcpy(&rawX, report + 6, 4);
+  memcpy(&rawY, report + 10, 4);
+  memcpy(&rawZ, report + 14, 4);
+
+  double x = (double)rawX / kScaleFactor;
+  double y = (double)rawY / kScaleFactor;
+  double z = (double)rawZ / kScaleFactor;
+
+  g_lastX.store(x);
+  g_lastY.store(y);
+  g_lastZ.store(z);
+
+  // Calibration phase: build baseline from first N samples
+  if (!g_baselineSet) {
+    g_sumX += x;
+    g_sumY += y;
+    g_sumZ += z;
+    g_calibrationSamples++;
+    if (g_calibrationSamples >= kCalibrationCount) {
+      g_baselineX = g_sumX / kCalibrationCount;
+      g_baselineY = g_sumY / kCalibrationCount;
+      g_baselineZ = g_sumZ / kCalibrationCount;
+      g_baselineSet = true;
+    }
+    return;
+  }
+
+  // Compute deviation from baseline
+  double dx = x - g_baselineX;
+  double dy = y - g_baselineY;
+  double dz = z - g_baselineZ;
+  double force = sqrt(dx * dx + dy * dy + dz * dz);
+
+  // Get threshold from context (default 0.05g)
+  double threshold = 0.05;
+  if (context) {
+    threshold = *(double *)context;
+  }
+
+  if (force > threshold) {
+    // Fire the JS callback
+    auto event = new SlapEvent{x, y, z, force,
+        (double)clock() / CLOCKS_PER_SEC};
+
+    g_tsfn.NonBlockingCall(event,
+        [](Napi::Env env, Napi::Function jsCallback, SlapEvent *evt) {
+          Napi::Object obj = Napi::Object::New(env);
+          obj.Set("x", Napi::Number::New(env, evt->x));
+          obj.Set("y", Napi::Number::New(env, evt->y));
+          obj.Set("z", Napi::Number::New(env, evt->z));
+          obj.Set("force", Napi::Number::New(env, evt->force));
+          obj.Set("timestamp", Napi::Number::New(env, evt->timestamp));
+          jsCallback.Call({obj});
+          delete evt;
+        });
+
+    // Update baseline slowly (adaptive)
+    g_baselineX = g_baselineX * 0.99 + x * 0.01;
+    g_baselineY = g_baselineY * 0.99 + y * 0.01;
+    g_baselineZ = g_baselineZ * 0.99 + z * 0.01;
+  } else {
+    // Update baseline faster when quiet
+    g_baselineX = g_baselineX * 0.95 + x * 0.05;
+    g_baselineY = g_baselineY * 0.95 + y * 0.05;
+    g_baselineZ = g_baselineZ * 0.95 + z * 0.05;
+  }
+}
+
+/**
+ * Find and open the AppleSPUHIDDevice accelerometer
+ */
+static IOHIDDeviceRef findAccelerometer() {
+  IOHIDManagerRef manager = IOHIDManagerCreate(
+      kCFAllocatorDefault, kIOHIDOptionsTypeNone);
+  if (!manager) return nullptr;
+
+  // Match on vendor usage page 0xFF00, usage 3 (accelerometer)
+  CFMutableDictionaryRef matching = CFDictionaryCreateMutable(
+      kCFAllocatorDefault, 0,
+      &kCFTypeDictionaryKeyCallBacks,
+      &kCFTypeDictionaryValueCallBacks);
+
+  int usagePage = kVendorUsagePage;
+  int usage = kAccelUsage;
+  CFNumberRef cfUsagePage = CFNumberCreate(
+      kCFAllocatorDefault, kCFNumberIntType, &usagePage);
+  CFNumberRef cfUsage = CFNumberCreate(
+      kCFAllocatorDefault, kCFNumberIntType, &usage);
+
+  CFDictionarySetValue(matching,
+      CFSTR(kIOHIDDeviceUsagePageKey), cfUsagePage);
+  CFDictionarySetValue(matching,
+      CFSTR(kIOHIDDeviceUsageKey), cfUsage);
+
+  IOHIDManagerSetDeviceMatching(manager, matching);
+  IOHIDManagerScheduleWithRunLoop(
+      manager, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode);
+  IOHIDManagerOpen(manager, kIOHIDOptionsTypeNone);
+
+  CFSetRef deviceSet = IOHIDManagerCopyDevices(manager);
+  IOHIDDeviceRef device = nullptr;
+
+  if (deviceSet) {
+    CFIndex count = CFSetGetCount(deviceSet);
+    if (count > 0) {
+      IOHIDDeviceRef *devices = new IOHIDDeviceRef[count];
+      CFSetGetValues(deviceSet, (const void **)devices);
+      device = devices[0];
+      CFRetain(device);
+      delete[] devices;
+    }
+    CFRelease(deviceSet);
+  }
+
+  CFRelease(cfUsagePage);
+  CFRelease(cfUsage);
+  CFRelease(matching);
+  // Don't release manager — we need it alive for the run loop
+
+  return device;
+}
+
+/**
+ * Sensor reading thread
+ */
+static void sensorThreadFunc(double threshold) {
+  g_device = findAccelerometer();
+  if (!g_device) {
+    // Signal error back to JS
+    g_running.store(false);
+    return;
+  }
+
+  // Open the device
+  IOReturn ret = IOHIDDeviceOpen(g_device, kIOHIDOptionsTypeNone);
+  if (ret != kIOReturnSuccess) {
+    CFRelease(g_device);
+    g_device = nullptr;
+    g_running.store(false);
+    return;
+  }
+
+  // Store threshold for callback
+  static double storedThreshold;
+  storedThreshold = threshold;
+
+  // Register input report callback
+  IOHIDDeviceRegisterInputReportCallback(
+      g_device,
+      g_reportBuffer,
+      kReportSize,
+      hidReportCallback,
+      &storedThreshold);
+
+  // Schedule with run loop
+  IOHIDDeviceScheduleWithRunLoop(
+      g_device, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode);
+
+  g_runLoop = CFRunLoopGetCurrent();
+
+  // Run until stopped
+  while (g_running.load()) {
+    CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.1, false);
+  }
+
+  // Cleanup
+  IOHIDDeviceClose(g_device, kIOHIDOptionsTypeNone);
+  CFRelease(g_device);
+  g_device = nullptr;
+  g_runLoop = nullptr;
+}
+
+// ============================================================
+// N-API exports
+// ============================================================
+
+/**
+ * start(callback, options?) - Begin listening for slaps
+ *
+ * Options:
+ *   threshold: number (default 0.05) - minimum force in g to trigger
+ */
+Napi::Value Start(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (g_running.load()) {
+    Napi::Error::New(env, "macslap is already running. Call stop() first.")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  if (info.Length() < 1 || !info[0].IsFunction()) {
+    Napi::TypeError::New(env, "Expected a callback function as first argument")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  double threshold = 0.05;
+  if (info.Length() > 1 && info[1].IsObject()) {
+    Napi::Object opts = info[1].As<Napi::Object>();
+    if (opts.Has("threshold")) {
+      threshold = opts.Get("threshold").As<Napi::Number>().DoubleValue();
+    }
+  }
+
+  // Reset calibration
+  g_baselineSet = false;
+  g_calibrationSamples = 0;
+  g_sumX = g_sumY = g_sumZ = 0.0;
+
+  // Create thread-safe function for calling JS from sensor thread
+  g_tsfn = Napi::ThreadSafeFunction::New(
+      env,
+      info[0].As<Napi::Function>(),
+      "macslap_callback",
+      0,   // unlimited queue
+      1);  // 1 thread
+
+  g_running.store(true);
+  g_sensorThread = std::thread(sensorThreadFunc, threshold);
+
+  return env.Undefined();
+}
+
+/**
+ * stop() - Stop listening for slaps
+ */
+Napi::Value Stop(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (!g_running.load()) {
+    return env.Undefined();
+  }
+
+  g_running.store(false);
+
+  // Stop the run loop
+  if (g_runLoop) {
+    CFRunLoopStop(g_runLoop);
+  }
+
+  if (g_sensorThread.joinable()) {
+    g_sensorThread.join();
+  }
+
+  g_tsfn.Release();
+
+  return env.Undefined();
+}
+
+/**
+ * read() - Get current accelerometer values (one-shot)
+ */
+Napi::Value Read(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  Napi::Object obj = Napi::Object::New(env);
+  obj.Set("x", Napi::Number::New(env, g_lastX.load()));
+  obj.Set("y", Napi::Number::New(env, g_lastY.load()));
+  obj.Set("z", Napi::Number::New(env, g_lastZ.load()));
+  obj.Set("running", Napi::Boolean::New(env, g_running.load()));
+  obj.Set("calibrated", Napi::Boolean::New(env, g_baselineSet));
+
+  return obj;
+}
+
+/**
+ * isSupported() - Check if the accelerometer is available
+ */
+Napi::Value IsSupported(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  IOHIDDeviceRef device = findAccelerometer();
+  bool supported = (device != nullptr);
+  if (device) CFRelease(device);
+
+  return Napi::Boolean::New(env, supported);
+}
+
+/**
+ * Module init
+ */
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("start", Napi::Function::New(env, Start));
+  exports.Set("stop", Napi::Function::New(env, Stop));
+  exports.Set("read", Napi::Function::New(env, Read));
+  exports.Set("isSupported", Napi::Function::New(env, IsSupported));
+  return exports;
+}
+
+NODE_API_MODULE(macslap_native, Init)