@mikrojs/native 0.21.0 → 0.21.1-next.20260927212749

package/CMakeLists.txt

@@ -95,14 +95,15 @@ endif()
 # `native:mikro/*` import with an explicit "not available" error (or is
 # satisfied by a sim stub) instead of a silent "Builtin not available".
 execute_process(
-    COMMAND node "${CMAKE_CURRENT_SOURCE_DIR}/scripts/modules-list.js" bytecode --host
-    OUTPUT_VARIABLE _MIK_HOST_MODULES
+    COMMAND node "${CMAKE_CURRENT_SOURCE_DIR}/scripts/modules-list.js" --host
+    OUTPUT_VARIABLE _MIK_HOST_LISTS
     OUTPUT_STRIP_TRAILING_WHITESPACE
     RESULT_VARIABLE _MIK_HOST_MODULES_RESULT
 )
 if(NOT _MIK_HOST_MODULES_RESULT EQUAL 0)
-    message(FATAL_ERROR "modules-list.js bytecode --host failed")
+    message(FATAL_ERROR "modules-list.js --host failed")
 endif()
+string(JSON _MIK_HOST_MODULES GET "${_MIK_HOST_LISTS}" bytecode)
 # The list is read at configure time, so configure must re-run when the table
 # or the script changes.
 set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
@@ -112,8 +113,6 @@ include(cmake/mikrojs_bytecode.cmake)
 mikrojs_generate_bytecode(
     RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime"
     MODULES ${_MIK_HOST_MODULES}
-    MODULE_PREFIX "mikro"
-    SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode
 )
 add_dependencies(mikrojs gen_bytecode)
@@ -205,7 +204,9 @@ if(BUILD_TESTING)
         test/runtime_test.cpp
         test/modules_test.cpp
         test/virtual_modules_test.cpp
-        test/ext_builtin_test.cpp
+        test/public_module_test.cpp
+        test/package_name_test.cpp
+        test/app_module_name_test.cpp
         test/text_encoding_test.cpp
         test/inspect_test.cpp
         test/platform_posix_test.cpp

package/cmake/mikrojs_bytecode.cmake

@@ -1,14 +1,12 @@
-# mikrojs_generate_bytecode() — Reusable CMake function for compiling TypeScript
-# runtime modules to QuickJS bytecode headers.
+# mikrojs_generate_bytecode() — CMake function that compiles the core runtime's
+# TypeScript modules to QuickJS bytecode headers, as the mikro/* builtins.
 #
-# Used by the core runtime, ESP-IDF component, and board/driver packages.
+# Used by the standalone library and the ESP-IDF component.
 #
 # 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. "mikro" -> "mikro/gpio")
-#       SYMBOL_PREFIX <prefix>     # C symbol prefix (e.g. "mikrojs" -> "mikrojs_pin_bytecode")
+#       MODULES <mod1> <mod2>      # Module names to compile ("fs" -> "mikro/fs")
 #       TARGET <name>              # Custom target name (default: gen_bytecode)
 #       WORKING_DIRECTORY <dir>    # Working dir for esbuild (default: CMAKE_CURRENT_SOURCE_DIR)
 #   )
@@ -25,7 +23,7 @@ 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})
+    cmake_parse_arguments(ARG "" "RUNTIME_DIR;TARGET;WORKING_DIRECTORY" "MODULES" ${ARGN})
 
     # Defaults
     if(NOT ARG_TARGET)
@@ -42,12 +40,6 @@ function(mikrojs_generate_bytecode)
     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}")
@@ -91,7 +83,7 @@ function(mikrojs_generate_bytecode)
     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")
+        set(_header "${_GEN_DIR}/mikro_${_mod_safe}.h")
         add_custom_command(
             OUTPUT ${_header}
             COMMAND ${CMAKE_COMMAND} -E make_directory ${_GEN_DIR}
@@ -99,25 +91,25 @@ function(mikrojs_generate_bytecode)
                 ${QJSC_EXECUTABLE}
                 ${_BUNDLE_DIR}/${mod}.js
                 ${_header}
-                "${ARG_MODULE_PREFIX}/${mod}"
-                "${ARG_SYMBOL_PREFIX}_${_mod_safe}_bytecode"
+                "mikro/${mod}"
+                "mikro_${_mod_safe}_bytecode"
             DEPENDS ${_BUNDLE_DIR}/bundle.stamp ${_COMPILE_SCRIPT} ${QJSC_EXECUTABLE}
-            COMMENT "Compiling bytecode: ${ARG_MODULE_PREFIX}/${mod}"
+            COMMENT "Compiling bytecode: mikro/${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_HEADER "${_GEN_DIR}/mikro_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")
+        string(APPEND _TABLE_CONTENT "#include \"mikro_${_mod_safe}.h\"\n")
     endforeach()
-    string(APPEND _TABLE_CONTENT "\nstatic const mik_builtin_t ${ARG_SYMBOL_PREFIX}_builtins[] = {\n")
+    string(APPEND _TABLE_CONTENT "\nstatic const mik_builtin_t mikro_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")
+        string(APPEND _TABLE_CONTENT "    {\"mikro/${mod}\", mikro_${_mod_safe}_bytecode, mikro_${_mod_safe}_bytecode_size},\n")
     endforeach()
     string(APPEND _TABLE_CONTENT "    {NULL, NULL, 0},\n};\n")
     file(GENERATE OUTPUT ${_TABLE_HEADER} CONTENT "${_TABLE_CONTENT}")
@@ -138,9 +130,3 @@ function(mikrojs_force_include_modules)
         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.d.ts

@@ -0,0 +1,12 @@
+/** Path to the main CMakeLists.txt */
+export declare const cmakePath: string
+/** Path to the public include directory */
+export declare const includePath: string
+/** Path to the C++ source directory */
+export declare const srcPath: string
+/** Path to the build scripts directory */
+export declare const scriptsPath: string
+/** Path to the runtime TypeScript modules directory */
+export declare const runtimePath: string
+/** Path to the reusable bytecode generation CMake module */
+export declare const bytecodeCmakePath: string

package/include/mikrojs/mikrojs.h

@@ -287,24 +287,45 @@ typedef struct mik_module_desc_t {
 extern mik_module_desc_t* mik__module_registry_head;
 
 /* NOLINTBEGIN(bugprone-macro-parentheses,cppcoreguidelines-avoid-non-const-global-variables) */
-/* Namespace governance. The build defines MIK_PACKAGE_NAME for every component:
- * "mikro" for the core runtime, and the owning npm package name for a discovered
- * driver/board package (assigned authoritatively from the dependency graph, not
- * self-declared). A native module must then be named "native:<MIK_PACKAGE_NAME>/…"
- * and a registered builtin "<MIK_PACKAGE_NAME>/…". This reserves the native:
- * namespace to mikro and stops a package from claiming or shadowing another's
- * name. Enforced at compile time; the static_assert needs string-literal args
+/* Namespace governance. Each component's CMakeLists.txt defines MIK_PACKAGE_NAME:
+ * "mikro" for the core runtime, the owning npm package name for a driver or
+ * board package. A native module must then be named "native:<MIK_PACKAGE_NAME>/…",
+ * and a public module "<MIK_PACKAGE_NAME>" (the package's root export) or
+ * "<MIK_PACKAGE_NAME>/…". This keeps the native: namespace to mikro and catches
+ * a module named for the wrong package; the name is self-declared, so it does
+ * not stop a package that declares another's.
+ * An app's own module, which the app imports with a "#" specifier from its
+ * package.json "imports", belongs to no package: its component defines no
+ * MIK_PACKAGE_NAME, and its public module name must start with "#".
+ * Enforced at compile time; the static_assert needs string-literal args
  * (always the case here). */
 #ifdef MIK_PACKAGE_NAME
 #define MIK__REQUIRE_PREFIX(name_, prefix_)                                        \
     static_assert(__builtin_strncmp((name_), (prefix_), sizeof(prefix_) - 1) == 0, \
                   "mikrojs: name must start with \"" prefix_ "\"")
 #define MIK__REQUIRE_NATIVE_NS(name_) MIK__REQUIRE_PREFIX(name_, "native:" MIK_PACKAGE_NAME "/")
-#define MIK__REQUIRE_BUILTIN_NS(name_) MIK__REQUIRE_PREFIX(name_, MIK_PACKAGE_NAME "/")
+/* The package name itself, or a subpath of it. sizeof compares the lengths, so
+ * "@acme/pi" does not pass for "@acme/pix". */
+#define MIK__REQUIRE_BUILTIN_NS(name_)                                                   \
+    static_assert((sizeof(name_) == sizeof(MIK_PACKAGE_NAME) &&                          \
+                   __builtin_strncmp((name_), MIK_PACKAGE_NAME, sizeof(name_)) == 0) ||  \
+                      __builtin_strncmp((name_), MIK_PACKAGE_NAME "/",                   \
+                                        sizeof(MIK_PACKAGE_NAME "/") - 1) == 0,          \
+                  "mikrojs: name must be \"" MIK_PACKAGE_NAME "\" or start with \"" \
+                  MIK_PACKAGE_NAME "/\"")
+#define MIK__REQUIRE_PACKAGE_NS(name_) MIK__REQUIRE_BUILTIN_NS(name_)
 #else
 #define MIK__REQUIRE_PREFIX(name_, prefix_) static_assert(true, "")
 #define MIK__REQUIRE_NATIVE_NS(name_) static_assert(true, "")
 #define MIK__REQUIRE_BUILTIN_NS(name_) static_assert(true, "")
+/* Core may build without MIK_PACKAGE_NAME (host builds); a package's module
+ * never does, or it could take any name, a core one included. Without it, a
+ * public module is an app's own, named "#…". */
+#define MIK__REQUIRE_PACKAGE_NS(name_)                                                \
+    static_assert(__builtin_strncmp((name_), "#", 1) == 0,                           \
+                  "mikrojs: MIK_REGISTER_PUBLIC_MODULE needs MIK_PACKAGE_NAME, or a " \
+                  "\"#\" name for an app's own module; define MIK_PACKAGE_NAME in "   \
+                  "the component's CMakeLists.txt")
 #endif
 
 /* The descriptor has external linkage so the linker can be told to keep it
@@ -312,6 +333,14 @@ extern mik_module_desc_t* mik__module_registry_head;
 #define MIK_REGISTER_MODULE(id, name_, init_, consume_, destroy_)              \
     MIK__REQUIRE_NATIVE_NS(name_);                                             \
     MIK__MODULE_DESC(id, name_, init_, consume_, destroy_)
+/* A package's C module under its public import specifier
+ * ("@mikrojs/drivers/sh8601"): what app code imports, with no JS layer and no
+ * native: name. The specifier must start with the owning package's name, or
+ * with "#" for an app's own module, and the module must validate its
+ * arguments: app code calls it directly. */
+#define MIK_REGISTER_PUBLIC_MODULE(id, name_, init_, consume_, destroy_)       \
+    MIK__REQUIRE_PACKAGE_NS(name_);                                            \
+    MIK__MODULE_DESC(id, name_, init_, consume_, destroy_)
 /* A platform C module under its public mikro/ name (mikro/gpio on ESP-IDF), for
  * modules with no bytecode layer. Core runtime only. */
 #define MIK__REGISTER_PUBLIC_MODULE(id, name_, init_, consume_, destroy_)      \
@@ -325,27 +354,6 @@ extern mik_module_desc_t* mik__module_registry_head;
         mik__mod_desc_##id.next = mik__module_registry_head;                   \
         mik__module_registry_head = &mik__mod_desc_##id;                       \
     }
-/* Self-registration for bytecode builtins (board/driver JS runtime modules).
- * Driver packages use MIK_REGISTER_BUILTIN() to embed their JS wrappers as
- * firmware builtins, resolved by the real npm package name (e.g. "@mikrojs/your-driver"). */
-typedef struct mik_ext_builtin_t {
-    const char* name;         /* module name, e.g. "@mikrojs/your-driver" */
-    const uint8_t* data;      /* compiled bytecode */
-    uint32_t data_size;
-    struct mik_ext_builtin_t* next;
-} mik_ext_builtin_t;
-
-extern mik_ext_builtin_t* mik__ext_builtin_head;
-
-/* The descriptor has external linkage so the linker can keep it via -u flags. */
-#define MIK_REGISTER_BUILTIN(id, name_, data_, size_)                              \
-    MIK__REQUIRE_BUILTIN_NS(name_);                                                \
-    mik_ext_builtin_t mik__builtin_##id = {                                        \
-        name_, data_, size_, NULL};                                                \
-    static void __attribute__((constructor)) mik__register_builtin_##id(void) {    \
-        mik__builtin_##id.next = mik__ext_builtin_head;                            \
-        mik__ext_builtin_head = &mik__builtin_##id;                                \
-    }
 /* NOLINTEND(bugprone-macro-parentheses,cppcoreguidelines-avoid-non-const-global-variables) */
 
 /* REPL (mik_repl.cpp) */
@@ -470,6 +478,11 @@ bool MIK_ClaimGpio(int gpio, const char* owner);
 void MIK_ReleaseGpio(int gpio, const char* owner);
 /* The current owner of `gpio`, or NULL when it is free. */
 const char* MIK_GpioOwner(int gpio);
+/* Claims every GPIO in `gpios` for `owner`. If one is already held, releases
+ * the ones this call claimed and returns an err Result carrying GpioInUse
+ * {name, owner, message}. Returns JS_UNDEFINED when all are claimed. */
+JSValue MIK_ClaimGpios(JSContext* ctx, const int* gpios, int count, const char* owner);
+void MIK_ReleaseGpios(const int* gpios, int count, const char* owner);
 
 /* A handle that owns a resource lives until its end() or close(), even when
  * the app no longer refers to it. Call MIK_KeepHandle when you create the
@@ -479,6 +492,15 @@ const char* MIK_GpioOwner(int gpio);
 void MIK_KeepHandle(JSContext* ctx, JSValueConst handle);
 void MIK_DropHandle(JSContext* ctx, JSValueConst handle);
 
+/* Results for native module functions: {ok: true, value}, {ok: true}, or
+ * {ok: false, error: {name, message}}, with the methods app code expects
+ * (.map, .orPanic and the rest). MIK_ResultOk takes ownership of `value`.
+ * The error message is printf-style. */
+JSValue MIK_ResultOk(JSContext* ctx, JSValue value);
+JSValue MIK_ResultOkVoid(JSContext* ctx);
+JSValue MIK_ResultErrNamed(JSContext* ctx, const char* name, const char* fmt, ...)
+    __attribute__((format(printf, 3, 4)));
+
 #ifdef __cplusplus
 }
 #endif

package/include/mikrojs/ota_env.h

@@ -47,7 +47,7 @@ typedef struct MIKDeviceIdentity {
     char firmware_version[32];
     char firmware_hash[65];
     int bytecode_version;
-    char board[48]; /* board name of this build, or empty string if unknown */
+    char board[64]; /* board name of this build, or empty string if unknown */
 } MIKDeviceIdentity;
 
 /* Diagnostic info from reconcile */
@@ -64,10 +64,13 @@ typedef struct MIKOtaReconcileOutcome {
     MIKOtaDiagnostic diagnostic;
 } MIKOtaReconcileOutcome;
 
+/* The registry caps an app version at 64 characters; plus the NUL. */
+#define MIK_OTA_VERSION_MAX 65
+
 /* Running build info */
 typedef struct MIKOtaRunningBuild {
-    char checksum[65]; /* SHA-256 hex or empty string if none */
-    char version[32];  /* package.json version or empty string if none */
+    char checksum[65];                 /* SHA-256 hex or empty string if none */
+    char version[MIK_OTA_VERSION_MAX]; /* package.json version or empty string if none */
     bool trial;
 } MIKOtaRunningBuild;
 
@@ -114,9 +117,9 @@ typedef struct MIKOtaConfigErrorReport {
 
 /* Stored config document representation */
 typedef struct MIKOtaStoredConfig {
-    char rev[MIK_OTA_REV_MAX]; /* empty string if none */
-    char version[32];          /* required */
-    uint8_t* doc_cbor;         /* CBOR-encoded document bytes, or NULL if absent/clear */
+    char rev[MIK_OTA_REV_MAX];         /* empty string if none */
+    char version[MIK_OTA_VERSION_MAX]; /* required */
+    uint8_t* doc_cbor;                 /* CBOR-encoded document bytes, or NULL if absent/clear */
     size_t doc_cbor_len;
 } MIKOtaStoredConfig;
 

package/include/mikrojs/platform.h

@@ -69,8 +69,8 @@ typedef struct MIKPlatform {
     int (*stdout_write)(const void* buf, size_t len);
     int (*stderr_write)(const void* buf, size_t len);
     int (*stdin_read)(void* buf, size_t len);
-    /** Return a unique device identifier string, or NULL if unavailable.
-     *  On ESP32 this is the base MAC address encoded as Crockford's Base32
+    /** Required. Return the device's unique identifier: a non-empty string,
+     *  never NULL. On ESP32 this is the base MAC address encoded as Crockford's Base32
      *  (10 lowercase chars). The encoding is lossless: decoding yields the
      *  original 6 MAC bytes. The returned pointer must remain valid for the
      *  lifetime of the platform. */

package/include/mikrojs/private.h

@@ -323,12 +323,6 @@ JSModuleDef* mik__observable_operators_load(JSContext* ctx);
 int mik__observable_multicast_new(JSContext* ctx, JSValue* observable, JSValue* next,
                                   JSValue* complete);
 
-/* GPIO claims (gpio_claim.cpp). Claims every GPIO for `owner`; on the first one
- * already held, releases those claimed so far and returns an err Result
- * carrying GpioInUse {name, owner, message}. Returns JS_UNDEFINED on success. */
-JSValue mik__claim_gpios(JSContext* ctx, const int* gpios, int count, const char* owner);
-void mik__release_gpios(const int* gpios, int count, const char* owner);
-
 /* Watchdog (mik_watchdog.cpp). */
 /* Start a fresh blocking budget: top of each MIK_Loop pass, eval entry
  * points, REPL eval, and on return from a deliberately blocking native

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.21.0",
+  "version": "0.21.1-next.20260927212749",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -24,6 +24,7 @@
     "prebuilds",
     "cmake",
     "cmake.js",
+    "cmake.d.ts",
     "CMakeLists.txt",
     "deps/nanocbor/src",
     "deps/nanocbor/include",
@@ -85,14 +86,14 @@
     "./runtime/wifi/types": "./runtime/wifi/types.ts"
   },
   "dependencies": {
-    "@mikrojs/quickjs": "0.21.0",
+    "@mikrojs/quickjs": "0.21.1-next.20260927212749+7f87381",
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.9.2",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
-    "@mikrojs/registry": "0.21.0",
-    "@mikrojs/schema": "0.21.0",
+    "@mikrojs/registry": "0.21.1-next.20260927212749+7f87381",
+    "@mikrojs/schema": "0.21.1-next.20260927212749+7f87381",
     "@swc/core": "^1.16.2",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.2",

package/runtime/kv/shared.ts

@@ -87,11 +87,12 @@ export function makeCreateValue(native: NativeKvFns) {
       return v
     }
 
+    function doDelete() {
+      return native.remove(key) ? ok() : err(KVError.WriteFailed(`failed to delete key "${key}"`))
+    }
+
     function doSet(value: unknown) {
-      if (value === undefined) {
-        native.remove(key)
-        return ok(undefined)
-      }
+      if (value === undefined) return doDelete()
       if (schema) {
         const result = parse(schema, value)
         if (!result.ok) {
@@ -109,10 +110,7 @@ export function makeCreateValue(native: NativeKvFns) {
       update(updater: (value: any) => any) {
         return doSet(updater(doGet()))
       },
-      delete() {
-        const removed = native.remove(key)
-        return removed ? ok() : err(KVError.WriteFailed(`failed to delete key "${key}"`))
-      },
+      delete: doDelete,
     }
   }
 }

package/scripts/bundle-runtime.js

@@ -108,7 +108,7 @@ for (const name of moduleNames) {
     target: 'es2024',
     platform: 'neutral',
     format: 'esm',
-    external: ['mikro', 'mikro/*', '@mikrojs/*', 'native:*'],
+    external: ['mikro', 'mikro/*', 'native:*'],
     metafile: true,
   })
 
@@ -141,9 +141,7 @@ for (const name of moduleNames) {
 
   // Extract external imports so CMake can pass them as -M flags to qjsc
   const externals = []
-  for (const match of source.matchAll(
-    /(?:from|import)\s*["']((?:native:|mikro\/|@mikrojs\/)[^"']+)["']/g,
-  )) {
+  for (const match of source.matchAll(/(?:from|import)\s*["']((?:native:|mikro\/)[^"']+)["']/g)) {
     externals.push(match[1])
   }
 

package/scripts/modules-list.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 /**
- * Print builtin module lists derived from runtime/modules.json for CMake.
+ * Print the builtin module lists derived from runtime/modules.json for CMake.
  *
- * Usage: node modules-list.js <bytecode|native|features> [--host] [--ble=on|off] [--wifi=on|off]
+ * Usage: node modules-list.js [--host] [--ble=on|off] [--wifi=on|off]
  *
- * - `bytecode`: bytecode module names (mikrojs_generate_bytecode MODULES)
- * - `native`: native module ids (mikrojs_force_include_modules)
- * - `features`: firmware features present in the build (for MIK_FW_FEATURES)
  * - `--host`: the host/sim build: every module, no compile gating
  * - `--ble`, `--wifi`: device builds only; a module whose `when` names the
  *   gate is included iff it is `on`
  *
- * Output is semicolon-separated (a CMake list) on stdout.
+ * Prints one JSON object on stdout, each value a semicolon-separated CMake list:
+ * - `bytecode`: bytecode module names (mikrojs_generate_bytecode MODULES)
+ * - `native`: native module ids (mikrojs_force_include_modules)
+ * - `features`: firmware features present in the build (for MIK_FW_FEATURES)
  *
  * Fields of a runtime/modules.json entry:
  * - `name`: the module name; the import specifier is `mikro/<name>`
@@ -32,19 +32,12 @@ import {fileURLToPath} from 'node:url'
 const modulesJsonPath = fileURLToPath(new URL('../runtime/modules.json', import.meta.url))
 const {modules} = JSON.parse(readFileSync(modulesJsonPath, 'utf8'))
 
-const kind = process.argv[2]
 const host = process.argv.includes('--host')
 const gates = ['ble', 'wifi']
 const flags = Object.fromEntries(
   gates.map((g) => [g, process.argv.find((a) => a.startsWith(`--${g}=`))]),
 )
 
-if (kind !== 'bytecode' && kind !== 'native' && kind !== 'features') {
-  process.stderr.write(
-    'usage: modules-list.js <bytecode|native|features> [--host] [--ble=on|off] [--wifi=on|off]\n',
-  )
-  process.exit(1)
-}
 if (!host && gates.some((g) => !flags[g])) {
   process.stderr.write('modules-list.js: device builds must pass --ble=on|off and --wifi=on|off\n')
   process.exit(1)
@@ -52,17 +45,20 @@ if (!host && gates.some((g) => !flags[g])) {
 
 const off = new Set(host ? [] : gates.filter((g) => flags[g] !== `--${g}=on`))
 const included = modules.filter((m) => !m.when || !off.has(m.when))
-const names =
-  kind === 'bytecode'
-    ? included.filter((m) => m.bytecode !== false).map((m) => m.name)
-    : kind === 'native'
-      ? included.filter((m) => m.native).map((m) => m.native)
-      : // A module can need a feature without being compiled under its gate
-        // (http/server needs wifi and always compiles), so a feature whose
-        // gate is off is dropped here. This relies on each gated feature
-        // having the same name as its gate.
-        [...new Set(included.filter((m) => m.feature).map((m) => m.feature))].filter(
-          (f) => !off.has(f),
-        )
+const bytecode = included.filter((m) => m.bytecode !== false).map((m) => m.name)
+const native = included.filter((m) => m.native).map((m) => m.native)
+// A module can need a feature without being compiled under its gate
+// (http/server needs wifi and always compiles), so a feature whose gate is
+// off is dropped here. This relies on each gated feature having the same
+// name as its gate.
+const features = [...new Set(included.filter((m) => m.feature).map((m) => m.feature))].filter(
+  (f) => !off.has(f),
+)
 
-process.stdout.write(names.join(';'))
+process.stdout.write(
+  JSON.stringify({
+    bytecode: bytecode.join(';'),
+    native: native.join(';'),
+    features: features.join(';'),
+  }),
+)

package/src/builtins.cpp

@@ -15,13 +15,8 @@ typedef struct {
 /* Generated by mikrojs_generate_bytecode() in CMake — includes + lookup table.
  * Adding a new module only requires updating the MODULES list in CMakeLists.txt. */
 #include "gen/mikro_builtins_table.h"
-#define builtins mikro_builtins
 
-/* External builtins registered by board/driver packages via MIK_REGISTER_BUILTIN() */
-// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
-mik_ext_builtin_t* mik__ext_builtin_head = nullptr;
-
-/* Deserialize bytecode into a module. Shared by core and external builtins. */
+/* Deserialize bytecode into a module. */
 static JSModuleDef* mik__deserialize_builtin(JSContext* ctx, const char* name,
                                              const uint8_t* data, uint32_t data_size) {
     const MIKPlatform* platform = MIK_GetPlatform();
@@ -68,15 +63,7 @@ static JSModuleDef* mik__deserialize_builtin(JSContext* ctx, const char* name,
 }
 
 JSModuleDef* mik__load_builtin(JSContext* ctx, const char* name) {
-    /* Check core builtins table */
-    for (const mik_builtin_t* p = builtins; p->name != NULL; ++p) {
-        if (strcmp(p->name, name) == 0) {
-            return mik__deserialize_builtin(ctx, name, p->data, p->data_size);
-        }
-    }
-
-    /* Check external builtins (registered by board/driver packages) */
-    for (mik_ext_builtin_t* p = mik__ext_builtin_head; p != nullptr; p = p->next) {
+    for (const mik_builtin_t* p = mikro_builtins; p->name != NULL; ++p) {
         if (strcmp(p->name, name) == 0) {
             return mik__deserialize_builtin(ctx, name, p->data, p->data_size);
         }

package/src/gpio_claim.cpp

@@ -42,7 +42,7 @@ static std::string mik__gpio_in_use_message(int gpio, const char* owner) {
     return message + owner;
 }
 
-JSValue mik__claim_gpios(JSContext* ctx, const int* gpios, int count, const char* owner) {
+JSValue MIK_ClaimGpios(JSContext* ctx, const int* gpios, int count, const char* owner) {
     for (int i = 0; i < count; i++) {
         if (MIK_ClaimGpio(gpios[i], owner)) continue;
         const char* holder = MIK_GpioOwner(gpios[i]);
@@ -52,12 +52,12 @@ JSValue mik__claim_gpios(JSContext* ctx, const int* gpios, int count, const char
         std::string message = mik__gpio_in_use_message(gpios[i], holder);
         JS_SetPropertyStr(ctx, error, "message",
                           JS_NewStringLen(ctx, message.data(), message.size()));
-        mik__release_gpios(gpios, i, owner);
+        MIK_ReleaseGpios(gpios, i, owner);
         return mik__result_err_obj(ctx, error);
     }
     return JS_UNDEFINED;
 }
 
-void mik__release_gpios(const int* gpios, int count, const char* owner) {
+void MIK_ReleaseGpios(const int* gpios, int count, const char* owner) {
     for (int i = 0; i < count; i++) MIK_ReleaseGpio(gpios[i], owner);
 }

package/src/mik_app_config.cpp

@@ -12,12 +12,18 @@
 
 static const char* TAG = "mik_app_config";
 
+/* memReserved when the config names none. The firmware lowers it for a build
+ * without radios, which has no WiFi or TLS demand to keep heap for. */
+#ifndef MIK_DEFAULT_MEM_RESERVED
+#define MIK_DEFAULT_MEM_RESERVED (64 * 1024)
+#endif
+
 void MIK_DefaultConfig(MIKConfig* config) {
     config->panic_restart_delay_ms = 1000;
     config->panic_mode = MIK_PANIC_RESTART;
     config->panic_sleep_duration_ms = 0;
     config->stack_size = 0;
-    config->mem_reserved = 64 * 1024;
+    config->mem_reserved = MIK_DEFAULT_MEM_RESERVED;
     config->fs_read_max = 0; /* 0 = runtime default (65536) */
     config->entry_point[0] = '\0';
     config->wifi_country[0] = '\0';

package/src/mik_ota_config.cpp

@@ -231,7 +231,7 @@ JSValue MIKOtaConfigReader::LoadDoc(JSContext* ctx, bool* out_failed) {
         return JS_UNDEFINED;
     }
 
-    char version[32] = {};
+    char version[MIK_OTA_VERSION_MAX] = {};
     if (!env_ || !env_->read_app_version ||
         !env_->read_app_version(env_->opaque, version, sizeof(version))) {
         return JS_UNDEFINED;
@@ -398,7 +398,7 @@ MIKOtaConfigWrite mik__ota_deliver_config(const MIKOtaEnv* env, const MIKOtaStor
                                           int trial_boots) {
     if (!config) return MIKOtaConfigWrite::kUnchanged;
 
-    char running[32] = {};
+    char running[MIK_OTA_VERSION_MAX] = {};
     if (!env || !env->read_app_version ||
         !env->read_app_version(env->opaque, running, sizeof(running))) {
         // The version the document has to be matched against could not be read,

package/src/mik_repl.cpp

@@ -34,9 +34,10 @@ static bool repl_async_skipped = false;  /* set when eval bails on paused async
 static MIKReplTransport* repl_transport = nullptr;
 /* Sized to hold the base map plus a maximum-length npm package name as the
  * `fw` identity (214 chars), with room to spare for a typical `[rev, name]`
- * pair. A max-length identity combined with a near-max device name can still
+ * pair, or a typical map with about ten package native modules (~30 bytes
+ * each). A max-length identity combined with a near-max device name can still
  * exceed this; refresh_ready then drops the name (never the identity). */
-static uint8_t ready_buf[384];
+static uint8_t ready_buf[512];
 static size_t ready_len = 0;
 
 /* Memory left for the app, captured once from the boot path (see
@@ -474,10 +475,7 @@ static bool handle_directive_impl(JSContext* ctx, const char* line, std::string&
         if (repl_transport && repl_transport->chip_name) {
             dir_printf(out, "Chip: %s\n", repl_transport->chip_name);
         }
-        const char* dev_id = MIK_GetPlatform()->get_device_id();
-        if (dev_id) {
-            dir_printf(out, "Device ID: %s\n", dev_id);
-        }
+        dir_printf(out, "Device ID: %s\n", MIK_GetPlatform()->get_device_id());
 
         /* Runtime uptime */
         int64_t uptime_us = platform->get_boot_us();
@@ -906,15 +904,19 @@ static std::vector<uint8_t> proto_complete(JSContext* ctx, const char* partial,
 
 /* Fills ready_buf/ready_len with CBOR device info:
  * {"chip": tstr, "id": tstr, "v": tstr, "board": tstr, "fw": tstr (when built
- * with MIK_FW_NAME), "name": tstr (only when named), "features": [tstr] (when
- * built with MIK_FW_FEATURES; host builds omit it)}.
+ * with MIK_BOARD_NAME), "name": tstr (only when named), "features": [tstr] (when
+ * built with MIK_FW_FEATURES; host builds omit it), "natives": [tstr]}.
  * `board` is mik__board_name(). `features` lists the firmware features the
  * build compiled in (from the comma-separated MIK_FW_FEATURES define), so the
- * host knows which feature-gated builtins this firmware carries.
- * `fw` is the firmware identity (the firmware project's package name). The
- * host only auto-flashes its bundled prebuilt over a device whose identity
- * matches that prebuilt; omitting it reads as firmware predating identity
- * reporting, which the host treats as its own bundled firmware.
+ * host knows which feature-gated builtins this firmware carries. `natives`
+ * lists the registered C modules outside the core namespace (package native
+ * modules compiled in, e.g. "@mikrojs/drivers/sh8601"; empty on a generic
+ * build), so the host can refuse an app importing one this firmware lacks.
+ * `fw` is the firmware identity: the board name the build set (MIK_BOARD_NAME),
+ * which `board` also reports. The host only auto-flashes its bundled image over
+ * a device whose identity matches that image's name; omitting it reads as
+ * firmware predating identity reporting, which the host treats as its own
+ * bundled firmware.
  * `name` carries the raw `[rev, name]` pair from mik.sys, so the host reads the
  * name and its revision together and can never see them out of step. Omitted
  * entirely when the device has never been named, which the host reads as
@@ -930,18 +932,25 @@ static std::vector<uint8_t> proto_complete(JSContext* ctx, const char* partial,
  * the runtime is new (see there). */
 static void refresh_ready(MIKReplTransport* transport);
 
+/* A package's native module, under the public specifier apps import
+ * ("@mikrojs/drivers/sh8601"). native: names are internal, and the host only
+ * compares public specifiers, so they would only take buffer space. */
+static bool is_package_module(const char* name) {
+    return strncmp(name, "native:", 7) != 0 && strncmp(name, "mikro/", 6) != 0;
+}
+
 /* Encodes the MSG_READY map into buf, or measures it when buf is null. Returns
  * the length the encoding needs, which exceeds cap when it did not fit. */
 static size_t encode_ready(uint8_t* buf, size_t cap, const char* chip, const char* id,
                            const char* version, const char* board, const char* fw,
-                           const char* name, const char* features, bool mem) {
+                           const char* name, const char* features, bool natives, bool mem) {
     /* Measuring calls pass buf=NULL; substitute a non-null base so
      * zero-length appends never hand memcpy a null pointer (UB). */
     static uint8_t measure_base;
     nanocbor_encoder_t enc;
     nanocbor_encoder_init(&enc, buf ? buf : &measure_base, buf ? cap : 0);
-    nanocbor_fmt_map(&enc,
-                     4 + (fw ? 1 : 0) + (name ? 1 : 0) + (features ? 1 : 0) + (mem ? 3 : 0));
+    nanocbor_fmt_map(&enc, 4 + (fw ? 1 : 0) + (name ? 1 : 0) + (features ? 1 : 0) +
+                               (natives ? 1 : 0) + (mem ? 3 : 0));
     nanocbor_put_tstr(&enc, "chip");
     nanocbor_put_tstr(&enc, chip);
     nanocbor_put_tstr(&enc, "id");
@@ -977,6 +986,17 @@ static size_t encode_ready(uint8_t* buf, size_t cap, const char* chip, const cha
             p = comma ? comma + 1 : p + len;
         }
     }
+    if (natives) {
+        size_t count = 0;
+        for (mik_module_desc_t* d = mik__module_registry_head; d != nullptr; d = d->next) {
+            if (is_package_module(d->name)) count++;
+        }
+        nanocbor_put_tstr(&enc, "natives");
+        nanocbor_fmt_array(&enc, count);
+        for (mik_module_desc_t* d = mik__module_registry_head; d != nullptr; d = d->next) {
+            if (is_package_module(d->name)) nanocbor_put_tstr(&enc, d->name);
+        }
+    }
     if (mem) {
         nanocbor_put_tstr(&enc, "heapFree");
         nanocbor_fmt_uint(&enc, boot_heap_free);
@@ -991,7 +1011,6 @@ static size_t encode_ready(uint8_t* buf, size_t cap, const char* chip, const cha
 static void refresh_ready(MIKReplTransport* transport) {
     const char* chip = transport->chip_name ? transport->chip_name : "unknown";
     const char* id = MIK_GetPlatform()->get_device_id();
-    if (!id) id = "";
     const char* version =
 #ifdef MIK_FW_VERSION
         MIK_FW_VERSION;
@@ -999,8 +1018,8 @@ static void refresh_ready(MIKReplTransport* transport) {
         "0.0.0-dev";
 #endif
     const char* fw =
-#ifdef MIK_FW_NAME
-        MIK_FW_NAME;
+#ifdef MIK_BOARD_NAME
+        MIK_BOARD_NAME;
 #else
         nullptr;
 #endif
@@ -1017,34 +1036,40 @@ static void refresh_ready(MIKReplTransport* transport) {
      * end but still reports the length it would have needed, so ready_len must
      * come from a run that actually fit: sending the measured length would read
      * past ready_buf. Fields go in order of how little losing them costs.
-     * `features` first: without it the host treats the firmware as legacy and
+     * The memory figures first (below). Then `natives`: without it the host
+     * skips the native module gate, as it does for firmware that predates it.
+     * Then `features`: without it the host treats the firmware as legacy and
      * skips the feature gate, which is how every older firmware behaves. Then
      * `name`, dropped whole rather than truncated, since a partial pair decodes
      * as a different name at the host. `fw` last: a dropped `fw` reads as the
      * host's own bundled firmware, re-enabling the auto-reflash the identity
      * exists to prevent. `board` and the core fields are never dropped. */
     bool mem = boot_mem_captured;
+    bool natives = true;
     /* Diagnostics are the first thing to go when the map does not fit: losing
      * them costs a memory figure, while losing `name` or `fw` breaks identity. */
-    if (mem && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, mem) >
-                   sizeof(ready_buf)) {
+    if (mem && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, natives,
+                            mem) > sizeof(ready_buf)) {
         mem = false;
     }
-    if (features &&
-        encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, mem) >
-            sizeof(ready_buf)) {
+    if (natives && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features,
+                                natives, mem) > sizeof(ready_buf)) {
+        natives = false;
+    }
+    if (features && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features,
+                                 natives, mem) > sizeof(ready_buf)) {
         features = nullptr;
     }
-    if (name && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, mem) >
-                    sizeof(ready_buf)) {
+    if (name && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, natives,
+                             mem) > sizeof(ready_buf)) {
         name = nullptr;
     }
-    if (fw && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, mem) >
-                  sizeof(ready_buf)) {
+    if (fw && encode_ready(nullptr, 0, chip, id, version, board, fw, name, features, natives,
+                           mem) > sizeof(ready_buf)) {
         fw = nullptr;
     }
     ready_len = encode_ready(ready_buf, sizeof(ready_buf), chip, id, version, board, fw, name,
-                             features, mem);
+                             features, natives, mem);
     if (ready_len > sizeof(ready_buf)) ready_len = 0;
 }
 

package/src/mik_result.cpp

@@ -3,6 +3,7 @@
 
 #include <quickjs.h>
 
+#include "mikrojs/mikrojs.h"
 #include "mikrojs/private.h"
 #include "mikrojs/utils.h"
 
@@ -83,14 +84,12 @@ JSValue mik__result_err(JSContext* ctx, int code, int platform_errno, const char
     return obj;
 }
 
-JSValue mik__result_err_named(JSContext* ctx, const char* name, const char* fmt, ...) {
-    va_list ap;
-    va_start(ap, fmt);
+static JSValue result_err_named_v(JSContext* ctx, const char* name, const char* fmt,
+                                  va_list ap) {
     /* 384 matches the HTTP task's error_buf: fetch errors pass through here
      * verbatim, and a smaller buffer truncates their trailing heap figures. */
     char msg[384];
     vsnprintf(msg, sizeof(msg), fmt, ap);
-    va_end(ap);
 
     JSValue error = JS_NewObject(ctx);
     JS_DefinePropertyValueStr(ctx, error, "name", JS_NewString(ctx, name), JS_PROP_C_W_E);
@@ -102,6 +101,26 @@ JSValue mik__result_err_named(JSContext* ctx, const char* name, const char* fmt,
     return obj;
 }
 
+JSValue mik__result_err_named(JSContext* ctx, const char* name, const char* fmt, ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    JSValue result = result_err_named_v(ctx, name, fmt, ap);
+    va_end(ap);
+    return result;
+}
+
+JSValue MIK_ResultOk(JSContext* ctx, JSValue value) { return mik__result_ok(ctx, value); }
+
+JSValue MIK_ResultOkVoid(JSContext* ctx) { return mik__result_ok_void(ctx); }
+
+JSValue MIK_ResultErrNamed(JSContext* ctx, const char* name, const char* fmt, ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    JSValue result = result_err_named_v(ctx, name, fmt, ap);
+    va_end(ap);
+    return result;
+}
+
 JSValue mik__result_err_tag(JSContext* ctx, const char* name) {
     JSValue error = JS_NewObject(ctx);
     JS_DefinePropertyValueStr(ctx, error, "name", JS_NewString(ctx, name), JS_PROP_C_W_E);

package/src/mik_sys.cpp

@@ -333,20 +333,18 @@ void mik__sys_api_init(JSContext* ctx, JSValue ns) {
     JS_SetPropertyStr(ctx, ns, "board", mik__sys_board(ctx));
     JS_SetPropertyStr(ctx, ns, "firmware", mik__sys_firmware(ctx));
 
-    /* Guard the platform function POINTERS, not just their results: a
-     * platform that omits an optional hook leaves a NULL pointer, and
-     * calling it is a segfault with no diagnostics (the sim was down for
-     * weeks because platform_node lacked get_reset_reason). */
     const MIKPlatform* platform = MIK_GetPlatform();
-    const char* device_id = platform->get_device_id ? platform->get_device_id() : NULL;
-    JS_SetPropertyStr(ctx, ns, "deviceId",
-                      device_id ? JS_NewString(ctx, device_id) : JS_UNDEFINED);
+    JS_SetPropertyStr(ctx, ns, "deviceId", JS_NewString(ctx, platform->get_device_id()));
 
     JS_SetPropertyStr(ctx, ns, "deviceName",
                       JS_NewCFunction(ctx, mik__sys_device_name, "deviceName", 0));
     JS_SetPropertyStr(ctx, ns, "setDeviceName",
                       JS_NewCFunction(ctx, mik__sys_set_device_name, "setDeviceName", 1));
 
+    /* Guard an optional hook's POINTER, not just its result: a platform that
+     * omits it leaves a NULL pointer, and calling it is a segfault with no
+     * diagnostics (the sim was down for weeks because platform_node lacked
+     * get_reset_reason). */
     const char* reset_reason =
         platform->get_reset_reason ? platform->get_reset_reason() : NULL;
     JS_SetPropertyStr(ctx, ns, "resetReason",

package/src/mikrojs.cpp

@@ -611,14 +611,6 @@ static void mik__check_module_collisions(void) {
             }
         }
     }
-    for (mik_ext_builtin_t* a = mik__ext_builtin_head; a != nullptr; a = a->next) {
-        for (mik_ext_builtin_t* b = a->next; b != nullptr; b = b->next) {
-            if (strcmp(a->name, b->name) == 0) {
-                fprintf(stderr, "FATAL: builtin module name collision: \"%s\"\n", a->name);
-                abort();
-            }
-        }
-    }
 }
 
 /* A chain of already-settled promises drains as one uninterrupted storm of
@@ -756,9 +748,9 @@ int MIK_Loop(MIKRuntime* mik_rt) {
     mik__stdin_consume(mik_rt->ctx);
     mik__timers_consume(mik_rt->ctx);
 
-    /* Call registered loop consumers */
+    /* Call registered loop consumers; a module may register only a destroy hook. */
     for (const auto& consumer : mik_rt->loop_consumers) {
-        consumer.consume_fn(mik_rt->ctx);
+        if (consumer.consume_fn) consumer.consume_fn(mik_rt->ctx);
     }
 
     mik__execute_jobs(mik_rt->ctx);

package/src/modules.cpp

@@ -227,7 +227,7 @@ static JSModuleDef* mik_module_loader_inner(JSContext* ctx, const char* module_n
         for (mik_module_desc_t* d = mik__module_registry_head; d != nullptr; d = d->next) {
             if (strcmp(d->name, module_name) == 0) {
                 JSModuleDef* lazy_m = d->init(ctx);
-                if (lazy_m && mik_rt && d->consume) {
+                if (lazy_m && mik_rt && (d->consume || d->destroy)) {
                     MIK_RegisterLoopConsumer(mik_rt, d->consume, d->destroy);
                 }
                 return lazy_m;
@@ -261,7 +261,7 @@ static JSModuleDef* mik_module_loader_inner(JSContext* ctx, const char* module_n
         for (mik_module_desc_t* d = mik__module_registry_head; d != nullptr; d = d->next) {
             if (strcmp(d->name, module_name) == 0) {
                 JSModuleDef* reg_m = d->init(ctx);
-                if (reg_m && mik_rt && d->consume) {
+                if (reg_m && mik_rt && (d->consume || d->destroy)) {
                     MIK_RegisterLoopConsumer(mik_rt, d->consume, d->destroy);
                 }
                 return reg_m;
@@ -282,18 +282,19 @@ static JSModuleDef* mik_module_loader_inner(JSContext* ctx, const char* module_n
         return NULL;
     }
 
-    /* Check external builtins for board/driver packages (e.g. "@mikrojs/your-driver").
-     * These are registered via MIK_REGISTER_BUILTIN() and resolved by package name
-     * before falling through to filesystem resolution. */
-    {
-        JSModuleDef* ext_m = mik__load_builtin(ctx, module_name);
-        if (ext_m) return ext_m;
-        /* NULL with an exception pending means the builtin was found but
-         * failed to load (deserialization or import resolution). Don't fall
-         * through to filesystem resolution — it would replace the real error
-         * with a generic "failed to resolve" one. Same probe as the mikro/
-         * branch above (JS_HasException, not JS_GetException + JS_IsNull). */
-        if (JS_HasException(ctx)) return NULL;
+    /* Package C modules registered under their public import specifier
+     * (MIK_REGISTER_PUBLIC_MODULE, e.g. "@mikrojs/drivers/sh8601"). Filesystem
+     * modules are named by path, so a bare name can only be one of these. */
+    if (module_name[0] != '/' && module_name[0] != '.') {
+        for (mik_module_desc_t* d = mik__module_registry_head; d != nullptr; d = d->next) {
+            if (strcmp(d->name, module_name) == 0) {
+                JSModuleDef* pkg_m = d->init(ctx);
+                if (pkg_m && mik_rt && (d->consume || d->destroy)) {
+                    MIK_RegisterLoopConsumer(mik_rt, d->consume, d->destroy);
+                }
+                return pkg_m;
+            }
+        }
     }
 
     return mik_module_load_from_fs(ctx, module_name);
@@ -450,7 +451,11 @@ int js_module_set_import_meta(JSContext* ctx, JSValue func_val, bool use_realpat
 
 /*
  * Resolve an export condition value to a string path.
- * Handles: string literals, and objects with "import" / "default" conditions.
+ * Handles: string literals, and objects with "import" / "default" / "native"
+ * conditions. A native module's "default" is JavaScript for hosts (tests, the
+ * simulator), so it wins; "native" last names the C/C++ source of a module
+ * without one, which is reported as missing from the firmware. A device never
+ * gets a native module's package files: the CLI keeps the import external.
  */
 static const char* mik__resolve_export_condition(JSContext* ctx, JSValue exp) {
     if (JS_IsString(exp)) {
@@ -459,7 +464,7 @@ static const char* mik__resolve_export_condition(JSContext* ctx, JSValue exp) {
     if (!JS_IsObject(exp)) {
         return NULL;
     }
-    static const char* conditions[] = {"import", "default"};
+    static const char* conditions[] = {"import", "default", "native"};
     for (size_t i = 0; i < countof(conditions); i++) {
         JSValue val = JS_GetPropertyStr(ctx, exp, conditions[i]);
         if (!JS_IsUndefined(val) && !JS_IsException(val)) {
@@ -698,18 +703,23 @@ static bool mik__is_anchored_name(const char* name) {
            strncmp(name, "@mikrojs/", 9) == 0;
 }
 
-/* A name registered via MIK_REGISTER_BUILTIN() is bytecode compiled into the
- * firmware — the same trust level as @mikrojs builtins, regardless of the
- * package's npm scope. */
-static bool mik__is_ext_builtin_name(const char* name) {
-    for (mik_ext_builtin_t* p = mik__ext_builtin_head; p != nullptr; p = p->next) {
-        if (strcmp(p->name, name) == 0) {
-            return true;
-        }
+/* A name registered via MIK_REGISTER_PUBLIC_MODULE(): a package's C module,
+ * imported by its bare specifier. */
+static bool mik__is_public_module_name(const char* name) {
+    for (mik_module_desc_t* d = mik__module_registry_head; d != nullptr; d = d->next) {
+        if (strcmp(d->name, name) == 0) return true;
     }
     return false;
 }
 
+/* A package export whose target is C/C++ source is a native module. */
+static bool mik__is_native_source(const char* path) {
+    const char* ext = strrchr(path, '.');
+    if (!ext) return false;
+    return strcmp(ext, ".c") == 0 || strcmp(ext, ".cc") == 0 || strcmp(ext, ".cpp") == 0 ||
+           strcmp(ext, ".cxx") == 0;
+}
+
 /* Record an edge in the module dependency graph: `base` imports `target`.
  * No-ops if the MIKRuntime is absent, base is empty/non-module, or target
  * is anchored. Keyed by normalized names. */
@@ -730,13 +740,9 @@ static char* mik__module_normalizer_impl(JSContext* ctx, const char* base_name,
 
     static const char internal_prefix[] = "native:";
     if (strncmp(name, internal_prefix, strlen(internal_prefix)) == 0) {
-        // Only firmware-embedded modules (native:, mikro/, @mikrojs/, registered
-        // external builtins) may import native: internals. A builtin may import
-        // any native: module, including another package's — native-level
-        // composition (e.g. an audio driver reusing a codec package's bindings)
-        // is intentionally allowed.
-        if (strncmp(base_name, "native:", 7) != 0 && strncmp(base_name, "mikro/", 6) != 0 &&
-            strncmp(base_name, "@mikrojs/", 9) != 0 && !mik__is_ext_builtin_name(base_name)) {
+        // Only firmware-embedded modules (native:, mikro/) may import native:
+        // internals.
+        if (strncmp(base_name, "native:", 7) != 0 && strncmp(base_name, "mikro/", 6) != 0) {
             JS_ThrowTypeError(
                 ctx, "Cannot import '%s': native modules can only be imported by firmware builtins",
                 name);
@@ -749,9 +755,9 @@ static char* mik__module_normalizer_impl(JSContext* ctx, const char* base_name,
         if (strncmp(name, "mikro/", 6) == 0 || strncmp(name, "native:", 7) == 0) {
             return js_strdup(ctx, name);
         }
-        /* Check if this bare specifier matches an external builtin (board/driver
-         * package). If so, pass through unchanged to avoid filesystem resolution. */
-        if (mik__is_ext_builtin_name(name)) {
+        /* A package's C module passes through too: the firmware provides it,
+         * so it is never looked up in node_modules. */
+        if (mik__is_public_module_name(name)) {
             return js_strdup(ctx, name);
         }
         /* Bare specifier — try node_modules resolution.
@@ -771,6 +777,16 @@ static char* mik__module_normalizer_impl(JSContext* ctx, const char* base_name,
                 }
                 char* resolved = mik__resolve_node_modules(ctx, base_dir, name);
                 js_free(ctx, base_dir);
+                if (resolved && mik__is_native_source(resolved)) {
+                    /* A registered native module never reaches node_modules, so
+                     * this one is not in the firmware. */
+                    js_free(ctx, resolved);
+                    JS_ThrowTypeError(ctx,
+                                      "Cannot import '%s': this firmware was not built with that "
+                                      "native module. Flash firmware that was built with it.",
+                                      name);
+                    return NULL;
+                }
                 if (resolved) {
                     return resolved;
                 }