@mikrojs/native 0.0.7

package/CMakeLists.txt

@@ -0,0 +1,198 @@
+cmake_minimum_required(VERSION 3.20)
+project(mikrojs LANGUAGES C CXX)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# ── Resolve @mikrojs/quickjs via Node.js ─────────────────────────────
+execute_process(
+    COMMAND node -e "import('@mikrojs/quickjs').then(m=>process.stdout.write(m.cmakePath))"
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    OUTPUT_VARIABLE QUICKJS_CMAKE_PATH
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    RESULT_VARIABLE _QUICKJS_RESOLVE_RESULT
+)
+if(NOT _QUICKJS_RESOLVE_RESULT EQUAL 0)
+    message(FATAL_ERROR "Failed to resolve @mikrojs/quickjs. Run pnpm install first.")
+endif()
+
+include("${QUICKJS_CMAKE_PATH}")
+
+# qjsc is built by @mikrojs/quickjs postinstall during pnpm install
+if(NOT EXISTS "${QJSC_EXECUTABLE}")
+    message(FATAL_ERROR "qjsc not found at ${QJSC_EXECUTABLE}. Run 'pnpm install' first.")
+endif()
+
+# ── mikrojs static library ──────────────────────────────────────────
+# Core source files shared between standalone lib and ESP-IDF builds.
+# platform_posix.cpp is only used in the standalone build (ESP-IDF uses platform_esp32.cpp).
+set(MIKROJS_CORE_SOURCES
+    src/cutils_compat.c
+    src/mikrojs.cpp
+    src/modules.cpp
+    src/builtins.cpp
+    src/timers.cpp
+    src/fs.cpp
+    src/mem.cpp
+    src/utils.cpp
+    src/eval_bytecode.cpp
+    src/mik_inspect.cpp
+    src/mik_stdio.cpp
+    src/mik_text_encoding.cpp
+    src/mik_color.cpp
+    src/mik_abort.cpp
+    src/mik_cbor.cpp
+    src/mik_result.cpp
+    src/mik_console.cpp
+    src/mik_sys.cpp
+    src/mik_repl.cpp
+    src/mik_app_config.cpp
+)
+
+add_library(mikrojs STATIC
+    ${MIKROJS_CORE_SOURCES}
+    src/platform_posix.cpp
+    deps/nanocbor/src/encoder.c
+    deps/nanocbor/src/decoder.c
+)
+set_target_properties(mikrojs PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+target_include_directories(mikrojs PUBLIC
+    "${CMAKE_CURRENT_SOURCE_DIR}/include"
+)
+target_include_directories(mikrojs PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/deps/nanocbor/include"
+)
+
+# nanocbor defaults to <endian.h> (glibc). Apple SDKs and MSVC don't ship
+# it, so route them to per-platform shims that map htobe*/be*toh onto
+# whatever native intrinsics the toolchain provides.
+if(APPLE)
+    target_compile_definitions(mikrojs PRIVATE "NANOCBOR_BYTEORDER_HEADER=\"byteorder_apple.h\"")
+elseif(WIN32)
+    target_compile_definitions(mikrojs PRIVATE "NANOCBOR_BYTEORDER_HEADER=\"byteorder_windows.h\"")
+endif()
+
+# ── Generated bytecode headers ────────────────────────────────────
+include(cmake/mikrojs_bytecode.cmake)
+mikrojs_generate_bytecode(
+    RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime"
+    MODULES cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared neopixel pin pwm reader sleep spi sntp stdio stream sys test uart wifi
+    MODULE_PREFIX "mikrojs"
+    SYMBOL_PREFIX "mikrojs"
+    TARGET gen_bytecode
+)
+add_dependencies(mikrojs gen_bytecode)
+target_include_directories(mikrojs PRIVATE "${gen_bytecode_INCLUDE_DIR}")
+
+target_link_libraries(mikrojs PUBLIC quickjs)
+
+# Note: self-registering native modules need force-include linker flags (-u symbol)
+# to prevent stripping from static libraries. These are added by consumers:
+# - ESP-IDF firmware: mikrojs_force_include_modules() in firmware CMakeLists
+# - Host tests: target_link_options on mikrojs_tests below
+
+# Suppress warnings from QuickJS headers in our code. MSVC uses /W3 by default
+# and doesn't understand the -W flags. The dead-stripping flags below are
+# similarly GCC/Clang-only; MSVC's linker dead-strips by default with /OPT:REF.
+if(NOT MSVC)
+    target_compile_options(mikrojs PRIVATE -Wall -Wextra -Wno-unused-parameter)
+    # Emit per-function/data sections so the linker can dead-strip unreferenced
+    # symbols at executable link time. This matches ESP-IDF's default toolchain
+    # flags and lets us measure flash-size effects of source-level changes
+    # (e.g. intrinsic stripping) on the host build.
+    target_compile_options(mikrojs PRIVATE -ffunction-sections -fdata-sections)
+endif()
+
+# Version metadata for sys.version()
+execute_process(
+    COMMAND node -e "import('../../../package.json',{with:{type:'json'}}).then(m=>process.stdout.write(m.default.version))"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+    OUTPUT_VARIABLE _MIK_VERSION
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    RESULT_VARIABLE _MIK_VERSION_RESULT
+)
+if(NOT _MIK_VERSION_RESULT EQUAL 0 OR _MIK_VERSION STREQUAL "")
+    message(FATAL_ERROR "Failed to resolve package version for MIK_FW_VERSION. Check that package.json exists at the workspace root.")
+endif()
+target_compile_definitions(mikrojs PRIVATE "MIK_FW_VERSION=\"${_MIK_VERSION}\"")
+
+# UTC build timestamp. `string(TIMESTAMP ... UTC)` honors SOURCE_DATE_EPOCH
+# when set (for reproducible builds). Refreshes on re-configure only, not
+# every build — coarse enough for sys.firmware.date, which is a sanity
+# fence for clock-synced checks, not a precise build identifier.
+string(TIMESTAMP _MIK_BUILD_DATE_UTC "%Y-%m-%dT%H:%M:%SZ" UTC)
+target_compile_definitions(mikrojs PRIVATE "MIK_BUILD_DATE_UTC=\"${_MIK_BUILD_DATE_UTC}\"")
+
+# ── Exported variables for ESP-IDF consumers ─────────────────────────
+# ESP-IDF components can't use CMake targets, so export source/include paths.
+# Only set PARENT_SCOPE when included as a subdirectory (avoids warnings in standalone builds).
+if(NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+# Prefix each core source with the full path for PARENT_SCOPE export
+set(MIKROJS_SOURCES "")
+foreach(_src ${MIKROJS_CORE_SOURCES})
+    list(APPEND MIKROJS_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/${_src}")
+endforeach()
+set(MIKROJS_SOURCES ${MIKROJS_SOURCES} PARENT_SCOPE)
+set(MIKROJS_NANOCBOR_DIR "${CMAKE_CURRENT_SOURCE_DIR}/deps/nanocbor" PARENT_SCOPE)
+set(MIKROJS_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include" PARENT_SCOPE)
+set(MIKROJS_SCRIPTS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/scripts" PARENT_SCOPE)
+set(MIKROJS_RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime" PARENT_SCOPE)
+endif()
+
+# ── Tests ────────────────────────────────────────────────────────────
+if(BUILD_TESTING)
+    enable_testing()
+
+    add_executable(mikrojs_tests
+        test/main.cpp
+        test/runtime_test.cpp
+        test/modules_test.cpp
+        test/text_encoding_test.cpp
+        test/cbor_test.cpp
+        test/abort_test.cpp
+        test/repl_protocol_test.cpp
+        test/app_config_test.cpp
+        test/oom_test.cpp
+        test/reader_test.cpp
+        test/stream_test.cpp
+        test/runtime_recycle_test.cpp
+    )
+
+    target_link_libraries(mikrojs_tests PRIVATE mikrojs)
+    target_include_directories(mikrojs_tests PRIVATE
+        "${CMAKE_CURRENT_SOURCE_DIR}/test"
+        "${CMAKE_CURRENT_SOURCE_DIR}/deps/nanocbor/include"
+    )
+
+    include(CTest)
+    add_test(NAME mikrojs_tests COMMAND mikrojs_tests)
+
+    # native_stubs registers no-op `native:*` modules so the bench can load
+    # ESP-only builtins (wifi, fetch, kv, …) on the host. Compiled into the
+    # executable directly so its self-registering constructors aren't
+    # dead-stripped (no -u flags needed).
+    add_executable(memory_bench test/memory_bench.cpp test/native_stubs.cpp)
+    target_link_libraries(memory_bench PRIVATE mikrojs)
+    # Run the bench as a smoke test so module-load regressions (e.g. a
+    # builtin that imports an unregistered native module on host) surface
+    # in `pnpm test:lib` / `pnpm check` rather than only in the CI
+    # memory-bench workflow. Output is discarded; we only assert it exits 0.
+    add_test(NAME memory_bench COMMAND memory_bench)
+    set_tests_properties(memory_bench PROPERTIES
+        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
+
+    add_executable(bundle_compare test/bundle_compare.cpp)
+    target_link_libraries(bundle_compare PRIVATE mikrojs)
+    # Dead-strip unreferenced code at link time. Used for measuring the
+    # binary-size impact of source-level changes (intrinsic drops, etc.).
+    # Applied only to memory_bench to avoid interfering with doctest's
+    # static-initializer registration in mikrojs_tests.
+    if(APPLE)
+        target_link_options(memory_bench PRIVATE -Wl,-dead_strip)
+    else()
+        target_link_options(memory_bench PRIVATE -Wl,--gc-sections)
+    endif()
+endif()

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Bjørge Næss
+
+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,49 @@
+# @mikrojs/native
+
+Standalone, platform-independent C++ runtime library for mikrojs, powered by QuickJS-NG. Zero ESP-IDF dependencies — runs on any POSIX host for development and testing, and on ESP32 via a thin platform adapter.
+
+## Directory structure
+
+```
+include/        Public C/C++ headers (mikrojs.h, platform.h, private.h, …)
+src/            C/C++ source files (runtime, modules, timers, REPL, …)
+runtime/        TypeScript runtime modules bundled to bytecode at build time
+addon/          Node-API addon exposing the runtime to Node.js
+scripts/        Build scripts (esbuild bundling, qjsc bytecode compilation)
+test/           Host-side C++ tests (Unity, run via ctest)
+```
+
+## Build
+
+```sh
+# Standalone library (host)
+cmake -B build && cmake --build build
+
+# Run C++ tests
+ctest --test-dir build --output-on-failure
+
+# Node addon
+pnpm run build:native
+```
+
+## Architecture
+
+The runtime abstracts platform-specific operations via `MIKPlatform` (defined in `include/mikrojs/platform.h`). A default POSIX implementation is provided in `src/platform_posix.cpp`. The ESP32 adapter in `packages/@mikrojs/firmware/components/mikrojs/` supplies an ESP-IDF implementation.
+
+### Runtime modules
+
+TypeScript modules in `runtime/` are the JS-facing APIs (fetch, pin, wifi, etc.). During each CMake build they are:
+
+1. Bundled with esbuild (`scripts/bundle-runtime.js`)
+2. Compiled to bytecode with qjsc (`scripts/compile-bytecode.sh`)
+3. Included as C headers in `src/builtins.cpp`
+
+Type-checked separately via `tsconfig.runtime.json`:
+
+```sh
+tsc --noEmit -p tsconfig.runtime.json
+```
+
+### Node addon
+
+The `addon/` directory contains a Node-API binding that wraps the C++ runtime for use from Node.js/TypeScript. See [`addon/README.md`](addon/README.md).

package/cmake/mikrojs_bytecode.cmake

@@ -0,0 +1,146 @@
+# mikrojs_generate_bytecode() — Reusable CMake function for compiling TypeScript
+# runtime modules to QuickJS bytecode headers.
+#
+# Used by the core runtime, ESP-IDF component, and board/driver packages.
+#
+# Usage:
+#   mikrojs_generate_bytecode(
+#       RUNTIME_DIR <path>         # Directory containing <mod>/<mod>.ts files
+#       MODULES <mod1> <mod2>      # Module names to compile
+#       MODULE_PREFIX <prefix>     # Module name prefix (e.g. "mikrojs" -> "mikrojs/pin")
+#       SYMBOL_PREFIX <prefix>     # C symbol prefix (e.g. "mikrojs" -> "mikrojs_pin_bytecode")
+#       TARGET <name>              # Custom target name (default: gen_bytecode)
+#       WORKING_DIRECTORY <dir>    # Working dir for esbuild (default: CMAKE_CURRENT_SOURCE_DIR)
+#   )
+#
+# After calling, the following are set in the caller's scope:
+#   ${TARGET}_HEADERS  — list of generated .h file paths
+#   ${TARGET}_GEN_DIR  — directory containing the generated headers (include this)
+
+include_guard(GLOBAL)
+
+# Resolve paths relative to this file (inside @mikrojs/native).
+# Use CACHE so the path is available across all components that include this file.
+get_filename_component(_MIK_BC_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" DIRECTORY)
+set(_MIK_BC_SCRIPTS_DIR "${_MIK_BC_CMAKE_DIR}/../scripts" CACHE INTERNAL "")
+
+function(mikrojs_generate_bytecode)
+    cmake_parse_arguments(ARG "" "RUNTIME_DIR;MODULE_PREFIX;SYMBOL_PREFIX;TARGET;WORKING_DIRECTORY" "MODULES" ${ARGN})
+
+    # Defaults
+    if(NOT ARG_TARGET)
+        set(ARG_TARGET "gen_bytecode")
+    endif()
+    if(NOT ARG_WORKING_DIRECTORY)
+        set(ARG_WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
+    endif()
+
+    # Validate required args
+    if(NOT ARG_RUNTIME_DIR)
+        message(FATAL_ERROR "mikrojs_generate_bytecode: RUNTIME_DIR is required")
+    endif()
+    if(NOT ARG_MODULES)
+        message(FATAL_ERROR "mikrojs_generate_bytecode: MODULES is required")
+    endif()
+    if(NOT ARG_MODULE_PREFIX)
+        message(FATAL_ERROR "mikrojs_generate_bytecode: MODULE_PREFIX is required")
+    endif()
+    if(NOT ARG_SYMBOL_PREFIX)
+        message(FATAL_ERROR "mikrojs_generate_bytecode: SYMBOL_PREFIX is required")
+    endif()
+
+    # Verify qjsc exists (set by quickjs.cmake)
+    if(NOT EXISTS "${QJSC_EXECUTABLE}")
+        message(FATAL_ERROR "qjsc not found at ${QJSC_EXECUTABLE}. Run 'pnpm install' first.")
+    endif()
+
+    set(_GEN_DIR "${CMAKE_CURRENT_BINARY_DIR}/gen")
+    set(_BUNDLE_DIR "${CMAKE_CURRENT_BINARY_DIR}/bundled")
+
+    # Collect source files so the bundle step re-runs when they change.
+    # Also track the shell scripts that drive the pipeline so changes to
+    # the scripts (e.g. qjsc flag fixes) invalidate the generated outputs
+    # and trigger a rebuild — otherwise ninja sees `bundle.stamp` unchanged
+    # and silently reuses stale bytecode headers.
+    file(GLOB_RECURSE _RUNTIME_SOURCES "${ARG_RUNTIME_DIR}/*.ts")
+    set(_BUNDLE_SCRIPT "${_MIK_BC_SCRIPTS_DIR}/bundle-runtime.js")
+    set(_COMPILE_SCRIPT "${_MIK_BC_SCRIPTS_DIR}/compile-bytecode.sh")
+
+    # Optional minifier override (e.g. -DMIK_MINIFIER=terser -DMIK_MINIFY_LEVEL=max)
+    set(_MINIFIER_ARGS "")
+    if(DEFINED MIK_MINIFIER)
+        list(APPEND _MINIFIER_ARGS "--minifier=${MIK_MINIFIER}")
+    endif()
+    if(DEFINED MIK_MINIFY_LEVEL)
+        list(APPEND _MINIFIER_ARGS "--minify-level=${MIK_MINIFY_LEVEL}")
+    endif()
+
+    # Step 1: Bundle TypeScript runtime modules to JS with esbuild
+    add_custom_command(
+        OUTPUT ${_BUNDLE_DIR}/bundle.stamp
+        COMMAND node ${_BUNDLE_SCRIPT}
+            ${_BUNDLE_DIR} ${ARG_RUNTIME_DIR} ${ARG_MODULES} ${_MINIFIER_ARGS}
+        COMMAND ${CMAKE_COMMAND} -E touch ${_BUNDLE_DIR}/bundle.stamp
+        DEPENDS ${_RUNTIME_SOURCES} ${_BUNDLE_SCRIPT}
+        COMMENT "Bundling runtime modules"
+        WORKING_DIRECTORY ${ARG_WORKING_DIRECTORY}
+    )
+
+    # Step 2: Compile each bundled JS file to a bytecode header with qjsc
+    set(_HEADERS "")
+    foreach(mod ${ARG_MODULES})
+        # Sanitize module name for C identifiers (replace non-alphanumeric with _)
+        string(REGEX REPLACE "[^a-zA-Z0-9]" "_" _mod_safe "${mod}")
+        set(_header "${_GEN_DIR}/${ARG_SYMBOL_PREFIX}_${_mod_safe}.h")
+        add_custom_command(
+            OUTPUT ${_header}
+            COMMAND ${CMAKE_COMMAND} -E make_directory ${_GEN_DIR}
+            COMMAND sh ${_COMPILE_SCRIPT}
+                ${QJSC_EXECUTABLE}
+                ${_BUNDLE_DIR}/${mod}.js
+                ${_header}
+                "${ARG_MODULE_PREFIX}/${mod}"
+                "${ARG_SYMBOL_PREFIX}_${_mod_safe}_bytecode"
+            DEPENDS ${_BUNDLE_DIR}/bundle.stamp ${_COMPILE_SCRIPT} ${QJSC_EXECUTABLE}
+            COMMENT "Compiling bytecode: ${ARG_MODULE_PREFIX}/${mod}"
+        )
+        list(APPEND _HEADERS ${_header})
+    endforeach()
+
+    # Step 3: Generate builtins table header (includes + lookup table)
+    set(_TABLE_HEADER "${_GEN_DIR}/${ARG_SYMBOL_PREFIX}_builtins_table.h")
+    set(_TABLE_CONTENT "/* Auto-generated by mikrojs_generate_bytecode() — do not edit */\n")
+    foreach(mod ${ARG_MODULES})
+        string(REGEX REPLACE "[^a-zA-Z0-9]" "_" _mod_safe "${mod}")
+        string(APPEND _TABLE_CONTENT "#include \"${ARG_SYMBOL_PREFIX}_${_mod_safe}.h\"\n")
+    endforeach()
+    string(APPEND _TABLE_CONTENT "\nstatic const mik_builtin_t ${ARG_SYMBOL_PREFIX}_builtins[] = {\n")
+    foreach(mod ${ARG_MODULES})
+        string(REGEX REPLACE "[^a-zA-Z0-9]" "_" _mod_safe "${mod}")
+        string(APPEND _TABLE_CONTENT "    {\"${ARG_MODULE_PREFIX}/${mod}\", ${ARG_SYMBOL_PREFIX}_${_mod_safe}_bytecode, ${ARG_SYMBOL_PREFIX}_${_mod_safe}_bytecode_size},\n")
+    endforeach()
+    string(APPEND _TABLE_CONTENT "    {NULL, NULL, 0},\n};\n")
+    file(GENERATE OUTPUT ${_TABLE_HEADER} CONTENT "${_TABLE_CONTENT}")
+    list(APPEND _HEADERS ${_TABLE_HEADER})
+
+    # Step 4: Create custom target
+    add_custom_target(${ARG_TARGET} DEPENDS ${_HEADERS})
+
+    # Export to caller's scope
+    set(${ARG_TARGET}_HEADERS ${_HEADERS} PARENT_SCOPE)
+    set(${ARG_TARGET}_GEN_DIR ${_GEN_DIR} PARENT_SCOPE)
+    # Include the parent of gen/ so #include "gen/foo.h" works
+    set(${ARG_TARGET}_INCLUDE_DIR ${CMAKE_CURRENT_BINARY_DIR} PARENT_SCOPE)
+endfunction()
+
+function(mikrojs_force_include_modules)
+    foreach(id ${ARGN})
+        target_link_libraries(${COMPONENT_LIB} INTERFACE "-u mik__mod_desc_${id}")
+    endforeach()
+endfunction()
+
+function(mikrojs_force_include_builtins)
+    foreach(id ${ARGN})
+        target_link_libraries(${COMPONENT_LIB} INTERFACE "-u mik__builtin_${id}")
+    endforeach()
+endfunction()

package/cmake.js

@@ -0,0 +1,22 @@
+import {dirname, join} from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/** Path to the main CMakeLists.txt */
+export const cmakePath = join(__dirname, 'CMakeLists.txt')
+
+/** Path to the public include directory */
+export const includePath = join(__dirname, 'include')
+
+/** Path to the C++ source directory */
+export const srcPath = join(__dirname, 'src')
+
+/** Path to the build scripts directory */
+export const scriptsPath = join(__dirname, 'scripts')
+
+/** Path to the runtime TypeScript modules directory */
+export const runtimePath = join(__dirname, 'runtime')
+
+/** Path to the reusable bytecode generation CMake module */
+export const bytecodeCmakePath = join(__dirname, 'cmake', 'mikrojs_bytecode.cmake')

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import type { HostMessage, MikroRuntimeOptions, ProfileEntry } from './types.js';
+export declare class MikroRuntime {
+    private native;
+    constructor(options?: MikroRuntimeOptions);
+    evalModule(filename: string, isMain?: boolean): void;
+    /** Evaluate module source code directly, bypassing filesystem path resolution. */
+    evalModuleContent(filename: string, content: string): void;
+    /** Evaluate a script (not module) and return the stringified result. Returns undefined if the result is undefined/null. */
+    evalScript(code: string): string | undefined;
+    loop(): Promise<void>;
+    /** Run one iteration of the event loop synchronously. Returns 0 on success. */
+    loopOnce(): number;
+    stop(): void;
+    dispose(): void;
+    /** Register a JS source string as a named virtual module.
+     * Virtual modules are checked by the loader before builtin bytecode,
+     * allowing JS-based mocks to override any native:* C module. */
+    registerModuleSource(name: string, source: string): void;
+    /** Drain all outbound messages sent from QuickJS via native:host.send().
+     * Returns and clears the queue. Call after each loopOnce(). */
+    drainMessages(): HostMessage[];
+    /** Post a message from Node.js into the QuickJS runtime.
+     * Delivered to the native:host.onMessage() callback on the next loop tick. */
+    postMessage(type: string, data: string): void;
+    /** Set a preprocessor function called on module source before compilation.
+     * Return a string to replace the source, or undefined to use the original.
+     * Useful for stripping TypeScript types from .ts files. */
+    setPreprocessor(fn: (filename: string, source: string) => string | undefined): void;
+    /** Set a synchronous RPC handler called from QuickJS via native:host.call().
+     * The handler receives a method name (e.g. 'pin.pinMode') and JSON-encoded args,
+     * and must return a JSON-encoded result string (or a Promise of one for async). */
+    setRpcHandler(handler: (method: string, argsJson: string) => string | Promise<string>): void;
+    /** Enable per-module memory profiling. Must be called before any module loads
+     * to capture the full import graph. Profile storage lives outside QuickJS's
+     * tracked heap so instrumentation does not pollute the numbers being measured. */
+    enableProfiling(): void;
+    /** Return the collected profile entries. Each entry records the QuickJS heap
+     * delta observed while loading a specific module. */
+    getProfile(): ProfileEntry[];
+    /** Return the QuickJS heap baseline (bytes) at the time profiling was enabled.
+     * This is the cost of the runtime + context + built-in prototypes, before
+     * any user modules are loaded. */
+    getProfileBaseline(): number;
+}
+/** Serialize a JSON string to QuickJS binary JSON (bjson) format. */
+export declare function jsonToBjson(json: string): Buffer;
+/** Compile a JS module to QuickJS bytecode. External imports must be declared to avoid resolution errors. */
+export declare function compileBytecode(source: string, moduleName: string, externals?: string[]): Buffer;
+/** Compile a JS module to bytecode and return as a C header string (equivalent to qjsc -o header.h). */
+export declare function compileBytecodeToHeader(source: string, moduleName: string, symbolName: string, externals?: string[]): string;
+export type { HostMessage, MikroRuntimeOptions, NativeMikroRuntime, ProfileEntry } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../addon/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EAGnB,YAAY,EACb,MAAM,YAAY,CAAA;AAuBnB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAoB;gBAEtB,OAAO,CAAC,EAAE,mBAAmB;IAIzC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAO,GAAG,IAAI;IAIjD,kFAAkF;IAClF,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI1D,2HAA2H;IAC3H,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,+EAA+E;IAC/E,QAAQ,IAAI,MAAM;IAIlB,IAAI,IAAI,IAAI;IAIZ,OAAO,IAAI,IAAI;IAIf;;oEAEgE;IAChE,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAIxD;mEAC+D;IAC/D,aAAa,IAAI,WAAW,EAAE;IAI9B;kFAC8E;IAC9E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI7C;;+DAE2D;IAC3D,eAAe,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI;IAInF;;uFAEmF;IACnF,aAAa,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI;IAI5F;;sFAEkF;IAClF,eAAe,IAAI,IAAI;IAIvB;yDACqD;IACrD,UAAU,IAAI,YAAY,EAAE;IAI5B;;sCAEkC;IAClC,kBAAkB,IAAI,MAAM;CAG7B;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAEhG;AAED,wGAAwG;AACxG,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,MAAM,CA4BR;AAED,YAAY,EAAC,WAAW,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,YAAY,EAAC,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,132 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+const require = createRequire(import.meta.url);
+const nodeGypBuild = require('node-gyp-build');
+function loadBindings() {
+    const pkgRoot = join(import.meta.dirname, '..');
+    try {
+        return nodeGypBuild(pkgRoot);
+    }
+    catch (prebuildErr) {
+        // Dev fallback: cmake-js builds to addon/build/Release/, which is outside
+        // the paths node-gyp-build probes by default.
+        const devPath = join(pkgRoot, 'addon', 'build', 'Release', 'mikrojs_node.node');
+        try {
+            return require(devPath);
+        }
+        catch {
+            throw prebuildErr;
+        }
+    }
+}
+const bindings = loadBindings();
+export class MikroRuntime {
+    native;
+    constructor(options) {
+        this.native = new bindings.MikroRuntime(options);
+    }
+    evalModule(filename, isMain = true) {
+        this.native.evalModule(filename, isMain);
+    }
+    /** Evaluate module source code directly, bypassing filesystem path resolution. */
+    evalModuleContent(filename, content) {
+        this.native.evalModuleContent(filename, content);
+    }
+    /** Evaluate a script (not module) and return the stringified result. Returns undefined if the result is undefined/null. */
+    evalScript(code) {
+        return this.native.evalScript(code);
+    }
+    loop() {
+        return this.native.loop();
+    }
+    /** Run one iteration of the event loop synchronously. Returns 0 on success. */
+    loopOnce() {
+        return this.native.loopOnce();
+    }
+    stop() {
+        this.native.stop();
+    }
+    dispose() {
+        this.native.dispose();
+    }
+    /** Register a JS source string as a named virtual module.
+     * Virtual modules are checked by the loader before builtin bytecode,
+     * allowing JS-based mocks to override any native:* C module. */
+    registerModuleSource(name, source) {
+        this.native.registerModuleSource(name, source);
+    }
+    /** Drain all outbound messages sent from QuickJS via native:host.send().
+     * Returns and clears the queue. Call after each loopOnce(). */
+    drainMessages() {
+        return this.native.drainMessages();
+    }
+    /** Post a message from Node.js into the QuickJS runtime.
+     * Delivered to the native:host.onMessage() callback on the next loop tick. */
+    postMessage(type, data) {
+        this.native.postMessage(type, data);
+    }
+    /** Set a preprocessor function called on module source before compilation.
+     * Return a string to replace the source, or undefined to use the original.
+     * Useful for stripping TypeScript types from .ts files. */
+    setPreprocessor(fn) {
+        this.native.setPreprocessor(fn);
+    }
+    /** Set a synchronous RPC handler called from QuickJS via native:host.call().
+     * The handler receives a method name (e.g. 'pin.pinMode') and JSON-encoded args,
+     * and must return a JSON-encoded result string (or a Promise of one for async). */
+    setRpcHandler(handler) {
+        this.native.setRpcHandler(handler);
+    }
+    /** Enable per-module memory profiling. Must be called before any module loads
+     * to capture the full import graph. Profile storage lives outside QuickJS's
+     * tracked heap so instrumentation does not pollute the numbers being measured. */
+    enableProfiling() {
+        this.native.enableProfiling();
+    }
+    /** Return the collected profile entries. Each entry records the QuickJS heap
+     * delta observed while loading a specific module. */
+    getProfile() {
+        return this.native.getProfile();
+    }
+    /** Return the QuickJS heap baseline (bytes) at the time profiling was enabled.
+     * This is the cost of the runtime + context + built-in prototypes, before
+     * any user modules are loaded. */
+    getProfileBaseline() {
+        return this.native.getProfileBaseline();
+    }
+}
+/** Serialize a JSON string to QuickJS binary JSON (bjson) format. */
+export function jsonToBjson(json) {
+    return bindings.jsonToBjson(json);
+}
+/** Compile a JS module to QuickJS bytecode. External imports must be declared to avoid resolution errors. */
+export function compileBytecode(source, moduleName, externals) {
+    return bindings.compileBytecode(source, moduleName, externals);
+}
+/** Compile a JS module to bytecode and return as a C header string (equivalent to qjsc -o header.h). */
+export function compileBytecodeToHeader(source, moduleName, symbolName, externals) {
+    const buf = bindings.compileBytecode(source, moduleName, externals);
+    // Match qjsc dump_hex format: " 0xNN," with newline every 8 bytes
+    let hex = '';
+    let col = 0;
+    for (let i = 0; i < buf.length; i++) {
+        hex += ` 0x${buf[i].toString(16).padStart(2, '0')},`;
+        if (++col === 8) {
+            hex += '\n';
+            col = 0;
+        }
+    }
+    if (col !== 0) {
+        hex += '\n';
+    }
+    return (`/* File generated automatically by the QuickJS-ng compiler. */\n` +
+        `\n` +
+        `#include <inttypes.h>\n` +
+        `\n` +
+        `const uint32_t ${symbolName}_size = ${buf.length};\n` +
+        `\n` +
+        `const uint8_t ${symbolName}[${buf.length}] = {\n` +
+        hex +
+        `};\n`);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../addon/index.ts"],"names":[],"mappings":"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"}