@mikrojs/native 0.8.0 → 0.9.0

package/CMakeLists.txt

@@ -81,7 +81,7 @@ endif()
 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 observable observable/lazy observable/operators pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
+    MODULES cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
     MODULE_PREFIX "mikrojs"
     SYMBOL_PREFIX "mikrojs"
     TARGET gen_bytecode

package/include/mikrojs/mikrojs.h

@@ -29,8 +29,20 @@ typedef enum MIKLogFlush {
     MIK_LOG_FLUSH_LINE = 1,
 } MIKLogFlush;
 
+/* What the device does after an uncaught exception (a "panic"). Mirror of
+ * the `onPanic.mode` field in the host-side TS config. */
+typedef enum MIKPanicMode {
+    MIK_PANIC_RESTART = 0,    /* default: reboot after the grace window */
+    MIK_PANIC_DEEP_SLEEP = 1, /* deep-sleep panic_sleep_duration_ms; wake reboots */
+} MIKPanicMode;
+
 typedef struct MIKConfig {
+    /* Grace window after a panic, awake and reachable, before the action
+     * fires (applies to both modes). */
     int panic_restart_delay_ms;
+    MIKPanicMode panic_mode;
+    /* Deep-sleep length for MIK_PANIC_DEEP_SLEEP; ignored otherwise. */
+    int panic_sleep_duration_ms;
     size_t stack_size;
     uint32_t mem_reserved;
     uint32_t fs_read_max; /* 0 = keep runtime default (65536) */

package/include/mikrojs/platform.h

@@ -14,6 +14,10 @@ typedef struct MIKPlatform {
     int64_t (*get_rtc_us)(void);        /* RTC timer, survives deep sleep */
     uint32_t (*random)(void);
     void (*restart)(void);
+    /** Enter deep sleep for `us` microseconds; the timer wake reboots the
+     *  chip, so this never returns on hardware. NULL on platforms without
+     *  deep sleep (hosts), where callers fall back to restart(). */
+    void (*deep_sleep_us)(uint64_t us);
     void (*yield)(void);
     size_t (*get_free_system_mem)(void);
     size_t (*get_min_free_system_mem)(void); /* All-time low watermark */

package/include/mikrojs/private.h

@@ -184,6 +184,16 @@ char* mik_module_normalizer(JSContext* ctx, const char* base_name, const char* n
  * mid-evaluation, or unknown modules. */
 int mik__unload_module(JSContext* ctx, const char* normalized_name);
 
+/* Unload the module whose namespace object is `ns` (reverse lookup via
+ * JS_FindModuleByNamespace, then mik__unload_module by name). Returns the
+ * number of modules freed, 0 if `ns` is not a currently-loaded module's
+ * namespace, or -1 with a pending JS exception. Backs `disposable()`. */
+int mik__unload_namespace(JSContext* ctx, JSValueConst ns);
+
+/* True if `ns` is the namespace of a currently-loaded, non-anchored module
+ * (i.e. one that disposable() is allowed to unload). */
+bool mik__is_unloadable_namespace(JSContext* ctx, JSValueConst ns);
+
 int js_module_set_import_meta(JSContext* ctx, JSValue func_val, bool use_realpath, bool is_main);
 
 JSValue mik__get_args(JSContext* ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -55,6 +55,7 @@
     "./runtime/inspect/types": "./runtime/inspect/types.ts",
     "./runtime/kv/shared": "./runtime/kv/shared.ts",
     "./runtime/kv/types": "./runtime/kv/types.ts",
+    "./runtime/module/types": "./runtime/module/types.ts",
     "./runtime/neopixel/types": "./runtime/neopixel/types.ts",
     "./runtime/observable/operators": "./runtime/observable/operators.ts",
     "./runtime/observable/types": "./runtime/observable/types.ts",
@@ -78,7 +79,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.8.0"
+    "@mikrojs/quickjs": "0.9.0"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/globals.d.ts

@@ -64,28 +64,4 @@ declare interface ImportMeta {
   readonly basename: string
   readonly path: string
   readonly env: Readonly<Record<string, string | undefined>>
-  /**
-   * Evict a module from the runtime's module cache, recursively freeing
-   * any transitive dependency whose only importer was the unloaded module.
-   * Builtin modules (native:*, mikrojs/*, @mikrojs/*) are anchored
-   * and cannot be unloaded.
-   *
-   * Intended for use with dynamic imports: a static `import` at the top of
-   * the module creates a binding that pins the imported module's exports,
-   * so unloading it while the binding is live reclaims nothing. Prefer
-   * `const x = await import(spec)` + local scope + `import.meta.unload(spec)`.
-   *
-   * **Incompatible with `bundle: true`.** When the build bundles modules
-   * into chunks, source-level specifiers like `./phases/display.js` no
-   * longer correspond to loaded module names (they become chunk names like
-   * `display-GYVGL5MB.js`) — the unload call silently resolves to 0 and
-   * frees nothing. Projects that rely on dynamic-import-then-unload for
-   * memory reclaim need `bundle: false` so specifier strings survive to
-   * runtime unchanged.
-   *
-   * Resolves to the number of modules actually freed (root + transitive
-   * orphans), after a GC pass has run so a subsequent `memoryUsage()`
-   * snapshot reflects the reclaim.
-   */
-  unload(specifier: string): Promise<number>
 }

package/runtime/internal.d.ts

@@ -46,6 +46,11 @@ declare module 'native:sys' {
   }
   export function jsMemoryUsage(): JsMemoryUsage
   export function gc(): void
+  /** Unload the module whose namespace object is `ns`; returns the number of
+   *  modules freed (0 if `ns` is not a loaded module's namespace). */
+  export function unloadNamespace(ns: object): number
+  /** True if `ns` is the namespace of a loaded, non-anchored (non-builtin) module. */
+  export function isUnloadableNamespace(ns: object): boolean
   export function activeTimers(): number
   export function setTime(millisSinceEpoch: number): void
   export function uptime(): {boot: number; rtc: number}

package/runtime/module/module.ts

@@ -0,0 +1,37 @@
+import {isUnloadableNamespace, unloadNamespace} from 'native:sys'
+
+/**
+ * Load a dynamically imported module, run `use` with it, then unload it and
+ * reclaim its memory. Use for app phases that pull in code you won't need again:
+ *
+ * ```ts
+ * const status = await withUnload(
+ *   import('./phases/modem.js'),
+ *   (modem) => modem.runPhase(input),
+ * )
+ * // the modem phase is unloaded and reclaimed by the time this resolves
+ * ```
+ *
+ * The module is unloaded when `use` returns (or throws), including any transitive
+ * dependency whose only importer was this module. Don't return one of the
+ * module's exports from `use`; that keeps the module alive. Throws if the
+ * resolved value isn't an unloadable module namespace (e.g. a builtin
+ * `mikrojs/*` or `native:*` module).
+ *
+ * This is non-standard: standard JavaScript modules stay loaded for the life of
+ * the program, and a later `import` re-evaluates an unloaded module from scratch.
+ */
+export async function withUnload<T extends object, R>(
+  mod: Promise<T>,
+  use: (mod: T) => R | Promise<R>,
+): Promise<R> {
+  const ns = await mod
+  if (!isUnloadableNamespace(ns)) {
+    throw new TypeError('withUnload() expects an unloadable module namespace')
+  }
+  try {
+    return await use(ns)
+  } finally {
+    unloadNamespace(ns)
+  }
+}

package/runtime/module/types.ts

@@ -0,0 +1,21 @@
+/** Load a dynamically imported module, run `use` with it, then unload it and
+ *  reclaim its memory:
+ *
+ *  ```ts
+ *  const status = await withUnload(
+ *    import('./phases/modem.js'),
+ *    (modem) => modem.runPhase(input),
+ *  )
+ *  ```
+ *
+ *  The module (and any transitive dependency whose only importer was it) is
+ *  unloaded when `use` returns or throws. Don't return one of the module's
+ *  exports from `use`; that keeps it alive. Throws if the resolved value isn't
+ *  an unloadable module namespace (e.g. a builtin `mikrojs/*` or `native:*`).
+ *
+ *  Non-standard: standard JavaScript modules stay loaded for the life of the
+ *  program, and a later `import` re-evaluates an unloaded module from scratch. */
+export declare function withUnload<T extends object, R>(
+  mod: Promise<T>,
+  use: (mod: T) => R | Promise<R>,
+): Promise<R>

package/src/mik_app_config.cpp

@@ -13,6 +13,8 @@ static const char* TAG = "mik_app_config";
 
 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->fs_read_max = 0; /* 0 = runtime default (65536) */
@@ -318,9 +320,19 @@ int MIK_LoadConfig(const char* base_path, MIKConfig* config) {
         if (buf) {
             double num_val;
 
-            if (mik__json_get_number(buf, "panicRestartDelay", &num_val)) {
+            if (mik__json_get_number(buf, "onPanic.delay", &num_val)) {
                 config->panic_restart_delay_ms = (int)num_val;
             }
+            char panic_mode_str[16];
+            if (mik__json_get_string(buf, "onPanic.mode", panic_mode_str,
+                                     sizeof(panic_mode_str))) {
+                config->panic_mode = strcmp(panic_mode_str, "deepSleep") == 0
+                                         ? MIK_PANIC_DEEP_SLEEP
+                                         : MIK_PANIC_RESTART;
+            }
+            if (mik__json_get_number(buf, "onPanic.duration", &num_val)) {
+                config->panic_sleep_duration_ms = (int)num_val;
+            }
             if (mik__json_get_number(buf, "stackSize", &num_val)) {
                 config->stack_size = (size_t)num_val;
             }

package/src/mik_sys.cpp

@@ -96,6 +96,24 @@ static JSValue mik__sys_gc(JSContext* ctx, JSValue this_val, int argc, JSValue*
     return JS_UNDEFINED;
 }
 
+/* Backs withUnload()'s unload step. Unloads the module whose
+ * namespace is argv[0]; returns the number of modules freed (0 if not a
+ * loaded module's namespace). Refcounting reclaims the memory once the
+ * caller's reference drops; no GC here. */
+static JSValue mik__sys_unload_namespace(JSContext* ctx, JSValue this_val, int argc,
+                                         JSValue* argv) {
+    int rv = mik__unload_namespace(ctx, argv[0]);
+    if (rv < 0) return JS_EXCEPTION;
+    return JS_NewInt32(ctx, rv);
+}
+
+/* True if argv[0] is the namespace of a loaded, non-anchored module.
+ * withUnload() uses this to reject builtins (native:/mikrojs//@mikrojs/). */
+static JSValue mik__sys_is_unloadable_namespace(JSContext* ctx, JSValue this_val, int argc,
+                                                JSValue* argv) {
+    return JS_NewBool(ctx, mik__is_unloadable_namespace(ctx, argv[0]));
+}
+
 static JSValue mik__sys_active_timers(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
     MIKRuntime* mik_rt = static_cast<MIKRuntime*>(JS_GetContextOpaque(ctx));
     CHECK_NOT_NULL(mik_rt);
@@ -220,6 +238,11 @@ void mik__sys_api_init(JSContext* ctx, JSValue ns) {
     JS_SetPropertyStr(ctx, ns, "jsMemoryUsage",
                       JS_NewCFunction(ctx, mik__sys_js_memory_usage, "jsMemoryUsage", 0));
     JS_SetPropertyStr(ctx, ns, "gc", JS_NewCFunction(ctx, mik__sys_gc, "gc", 0));
+    JS_SetPropertyStr(ctx, ns, "unloadNamespace",
+                      JS_NewCFunction(ctx, mik__sys_unload_namespace, "unloadNamespace", 1));
+    JS_SetPropertyStr(
+        ctx, ns, "isUnloadableNamespace",
+        JS_NewCFunction(ctx, mik__sys_is_unloadable_namespace, "isUnloadableNamespace", 1));
     JS_SetPropertyStr(ctx, ns, "activeTimers",
                       JS_NewCFunction(ctx, mik__sys_active_timers, "activeTimers", 0));
     JS_SetPropertyStr(ctx, ns, "setTime",

package/src/mik_text_encoding.cpp

@@ -242,44 +242,138 @@ static const JSCFunctionListEntry mik__text_decoder_proto_funcs[] = {
 
 static const char b64_table[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
-static const uint8_t b64_decode_table[256] = {
+/* The base64 decoder below is ported from QuickJS-NG (quickjs.c, `b64_decode`
+ * and its lookup tables), which implements the WHATWG forgiving-base64 decode
+ * algorithm. QuickJS-NG is MIT licensed:
+ *   Copyright (c) 2017-2024 Fabrice Bellard, Charlie Gordon and contributors.
+ * We use only the standard alphabet (atob/btoa never decode base64url) and
+ * surface decode failures as our own error type rather than a DOMException. */
+enum { K_VAL = 1u, K_WS = 2u };
+
+/* Sextet value per base64 character (0 for non-base64 bytes; validity is gated
+ * by b64_flags below). Positional initializer to stay standard C++. */
+static const uint8_t b64_val[256] = {
     /* clang-format off */
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255, 62,255,255,255, 63,
-     52, 53, 54, 55, 56, 57, 58, 59, 60, 61,255,255,255,  0,255,255,
-    255,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14,
-     15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,255,255,255,255,255,
-    255, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
-     41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
-    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,62, 0, 0, 0,63,
+    52,53,54,55,56,57,58,59,60,61, 0, 0, 0, 0, 0, 0,
+     0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,10,11,12,13,14,
+    15,16,17,18,19,20,21,22,23,24,25, 0, 0, 0, 0, 0,
+     0,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,
+    41,42,43,44,45,46,47,48,49,50,51, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
     /* clang-format on */
 };
 
+/* Per-byte class: K_WS (2) for ASCII whitespace, K_VAL (1) for the 64 standard
+ * base64 alphabet characters, 0 (invalid) otherwise. */
+static const char b64_flags[256] = {
+    /* clang-format off */
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 2, 2, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1,
+     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,
+     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
+     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,
+     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
+     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+    /* clang-format on */
+};
+
+/* Implements https://infra.spec.whatwg.org/#forgiving-base64-decode.
+ * Writes decoded bytes to dst and returns the count; sets *err on malformed
+ * input. dst must have room for at least (len / 4) * 3 + 3 bytes. */
+static size_t b64_decode(const char* src, size_t len, uint8_t* dst, int* err) {
+    size_t i, j;
+    uint32_t acc;
+    int seen, pad;
+    unsigned ch;
+
+    acc = 0;
+    seen = 0;
+    for (i = 0, j = 0; i < len; i++) {
+        ch = (unsigned char)src[i];
+        if ((b64_flags[ch] & K_WS)) continue;
+        if (!(b64_flags[ch] & K_VAL)) break;
+        acc = (acc << 6) | b64_val[ch];
+        seen++;
+        if (seen == 4) {
+            dst[j++] = (acc >> 16) & 0xFF;
+            dst[j++] = (acc >> 8) & 0xFF;
+            dst[j++] = acc & 0xFF;
+            seen = 0;
+            acc = 0;
+        }
+    }
+
+    if (seen != 0) {
+        if (seen == 3) {
+            dst[j++] = (acc >> 10) & 0xFF;
+            dst[j++] = (acc >> 2) & 0xFF;
+        } else if (seen == 2) {
+            dst[j++] = (acc >> 4) & 0xFF;
+        } else {
+            *err = 1;
+            return 0;
+        }
+        for (pad = 0; i < len; i++) {
+            ch = (unsigned char)src[i];
+            if (pad < 2 && ch == '=') {
+                pad++;
+            } else if (!(b64_flags[ch] & K_WS)) {
+                break;
+            }
+        }
+        if (pad != 0 && seen + pad != 4) {
+            *err = 1;
+            return 0;
+        }
+    }
+
+    *err = i < len;
+    return j;
+}
+
 /* btoa: encode a binary string to base64.
- * Per the web spec, each JS character's code point is treated as a raw byte.
- * We must iterate by code point, not by UTF-8 bytes, since JS_ToCStringLen
- * returns UTF-8 where e.g. U+0080 becomes two bytes (\xC2\x80). */
+ * Per the web spec, the argument is first coerced to a string (ToString), then
+ * each character's code point is treated as a raw byte. We iterate by code
+ * point, not by UTF-8 bytes, since JS_ToCStringLen would turn e.g. U+0080 into
+ * two bytes (\xC2\x80). */
 static JSValue mik__btoa(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
-    JSValue str_val = argv[0];
+    JSValue str_val = JS_ToString(ctx, argv[0]);
+    if (JS_IsException(str_val)) return JS_EXCEPTION;
+
     JSValue len_val = JS_GetPropertyStr(ctx, str_val, "length");
     int64_t len;
     if (JS_ToInt64(ctx, &len, len_val)) {
         JS_FreeValue(ctx, len_val);
+        JS_FreeValue(ctx, str_val);
         return JS_EXCEPTION;
     }
     JS_FreeValue(ctx, len_val);
 
     /* Extract code points into a byte buffer, validating latin1 range */
     uint8_t* bytes = static_cast<uint8_t*>(js_malloc(ctx, len > 0 ? len : 1));
-    if (!bytes) return JS_EXCEPTION;
+    if (!bytes) {
+        JS_FreeValue(ctx, str_val);
+        return JS_EXCEPTION;
+    }
 
     JSAtom charCodeAt_atom = JS_NewAtom(ctx, "charCodeAt");
     for (int64_t i = 0; i < len; i++) {
@@ -289,6 +383,7 @@ static JSValue mik__btoa(JSContext* ctx, JSValue this_val, int argc, JSValue* ar
         if (JS_IsException(code)) {
             JS_FreeAtom(ctx, charCodeAt_atom);
             js_free(ctx, bytes);
+            JS_FreeValue(ctx, str_val);
             return JS_EXCEPTION;
         }
         int32_t cp;
@@ -297,6 +392,7 @@ static JSValue mik__btoa(JSContext* ctx, JSValue this_val, int argc, JSValue* ar
         if (cp > 0xFF) {
             JS_FreeAtom(ctx, charCodeAt_atom);
             js_free(ctx, bytes);
+            JS_FreeValue(ctx, str_val);
             return JS_ThrowRangeError(ctx,
                                       "The string to be encoded contains characters outside of the "
                                       "Latin1 range");
@@ -304,6 +400,7 @@ static JSValue mik__btoa(JSContext* ctx, JSValue this_val, int argc, JSValue* ar
         bytes[i] = (uint8_t)cp;
     }
     JS_FreeAtom(ctx, charCodeAt_atom);
+    JS_FreeValue(ctx, str_val);
 
     size_t out_len = 4 * ((len + 2) / 3);
     char* out = static_cast<char*>(js_malloc(ctx, out_len + 1));
@@ -332,55 +429,32 @@ static JSValue mik__btoa(JSContext* ctx, JSValue this_val, int argc, JSValue* ar
     return ret;
 }
 
-/* atob: decode a base64 string to a binary string */
+/* atob: decode a base64 string to a binary string. The argument is coerced to
+ * a string (ToString) per spec, then decoded via the ported forgiving-base64
+ * decoder above. */
 static JSValue mik__atob(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    JSValue str_val = JS_ToString(ctx, argv[0]);
+    if (JS_IsException(str_val)) return JS_EXCEPTION;
     size_t len;
-    const char* str = JS_ToCStringLen(ctx, &len, argv[0]);
+    const char* str = JS_ToCStringLen(ctx, &len, str_val);
+    JS_FreeValue(ctx, str_val);
     if (!str) return JS_EXCEPTION;
 
-    /* Strip whitespace and validate */
-    size_t out_cap = (len * 3) / 4 + 1;
-    char* out = static_cast<char*>(js_malloc(ctx, out_cap));
+    size_t out_cap = (len / 4) * 3 + 3;
+    uint8_t* out = static_cast<uint8_t*>(js_malloc(ctx, out_cap));
     if (!out) {
         JS_FreeCString(ctx, str);
         return JS_EXCEPTION;
     }
 
-    uint32_t accum = 0;
-    int bits = 0;
-    size_t j = 0;
-    int pad = 0;
-
-    for (size_t i = 0; i < len; i++) {
-        char ch = str[i];
-        if (ch == ' ' || ch == '\t' || ch == '\n' || ch == '\r' || ch == '\f') continue;
-        if (ch == '=') {
-            pad++;
-            continue;
-        }
-        if (pad > 0) {
-            /* Data after padding */
-            js_free(ctx, out);
-            JS_FreeCString(ctx, str);
-            return JS_ThrowSyntaxError(ctx,
-                                       "The string to be decoded is not correctly encoded");
-        }
-        uint8_t val = b64_decode_table[(uint8_t)ch];
-        if (val == 255) {
-            js_free(ctx, out);
-            JS_FreeCString(ctx, str);
-            return JS_ThrowSyntaxError(ctx,
-                                       "The string to be decoded is not correctly encoded");
-        }
-        accum = (accum << 6) | val;
-        bits += 6;
-        if (bits >= 8) {
-            bits -= 8;
-            out[j++] = (char)((accum >> bits) & 0xFF);
-        }
-    }
-
+    int err = 0;
+    size_t j = b64_decode(str, len, out, &err);
     JS_FreeCString(ctx, str);
+    if (err) {
+        js_free(ctx, out);
+        return JS_ThrowSyntaxError(ctx,
+                                   "The string to be decoded is not correctly encoded");
+    }
 
     /* Convert decoded bytes to a JS string. Bytes 0x80-0xFF must become
      * their corresponding Unicode code points (U+0080-U+00FF), which in

package/src/mikrojs.cpp

@@ -89,8 +89,9 @@ static void mik__add_exports(JSContext* ctx, JSModuleDef* m, const char* const*
 }
 
 static const char* const sys_exports[] = {
-    "evalScript", "memoryUsage", "jsMemoryUsage", "gc",       "setTime",      "uptime",
-    "restart",    "version",     "board",         "firmware", "deviceId",     "activeTimers"};
+    "evalScript", "memoryUsage", "jsMemoryUsage",  "gc",          "setTime",
+    "uptime",     "restart",     "version",        "board",       "firmware",
+    "deviceId",   "activeTimers", "unloadNamespace", "isUnloadableNamespace"};
 
 static int mik__sys_module_init(JSContext* ctx, JSModuleDef* m) {
     JSValue ns = JS_NewObjectProto(ctx, JS_NULL);
@@ -542,6 +543,14 @@ int MIK_Loop(MIKRuntime* mik_rt) {
     if (mik_rt->restart_at_us > 0) {
         const MIKPlatform* platform = MIK_GetPlatform();
         if (platform->get_boot_us() >= mik_rt->restart_at_us) {
+            /* The grace window has elapsed; take the configured panic action.
+             * In deep-sleep mode the timer wake reboots the chip, so the wake
+             * IS the restart — and the live --recover window is forfeit by
+             * design (the CPU is suspended). If the platform has no deep-sleep
+             * hook (hosts), fall through to a plain restart. */
+            if (mik_rt->config.panic_mode == MIK_PANIC_DEEP_SLEEP && platform->deep_sleep_us) {
+                platform->deep_sleep_us((uint64_t)mik_rt->config.panic_sleep_duration_ms * 1000);
+            }
             platform->restart();
         }
         return 0;

package/src/modules.cpp

@@ -360,39 +360,6 @@ JSModuleDef* mik_module_loader(JSContext* ctx, const char* module_name, void* op
 #define MIK__PATHSEP '/'
 #define MIK__PATHSEP_STR "/"
 
-/* import.meta.unload(specifier) implementation. Resolves `specifier` via
- * the standard normalizer using the captured base path (the owning
- * module's logical path, stripped of the `file://` prefix), evicts the
- * resulting module + orphaned deps via mik__unload_module, then runs a
- * GC pass so the caller's next memoryUsage() snapshot reflects the free. */
-static JSValue mik__import_meta_unload(JSContext* ctx, JSValueConst this_val,
-                                       int argc, JSValueConst* argv,
-                                       int magic, JSValueConst* func_data) {
-    (void)magic;
-    (void)this_val;
-    if (argc < 1 || !JS_IsString(argv[0])) {
-        return JS_ThrowTypeError(ctx, "import.meta.unload: specifier must be a string");
-    }
-    const char* specifier = JS_ToCString(ctx, argv[0]);
-    if (!specifier) return JS_EXCEPTION;
-    const char* base = JS_ToCString(ctx, func_data[0]);
-    if (!base) {
-        JS_FreeCString(ctx, specifier);
-        return JS_EXCEPTION;
-    }
-    char* normalized = mik_module_normalizer(ctx, base, specifier, nullptr);
-    JS_FreeCString(ctx, specifier);
-    JS_FreeCString(ctx, base);
-    if (!normalized) return JS_EXCEPTION;
-
-    int rv = mik__unload_module(ctx, normalized);
-    js_free(ctx, normalized);
-    if (rv < 0) return JS_EXCEPTION;
-
-    JS_RunGC(JS_GetRuntime(ctx));
-    return JS_NewInt32(ctx, rv);
-}
-
 int js_module_set_import_meta(JSContext* ctx, JSValue func_val, bool use_realpath, bool is_main) {
     JSModuleDef* m;
     char buf[PATH_MAX + 16] = {0};
@@ -454,16 +421,6 @@ int js_module_set_import_meta(JSContext* ctx, JSValue func_val, bool use_realpat
                                   JS_PROP_C_W_E);
     }
 
-    /* Attach import.meta.unload(specifier). Needs the owning module's
-     * logical path (not URL) as the normalizer base. Only exposed for
-     * file-backed modules; synthetic modules don't have a stable path. */
-    if (use_realpath) {
-        JSValue base_str = JS_NewString(ctx, buf + 7 /* strip "file://" */);
-        JSValue unload_fn = JS_NewCFunctionData(ctx, mik__import_meta_unload, 1, 0, 1, &base_str);
-        JS_FreeValue(ctx, base_str);
-        JS_DefinePropertyValueStr(ctx, meta_obj, "unload", unload_fn, JS_PROP_C_W_E);
-    }
-
     JS_FreeValue(ctx, meta_obj);
     return 0;
 }
@@ -942,3 +899,32 @@ int mik__unload_module(JSContext* ctx, const char* normalized_name) {
 
     return freed_count;
 }
+
+/* Resolve `ns` to the loaded module it is the namespace of, returning its
+ * normalized name as a C string (caller frees via JS_FreeCString), or NULL
+ * if `ns` is not an object or not a loaded module's namespace. */
+static const char* mik__module_name_from_ns(JSContext* ctx, JSValueConst ns) {
+    if (!JS_IsObject(ns)) return nullptr;
+    JSModuleDef* m = JS_FindModuleByNamespace(ctx, ns);
+    if (!m) return nullptr;
+    JSAtom atom = JS_GetModuleName(ctx, m);
+    const char* name = JS_AtomToCString(ctx, atom);
+    JS_FreeAtom(ctx, atom);
+    return name;
+}
+
+int mik__unload_namespace(JSContext* ctx, JSValueConst ns) {
+    const char* name = mik__module_name_from_ns(ctx, ns);
+    if (!name) return 0; /* not a loaded module's namespace: idempotent no-op */
+    int rv = mik__unload_module(ctx, name);
+    JS_FreeCString(ctx, name);
+    return rv;
+}
+
+bool mik__is_unloadable_namespace(JSContext* ctx, JSValueConst ns) {
+    const char* name = mik__module_name_from_ns(ctx, ns);
+    if (!name) return false;
+    bool ok = !mik__is_anchored_name(name);
+    JS_FreeCString(ctx, name);
+    return ok;
+}