@mikrojs/firmware 0.16.0 → 0.17.0-next.20260722220623

package/components/mikrojs/platform_esp32.cpp

@@ -4,6 +4,8 @@
 #include <esp_log.h>
 #include <esp_heap_caps.h>
 #include <esp_mac.h>
+#include <nanocbor/nanocbor.h>
+#include <nvs.h>
 #include <esp_random.h>
 #include <esp_sleep.h>
 #include <esp_system.h>
@@ -143,6 +145,61 @@ static int esp32_stdin_read(void* buf, size_t len) {
 /* Base MAC (6 bytes) encoded as Crockford's Base32 (10 lowercase chars).
  * Lossless: decode the 10 chars to recover the original 6 MAC bytes.
  * Crockford's Base32 excludes I, L, O, U to avoid visual ambiguity. */
+/* The name pair lives in mik.sys under `name`, stored the way every other
+ * mik.sys value is: a CBOR text-string blob, so `mikro/kv/nvs` and CMD_KV_SET
+ * both read and write it unchanged. */
+static char esp32_device_name[128] = {0};
+
+static const char* esp32_get_device_name(void) {
+    nvs_handle_t handle;
+    if (nvs_open("mik.sys", NVS_READONLY, &handle) != ESP_OK) return NULL;
+
+    size_t len = 0;
+    if (nvs_get_blob(handle, "name", NULL, &len) != ESP_OK || len == 0 || len > 256) {
+        nvs_close(handle);
+        return NULL;
+    }
+    uint8_t buf[256];
+    esp_err_t err = nvs_get_blob(handle, "name", buf, &len);
+    nvs_close(handle);
+    if (err != ESP_OK) return NULL;
+
+    nanocbor_value_t decoder;
+    nanocbor_decoder_init(&decoder, buf, len);
+    const uint8_t* str = NULL;
+    size_t str_len = 0;
+    if (nanocbor_get_tstr(&decoder, &str, &str_len) < 0) return NULL;
+    if (str_len == 0 || str_len >= sizeof(esp32_device_name)) return NULL;
+
+    memcpy(esp32_device_name, str, str_len);
+    esp32_device_name[str_len] = '\0';
+    return esp32_device_name;
+}
+
+static void esp32_set_device_name(const char* value) {
+    nvs_handle_t handle;
+    if (nvs_open("mik.sys", NVS_READWRITE, &handle) != ESP_OK) return;
+
+    if (!value || value[0] == '\0') {
+        nvs_erase_key(handle, "name");
+        nvs_commit(handle);
+        nvs_close(handle);
+        return;
+    }
+
+    size_t value_len = strlen(value);
+    uint8_t buf[256];
+    nanocbor_encoder_t enc;
+    nanocbor_encoder_init(&enc, buf, sizeof(buf));
+    if (nanocbor_put_tstrn(&enc, value, value_len) < 0) {
+        nvs_close(handle);
+        return;
+    }
+    nvs_set_blob(handle, "name", buf, nanocbor_encoded_len(&enc));
+    nvs_commit(handle);
+    nvs_close(handle);
+}
+
 static const char* esp32_get_device_id(void) {
     static const char cb32[] = "0123456789abcdefghjkmnpqrstvwxyz";
     static char id[11] = {0};  /* 6 bytes (48 bits) -> 10 x 5-bit chars + NUL */
@@ -275,6 +332,8 @@ static const MIKPlatform esp32_platform = {
     .stderr_write = esp32_stderr_write,
     .stdin_read = esp32_stdin_read,
     .get_device_id = esp32_get_device_id,
+    .get_device_name = esp32_get_device_name,
+    .set_device_name = esp32_set_device_name,
     .get_reset_reason = esp32_get_reset_reason,
 };
 

package/components/mikrojs/test/CMakeLists.txt

@@ -10,6 +10,7 @@ set(_MIK_TEST_SRCS
     i2s_test.cpp
     modules_extended_test.cpp
     modules_test.cpp
+    nvs_kv_test.cpp
     pins_test.cpp
     pwm_test.cpp
     repl_protocol_test.cpp

package/components/mikrojs/test/ble_test.cpp

@@ -28,7 +28,7 @@ static void teardown() {
     /* Ensure the BLE stack is stopped between tests so every test starts
      * from a clean state. stop() is idempotent. */
     JSValue ret = MIK_EvalModuleContent(
-        ctx, "mikrojs/ble-test-teardown",
+        ctx, "mikro/ble-test-teardown",
         "import {Ble} from \"native:mikro/ble\"; new Ble().stop();", 48);
     if (!JS_IsException(ret)) {
         JS_FreeValue(ctx, ret);
@@ -43,7 +43,7 @@ static void teardown() {
 }
 
 static JSValue eval_module(const char* code) {
-    JSValue ret = MIK_EvalModuleContent(ctx, "mikrojs/ble-test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/ble-test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(ctx, ret);
         mik__execute_jobs(ctx);

package/components/mikrojs/test/fs_js_test.cpp

@@ -44,7 +44,7 @@ static void fs_js_setup() {
 static void fs_js_teardown() { MIK_FreeRuntime(mik_rt); }
 
 static JSValue fs_eval_module(const char* code) {
-    JSValue ret = MIK_EvalModuleContent(mik_ctx, "mikrojs/test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(mik_ctx, "mikro/test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(mik_ctx, ret);
         mik__execute_jobs(mik_ctx);

package/components/mikrojs/test/fs_pub_test.cpp

@@ -25,7 +25,7 @@ static void pub_fs_teardown() {
 }
 
 static JSValue pub_fs_eval(const char* code) {
-    JSValue ret = MIK_EvalModuleContent(mik_ctx, "mikrojs/test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(mik_ctx, "mikro/test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(mik_ctx, ret);
         mik__execute_jobs(mik_ctx);
@@ -65,11 +65,11 @@ static int32_t get_global_int32(const char* name) {
 
 /* ── readFile ────────────────────────────────────────────────────── */
 
-TEST_CASE("mikrojs/fs readFile returns Uint8Array", "[fs]") {
+TEST_CASE("mikro/fs readFile returns Uint8Array", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { readFile } from "mikrojs/fs";
+        import { readFile } from "mikro/fs";
         const r = readFile("/dummy.txt");
         globalThis.__ok = r.ok;
         if (r.ok) globalThis.__content = new TextDecoder().decode(r.value);
@@ -85,11 +85,11 @@ TEST_CASE("mikrojs/fs readFile returns Uint8Array", "[fs]") {
     free(content);
 }
 
-TEST_CASE("mikrojs/fs readFile with utf-8 returns string", "[fs]") {
+TEST_CASE("mikro/fs readFile with utf-8 returns string", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { readFile } from "mikrojs/fs";
+        import { readFile } from "mikro/fs";
         const r = readFile("/dummy.txt", "utf-8");
         globalThis.__ok = r.ok;
         globalThis.__isString = r.ok && typeof r.value === "string";
@@ -108,11 +108,11 @@ TEST_CASE("mikrojs/fs readFile with utf-8 returns string", "[fs]") {
     free(content);
 }
 
-TEST_CASE("mikrojs/fs readFile returns NotFound error for missing file", "[fs]") {
+TEST_CASE("mikro/fs readFile returns NotFound error for missing file", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { readFile } from "mikrojs/fs";
+        import { readFile } from "mikro/fs";
         const r = readFile("/nonexistent.txt");
         globalThis.__ok = r.ok;
         if (!r.ok) {
@@ -136,11 +136,11 @@ TEST_CASE("mikrojs/fs readFile returns NotFound error for missing file", "[fs]")
 
 /* ── writeFile ───────────────────────────────────────────────────── */
 
-TEST_CASE("mikrojs/fs writeFile and readFile roundtrip", "[fs]") {
+TEST_CASE("mikro/fs writeFile and readFile roundtrip", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { writeFile, readFile } from "mikrojs/fs";
+        import { writeFile, readFile } from "mikro/fs";
         const w = writeFile("/test_pub_write.txt", "hello from pub fs");
         const r = readFile("/test_pub_write.txt", "utf-8");
         globalThis.__ok = w.ok && r.ok;
@@ -157,11 +157,11 @@ TEST_CASE("mikrojs/fs writeFile and readFile roundtrip", "[fs]") {
     free(content);
 }
 
-TEST_CASE("mikrojs/fs writeFile with Uint8Array", "[fs]") {
+TEST_CASE("mikro/fs writeFile with Uint8Array", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { writeFile, readFile } from "mikrojs/fs";
+        import { writeFile, readFile } from "mikro/fs";
         const data = new TextEncoder().encode("binary data");
         const w = writeFile("/test_pub_binary.txt", data);
         const r = readFile("/test_pub_binary.txt", "utf-8");
@@ -181,11 +181,11 @@ TEST_CASE("mikrojs/fs writeFile with Uint8Array", "[fs]") {
 
 /* ── stat ────────────────────────────────────────────────────────── */
 
-TEST_CASE("mikrojs/fs stat returns file info", "[fs]") {
+TEST_CASE("mikro/fs stat returns file info", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { stat } from "mikrojs/fs";
+        import { stat } from "mikro/fs";
         const r = stat("/dummy.txt");
         globalThis.__ok = r.ok;
         if (r.ok) {
@@ -208,11 +208,11 @@ TEST_CASE("mikrojs/fs stat returns file info", "[fs]") {
     TEST_ASSERT_FALSE(is_dir);
 }
 
-TEST_CASE("mikrojs/fs stat returns NotFound for missing path", "[fs]") {
+TEST_CASE("mikro/fs stat returns NotFound for missing path", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { stat } from "mikrojs/fs";
+        import { stat } from "mikro/fs";
         const r = stat("/nonexistent.txt");
         globalThis.__ok = r.ok;
         if (!r.ok) globalThis.__name = r.error.name;
@@ -230,11 +230,11 @@ TEST_CASE("mikrojs/fs stat returns NotFound for missing path", "[fs]") {
 
 /* ── exists ──────────────────────────────────────────────────────── */
 
-TEST_CASE("mikrojs/fs exists returns true for existing file", "[fs]") {
+TEST_CASE("mikro/fs exists returns true for existing file", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { exists } from "mikrojs/fs";
+        import { exists } from "mikro/fs";
         globalThis.__exists = exists("/dummy.txt");
     )");
     bool was_exception = JS_IsException(ret);
@@ -245,11 +245,11 @@ TEST_CASE("mikrojs/fs exists returns true for existing file", "[fs]") {
     TEST_ASSERT_TRUE(file_exists);
 }
 
-TEST_CASE("mikrojs/fs exists returns false for missing file", "[fs]") {
+TEST_CASE("mikro/fs exists returns false for missing file", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { exists } from "mikrojs/fs";
+        import { exists } from "mikro/fs";
         globalThis.__exists = exists("/nonexistent.txt");
     )");
     bool was_exception = JS_IsException(ret);
@@ -262,11 +262,11 @@ TEST_CASE("mikrojs/fs exists returns false for missing file", "[fs]") {
 
 /* ── mkdir / readDir / rmdir ─────────────────────────────────────── */
 
-TEST_CASE("mikrojs/fs mkdir, readDir, rmdir roundtrip", "[fs]") {
+TEST_CASE("mikro/fs mkdir, readDir, rmdir roundtrip", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { mkdir, readDir, writeFile, unlink, rmdir } from "mikrojs/fs";
+        import { mkdir, readDir, writeFile, unlink, rmdir } from "mikro/fs";
         const m = mkdir("/test_pub_dir");
         const w = writeFile("/test_pub_dir/file.txt", "hi");
         const entries = readDir("/test_pub_dir");
@@ -288,11 +288,11 @@ TEST_CASE("mikrojs/fs mkdir, readDir, rmdir roundtrip", "[fs]") {
 
 /* ── unlink / rename ─────────────────────────────────────────────── */
 
-TEST_CASE("mikrojs/fs unlink and rename", "[fs]") {
+TEST_CASE("mikro/fs unlink and rename", "[fs]") {
     pub_fs_setup();
 
     JSValue ret = pub_fs_eval(R"(
-        import { writeFile, rename, readFile, unlink } from "mikrojs/fs";
+        import { writeFile, rename, readFile, unlink } from "mikro/fs";
         const w = writeFile("/test_pub_rename_src.txt", "rename me");
         const mv = rename("/test_pub_rename_src.txt", "/test_pub_rename_dst.txt");
         const r = readFile("/test_pub_rename_dst.txt", "utf-8");

package/components/mikrojs/test/http_server_test.cpp

@@ -33,7 +33,7 @@ static void setup() {
 static void teardown() { MIK_FreeRuntime(rt); }
 
 static JSValue eval_module(const char* code) {
-    JSValue ret = MIK_EvalModuleContent(ctx, "mikrojs/test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(ctx, ret);
         mik__execute_jobs(ctx);
@@ -43,13 +43,19 @@ static JSValue eval_module(const char* code) {
 
 static void ensure_initialized() {
     const char* code = "import { nextRequest } from 'native:mikro/http_server';";
-    JSValue ret = MIK_EvalModuleContent(ctx, "mikrojs/test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(ctx, ret);
         mik__execute_jobs(ctx);
     }
 }
 
+/* nextRequest() resolves with the closed sentinel unless a server is running.
+ * Fake a handle so tests can drive the queues without esp_http_server; clear
+ * it before teardown so destroy doesn't httpd_stop the fake. */
+static void fake_server_start() { mik__hs(rt)->server = reinterpret_cast<httpd_handle_t>(1); }
+static void fake_server_stop() { mik__hs(rt)->server = nullptr; }
+
 static void read_global_string(const char* key, char* out, size_t out_len) {
     JSValue global = JS_GetGlobalObject(ctx);
     JSValue v = JS_GetPropertyStr(ctx, global, key);
@@ -139,6 +145,7 @@ TEST_CASE("http_server consume with no messages is a no-op", "[httpd]") {
 TEST_CASE("nextRequest delivers method/url and respond fills the exchange", "[httpd]") {
     setup();
     ensure_initialized();
+    fake_server_start();
 
     MIKHsExchange* ex = push_request("GET", "/hello?x=1");
 
@@ -168,6 +175,7 @@ TEST_CASE("nextRequest delivers method/url and respond fills the exchange", "[ht
     size_t headerCount = ex->header_count;
 
     free_exchange(ex);
+    fake_server_stop();
     teardown();
 
     TEST_ASSERT_EQUAL_STRING("GET", method);
@@ -184,6 +192,7 @@ TEST_CASE("nextRequest delivers method/url and respond fills the exchange", "[ht
 TEST_CASE("respond tolerates a bodyless response", "[httpd]") {
     setup();
     ensure_initialized();
+    fake_server_start();
 
     MIKHsExchange* ex = push_request("POST", "/save");
 
@@ -208,6 +217,7 @@ TEST_CASE("respond tolerates a bodyless response", "[httpd]") {
     bool bodyNull = (ex->body == nullptr);
 
     free_exchange(ex);
+    fake_server_stop();
     teardown();
 
     TEST_ASSERT_FALSE_MESSAGE(threw, "bodyless respond must not throw");

package/components/mikrojs/test/http_test.cpp

@@ -43,7 +43,7 @@ static void setup() {
 
 static void ensure_http_initialized() {
     const char* code = "import { request } from 'native:mikro/http';";
-    JSValue ret = MIK_EvalModuleContent(ctx, "mikrojs/test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(ctx, ret);
         mik__execute_jobs(ctx);
@@ -53,7 +53,7 @@ static void ensure_http_initialized() {
 static void teardown() { MIK_FreeRuntime(rt); }
 
 static JSValue eval_module(const char* code) {
-    JSValue ret = MIK_EvalModuleContent(ctx, "mikrojs/test", code, strlen(code));
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/test", code, strlen(code));
     if (!JS_IsException(ret)) {
         JS_FreeValue(ctx, ret);
         mik__execute_jobs(ctx);

package/components/mikrojs/test/modules_extended_test.cpp

@@ -108,8 +108,8 @@ TEST_CASE("native:* internal import blocked from user code", "[modules]") {
     TEST_ASSERT_NULL_MESSAGE(result, "native:mikro/sys should be blocked from user code");
 
     // But a built-in module should be allowed to import native:mikro/sys
-    result = mik_module_normalizer(ctx, "mikrojs/sys", "native:mikro/sys", nullptr);
-    TEST_ASSERT_NOT_NULL_MESSAGE(result, "native:mikro/sys should be allowed from mikrojs/ modules");
+    result = mik_module_normalizer(ctx, "mikro/sys", "native:mikro/sys", nullptr);
+    TEST_ASSERT_NOT_NULL_MESSAGE(result, "native:mikro/sys should be allowed from mikro/ modules");
     TEST_ASSERT_EQUAL_STRING("native:mikro/sys", result);
     js_free(ctx, result);
 

package/components/mikrojs/test/modules_test.cpp

@@ -17,7 +17,7 @@ TEST_CASE("Bare module names pass through unchanged", "[modules]") {
     JSRuntime* rt = JS_NewRuntime();
     JSContext* ctx = JS_NewContext(rt);
 
-    assert_normalizes_to(ctx, "main.js", "mikrojs/fs", "mikrojs/fs");
+    assert_normalizes_to(ctx, "main.js", "mikro/fs", "mikro/fs");
     assert_normalizes_to(ctx, "main.js", "lodash", "lodash");
 
     JS_FreeContext(ctx);
@@ -112,7 +112,7 @@ TEST_CASE("withUnload() unloads a module after the callback returns", "[modules]
 
     /* Exercises the real shipped mikrojs/module withUnload() on device. */
     const char* code =
-        "import {withUnload} from 'mikrojs/module';\n"
+        "import {withUnload} from 'mikro/module';\n"
         "globalThis.__first = await withUnload(import('./leaf.js'), (mod) => mod.v);\n"
         "globalThis.__after = true;\n"
         "const b = await import('./leaf.js');\n"

package/components/mikrojs/test/nvs_kv_test.cpp

@@ -0,0 +1,245 @@
+#include <nvs_flash.h>
+
+#include "mikrojs.h"
+#include "private.h"
+#include "quickjs.h"
+#include "unity.h"
+
+/* nvs_kv module is self-registered via MIK_REGISTER_MODULE and lazily
+ * initialized. These tests cover the mik.kv / mik.sys namespace split on
+ * real NVS flash; each test clears both namespaces it touched. */
+
+static MIKRuntime* rt;
+static JSContext* ctx;
+
+static void setup() {
+    /* The bare test runtime has no MIK_Main; init NVS flash once ourselves. */
+    static bool nvs_ready = false;
+    if (!nvs_ready) {
+        esp_err_t err = nvs_flash_init();
+        if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+            nvs_flash_erase();
+            nvs_flash_init();
+        }
+        nvs_ready = true;
+    }
+    rt = MIK_NewRuntime();
+    ctx = MIK_GetJSContext(rt);
+}
+
+static void teardown() { MIK_FreeRuntime(rt); }
+
+static JSValue eval_module(const char* code) {
+    /* The name must pass the loader's builtin-importer check ("mikro/" prefix)
+     * or native: imports are denied. */
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/test", code, strlen(code));
+    if (!JS_IsException(ret)) {
+        JS_FreeValue(ctx, ret);
+        mik__execute_jobs(ctx);
+    } else {
+        JSValue exc = JS_GetException(ctx);
+        const char* msg = JS_ToCString(ctx, exc);
+        printf("eval exception: %s\n", msg ? msg : "(unprintable)");
+        JS_FreeCString(ctx, msg);
+        JS_Throw(ctx, exc);
+    }
+    return ret;
+}
+
+/* ── Module exports ───────────────────────────────────────────────── */
+
+TEST_CASE("native:mikro/nvs_kv exports sys functions and Result-returning clears", "[kv]") {
+    setup();
+
+    JSValue ret = eval_module(R"(
+        import { clear, sysSet, sysGet, sysRemove, sysClear } from "native:mikro/nvs_kv";
+        globalThis.__sysSetIsFunc = typeof sysSet === "function";
+        globalThis.__sysGetIsFunc = typeof sysGet === "function";
+        globalThis.__sysRemoveIsFunc = typeof sysRemove === "function";
+        globalThis.__sysClearIsFunc = typeof sysClear === "function";
+        globalThis.__clearOk = clear().ok === true;
+        globalThis.__sysClearOk = sysClear().ok === true;
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+
+    JSValue global = JS_GetGlobalObject(ctx);
+
+    JSValue v;
+    v = JS_GetPropertyStr(ctx, global, "__sysSetIsFunc");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysSet should be a function");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysGetIsFunc");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysGet should be a function");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysRemoveIsFunc");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysRemove should be a function");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysClearIsFunc");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysClear should be a function");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__clearOk");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear() should return {ok: true}");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysClearOk");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysClear() should return {ok: true}");
+    JS_FreeValue(ctx, v);
+
+    JS_FreeValue(ctx, global);
+    teardown();
+}
+
+/* ── Namespace isolation ──────────────────────────────────────────── */
+
+TEST_CASE("native:mikro/nvs_kv kv and sys namespaces are isolated", "[kv]") {
+    setup();
+
+    JSValue ret = eval_module(R"(
+        import { set, get, remove, clear, sysSet, sysGet, sysRemove, sysClear }
+            from "native:mikro/nvs_kv";
+        clear();
+        sysClear();
+        set("probe", "app");
+        sysSet("probe", "sys");
+        globalThis.__kvSees = get("probe") === "app";
+        globalThis.__sysSees = sysGet("probe") === "sys";
+        remove("probe");
+        globalThis.__kvGone = get("probe") === undefined;
+        globalThis.__sysSurvivesRemove = sysGet("probe") === "sys";
+        sysRemove("probe");
+        globalThis.__sysGone = sysGet("probe") === undefined;
+        clear();
+        sysClear();
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+
+    JSValue global = JS_GetGlobalObject(ctx);
+
+    JSValue v;
+    v = JS_GetPropertyStr(ctx, global, "__kvSees");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "kv should read its own value under a shared key");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysSees");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sys should read its own value under a shared key");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__kvGone");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "remove should delete the kv entry");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysSurvivesRemove");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "kv remove must not touch the sys entry");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysGone");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysRemove should delete the sys entry");
+    JS_FreeValue(ctx, v);
+
+    JS_FreeValue(ctx, global);
+    teardown();
+}
+
+/* ── Clear scopes ─────────────────────────────────────────────────── */
+
+TEST_CASE("native:mikro/nvs_kv clear() leaves sys, sysClear() leaves kv", "[kv]") {
+    setup();
+
+    JSValue ret = eval_module(R"(
+        import { set, get, clear, sysSet, sysGet, sysClear } from "native:mikro/nvs_kv";
+        clear();
+        sysClear();
+        set("a", 1);
+        sysSet("b", 2);
+        clear();
+        globalThis.__kvGone = get("a") === undefined;
+        globalThis.__sysIntact = sysGet("b") === 2;
+        set("a", 1);
+        sysClear();
+        globalThis.__kvIntact = get("a") === 1;
+        globalThis.__sysGone = sysGet("b") === undefined;
+        clear();
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+
+    JSValue global = JS_GetGlobalObject(ctx);
+
+    JSValue v;
+    v = JS_GetPropertyStr(ctx, global, "__kvGone");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear should empty the kv namespace");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysIntact");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear must not touch the sys namespace");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__kvIntact");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysClear must not touch the kv namespace");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysGone");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "sysClear should empty the sys namespace");
+    JS_FreeValue(ctx, v);
+
+    JS_FreeValue(ctx, global);
+    teardown();
+}
+
+/* ── Public API full clear ────────────────────────────────────────── */
+
+TEST_CASE("mikro/kv/nvs clear({full: true}) empties both stores", "[kv]") {
+    setup();
+
+    JSValue ret = eval_module(R"(
+        import { nvsStorage } from "mikro/kv/nvs";
+        import { set, get, clear, sysSet, sysGet, sysClear } from "native:mikro/nvs_kv";
+        clear();
+        sysClear();
+        set("a", 1);
+        sysSet("b", 2);
+        const partial = nvsStorage.clear();
+        globalThis.__partialOk = partial.ok === true;
+        globalThis.__kvAfterPartial = get("a") === undefined;
+        globalThis.__sysAfterPartial = sysGet("b") === 2;
+        set("a", 1);
+        const full = nvsStorage.clear({full: true});
+        globalThis.__fullOk = full.ok === true;
+        globalThis.__kvAfterFull = get("a") === undefined;
+        globalThis.__sysAfterFull = sysGet("b") === undefined;
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+
+    JSValue global = JS_GetGlobalObject(ctx);
+
+    JSValue v;
+    v = JS_GetPropertyStr(ctx, global, "__partialOk");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear() should return ok");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__kvAfterPartial");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear() should empty app data");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysAfterPartial");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear() must leave the system store intact");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__fullOk");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear({full: true}) should return ok");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__kvAfterFull");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear({full: true}) should empty app data");
+    JS_FreeValue(ctx, v);
+
+    v = JS_GetPropertyStr(ctx, global, "__sysAfterFull");
+    TEST_ASSERT_TRUE_MESSAGE(JS_ToBool(ctx, v), "clear({full: true}) should empty the system store");
+    JS_FreeValue(ctx, v);
+
+    JS_FreeValue(ctx, global);
+    teardown();
+}