@mikrojs/native 0.0.7

package/scripts/compare-minifiers.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+/**
+ * Compare minifier output sizes for firmware runtime modules.
+ *
+ * Usage: node scripts/compare-minifiers.js [--open]
+ *
+ * Builds runtime modules with each minifier/level combination, collects
+ * bundle sizes, and writes an HTML report to compare-minifiers.html.
+ * Pass --open to open the report in the default browser.
+ */
+
+import {execSync} from 'node:child_process'
+import {existsSync, mkdirSync, readFileSync, rmSync, writeFileSync} from 'node:fs'
+import {join} from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+const ROOT = join(fileURLToPath(import.meta.url), '../..')
+const CONFIGS = [
+  {name: 'esbuild', args: ''},
+  {name: 'terser', args: '-DMIK_MINIFIER=terser'},
+  {name: 'terser max', args: '-DMIK_MINIFIER=terser -DMIK_MINIFY_LEVEL=max'},
+  {name: 'swc', args: '-DMIK_MINIFIER=swc'},
+  {name: 'swc max', args: '-DMIK_MINIFIER=swc -DMIK_MINIFY_LEVEL=max'},
+]
+
+function run(cmd) {
+  return execSync(cmd, {cwd: ROOT, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']})
+}
+
+function parseBundleOutput(output) {
+  const modules = new Map()
+  for (const match of output.matchAll(/Bundled (\S+) \((\d+) bytes/g)) {
+    modules.set(match[1], Number(match[2]))
+  }
+  return modules
+}
+
+function buildConfig(config) {
+  const buildDir = join(ROOT, `.compare-${config.name.replace(/\s+/g, '-')}`)
+  if (existsSync(buildDir)) rmSync(buildDir, {recursive: true, force: true})
+  mkdirSync(buildDir, {recursive: true})
+
+  const configureCmd = `cmake -B ${buildDir} ${config.args} .`
+  run(configureCmd)
+
+  const buildCmd = `cmake --build ${buildDir} --target gen_bytecode`
+  const output = run(buildCmd)
+
+  const modules = parseBundleOutput(output)
+  rmSync(buildDir, {recursive: true, force: true})
+  return modules
+}
+
+// Run all builds
+// eslint-disable-next-line no-console
+console.log('Comparing minifiers for firmware runtime modules...\n')
+const results = []
+for (const config of CONFIGS) {
+  process.stdout.write(`  Building with ${config.name}...`)
+  const start = Date.now()
+  const modules = buildConfig(config)
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1)
+  // eslint-disable-next-line no-console
+  console.log(` ${modules.size} modules (${elapsed}s)`)
+  results.push({name: config.name, modules})
+}
+
+// Collect all module names
+const allModules = [...new Set(results.flatMap((r) => [...r.modules.keys()]))].sort()
+
+// Find the baseline (esbuild)
+const baseline = results[0].modules
+
+// Generate HTML
+function generateHtml() {
+  const rows = allModules.map((mod) => {
+    const cells = results.map((r) => {
+      const size = r.modules.get(mod) ?? 0
+      const base = baseline.get(mod) ?? 0
+      const diff = size - base
+      const pct = base > 0 ? ((diff / base) * 100).toFixed(1) : '—'
+      return {size, diff, pct}
+    })
+    return {mod, cells}
+  })
+
+  const totals = results.map((r) => {
+    const total = allModules.reduce((sum, mod) => sum + (r.modules.get(mod) ?? 0), 0)
+    const baseTotal = allModules.reduce((sum, mod) => sum + (baseline.get(mod) ?? 0), 0)
+    const diff = total - baseTotal
+    const pct = baseTotal > 0 ? ((diff / baseTotal) * 100).toFixed(1) : '—'
+    return {total, diff, pct}
+  })
+
+  const configHeaders = results.map((r) => `<th>${r.name}</th>`).join('\n            ')
+
+  const tableRows = rows
+    .map(({mod, cells}) => {
+      const tds = cells
+        .map(({size, diff, pct}, i) => {
+          if (i === 0) return `<td class="num">${size}</td>`
+          const cls = diff < 0 ? 'better' : diff > 0 ? 'worse' : 'same'
+          const sign = diff > 0 ? '+' : ''
+          return `<td class="num ${cls}">${size} <span class="diff">(${sign}${diff}, ${sign}${pct}%)</span></td>`
+        })
+        .join('\n              ')
+      return `          <tr>
+            <td class="mod">${mod}</td>
+            ${tds}
+          </tr>`
+    })
+    .join('\n')
+
+  const totalRow = totals
+    .map(({total, diff, pct}, i) => {
+      if (i === 0) return `<td class="num"><strong>${total}</strong></td>`
+      const cls = diff < 0 ? 'better' : diff > 0 ? 'worse' : 'same'
+      const sign = diff > 0 ? '+' : ''
+      return `<td class="num ${cls}"><strong>${total}</strong> <span class="diff">(${sign}${diff}, ${sign}${pct}%)</span></td>`
+    })
+    .join('\n            ')
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Minifier Comparison — mikrojs firmware runtime modules</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; background: #f8f9fa; color: #1a1a1a; }
+    h1 { font-size: 1.4rem; margin-bottom: 0.25rem; }
+    .subtitle { color: #666; margin-bottom: 1.5rem; font-size: 0.9rem; }
+    table { border-collapse: collapse; width: 100%; background: white; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    th { background: #1a1a1a; color: white; padding: 0.6rem 1rem; text-align: left; font-weight: 500; font-size: 0.85rem; }
+    td { padding: 0.45rem 1rem; border-bottom: 1px solid #eee; font-size: 0.85rem; }
+    tr:last-child td { border-bottom: none; }
+    tr:hover td { background: #f5f5f5; }
+    .mod { font-family: ui-monospace, monospace; font-size: 0.8rem; }
+    .num { text-align: right; font-family: ui-monospace, monospace; font-size: 0.8rem; white-space: nowrap; }
+    .diff { font-size: 0.75rem; opacity: 0.7; }
+    .better { color: #16a34a; }
+    .worse { color: #dc2626; }
+    .same { color: #666; }
+    .total-row td { border-top: 2px solid #1a1a1a; background: #f9fafb; }
+    .legend { margin-top: 1rem; font-size: 0.8rem; color: #666; }
+    .legend span { margin-right: 1.5rem; }
+    .timestamp { margin-top: 0.5rem; font-size: 0.75rem; color: #999; }
+  </style>
+</head>
+<body>
+  <h1>Minifier Comparison</h1>
+  <p class="subtitle">Bundle sizes (bytes) for mikrojs firmware runtime modules. Diff relative to esbuild baseline.</p>
+  <table>
+    <thead>
+      <tr>
+        <th>Module</th>
+        ${configHeaders}
+      </tr>
+    </thead>
+    <tbody>
+${tableRows}
+      <tr class="total-row">
+        <td class="mod"><strong>Total</strong></td>
+        ${totalRow}
+      </tr>
+    </tbody>
+  </table>
+  <p class="legend">
+    <span class="better">Green = smaller than esbuild</span>
+    <span class="worse">Red = larger than esbuild</span>
+    <span class="same">Gray = same size</span>
+  </p>
+  <p class="timestamp">Generated ${new Date().toISOString()}</p>
+</body>
+</html>`
+}
+
+const html = generateHtml()
+const outPath = join(ROOT, 'compare-minifiers.html')
+writeFileSync(outPath, html)
+// eslint-disable-next-line no-console
+console.log(`\nReport written to ${outPath}`)
+
+if (process.argv.includes('--open')) {
+  const {platform} = await import('node:os')
+  const cmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start' : 'xdg-open'
+  execSync(`${cmd} ${outPath}`)
+}

package/scripts/compile-bytecode.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Compile a bundled JS module to a C bytecode header using qjsc.
+#
+# Usage: compile-bytecode.sh <qjsc> <input.js> <output.h> <module_name> <symbol_name>
+#
+# Reads <input>.externals for external module declarations.
+
+set -e
+
+QJSC="$1"
+INPUT="$2"
+OUTPUT="$3"
+MODULE_NAME="$4"
+SYMBOL_NAME="$5"
+
+EXTERNALS_FILE="${INPUT%.js}.externals"
+
+# Build -M flags for external modules
+M_FLAGS=""
+if [ -f "$EXTERNALS_FILE" ]; then
+    while IFS= read -r ext || [ -n "$ext" ]; do
+        [ -n "$ext" ] && M_FLAGS="$M_FLAGS -M $ext"
+    done < "$EXTERNALS_FILE"
+fi
+
+# Compile with qjsc: ES module, strip source, custom name and script name.
+#
+# We use -s (strip source), NOT -ss (strip source + debug info). Stripping
+# debug info via -ss drops b->filename from every function bytecode
+# (quickjs.c writes filename inside `if (s->allow_debug)` — see
+# JS_WriteFunctionBytecode). Once filename is gone, JS_GetScriptOrModuleName
+# returns JS_ATOM_NULL for any function in the deserialized module, and
+# js_import_meta fails with "import.meta not supported in this context" —
+# so any runtime module that reads `import.meta.*` (e.g. mikrojs/env
+# accessing import.meta.env) breaks at runtime. The ~1 KB heap saving
+# from stripping debug isn't worth crippling a spec-standard module API.
+# shellcheck disable=SC2086
+"$QJSC" -m -s -N "$SYMBOL_NAME" -n "$MODULE_NAME" $M_FLAGS -o "$OUTPUT" "$INPUT"

package/scripts/copy-prebuild.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import {copyFileSync, existsSync, mkdirSync} from 'node:fs'
+import {dirname, resolve} from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const source = resolve(pkgRoot, 'addon', 'build', 'Release', 'mikrojs_node.node')
+
+if (!existsSync(source)) {
+  // eslint-disable-next-line no-console
+  console.error(`No native binary at ${source}. Run 'cmake-js compile --directory addon' first.`)
+  process.exit(1)
+}
+
+const targetDir = resolve(pkgRoot, 'prebuilds', `${process.platform}-${process.arch}`)
+mkdirSync(targetDir, {recursive: true})
+const target = resolve(targetDir, 'mikrojs.napi.node')
+copyFileSync(source, target)
+// eslint-disable-next-line no-console
+console.log(`Copied → ${target}`)

package/scripts/generate-symbol-map.js

@@ -0,0 +1,146 @@
+/* eslint-disable no-console */
+import {execFileSync, spawnSync} from 'node:child_process'
+import {createHash} from 'node:crypto'
+import {readFileSync, writeFileSync} from 'node:fs'
+
+/**
+ * Generate a compact symbol map from an ELF for offline panic-trace decoding.
+ *
+ * Toolchain-agnostic: takes a binutils prefix (e.g. "riscv32-esp-elf-",
+ * "xtensa-esp32-elf-", "arm-none-eabi-") so the same script works for any
+ * target a future port (RP2350, etc.) might add.
+ *
+ * Usage: node generate-symbol-map.js <elf> <out.json> <toolchain-prefix> [chip]
+ */
+
+const [, , elfPath, outPath, toolchainPrefix, chip = ''] = process.argv
+
+if (!elfPath || !outPath || !toolchainPrefix) {
+  console.error('Usage: node generate-symbol-map.js <elf> <out.json> <toolchain-prefix> [chip]')
+  process.exit(1)
+}
+
+const nm = `${toolchainPrefix}nm`
+const addr2line = `${toolchainPrefix}addr2line`
+
+const elfBuf = readFileSync(elfPath)
+const elfHash = createHash('sha256').update(elfBuf).digest('hex')
+
+// nm -S --defined-only --print-size: "ADDR SIZE T name"
+// Symbols without a size (size = 0) are skipped — they're typically labels,
+// not real functions, and would only pollute the lookup table.
+const nmOut = execFileSync(nm, ['-S', '--defined-only', '--print-size', elfPath], {
+  encoding: 'utf8',
+  maxBuffer: 256 * 1024 * 1024,
+})
+
+const rawFuncs = []
+const addrs = []
+let codeMin = Infinity
+let codeMax = 0
+
+for (const line of nmOut.split('\n')) {
+  const m = line.match(/^([0-9a-f]+)\s+([0-9a-f]+)\s+([tTwW])\s+(.+)$/)
+  if (!m) continue
+  const start = parseInt(m[1], 16)
+  const size = parseInt(m[2], 16)
+  if (size === 0) continue
+  rawFuncs.push({start, size, mangled: m[4]})
+  addrs.push('0x' + start.toString(16))
+  if (start < codeMin) codeMin = start
+  if (start + size > codeMax) codeMax = start + size
+}
+
+if (rawFuncs.length === 0) {
+  console.error('No function symbols found in ELF — nothing to do.')
+  process.exit(1)
+}
+
+// Resolve every function entry's file:line in a single addr2line invocation.
+// `-f` = function name, `-C` = demangle, `-s` = base names only (we keep
+// full paths from the file column instead — `-s` would shorten file paths).
+// Actually we want full paths: drop -s.
+const a2l = spawnSync(addr2line, ['-f', '-C', '-e', elfPath], {
+  input: addrs.join('\n') + '\n',
+  encoding: 'utf8',
+  maxBuffer: 256 * 1024 * 1024,
+})
+
+if (a2l.status !== 0) {
+  console.error(`addr2line failed: ${a2l.stderr}`)
+  process.exit(1)
+}
+
+// addr2line output: two lines per input address — function name, then file:line
+const a2lLines = a2l.stdout.split('\n')
+
+const fileIdx = new Map()
+const files = []
+const nameIdx = new Map()
+const names = []
+
+function internFile(f) {
+  let i = fileIdx.get(f)
+  if (i === undefined) {
+    i = files.length
+    files.push(f)
+    fileIdx.set(f, i)
+  }
+  return i
+}
+
+function internName(n) {
+  let i = nameIdx.get(n)
+  if (i === undefined) {
+    i = names.length
+    names.push(n)
+    nameIdx.set(n, i)
+  }
+  return i
+}
+
+const funcs = [] // [start, size, nameIdx, fileIdx, line]
+
+for (let i = 0; i < rawFuncs.length; i++) {
+  const fn = rawFuncs[i]
+  const fname = (a2lLines[i * 2] || '').trim()
+  const floc = (a2lLines[i * 2 + 1] || '').trim()
+
+  // addr2line emits "??" when DWARF info is missing.
+  const displayName = fname && fname !== '??' ? fname : fn.mangled
+  let fIdx = -1
+  let lineNo = 0
+  if (floc && floc !== '??:?' && floc !== '??:0') {
+    // "path/to/file.cpp:123" (or "...:123 (discriminator N)")
+    const colon = floc.lastIndexOf(':')
+    if (colon > 0) {
+      const file = floc.slice(0, colon)
+      const lineStr = floc.slice(colon + 1).split(/\s/)[0]
+      const parsed = parseInt(lineStr, 10)
+      if (file && file !== '??' && Number.isFinite(parsed)) {
+        fIdx = internFile(file)
+        lineNo = parsed
+      }
+    }
+  }
+  funcs.push([fn.start, fn.size, internName(displayName), fIdx, lineNo])
+}
+
+funcs.sort((a, b) => a[0] - b[0])
+
+const out = {
+  v: 1,
+  chip,
+  elfHash,
+  codeStart: codeMin,
+  codeEnd: codeMax,
+  files,
+  names,
+  funcs,
+}
+
+writeFileSync(outPath, JSON.stringify(out))
+console.log(
+  `Wrote ${outPath}: ${funcs.length} funcs, ${files.length} files, ${names.length} names, ` +
+    `code range 0x${codeMin.toString(16)}-0x${codeMax.toString(16)}`,
+)

package/src/builtins.cpp

@@ -0,0 +1,82 @@
+
+#include <cinttypes>
+#include <cstdio>
+
+#include "mikrojs/platform.h"
+#include "mikrojs/private.h"
+#include "mikrojs/utils.h"
+
+typedef struct {
+    const char* name;
+    const uint8_t* data;
+    uint32_t data_size;
+} mik_builtin_t;
+
+/* 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/mikrojs_builtins_table.h"
+#define builtins mikrojs_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. */
+static JSModuleDef* mik__deserialize_builtin(JSContext* ctx, const char* name,
+                                             const uint8_t* data, uint32_t data_size) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+
+    platform->log(MIK_LOG_DEBUG, "mikrojs", "Loading builtin '%s' (%u bytes, bc_version=%u, data_ptr=%p)", name,
+             data_size, data_size > 0 ? data[0] : 0, (void*)data);
+
+    JSValue obj = JS_ReadObject(ctx, data, data_size, JS_READ_OBJ_BYTECODE);
+
+    if (JS_IsException(obj)) {
+        platform->log(MIK_LOG_ERROR, "mikrojs", "Failed to deserialize bytecode for builtin '%s' (%u bytes)", name,
+                 data_size);
+        /* Leave the JS exception on ctx so the caller can propagate the
+         * real error (e.g. "Maximum call stack size exceeded") instead of
+         * replacing it with a generic "not available" message. */
+        return NULL;
+    }
+
+    if (JS_VALUE_GET_TAG(obj) != JS_TAG_MODULE) {
+        platform->log(MIK_LOG_ERROR, "mikrojs", "Builtin '%s' bytecode is not a module (tag=%d)", name,
+                 JS_VALUE_GET_TAG(obj));
+        JS_FreeValue(ctx, obj);
+        return NULL;
+    }
+
+    /* Initialize import.meta (url, env, etc.) for the builtin module */
+    js_module_set_import_meta(ctx, obj, false, false);
+
+    /* Resolve imports so the module loader is called for dependencies */
+    if (JS_ResolveModule(ctx, obj) < 0) {
+        platform->log(MIK_LOG_ERROR, "mikrojs", "Failed to resolve imports for builtin '%s'", name);
+        JS_FreeValue(ctx, obj);
+        return NULL;
+    }
+
+    JSModuleDef* m = static_cast<JSModuleDef*>(JS_VALUE_GET_PTR(obj));
+    JS_FreeValue(ctx, obj);
+
+    return m;
+}
+
+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) {
+        if (strcmp(p->name, name) == 0) {
+            return mik__deserialize_builtin(ctx, name, p->data, p->data_size);
+        }
+    }
+
+    return NULL;
+}

package/src/cutils_compat.c

@@ -0,0 +1,38 @@
+/* Provide non-inline definitions of cutils.h functions for C++ linkage.
+ *
+ * cutils.h declares these as static inline, so they have internal linkage
+ * and aren't visible to C++ translation units that use cutils_wrap.h
+ * (declarations only). This file provides real external definitions. */
+#include <cutils.h>
+
+int mik__dbuf_put(DynBuf *s, const void *data, size_t len) {
+    return dbuf_put(s, data, len);
+}
+
+int mik__dbuf_putc(DynBuf *s, uint8_t val) {
+    return dbuf_putc(s, val);
+}
+
+int mik__dbuf_putstr(DynBuf *s, const char *str) {
+    return dbuf_putstr(s, str);
+}
+
+void mik__dbuf_free(DynBuf *s) {
+    dbuf_free(s);
+}
+
+void mik__dbuf_init2(DynBuf *s, void *opaque, DynBufReallocFunc *realloc_func) {
+    dbuf_init2(s, opaque, realloc_func);
+}
+
+int mik__js_has_suffix(const char *str, const char *suffix) {
+    return js__has_suffix(str, suffix);
+}
+
+void mik__js_pstrcpy(char *buf, int buf_size, const char *str) {
+    js__pstrcpy(buf, buf_size, str);
+}
+
+char *mik__js_pstrcat(char *buf, int buf_size, const char *s) {
+    return js__pstrcat(buf, buf_size, s);
+}

package/src/eval_bytecode.cpp

@@ -0,0 +1,42 @@
+#include <quickjs.h>
+
+#include "mikrojs/private.h"
+#include "mikrojs/utils.h"
+
+int mik__eval_bytecode(JSContext* ctx, const uint8_t* buf, size_t buf_len, bool check_promise) {
+    JSValue obj = JS_ReadObject(ctx, buf, buf_len, JS_READ_OBJ_BYTECODE);
+
+    if (JS_IsException(obj)) {
+        mik_dump_error(ctx);
+        return -1;
+    }
+
+    if (JS_VALUE_GET_TAG(obj) == JS_TAG_MODULE) {
+        if (JS_ResolveModule(ctx, obj) < 0) {
+            JS_FreeValue(ctx, obj);
+            mik_dump_error(ctx);
+            return -1;
+        }
+    }
+
+    JSValue val = JS_EvalFunction(ctx, obj);
+    if (JS_IsException(val)) {
+        mik_dump_error(ctx);
+        return -1;
+    }
+
+    if (check_promise) {
+        JSPromiseStateEnum promise_state = JS_PromiseState(ctx, val);
+        if (promise_state != (JSPromiseStateEnum)-1) {
+            if (promise_state == JS_PROMISE_REJECTED) {
+                JSValue res = JS_PromiseResult(ctx, val);
+                JS_FreeValue(ctx, res);
+                JS_FreeValue(ctx, val);
+                return -1;
+            }
+        }
+    }
+
+    JS_FreeValue(ctx, val);
+    return 0;
+}