feat: injectee

Author: std-microblock

.github/workflows/build.yml

@@ -3,6 +3,7 @@ name: Build & Test
 on:
   push:
     branches: [main, master]
+    tags: ['v*']
   pull_request:
     branches: [main, master]
 
@@ -14,19 +15,24 @@ jobs:
         include:
           - os: macos-latest
             arch: arm64
-            name: macOS ARM64
+            name: macos-arm64
           - os: macos-15-intel
             arch: x64
-            name: macOS x64
+            name: macos-x64
           - os: ubuntu-24.04
             arch: x64
-            name: Linux x64
+            name: linux-x64
           - os: ubuntu-24.04-arm
             arch: arm64
-            name: Linux ARM64
+            name: linux-arm64
           - os: windows-latest
             arch: x64
-            name: Windows x64
+            name: windows-x64
+          # Android cross-compile on Linux x64
+          - os: ubuntu-24.04
+            arch: arm64
+            name: android-arm64
+            android: true
 
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.name }}
@@ -40,25 +46,29 @@ jobs:
           xmake-version: 3.0.7
 
       - name: Setup pnpm
+        if: ${{ !matrix.android }}
         uses: pnpm/action-setup@v4
         with:
           version: 10
 
       - name: Setup Node.js
+        if: ${{ !matrix.android }}
         uses: actions/setup-node@v4
         with:
           node-version: 22
 
       - name: Install TS dependencies
+        if: ${{ !matrix.android }}
         working-directory: src/core/typescript
         run: pnpm install
 
       - name: Build TypeScript
+        if: ${{ !matrix.android }}
         working-directory: src/core/typescript
         run: pnpm build
 
-      - name: Install GCC 15 (Linux)
-        if: runner.os == 'Linux'
+      - name: Install GCC 15 (Linux native)
+        if: runner.os == 'Linux' && !matrix.android
         run: |
           sudo apt-get update
           sudo apt-get install -y software-properties-common
@@ -68,18 +78,54 @@ jobs:
           sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 100
           sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 100
 
-      - name: Configure xmake
-        if: runner.os == 'Linux'
+      - name: Setup Android NDK
+        if: ${{ matrix.android }}
+        uses: nttld/setup-ndk@v1
+        id: setup-ndk
+        with:
+          ndk-version: r27c
+
+      - name: Configure xmake (Android)
+        if: ${{ matrix.android }}
+        run: |
+          xmake f -p android --ndk=${{ steps.setup-ndk.outputs.ndk-path }} --ndk_sdkver=21 -a arm64-v8a -m releasedbg -v -y
+
+      - name: Configure xmake (Linux native)
+        if: runner.os == 'Linux' && !matrix.android
         run: |
           xmake f -m releasedbg -v -y --toolchain=gcc
-      
-      - name: Configure xmake
+
+      - name: Configure xmake (non-Linux)
         if: runner.os != 'Linux'
         run: |
           xmake f -m releasedbg -v -y
 
-      - name: Build
+      - name: Build (Android - injectee only)
+        if: ${{ matrix.android }}
+        run: xmake build -y chromatic-injectee
+
+      - name: Build (native)
+        if: ${{ !matrix.android }}
         run: xmake build -y
 
       - name: Test
+        if: ${{ !matrix.android }}
         run: xmake run chromatic-test
+
+      - name: Prepare artifacts
+        shell: bash
+        run: |
+          mkdir -p artifacts
+          if [ "${{ runner.os }}" = "Windows" ]; then
+            find build -name "chromatic-injectee.dll" -exec cp {} artifacts/ \;
+          elif [ "${{ runner.os }}" = "macOS" ]; then
+            find build -name "libchromatic-injectee.dylib" -exec cp {} artifacts/ \;
+          else
+            find build -name "libchromatic-injectee.so" -exec cp {} artifacts/ \;
+          fi
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: chromatic-injectee-${{ matrix.name }}
+          path: artifacts/*

src/core/bindings/binding_types.h

@@ -13,3 +13,4 @@
 #include "native_breakpoint.h"
 #include "native_hw_breakpoint.h"
 #include "native_memory_access_monitor.h"
+#include "script_lifecycle.h"

src/core/bindings/generated_bindings/binding_qjs.h

@@ -685,6 +685,30 @@ template<> struct js_bind<chromatic::js::NativeMemoryAccessMonitor> {
     }
 };
 
+template <> struct qjs::js_traits<chromatic::js::ScriptLifecycle> {
+    static chromatic::js::ScriptLifecycle unwrap(JSContext *ctx, JSValueConst v) {
+        chromatic::js::ScriptLifecycle obj;
+
+        return obj;
+    }
+
+    static JSValue wrap(JSContext *ctx, const chromatic::js::ScriptLifecycle &val) noexcept {
+        JSValue obj = JS_NewObject(ctx);
+
+        return obj;
+    }
+};
+template<> struct js_bind<chromatic::js::ScriptLifecycle> {
+    static void bind(qjs::Context::Module &mod) {
+        mod.class_<chromatic::js::ScriptLifecycle>("ScriptLifecycle")
+            .constructor<>()
+                .static_fun<&chromatic::js::ScriptLifecycle::onDispose>("onDispose")
+                .static_fun<&chromatic::js::ScriptLifecycle::removeDisposeCallback>("removeDisposeCallback")
+                .static_fun<&chromatic::js::ScriptLifecycle::removeAllDisposeCallbacks>("removeAllDisposeCallbacks")
+            ;
+    }
+};
+
 inline void chromatic_bindAll(qjs::Context::Module &mod) {
 
     js_bind<chromatic::js::console>::bind(mod);
@@ -725,4 +749,6 @@ inline void chromatic_bindAll(qjs::Context::Module &mod) {
 
     js_bind<chromatic::js::NativeMemoryAccessMonitor>::bind(mod);
 
+    js_bind<chromatic::js::ScriptLifecycle>::bind(mod);
+
 }

src/core/bindings/generated_bindings/binding_types.d.ts

@@ -709,5 +709,25 @@ export class NativeMemoryAccessMonitor {
      */
     static drainPending(): number
 }
+export class ScriptLifecycle {
+	/**
+	 *  Register a callback to be called before script dispose/reload.
+	 *  Returns callbackId (hex) for removal.
+	 * @param callback: (() => void)
+	 * @returns string
+	 */
+    static onDispose(callback: (() => void)): string
+	/**
+	 *  Remove a dispose callback by ID.
+	 * @param callbackId: string
+	 * @returns void
+	 */
+    static removeDisposeCallback(callbackId: string): void
+	/**
+	 *  Remove all dispose callbacks.
+	  @returns void
+	 */
+    static removeAllDisposeCallbacks(): void
+}
 }
 

src/core/bindings/script_lifecycle.cc

@@ -0,0 +1,68 @@
+#include "script_lifecycle.h"
+#include <cstdint>
+#include <mutex>
+#include <sstream>
+#include <unordered_map>
+#include <vector>
+#include <fmt/core.h>
+
+namespace {
+
+static std::mutex g_mutex;
+static uint64_t g_nextId = 1;
+static std::unordered_map<uint64_t, std::function<void()>> g_callbacks;
+
+std::string toHexId(uint64_t id) {
+  std::ostringstream oss;
+  oss << "0x" << std::hex << id;
+  return oss.str();
+}
+
+} // namespace
+
+namespace chromatic::js {
+
+std::string ScriptLifecycle::onDispose(std::function<void()> callback) {
+  std::lock_guard lock(g_mutex);
+  auto id = g_nextId++;
+  g_callbacks[id] = std::move(callback);
+  return toHexId(id);
+}
+
+void ScriptLifecycle::removeDisposeCallback(const std::string &callbackId) {
+  uint64_t id = std::stoull(callbackId, nullptr, 16);
+  std::lock_guard lock(g_mutex);
+  g_callbacks.erase(id);
+}
+
+void ScriptLifecycle::removeAllDisposeCallbacks() {
+  std::lock_guard lock(g_mutex);
+  g_callbacks.clear();
+}
+
+void ScriptLifecycle::_callDisposeCallbacks() {
+  // Take a snapshot of callbacks under lock, then call them outside lock
+  std::vector<std::function<void()>> callbacks;
+  {
+    std::lock_guard lock(g_mutex);
+    callbacks.reserve(g_callbacks.size());
+    for (auto &[id, cb] : g_callbacks) {
+      callbacks.push_back(cb);
+    }
+  }
+
+  for (auto &cb : callbacks) {
+    try {
+      cb();
+    } catch (const std::exception &e) {
+      fmt::print(stderr, "Exception in dispose callback: {}\n", e.what());
+    } catch (...) {
+      fmt::print(stderr, "Unknown exception in dispose callback\n");
+    }
+  }
+
+  // Clear all callbacks after calling
+  removeAllDisposeCallbacks();
+}
+
+} // namespace chromatic::js

src/core/bindings/script_lifecycle.h

@@ -0,0 +1,22 @@
+#pragma once
+#include <functional>
+#include <string>
+
+namespace chromatic::js {
+
+struct ScriptLifecycle {
+  /// Register a callback to be called before script dispose/reload.
+  /// Returns callbackId (hex) for removal.
+  static std::string onDispose(std::function<void()> callback);
+
+  /// Remove a dispose callback by ID.
+  static void removeDisposeCallback(const std::string &callbackId);
+
+  /// Remove all dispose callbacks.
+  static void removeAllDisposeCallbacks();
+
+  /// [Internal] Call all registered dispose callbacks, then clear them.
+  static void _callDisposeCallbacks();
+};
+
+} // namespace chromatic::js

src/core/script.cc

@@ -5,6 +5,7 @@
 #include "bindings/native_hw_breakpoint.h"
 #include "bindings/native_interceptor.h"
 #include "bindings/native_memory_access_monitor.h"
+#include "bindings/script_lifecycle.h"
 #include "fmt/base.h"
 
 extern "C" {
@@ -18,6 +19,7 @@ std::string index_js = {(const char *)_binary_index_js_start,
 namespace chromatic::script {
 void runtime::cleanup() {
   // Auto-cleanup all subsystems when the script context is disposed
+  chromatic::js::ScriptLifecycle::removeAllDisposeCallbacks();
   chromatic::js::NativeMemoryAccessMonitor::disableAll();
   chromatic::js::NativeHardwareBreakpoint::removeAll();
   chromatic::js::NativeSoftwareBreakpoint::removeAll();
@@ -26,7 +28,9 @@ void runtime::cleanup() {
   chromatic::js::NativeExceptionHandler::disable();
 }
 void runtime::reset() {
-  // Auto-cleanup before resetting the JS runtime
+  // Let JS do its cleanup first via dispose callbacks
+  chromatic::js::ScriptLifecycle::_callDisposeCallbacks();
+  // Then native cleanup
   cleanup();
   context.on_bind.clear();
   context.on_bind.push_back(

src/core/typescript/src/main.ts

@@ -15,6 +15,7 @@ import { Interceptor } from './interceptor/index';
 import { ExceptionHandler } from './exception-handler';
 import { SoftwareBreakpoint, HardwareBreakpoint } from './breakpoint';
 import { MemoryAccessMonitor } from './memory-access-monitor';
+import { Script } from './script-lifecycle';
 
 // Register globals (Frida-compatible)
 const g = globalThis as any;
@@ -37,6 +38,9 @@ g.SoftwareBreakpoint = SoftwareBreakpoint;
 g.HardwareBreakpoint = HardwareBreakpoint;
 g.MemoryAccessMonitor = MemoryAccessMonitor;
 
+// Script lifecycle
+g.Script = Script;
+
 // Utility functions
 g.ptr = ptr;
 g.NULL = NULL;

src/core/typescript/src/script-lifecycle.ts

@@ -0,0 +1,24 @@
+import { ScriptLifecycle as NativeScriptLifecycle } from 'chromatic';
+
+export const Script = {
+  /**
+   * Register a callback to be called before script dispose/reload.
+   * Returns a disposable handle with a `remove()` method.
+   *
+   * @example
+   * const handle = Script.onDispose(() => {
+   *   Interceptor.detachAll();
+   *   console.log('Cleaning up before reload...');
+   * });
+   * // Later, to unregister:
+   * handle.remove();
+   */
+  onDispose(callback: () => void): { remove: () => void } {
+    const id = NativeScriptLifecycle.onDispose(callback);
+    return {
+      remove() {
+        NativeScriptLifecycle.removeDisposeCallback(id);
+      },
+    };
+  },
+};