@memoryprocess/bindings 0.0.3-beta.2 → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 JoShMiQueL
+
+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,47 @@
+# @memoryprocess/bindings
+
+The raw N-API native layer of the [memoryprocess](https://github.com/memoryprocess/memoryprocess) toolkit: the `.node` binary plus a typed TypeScript interface over the stateless process-memory functions (open/close, read/write, VirtualQueryEx walk, pattern scan, thread ops, hooks primitives).
+
+Most consumers want [`@memoryprocess/core`](https://www.npmjs.com/package/@memoryprocess/core) instead -- it wraps this layer in the `Process` class with typed reads/writes, CE-style scanning, and remote structs.
+
+## Install
+
+```bash
+npm install @memoryprocess/bindings
+```
+
+Windows only (`"os": ["win32"]`), Node >= 22. Prebuilt binaries ship under `prebuilds/` for the CI-covered Node majors via `node-gyp-build`.
+
+## Usage
+
+```ts
+import { native } from '@memoryprocess/bindings';
+
+const { handle, pid } = native.openProcess('notepad.exe');
+try {
+  const mods = native.getModules(handle, pid);
+  const buf = native.readBuffer(handle, Number(mods[0].base), 16);
+} finally {
+  native.closeHandle(handle);
+}
+```
+
+Every function is stateless: it takes a `handle`/`pid`/`tid` argument and holds no shared native state. The full function surface is declared in `src/native.ts` (`Native` interface).
+
+## Binary resolution
+
+At load time the addon resolves in order:
+
+1. `dist/memoryprocess.node` (bundled in the published tarball)
+2. `prebuilds/<platform>-<arch>/memoryprocess.node` via `node-gyp-build`
+3. `build/Release/memoryprocess.node` (local `node-gyp` build)
+
+Future Node majors not covered by the shipped prebuilds will need a local `node-gyp rebuild` (`binding.gyp` + `native/` sources are included in the tarball), or wait for a new release.
+
+## Part of
+
+[`memoryprocess`](https://github.com/memoryprocess/memoryprocess) -- a Windows process-memory toolkit (`@memoryprocess/{bindings,core,cli,mcp}`), a ground-up rewrite of `memoryjs`.
+
+## License
+
+MIT

package/native/module.cc

@@ -21,6 +21,14 @@ static const double MAX_READ_BYTES = 512.0 * 1024.0 * 1024.0;
 // silently round. Harmless today (canonical user-space VA < 2^48, real HANDLE
 // values are small) but don't feed pointers >2^53 through these bindings.
 
+// Converts a JS number|bigint to u64. Numbers are truncated via the double -
+// callers document the >2^53 rounding caveat (see header note above).
+static bool JsToU64(const Napi::Value& v, std::uint64_t& out) {
+  if (v.IsBigInt()) { bool ls; out = v.As<Napi::BigInt>().Uint64Value(&ls); return true; }
+  if (v.IsNumber()) { out = static_cast<std::uint64_t>(v.As<Napi::Number>().DoubleValue()); return true; }
+  return false;
+}
+
 static bool CheckSize(Napi::Env env, double size) {
   if (!std::isfinite(size) || size < 0 || size > MAX_READ_BYTES) {
     Napi::RangeError::New(env, "size must be a finite number between 0 and 512MB")
@@ -133,7 +141,9 @@ Napi::Value GetRegionsSync(const Napi::CallbackInfo& info) {
 
 Napi::Value ReadBufferSync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,address,size)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 3 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,size:number)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   double sizeD = info[2].As<Napi::Number>().DoubleValue();
@@ -153,7 +163,9 @@ Napi::Value ReadBufferSync(const Napi::CallbackInfo& info) {
 
 Napi::Value WriteBufferSync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,address,buffer)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 3 || !info[0].IsNumber() || !info[1].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,buffer:Buffer)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   if (!info[2].IsBuffer()) { Napi::TypeError::New(env, "value must be a Buffer").ThrowAsJavaScriptException(); return env.Null(); }
@@ -169,7 +181,9 @@ Napi::Value WriteBufferSync(const Napi::CallbackInfo& info) {
 // trampoline stubs within rel32 range (+/-2GB) of a hook site.
 Napi::Value AllocMemorySync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,size,protection[,nearAddress])").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 3 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,size:number,protection:number[,nearAddress:number])").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto size = static_cast<SIZE_T>(info[1].As<Napi::Number>().DoubleValue());
   DWORD prot = info[2].As<Napi::Number>().Uint32Value();
@@ -183,7 +197,9 @@ Napi::Value AllocMemorySync(const Napi::CallbackInfo& info) {
 
 Napi::Value FreeMemorySync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 2) { Napi::TypeError::New(env, "expected (handle,address)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   return Napi::Boolean::New(env, VirtualFreeEx(h, reinterpret_cast<LPVOID>(addr), 0, MEM_RELEASE) != 0);
@@ -191,7 +207,10 @@ Napi::Value FreeMemorySync(const Napi::CallbackInfo& info) {
 
 Napi::Value ProtectMemorySync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,address,size,prot)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 4 || !info[0].IsNumber() || !info[1].IsNumber() ||
+      !info[2].IsNumber() || !info[3].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,size:number,prot:number)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   auto size = static_cast<SIZE_T>(info[2].As<Napi::Number>().DoubleValue());
@@ -267,7 +286,9 @@ Napi::Value ResumeThreadSync(const Napi::CallbackInfo& info) {
 // "int32","uint32","int64","uint64","float","double","pointer"
 Napi::Value ReadValueSync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,address,type)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 3 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsString()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,type:string)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   std::string type = info[2].As<Napi::String>().Utf8Value();
@@ -292,19 +313,39 @@ Napi::Value ReadValueSync(const Napi::CallbackInfo& info) {
 
 Napi::Value WriteValueSync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 4) { Napi::TypeError::New(env, "expected (handle,address,type,value)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 4 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsString()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,type:string,value:number|bigint)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   std::string type = info[2].As<Napi::String>().Utf8Value();
+  // `value` must match the type family: number for int32/uint32/float/double;
+  // number|bigint for int64/uint64/pointer (converted via JsToU64 - the TS
+  // signature declares `number|bigint`). The old As<BigInt>() on a Number was
+  // an unchecked static_cast: Int64Value() failed, the out-param stayed
+  // uninitialized and WriteProcessMemory wrote stack garbage. No C++
+  // exception is thrown under NAPI_DISABLE_CPP_EXCEPTIONS, so catch(...)
+  // could not save it - validate BEFORE converting.
+  const bool is64 = (type == "int64" || type == "uint64" || type == "pointer");
+  const bool is32 = (type == "int32" || type == "uint32" || type == "float" || type == "double");
+  if (is32 && !info[3].IsNumber()) {
+    Napi::TypeError::New(env, "value must be a number for type " + type).ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::uint64_t u64 = 0;
+  if (is64 && !JsToU64(info[3], u64)) {
+    Napi::TypeError::New(env, "value must be number|bigint for type " + type).ThrowAsJavaScriptException();
+    return env.Null();
+  }
   bool ok = false;
   try {
     if (type == "int32") ok = WriteValue<std::int32_t>(h, addr, info[3].As<Napi::Number>().Int32Value());
     else if (type == "uint32") ok = WriteValue<std::uint32_t>(h, addr, info[3].As<Napi::Number>().Uint32Value());
     else if (type == "float") ok = WriteValue<float>(h, addr, info[3].As<Napi::Number>().FloatValue());
     else if (type == "double") ok = WriteValue<double>(h, addr, info[3].As<Napi::Number>().DoubleValue());
-    else if (type == "int64") { bool ls; ok = WriteValue<std::int64_t>(h, addr, info[3].As<Napi::BigInt>().Int64Value(&ls)); }
-    else if (type == "uint64") { bool ls; ok = WriteValue<std::uint64_t>(h, addr, info[3].As<Napi::BigInt>().Uint64Value(&ls)); }
-    else if (type == "pointer") { bool ls; ok = WriteValue<std::uintptr_t>(h, addr, static_cast<std::uintptr_t>(info[3].As<Napi::BigInt>().Uint64Value(&ls))); }
+    else if (type == "int64") ok = WriteValue<std::int64_t>(h, addr, static_cast<std::int64_t>(u64));
+    else if (type == "uint64") ok = WriteValue<std::uint64_t>(h, addr, u64);
+    else if (type == "pointer") ok = WriteValue<std::uintptr_t>(h, addr, static_cast<std::uintptr_t>(u64));
     else { Napi::TypeError::New(env, "unknown type " + type).ThrowAsJavaScriptException(); return env.Null(); }
     return Napi::Boolean::New(env, ok);
   } catch (...) {
@@ -322,7 +363,9 @@ Napi::Value WriteValueSync(const Napi::CallbackInfo& info) {
 // gaps/unreadable spans. Only throws if the handle is invalid for VirtualQueryEx.
 Napi::Value ReadSafeSync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,address,size)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 3 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,size:number)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   double sizeD = info[2].As<Napi::Number>().DoubleValue();
@@ -374,7 +417,9 @@ Napi::Value ReadSafeSync(const Napi::CallbackInfo& info) {
 // flushInstructions(handle, address, size) -> boolean  (FlushInstructionCache)
 Napi::Value FlushInstructionsSync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  if (info.Length() < 3) { Napi::TypeError::New(env, "expected (handle,address,size)").ThrowAsJavaScriptException(); return env.Null(); }
+  if (info.Length() < 3 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsNumber()) {
+    Napi::TypeError::New(env, "expected (handle:number,address:number,size:number)").ThrowAsJavaScriptException(); return env.Null();
+  }
   HANDLE h = reinterpret_cast<HANDLE>(static_cast<std::uintptr_t>(info[0].As<Napi::Number>().DoubleValue()));
   auto addr = static_cast<std::uintptr_t>(info[1].As<Napi::Number>().DoubleValue());
   auto size = static_cast<SIZE_T>(info[2].As<Napi::Number>().DoubleValue());
@@ -744,12 +789,6 @@ Napi::Value GetThreadContextSync(const Napi::CallbackInfo& info) {
   return o;
 }
 
-static bool JsToU64(const Napi::Value& v, std::uint64_t& out) {
-  if (v.IsBigInt()) { bool ls; out = v.As<Napi::BigInt>().Uint64Value(&ls); return true; }
-  if (v.IsNumber()) { out = static_cast<std::uint64_t>(v.As<Napi::Number>().DoubleValue()); return true; }
-  return false;
-}
-
 // setThreadContext(tid, { rip?, rsp?, rbp?, dr0?..dr3?, dr6?, dr7?, eflags? }) -> boolean
 // Reads the current context, patches provided fields, writes it back.
 Napi::Value SetThreadContextSync(const Napi::CallbackInfo& info) {

package/native/pattern.cc

@@ -219,8 +219,8 @@ private:
 Napi::Value ScanAsync(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   // scan(pid, pattern[, {start,end,onlyReadable}]) -> Promise<bigint[]>
-  if (info.Length() < 2) {
-    Napi::TypeError::New(env, "expected (pid, pattern[, opts])").ThrowAsJavaScriptException();
+  if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsString()) {
+    Napi::TypeError::New(env, "expected (pid:number, pattern:string[, opts])").ThrowAsJavaScriptException();
     return env.Null();
   }
   DWORD pid = info[0].As<Napi::Number>().Uint32Value();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryprocess/bindings",
-  "version": "0.0.3-beta.2",
+  "version": "0.1.0-beta.0",
   "description": "Native N-API bindings for Windows process memory access (read/write, VirtualQueryEx, pattern scan, thread ops). The .node binary layer of the memoryprocess toolkit.",
   "type": "module",
   "packageManager": "bun@1.4.4",
@@ -16,9 +16,12 @@
   },
   "files": [
     "dist",
+    "src",
     "prebuilds",
     "binding.gyp",
-    "native"
+    "native",
+    "LICENSE",
+    "README.md"
   ],
   "os": [
     "win32"
@@ -31,8 +34,10 @@
     "clean": "node scripts/clean.mjs",
     "check": "bun check",
     "typecheck": "tsc --noEmit",
-    "prebuild:all": "prebuildify --napi -t 22.17.0 -t 24.4.0 -t 25.0.0 -t 26.0.0",
-    "prepublishOnly": "npm run build && npm run prebuild:all"
+    "prebuild:all": "prebuildify --napi -t 22.17.0 -t 24.4.0 -t 25.0.0 -t 26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @memoryprocess/bindings -- the native N-API layer.
+ * Exposes the raw `.node` module plus its TypeScript interface.
+ * Most consumers want `@memoryprocess/core` (the Process class) instead.
+ */
+export * from './native.js';

package/src/native.ts

@@ -0,0 +1,209 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const __dir = dirname(fileURLToPath(import.meta.url));
+
+interface Native {
+  openProcess(
+    nameOrPid: string | number,
+    access?: number,
+  ): { handle: number; pid: number };
+  closeHandle(handle: number): boolean;
+  listProcesses(): { pid: number; name: string }[];
+  getModules(
+    handle: number,
+    pid: number,
+  ): { base: number; size: number; path: string }[];
+  getRegions(
+    handle: number,
+  ): { baseAddress: number; size: number; protection: number; type: number }[];
+  readValue(handle: number, address: number, type: string): number | bigint;
+  writeValue(
+    handle: number,
+    address: number,
+    type: string,
+    value: number | bigint,
+  ): boolean;
+  readBuffer(handle: number, address: number, size: number): Buffer;
+  writeBuffer(handle: number, address: number, data: Buffer): boolean;
+  scan(
+    pid: number,
+    pattern: string,
+    opts?: { start?: number; end?: number; onlyReadable?: boolean },
+  ): Promise<bigint[]>;
+  scanValue(
+    pid: number,
+    needle: Uint8Array,
+    opts?: {
+      start?: number;
+      end?: number;
+      onlyWritable?: boolean;
+      alignment?: number;
+    },
+  ): Promise<bigint[]>;
+  allocMemory(
+    handle: number,
+    size: number,
+    protection: number,
+    nearAddress?: number,
+  ): bigint;
+  freeMemory(handle: number, address: number): boolean;
+  protectMemory(
+    handle: number,
+    address: number,
+    size: number,
+    protection: number,
+  ): number;
+  isWow64(handle: number): boolean;
+  listThreads(pid: number): number[];
+  suspendThread(tid: number): boolean;
+  resumeThread(tid: number): boolean;
+  readSafe(handle: number, address: number, size: number): Buffer;
+  flushInstructions(handle: number, address: number, size: number): boolean;
+  injectDll(pid: number, dllPath: string, timeoutMs?: number): boolean;
+  ejectDll(pid: number, moduleBase: number): boolean;
+  queryAddress(
+    handle: number,
+    address: number,
+  ): {
+    baseAddress: number;
+    allocationBase: number;
+    size: number;
+    protection: number;
+    state: number;
+    type: number;
+  } | null;
+  getThreadContext(tid: number): {
+    rip: bigint;
+    rsp: bigint;
+    rbp: bigint;
+    dr0: bigint;
+    dr1: bigint;
+    dr2: bigint;
+    dr3: bigint;
+    dr6: bigint;
+    dr7: bigint;
+    eflags: bigint;
+  } | null;
+  setThreadContext(
+    tid: number,
+    ctx: Partial<
+      Record<
+        | 'rip'
+        | 'rsp'
+        | 'rbp'
+        | 'dr0'
+        | 'dr1'
+        | 'dr2'
+        | 'dr3'
+        | 'dr6'
+        | 'dr7'
+        | 'eflags',
+        number | bigint
+      >
+    >,
+  ): boolean;
+  callRemote(
+    pid: number,
+    fnAddress: number | bigint,
+    param: number | bigint,
+    timeoutMs?: number,
+  ): number | null;
+  disasmInstructions(
+    handle: number,
+    address: number,
+    count: number,
+  ): { offset: number; length: number; relative: boolean }[];
+  /**
+   * Walk instructions at `address` until `minBytes` are covered, then
+   * RELOCATE position-relative operands (rel32 branch/call immediates,
+   * RIP-relative disp32) so the stolen bytes are correct when executed from
+   * `stubAddr` (must be within rel32 range of `address`). External rel8/16
+   * branches (incl. LOOP/JECXZ) can't be widened -- refused `HOOK_RELOCATE`,
+   * like MinHook; rel8/16 internal (target inside the stolen window) and
+   * all non-relative instructions copy verbatim. Without `stubAddr` any
+   * position-relative instruction is refused (inspection mode).
+   * Throws `HOOK_STEAL`/`HOOK_RELOCATE` -- returns the relocated bytes.
+   */
+  hookSteal(
+    handle: number,
+    address: number,
+    minBytesOrOpts?: number | { minBytes?: number; stubAddr?: number | bigint },
+    stubAddr?: number | bigint,
+  ): { length: number; bytes: Buffer; original: Buffer };
+  /**
+   * Per-region VirtualProtectEx->write->restore across the whole write span --
+   * records each region's real old protection before writing, restores each
+   * individually. `restored=false` means part of the span is left weakened.
+   */
+  writeProtectedMemory(
+    handle: number,
+    address: number,
+    buffer: Buffer,
+    protection?: number,
+  ): { ok: boolean; restored: boolean; protected: boolean };
+  /** Current thread id (TID) -- used to refuse self-suspend. */
+  currentThreadId(): number;
+  suspendProcess(pid: number): boolean;
+  resumeProcess(pid: number): boolean;
+  enableDebugPrivilege(): boolean;
+  waitForExit(pid: number, timeoutMs?: number): Promise<number | null>;
+  findWhatWrites(
+    pid: number,
+    address: number | bigint,
+    size: number,
+    timeoutMs: number,
+    maxHits: number,
+  ): Promise<
+    {
+      rip: bigint;
+      tid: number;
+      threadContext: {
+        rip: bigint;
+        rsp: bigint;
+        rbp: bigint;
+        dr0: bigint;
+        dr1: bigint;
+        dr2: bigint;
+        dr3: bigint;
+        dr6: bigint;
+        dr7: bigint;
+        eflags: bigint;
+      };
+    }[]
+  >;
+}
+
+// Resolution order: dist/memoryprocess.node (built/packaged) -> prebuilds via
+// node-gyp-build -> build/Release/memoryprocess.node (dev). Works whether this
+// file is loaded from src/ (bun test) or bundled into dist/index.js.
+const candidates = [
+  join(__dir, 'memoryprocess.node'), // dist/ or src/ (copied for tests)
+  join(__dir, '..', 'dist', 'memoryprocess.node'), // src/ -> dist/
+  join(__dir, '..', 'build', 'Release', 'memoryprocess.node'), // src/ -> build/
+];
+
+export const native: Native = (() => {
+  // Keep the last real load error: a .node that EXISTS but fails to load
+  // (missing VC++ CRT, arch or N-API mismatch, wrong Node ABI) must not be
+  // reported as "not found" -- surface the underlying loader message.
+  let lastErr: unknown;
+  for (const path of candidates) {
+    try {
+      return require(path) as Native;
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  try {
+    return require('node-gyp-build')(join(__dir, '..')) as Native;
+  } catch (e) {
+    lastErr = lastErr ?? e;
+  }
+  const detail = lastErr instanceof Error ? `: ${lastErr.message}` : '';
+  throw new Error(
+    `memoryprocess native addon failed to load (run \`bun run build\`)${detail}`,
+  );
+})();