npu-detect 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dylan Meza
+
+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,148 @@
+# npu-detect
+
+Cross-platform NPU (Neural Processing Unit) detection for JavaScript.
+
+Works in **Node.js** (server-side, shells out to OS tools) and **Browsers** (client-side, via the WebNN API).
+
+## Why?
+
+You can query CPU info with `os.cpus()` and GPU info with `navigator.gpu` — but there's no equivalent for NPUs. This library fills that gap.
+
+## Install
+
+```bash
+npm install npu-detect
+```
+
+## Quick Start
+
+### Node.js
+
+```js
+const { detectNPU, hasNPU, npuSummary } = require('npu-detect');
+
+// Full detection with details
+const info = await detectNPU();
+console.log(info);
+// {
+//   detected: true,
+//   platform: 'darwin',
+//   devices: [{ name: 'Apple Neural Engine (ANE)', cores: 16, ... }],
+//   cpuHeuristic: { likely: true, vendor: 'Apple', npuName: 'Apple Neural Engine' },
+//   ...
+// }
+
+// Quick boolean
+const has = await hasNPU(); // true
+
+// One-liner summary
+const summary = await npuSummary(); // "NPU detected: Apple Neural Engine (ANE)"
+```
+
+### Browser
+
+```js
+import { detectNPU, hasNPU } from 'npu-detect/browser';
+
+const info = await detectNPU({ benchmark: true });
+console.log(info);
+// {
+//   webnnSupported: true,
+//   npuAvailable: true,
+//   devices: {
+//     npu: { available: true, benchmark: { functional: true, execLatencyMs: 0.4 } },
+//     cpu: { available: true, ... },
+//     gpu: { available: true, ... },
+//   },
+//   ...
+// }
+```
+
+### CLI
+
+```bash
+npx npu-detect
+npx npu-detect --verbose
+npx npu-detect --json
+```
+
+## How It Works
+
+### Node.js Detection (per platform)
+
+| Platform | Method |
+|----------|--------|
+| **Linux** | Checks `/dev/accel/*` devices, `lspci` for NPU-class hardware, `lsmod` for `intel_vpu`/`amdxdna` kernel modules, sysfs for NPU frequency |
+| **Windows** | Queries Device Manager's "Neural processors" class via PowerShell (`Get-PnpDevice`), falls back to WMI |
+| **macOS** | Uses `ioreg` to find AppleNeuralEngine, infers ANE core count and TOPS from chip model, reads `powermetrics` for ANE power (requires root) |
+| **All** | CPU model string heuristic to identify known NPU-equipped processors (Intel Core Ultra, Snapdragon X, Ryzen AI, Apple M-series, etc.) |
+
+### Browser Detection
+
+Uses the **W3C Web Neural Network API** (`navigator.ml`):
+
+1. Checks if `navigator.ml` exists
+2. Attempts `navigator.ml.createContext({ deviceType: 'npu' })` — success means NPU is available
+3. Optionally runs a minimal add-two-matrices computation graph to verify the device is functional
+4. Also probes `cpu` and `gpu` device types for comparison
+
+> **Note:** WebNN requires Chrome/Edge with the flag `chrome://flags/#web-machine-learning-neural-network` enabled, or Edge with `--disable_webnn_for_npu=0` for NPU specifically.
+
+## Supported NPU Hardware
+
+| Vendor | NPU | Detection |
+|--------|-----|-----------|
+| **Intel** | AI Boost (Core Ultra / Meteor Lake, Arrow Lake, Lunar Lake) | Linux: `intel_vpu` module + `/dev/accel/accel0`. Windows: Device Manager. |
+| **AMD** | XDNA / XDNA2 (Ryzen AI, Hawk Point, Strix Point) | Linux: `amdxdna` module. Windows: Device Manager. |
+| **Qualcomm** | Hexagon (Snapdragon X Elite/Plus) | Windows: Device Manager. Browser: WebNN. |
+| **Apple** | Neural Engine (M1–M4, A11–A19) | macOS: `ioreg` + chip identification. |
+
+## API Reference
+
+### Node.js (`npu-detect`)
+
+#### `detectNPU(options?): Promise<NPUDetectionResult>`
+
+Full detection. Options:
+- `cpuHeuristic` (boolean, default `true`) — also check CPU model string
+- `verbose` (boolean, default `false`) — include raw OS command output
+
+#### `hasNPU(): Promise<boolean>`
+
+Quick boolean — confirmed NPU present?
+
+#### `npuSummary(): Promise<string>`
+
+Human-readable one-liner.
+
+### Browser (`npu-detect/browser`)
+
+#### `detectNPU(options?): Promise<BrowserNPUDetectionResult>`
+
+Full browser detection. Options:
+- `benchmark` (boolean, default `false`) — run a test computation on each device
+- `probeAll` (boolean, default `true`) — also probe CPU and GPU
+
+#### `hasNPU(): Promise<boolean>`
+
+Quick boolean — NPU available via WebNN?
+
+#### `probeDevice(deviceType): Promise<{available, error?, context?}>`
+
+Low-level probe for a specific WebNN device type.
+
+#### `benchmarkDevice(deviceType): Promise<{functional, buildLatencyMs?, execLatencyMs?, error?}>`
+
+Run a minimal computation on a device and measure latency.
+
+## Caveats
+
+- **Linux:** NPU detection requires the kernel module to be loaded and `/dev/accel/` to be populated. Some sysfs paths require root.
+- **Windows:** PowerShell queries may be slow (~1-2s). The "NeuralProcessor" PnP class requires up-to-date drivers.
+- **macOS:** Apple provides almost no public API for ANE introspection. Detection relies on `ioreg` and chip identification. `powermetrics` requires `sudo`.
+- **Browser:** WebNN is still an emerging standard. NPU support requires specific browser flags and up-to-date GPU/NPU drivers.
+- **CPU Heuristic:** The CPU model string check is a "best guess" — it tells you the CPU *should* have an NPU, not that it's accessible.
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * npu-detect CLI
+ * Quick way to check NPU status from the terminal.
+ *
+ * Usage:
+ *   npx npu-detect
+ *   node cli.js
+ *   node cli.js --verbose
+ *   node cli.js --json
+ */
+
+const { detectNPU, npuSummary } = require('./src/index');
+
+const args = process.argv.slice(2);
+const verbose = args.includes('--verbose') || args.includes('-v');
+const jsonOutput = args.includes('--json') || args.includes('-j');
+
+(async () => {
+  try {
+    const result = await detectNPU({ verbose, cpuHeuristic: true });
+
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    // Pretty print
+    const BOLD = '\x1b[1m';
+    const GREEN = '\x1b[32m';
+    const RED = '\x1b[31m';
+    const YELLOW = '\x1b[33m';
+    const CYAN = '\x1b[36m';
+    const DIM = '\x1b[2m';
+    const RESET = '\x1b[0m';
+
+    console.log();
+    console.log(`${BOLD}╔══════════════════════════════════════╗${RESET}`);
+    console.log(`${BOLD}║         NPU Detection Report         ║${RESET}`);
+    console.log(`${BOLD}╚══════════════════════════════════════╝${RESET}`);
+    console.log();
+
+    console.log(`  ${DIM}Platform:${RESET}  ${result.platform}`);
+    console.log(`  ${DIM}Time:${RESET}      ${result.timestamp}`);
+    console.log();
+
+    if (result.detected) {
+      console.log(`  ${GREEN}●${RESET} ${BOLD}NPU Detected${RESET}`);
+      for (const dev of result.devices) {
+        console.log(`    ${CYAN}→${RESET} ${dev.name}`);
+        if (dev.status) console.log(`      Status: ${dev.status}`);
+        if (dev.cores) console.log(`      Cores: ${dev.cores}`);
+        if (dev.estimatedTops) console.log(`      Est. TOPS: ${dev.estimatedTops}`);
+        if (dev.chip) console.log(`      Chip: ${dev.chip}`);
+        console.log(`      ${DIM}Source: ${dev.source}${RESET}`);
+      }
+    } else {
+      console.log(`  ${RED}○${RESET} ${BOLD}No NPU Detected${RESET}`);
+    }
+
+    if (result.likelyPresent) {
+      console.log();
+      console.log(`  ${YELLOW}⚠${RESET}  ${result.note}`);
+    }
+
+    if (result.cpuHeuristic) {
+      console.log();
+      console.log(`  ${DIM}CPU Model:${RESET} ${result.cpuHeuristic.cpuModel}`);
+      if (result.cpuHeuristic.likely) {
+        console.log(`  ${DIM}NPU Hint:${RESET}  ${GREEN}${result.cpuHeuristic.npuName}${RESET} (${result.cpuHeuristic.vendor})`);
+      }
+    }
+
+    if (verbose && result._raw) {
+      console.log();
+      console.log(`  ${DIM}─── Raw Data ───${RESET}`);
+      console.log(JSON.stringify(result._raw, null, 2).split('\n').map(l => `  ${DIM}${l}${RESET}`).join('\n'));
+    }
+
+    console.log();
+  } catch (err) {
+    console.error('Detection failed:', err.message);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "npu-detect",
+  "author": {
+    "name": "Dylan Meza",
+    "email": "dylanmmeza@gmail.com",
+    "url": "https://github.com/dylanmmeza"
+  },
+  "version": "1.0.0",
+  "description": "Cross-platform NPU (Neural Processing Unit) detection for JavaScript — Node.js + Browser (WebNN)",
+  "main": "src/index.js",
+  "types": "src/types.d.ts",
+  "bin": {
+    "npu-detect": "cli.js"
+  },
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "types": "./src/types.d.ts"
+    },
+    "./browser": {
+      "import": "./src/browser.js",
+      "default": "./src/browser.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/test.js",
+    "detect": "node cli.js"
+  },
+  "keywords": [
+    "npu",
+    "neural-processing-unit",
+    "ai",
+    "machine-learning",
+    "hardware-detection",
+    "webnn",
+    "apple-neural-engine",
+    "intel-ai-boost",
+    "amd-xdna",
+    "qualcomm-hexagon",
+    "system-info"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dylanmmeza/npu-detect.git"
+  },
+  "homepage": "https://github.com/dylanmmeza/npu-detect#readme",
+  "bugs": {
+    "url": "https://github.com/dylanmmeza/npu-detect/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "src/",
+    "cli.js",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/browser.js

@@ -0,0 +1,205 @@
+/**
+ * npu-detect/browser
+ * Browser-side NPU detection using the WebNN API (navigator.ml)
+ *
+ * This module runs in the browser and probes for NPU availability
+ * using the W3C Web Neural Network API.
+ *
+ * Usage:
+ *   import { detectNPU } from 'npu-detect/browser';
+ *   const info = await detectNPU();
+ */
+
+/**
+ * Probe whether a specific WebNN device type is available
+ * by attempting to create an MLContext with that device.
+ *
+ * @param {'cpu'|'gpu'|'npu'} deviceType
+ * @returns {Promise<{available: boolean, error?: string, context?: MLContext}>}
+ */
+async function probeDevice(deviceType) {
+  try {
+    const context = await navigator.ml.createContext({ deviceType });
+    return { available: true, context };
+  } catch (err) {
+    return { available: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Attempt to run a minimal computation graph on a device to verify it actually works.
+ *
+ * @param {'cpu'|'gpu'|'npu'} deviceType
+ * @returns {Promise<{functional: boolean, latencyMs?: number, error?: string}>}
+ */
+async function benchmarkDevice(deviceType) {
+  try {
+    const context = await navigator.ml.createContext({ deviceType });
+    const builder = new MLGraphBuilder(context);
+
+    const descriptor = { dataType: 'float32', shape: [2, 2] };
+    const a = builder.input('A', descriptor);
+    const b = builder.input('B', descriptor);
+    const c = builder.add(a, b);
+
+    const start = performance.now();
+    const graph = await builder.build({ C: c });
+    const buildTime = performance.now() - start;
+
+    // Create tensors and run
+    const tensorA = await context.createTensor({
+      dataType: 'float32',
+      shape: [2, 2],
+      writable: true,
+      readable: true,
+    });
+    const tensorB = await context.createTensor({
+      dataType: 'float32',
+      shape: [2, 2],
+      writable: true,
+      readable: true,
+    });
+    const tensorC = await context.createTensor({
+      dataType: 'float32',
+      shape: [2, 2],
+      readable: true,
+    });
+
+    context.writeTensor(tensorA, new Float32Array([1, 2, 3, 4]));
+    context.writeTensor(tensorB, new Float32Array([5, 6, 7, 8]));
+
+    const execStart = performance.now();
+    await context.dispatch(graph, { A: tensorA, B: tensorB }, { C: tensorC });
+    const execTime = performance.now() - execStart;
+
+    // Read result to verify correctness
+    const resultBuffer = await context.readTensor(tensorC);
+    const result = new Float32Array(resultBuffer);
+    const correct = result[0] === 6 && result[1] === 8 && result[2] === 10 && result[3] === 12;
+
+    return {
+      functional: correct,
+      buildLatencyMs: Math.round(buildTime * 100) / 100,
+      execLatencyMs: Math.round(execTime * 100) / 100,
+    };
+  } catch (err) {
+    return { functional: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Detect NPU and ML hardware acceleration in the browser.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.benchmark=false]  Run a small computation to verify each device works
+ * @param {boolean} [options.probeAll=true]    Also probe CPU and GPU devices
+ * @returns {Promise<BrowserNPUDetectionResult>}
+ */
+async function detectNPU(options = {}) {
+  const { benchmark = false, probeAll = true } = options;
+
+  const result = {
+    webnnSupported: false,
+    npuAvailable: false,
+    devices: {},
+    browser: {
+      userAgent: navigator.userAgent,
+      platform: navigator.platform,
+    },
+    timestamp: new Date().toISOString(),
+  };
+
+  // 1. Check if WebNN API exists
+  if (!('ml' in navigator)) {
+    result.note = 'WebNN API (navigator.ml) is not available in this browser. ' +
+      'Enable it in Chrome/Edge via chrome://flags/#web-machine-learning-neural-network';
+    return result;
+  }
+
+  result.webnnSupported = true;
+
+  // 2. Probe NPU
+  const npuProbe = await probeDevice('npu');
+  result.npuAvailable = npuProbe.available;
+  result.devices.npu = {
+    available: npuProbe.available,
+    error: npuProbe.error || null,
+  };
+
+  if (benchmark && npuProbe.available) {
+    result.devices.npu.benchmark = await benchmarkDevice('npu');
+  }
+
+  // 3. Optionally probe CPU and GPU
+  if (probeAll) {
+    const cpuProbe = await probeDevice('cpu');
+    result.devices.cpu = {
+      available: cpuProbe.available,
+      error: cpuProbe.error || null,
+    };
+    if (benchmark && cpuProbe.available) {
+      result.devices.cpu.benchmark = await benchmarkDevice('cpu');
+    }
+
+    const gpuProbe = await probeDevice('gpu');
+    result.devices.gpu = {
+      available: gpuProbe.available,
+      error: gpuProbe.error || null,
+    };
+    if (benchmark && gpuProbe.available) {
+      result.devices.gpu.benchmark = await benchmarkDevice('gpu');
+    }
+  }
+
+  // 4. WebGPU info for context
+  if (navigator.gpu) {
+    try {
+      const adapter = await navigator.gpu.requestAdapter();
+      if (adapter) {
+        const info = await adapter.requestAdapterInfo?.() || {};
+        result.webgpuAdapter = {
+          vendor: info.vendor || null,
+          architecture: info.architecture || null,
+          device: info.device || null,
+          description: info.description || null,
+        };
+      }
+    } catch { /* ignore */ }
+  }
+
+  // 5. CPU heuristic from User-Agent
+  const ua = navigator.userAgent;
+  if (/Snapdragon/i.test(ua)) {
+    result.cpuHint = 'Qualcomm Snapdragon (likely has Hexagon NPU)';
+  }
+
+  return result;
+}
+
+/**
+ * Quick boolean — is an NPU available via WebNN?
+ */
+async function hasNPU() {
+  if (!('ml' in navigator)) return false;
+  const probe = await probeDevice('npu');
+  return probe.available;
+}
+
+/**
+ * Get short summary string.
+ */
+async function npuSummary() {
+  const result = await detectNPU();
+  if (!result.webnnSupported) return 'WebNN not supported in this browser';
+  if (result.npuAvailable) return 'NPU available via WebNN API';
+  return 'No NPU detected (WebNN supported, but NPU device unavailable)';
+}
+
+// ESM + CJS compatible export
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { detectNPU, hasNPU, npuSummary, probeDevice, benchmarkDevice };
+} else if (typeof window !== 'undefined') {
+  window.NPUDetect = { detectNPU, hasNPU, npuSummary, probeDevice, benchmarkDevice };
+}
+
+export { detectNPU, hasNPU, npuSummary, probeDevice, benchmarkDevice };

package/src/index.js

@@ -0,0 +1,400 @@
+/**
+ * npu-detect
+ * Cross-platform NPU (Neural Processing Unit) detection library for JavaScript.
+ *
+ * Supports:
+ *   - Node.js (server-side) — shells out to OS-specific tools
+ *   - Browser (client-side) — probes WebNN API (navigator.ml)
+ *
+ * Usage (Node.js):
+ *   const { detectNPU } = require('npu-detect');
+ *   const info = await detectNPU();
+ *
+ * Usage (Browser):
+ *   import { detectNPU } from 'npu-detect/browser';
+ *   const info = await detectNPU();
+ */
+
+const os = require('os');
+const { execSync } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function exec(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function parseWindowsWmic(raw) {
+  // Parse WMIC / PowerShell CSV-ish output into objects
+  const lines = raw.split(/\r?\n/).filter(Boolean);
+  if (lines.length < 2) return [];
+  const headers = lines[0].split(/\s{2,}/).map(h => h.trim());
+  return lines.slice(1).map(line => {
+    const values = line.split(/\s{2,}/).map(v => v.trim());
+    const obj = {};
+    headers.forEach((h, i) => { obj[h] = values[i] || ''; });
+    return obj;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Platform-specific detectors
+// ---------------------------------------------------------------------------
+
+/**
+ * Linux NPU detection
+ *  - Check /dev/accel/* devices (DRM accel subsystem used by Intel VPU / AMD XDNA)
+ *  - Parse lspci for NPU-class devices
+ *  - Read sysfs for frequency info
+ *  - Check loaded kernel modules (intel_vpu, amdxdna)
+ */
+function detectLinux() {
+  const devices = [];
+
+  // 1. Check accel subsystem devices
+  const accelDevices = exec('ls /dev/accel/ 2>/dev/null');
+  const hasAccelDevices = accelDevices.length > 0;
+
+  // 2. Check for Intel VPU / NPU kernel module
+  const intelVpuLoaded = exec('lsmod 2>/dev/null | grep intel_vpu').length > 0;
+  const amdXdnaLoaded = exec('lsmod 2>/dev/null | grep amdxdna').length > 0;
+
+  // 3. lspci — look for processing accelerators (class 12xx) or known NPU vendors
+  const lspciOutput = exec('lspci -nn 2>/dev/null');
+  const npuPatterns = [
+    /neural/i,
+    /npu/i,
+    /processing accelerator/i,
+    /\[0bxx\]/i, // PCI class for processing accelerators
+    /intel.*vpu/i,
+    /intel.*ai boost/i,
+    /amd.*xdna/i,
+    /amd.*ipu/i,
+    /qualcomm.*hexagon/i,
+  ];
+
+  if (lspciOutput) {
+    for (const line of lspciOutput.split('\n')) {
+      if (npuPatterns.some(p => p.test(line))) {
+        devices.push({
+          name: line.replace(/^\S+\s+/, '').trim(),
+          source: 'lspci',
+          raw: line.trim(),
+        });
+      }
+    }
+  }
+
+  // 4. Try sysfs for Intel NPU frequency info
+  let frequencyMhz = null;
+  let maxFrequencyMhz = null;
+  if (hasAccelDevices) {
+    // Try multiple possible sysfs paths
+    const sysfsPaths = [
+      '/sys/class/accel/accel0/device/npu_current_frequency_mhz',
+      '/sys/class/accel/accel0/device/npu_max_frequency_mhz',
+    ];
+    const currentFreq = exec(`cat ${sysfsPaths[0]} 2>/dev/null`);
+    const maxFreq = exec(`cat ${sysfsPaths[1]} 2>/dev/null`);
+    if (currentFreq) frequencyMhz = parseInt(currentFreq, 10);
+    if (maxFreq) maxFrequencyMhz = parseInt(maxFreq, 10);
+  }
+
+  // 5. Check for intel_vpu module info
+  let driverVersion = null;
+  if (intelVpuLoaded) {
+    driverVersion = exec('modinfo intel_vpu 2>/dev/null | grep "^version:" | awk \'{print $2}\'') || null;
+    if (!devices.length) {
+      const desc = exec('modinfo intel_vpu 2>/dev/null | grep "^description:" | sed "s/description:\\s*//"') || 'Intel NPU (VPU)';
+      devices.push({ name: desc, source: 'kernel-module' });
+    }
+  }
+
+  if (amdXdnaLoaded && !devices.length) {
+    const desc = exec('modinfo amdxdna 2>/dev/null | grep "^description:" | sed "s/description:\\s*//"') || 'AMD XDNA NPU';
+    devices.push({ name: desc, source: 'kernel-module' });
+  }
+
+  // 6. Check dmesg for NPU init messages (may require root)
+  const dmesgNpu = exec('dmesg 2>/dev/null | grep -iE "(intel_vpu|amdxdna|npu|neural)" | tail -5');
+
+  const detected = devices.length > 0 || hasAccelDevices || intelVpuLoaded || amdXdnaLoaded;
+
+  return {
+    detected,
+    platform: 'linux',
+    devices,
+    accelDevices: hasAccelDevices ? accelDevices.split(/\s+/).filter(Boolean) : [],
+    kernelModules: {
+      intel_vpu: intelVpuLoaded,
+      amdxdna: amdXdnaLoaded,
+    },
+    driverVersion,
+    frequency: frequencyMhz ? {
+      currentMhz: frequencyMhz,
+      maxMhz: maxFrequencyMhz,
+    } : null,
+    dmesgHints: dmesgNpu ? dmesgNpu.split('\n').filter(Boolean) : [],
+  };
+}
+
+/**
+ * Windows NPU detection
+ *  - Query Device Manager "Neural processors" class via PowerShell
+ *  - Check for DirectML NPU support
+ */
+function detectWindows() {
+  const devices = [];
+
+  // 1. PowerShell: query PnP devices in "Neural processors" class
+  const psCmd = `powershell -NoProfile -Command "Get-PnpDevice -Class 'NeuralProcessor' -ErrorAction SilentlyContinue | Select-Object -Property FriendlyName, Status, InstanceId | ConvertTo-Json"`;
+  const psOutput = exec(psCmd);
+
+  if (psOutput) {
+    try {
+      let parsed = JSON.parse(psOutput);
+      if (!Array.isArray(parsed)) parsed = [parsed];
+      for (const dev of parsed) {
+        devices.push({
+          name: dev.FriendlyName || 'Unknown NPU',
+          status: dev.Status || 'Unknown',
+          instanceId: dev.InstanceId || null,
+          source: 'pnp-device',
+        });
+      }
+    } catch { /* JSON parse failed, try alternate approach */ }
+  }
+
+  // 2. Fallback: try WMI query for processing accelerators
+  if (!devices.length) {
+    const wmiCmd = `powershell -NoProfile -Command "Get-WmiObject Win32_PnPEntity | Where-Object { $_.PNPClass -eq 'NeuralProcessor' -or $_.Name -match 'NPU|Neural|AI Boost' } | Select-Object Name, Status, DeviceID | ConvertTo-Json"`;
+    const wmiOutput = exec(wmiCmd);
+    if (wmiOutput) {
+      try {
+        let parsed = JSON.parse(wmiOutput);
+        if (!Array.isArray(parsed)) parsed = [parsed];
+        for (const dev of parsed) {
+          devices.push({
+            name: dev.Name || 'Unknown NPU',
+            status: dev.Status || 'Unknown',
+            deviceId: dev.DeviceID || null,
+            source: 'wmi',
+          });
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  // 3. Check CPU model for known NPU-equipped processors
+  const cpuModel = os.cpus()[0]?.model || '';
+  const hasNpuCpu = /core\s*(?:\(TM\)\s*)?ultra|snapdragon\s*x|ryzen\s*(ai|8040|9)/i.test(cpuModel);
+
+  return {
+    detected: devices.length > 0,
+    platform: 'windows',
+    devices,
+    cpuModel,
+    cpuHasKnownNPU: hasNpuCpu,
+    note: devices.length === 0 && hasNpuCpu
+      ? 'CPU model suggests NPU may be present but was not found in Device Manager. Driver may need to be installed or updated.'
+      : undefined,
+  };
+}
+
+/**
+ * macOS NPU detection
+ *  - Check for Apple Neural Engine via ioreg / system_profiler
+ *  - Detect Apple Silicon chip model
+ *  - Check ANE power via powermetrics (requires root)
+ */
+function detectMacOS() {
+  const devices = [];
+
+  // 1. Determine chip type
+  const cpuBrand = exec('sysctl -n machdep.cpu.brand_string 2>/dev/null') || os.cpus()[0]?.model || '';
+  const arch = os.arch(); // 'arm64' for Apple Silicon
+
+  const isAppleSilicon = arch === 'arm64';
+
+  // 2. ioreg: search for ANE (AppleNeuralEngine or similar)
+  const ioregANE = exec('ioreg -r -c AppleNeuralEngine 2>/dev/null | head -20');
+  const hasANE = ioregANE.includes('AppleNeuralEngine') || ioregANE.includes('ANE');
+
+  // 3. Check for H13ANEIn (ANE interface class)
+  const ioregH13 = exec('ioreg -l 2>/dev/null | grep -i "ANE\\|NeuralEngine" | head -10');
+
+  if (hasANE || isAppleSilicon) {
+    // Determine ANE core count from chip model
+    let aneCores = null;
+    if (/M[1-4]/.test(cpuBrand) || /A1[4-9]/.test(cpuBrand)) {
+      aneCores = 16; // M1+ and A14+ all have 16-core ANE
+    }
+    if (/M[1-4]\s*Ultra/.test(cpuBrand)) {
+      aneCores = 32; // Ultra doubles via UltraFusion
+    }
+    if (/A1[1-3]/.test(cpuBrand)) {
+      // A11 = 2 cores, A12/A13 = 8 cores
+      if (/A11/.test(cpuBrand)) aneCores = 2;
+      else aneCores = 8;
+    }
+
+    // Estimate TOPS from known data
+    let estimatedTops = null;
+    if (/M4/.test(cpuBrand)) estimatedTops = 38;
+    else if (/M3/.test(cpuBrand)) estimatedTops = 18;
+    else if (/M2/.test(cpuBrand)) estimatedTops = 15.8;
+    else if (/M1/.test(cpuBrand)) estimatedTops = 11;
+    if (/Ultra/.test(cpuBrand) && estimatedTops) estimatedTops *= 2;
+
+    devices.push({
+      name: 'Apple Neural Engine (ANE)',
+      chip: cpuBrand,
+      cores: aneCores,
+      estimatedTops: estimatedTops,
+      source: hasANE ? 'ioreg' : 'cpu-inference',
+    });
+  }
+
+  // 4. powermetrics ANE power (requires root, likely fails without sudo)
+  const anePower = exec('sudo powermetrics --samplers ane_energy -n 1 -i 100 2>/dev/null | grep -i "ane"');
+
+  return {
+    detected: devices.length > 0,
+    platform: 'darwin',
+    devices,
+    isAppleSilicon,
+    cpuModel: cpuBrand,
+    anePower: anePower || null,
+    note: !isAppleSilicon
+      ? 'Intel Macs do not have an Apple Neural Engine.'
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Unified CPU heuristic (cross-platform fallback)
+// ---------------------------------------------------------------------------
+
+function cpuNPUHeuristic() {
+  const cpuModel = os.cpus()[0]?.model || '';
+
+  const knownNPUCPUs = [
+    { pattern: /Core\s*(?:\(TM\)\s*)?Ultra/i, vendor: 'Intel', npuName: 'Intel AI Boost' },
+    { pattern: /Snapdragon\s*X/i, vendor: 'Qualcomm', npuName: 'Qualcomm Hexagon NPU' },
+    { pattern: /Snapdragon\s*8\s*Gen\s*[3-9]/i, vendor: 'Qualcomm', npuName: 'Qualcomm Hexagon NPU' },
+    { pattern: /Ryzen\s*AI/i, vendor: 'AMD', npuName: 'AMD XDNA NPU' },
+    { pattern: /Ryzen\s*[79]\s*8[0-9]{3}/i, vendor: 'AMD', npuName: 'AMD XDNA NPU (Hawk Point)' },
+    { pattern: /Ryzen\s*AI\s*9/i, vendor: 'AMD', npuName: 'AMD XDNA2 NPU (Strix Point)' },
+    { pattern: /Apple\s*M[1-9]/i, vendor: 'Apple', npuName: 'Apple Neural Engine' },
+    { pattern: /A1[4-9]\s*Bionic/i, vendor: 'Apple', npuName: 'Apple Neural Engine' },
+  ];
+
+  for (const { pattern, vendor, npuName } of knownNPUCPUs) {
+    if (pattern.test(cpuModel)) {
+      return { likely: true, vendor, npuName, cpuModel };
+    }
+  }
+
+  return { likely: false, cpuModel };
+}
+
+// ---------------------------------------------------------------------------
+// Main detection function
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect NPU presence and return information.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.cpuHeuristic=true]  Also check CPU model for known NPU-equipped processors
+ * @param {boolean} [options.verbose=false]       Include raw diagnostic data
+ * @returns {Promise<NPUDetectionResult>}
+ */
+async function detectNPU(options = {}) {
+  const { cpuHeuristic: useCpuHeuristic = true, verbose = false } = options;
+
+  const platform = os.platform();
+  let platformResult;
+
+  switch (platform) {
+    case 'linux':
+      platformResult = detectLinux();
+      break;
+    case 'win32':
+      platformResult = detectWindows();
+      break;
+    case 'darwin':
+      platformResult = detectMacOS();
+      break;
+    default:
+      platformResult = {
+        detected: false,
+        platform,
+        devices: [],
+        note: `Platform "${platform}" is not yet supported for NPU detection.`,
+      };
+  }
+
+  const heuristic = useCpuHeuristic ? cpuNPUHeuristic() : null;
+
+  const result = {
+    detected: platformResult.detected,
+    platform: platformResult.platform,
+    devices: platformResult.devices,
+    cpuHeuristic: heuristic,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (verbose) {
+    result._raw = platformResult;
+  }
+
+  // If platform detection failed but CPU heuristic says likely, note it
+  if (!result.detected && heuristic?.likely) {
+    result.detected = false; // Keep false — not confirmed
+    result.likelyPresent = true;
+    result.note = `NPU not confirmed by OS, but CPU model (${heuristic.cpuModel}) is known to include ${heuristic.npuName}. Driver may not be installed.`;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience helpers
+// ---------------------------------------------------------------------------
+
+/** Quick boolean check — does this system have an NPU? */
+async function hasNPU() {
+  const result = await detectNPU({ cpuHeuristic: false });
+  return result.detected;
+}
+
+/** Get a short summary string */
+async function npuSummary() {
+  const result = await detectNPU();
+  if (result.detected && result.devices.length > 0) {
+    const names = result.devices.map(d => d.name).join(', ');
+    return `NPU detected: ${names}`;
+  }
+  if (result.likelyPresent) {
+    return `NPU likely present (${result.cpuHeuristic.npuName}) but not confirmed by OS`;
+  }
+  return 'No NPU detected';
+}
+
+module.exports = {
+  detectNPU,
+  hasNPU,
+  npuSummary,
+  // Expose internals for advanced use
+  _detectLinux: detectLinux,
+  _detectWindows: detectWindows,
+  _detectMacOS: detectMacOS,
+  _cpuNPUHeuristic: cpuNPUHeuristic,
+};

package/src/types.d.ts

@@ -0,0 +1,97 @@
+// Type definitions for npu-detect
+
+export interface NPUDevice {
+  name: string;
+  source: string;
+  status?: string;
+  instanceId?: string;
+  deviceId?: string;
+  raw?: string;
+  chip?: string;
+  cores?: number | null;
+  estimatedTops?: number | null;
+}
+
+export interface CPUHeuristic {
+  likely: boolean;
+  vendor?: string;
+  npuName?: string;
+  cpuModel: string;
+}
+
+export interface FrequencyInfo {
+  currentMhz: number;
+  maxMhz: number | null;
+}
+
+export interface NPUDetectionResult {
+  detected: boolean;
+  platform: string;
+  devices: NPUDevice[];
+  cpuHeuristic: CPUHeuristic | null;
+  timestamp: string;
+  likelyPresent?: boolean;
+  note?: string;
+  _raw?: any;
+}
+
+export interface DetectOptions {
+  /** Also check CPU model for known NPU-equipped processors (default: true) */
+  cpuHeuristic?: boolean;
+  /** Include raw diagnostic data (default: false) */
+  verbose?: boolean;
+}
+
+/** Detect NPU presence and return detailed information (Node.js) */
+export function detectNPU(options?: DetectOptions): Promise<NPUDetectionResult>;
+
+/** Quick boolean check — does this system have an NPU? */
+export function hasNPU(): Promise<boolean>;
+
+/** Get a short human-readable summary string */
+export function npuSummary(): Promise<string>;
+
+// Browser module types
+
+export interface DeviceBenchmark {
+  functional: boolean;
+  buildLatencyMs?: number;
+  execLatencyMs?: number;
+  error?: string;
+}
+
+export interface BrowserDeviceInfo {
+  available: boolean;
+  error: string | null;
+  benchmark?: DeviceBenchmark;
+}
+
+export interface BrowserNPUDetectionResult {
+  webnnSupported: boolean;
+  npuAvailable: boolean;
+  devices: {
+    npu?: BrowserDeviceInfo;
+    cpu?: BrowserDeviceInfo;
+    gpu?: BrowserDeviceInfo;
+  };
+  browser: {
+    userAgent: string;
+    platform: string;
+  };
+  webgpuAdapter?: {
+    vendor: string | null;
+    architecture: string | null;
+    device: string | null;
+    description: string | null;
+  };
+  cpuHint?: string;
+  timestamp: string;
+  note?: string;
+}
+
+export interface BrowserDetectOptions {
+  /** Run a small computation to verify each device (default: false) */
+  benchmark?: boolean;
+  /** Also probe CPU and GPU devices (default: true) */
+  probeAll?: boolean;
+}