bunmicro 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.0.3] - 2026-06-27
+- Added hex3 series encodings
+  * hex3gz / hex3zst add compressed binary-view encodings
+- Added experimental single-file exe support
+  * bundled assets loader
+  * internal assets fallback to external file tree when needed
+- Added build helpers for single-exe packaging
+  * `--build-exe` runs the asset pack + compile flow
+  * `--build-for <target>` runs the same flow with an explicit Bun build target
+
 ## [1.0.2] - 2026-06-24
 - Added startup profiling flags
   * -profile / --profile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunmicro",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Bun JavaScript rewrite of the micro editor originally in Golang",
   "type": "module",
   "main": "./src/index.js",

package/single-exe/README.md

@@ -0,0 +1,49 @@
+# This is completely optional
+- I still recommend using the methods in the root README.md
+- Bun's Android build is currently not supported
+
+# Usage
+- First run `bun ./packAssets.sh` to bundle the assets into `assets.tar`
+- Then run the build script like this
+
+  ```shell
+  bun build --compile --bytecode --minify ./entry.mjs --outfile=bmi
+  ```
+
+- You'll get a bmi executable
+
+# Single Executable Intro
+
+This folder contains the Bun single-exe bootstrap used by the project.
+
+## Entry Flow
+
+- `entry.mjs` imports `assetsLoader.mjs` first
+- `assetsLoader.mjs` loads `assets.tar` with `Bun.Archive` and mounts it as `globalThis.internalAssets`
+- `assetsLoaderPromise` is exposed on `globalThis`
+- `../src/index.js` waits for `assetsLoaderPromise` if it exists
+
+That keeps the main program bootable even if asset loading reports errors.
+
+## Assets Loading
+
+- Bundled assets are loaded sequentially with `await file.bytes()`
+- Load failures are collected and printed to `stderr`
+- Asset loading never rejects the bootstrap promise
+- When loading succeeds, the archive is available through `globalThis.internalAssets`
+
+## CLI Flags
+
+- `--assets-list`
+  - Lists all entries inside bundled `assets.tar`
+  - Exits early before the main program starts
+
+- `--assets-extract`
+  - Extracts bundled assets to the same directory as the executable
+  - Exits early before the main program starts
+
+- `--assets-external`
+  - Skips loading bundled assets into `globalThis.internalAssets`
+  - Forces `../src/index.js` and runtime helpers to use the external file tree
+  - Keeps the bootstrap alive while leaving `internalAssets` falsy
+

package/single-exe/assetsLoader.mjs

@@ -0,0 +1,85 @@
+import assets from "./assets.tar" with { type: "file" };
+import { resolveCompiledBaseDir, isCompiledBinary } from "../src/runtime/compiled.js";
+
+const forceExternalAssets = process.argv.includes("--assets-external");
+const debugAssetsLoader = Boolean(process.env.BUNMICRO_DEBUG);
+if (forceExternalAssets) {
+  const flagIndex = process.argv.indexOf("--assets-external");
+  if (flagIndex >= 0) process.argv.splice(flagIndex, 1);
+}
+
+globalThis.internalAssets = forceExternalAssets ? null : Object.create(null);
+globalThis.assetsLoaderPromise = main(process.argv).catch((error) => {
+  console.error("# assets loader failed");
+  console.error(error);
+  return globalThis.internalAssets;
+});
+
+async function main(argv) { 
+
+  if (forceExternalAssets &&
+      !argv.includes("--assets-list") &&
+      !argv.includes("--assets-extract")) {
+    return null;
+  }
+
+  const startedAt = debugAssetsLoader ? Bun.nanoseconds() : 0;
+
+  const tarball = await Bun.file(assets).bytes();
+  const archive = new Bun.Archive(tarball);
+
+  await cliEarlyExit(archive, argv);
+
+  const files = await archive.files();
+  const entries = [...files.entries()];
+  const assetsByPath = Object.create(null);
+  const errors = [];
+
+  for (const [path, file] of entries) {
+    try {
+      assetsByPath[path] = await file.bytes();
+    } catch (reason) {
+      errors.push({ path, reason });
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error(`# Failed to load ${errors.length} bundled asset(s):`);
+    for (const { path, reason } of errors) {
+      console.error(`- ${path}`);
+      if (reason) {
+        console.error(reason);
+      }
+    }
+  }
+  if (debugAssetsLoader) {
+    const elapsedMs = (Bun.nanoseconds() - startedAt) / 1e6;
+    console.error(`Loaded assets: ${elapsedMs.toFixed(3)} ms`);
+  }
+
+  globalThis.internalAssets = assetsByPath;
+  return assetsByPath;
+}
+
+async function cliEarlyExit(archive, argv) {
+  if (argv.includes("--assets-list")) {
+    const files = await archive.files();
+    for (const path of [...files.keys()].sort()) {
+      console.log(path);
+    }
+    process.exit(0);
+  }
+
+  if (argv.includes("--assets-extract")) {
+    if (isCompiledBinary(argv))
+    {
+      const targetDir = resolveCompiledBaseDir({ argv });
+      const extracted = await archive.extract(targetDir);
+      console.log(`Extracted ${extracted} asset(s) to ${targetDir}`);
+    }  //  if isCompiled
+    else
+      console.log("Assets extraction should only be used in a Bun compiled single-file executable");
+      
+    process.exit(0);
+  }
+}

package/single-exe/entry.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+
+// 1. Injects assets to global.internalAssets
+//   as { "./path/in/tar":file.bytes() }
+// 2. Sets global.assetsLoaderPromise
+import "./assetsLoader.mjs"
+
+import "../src/index.js"
+

package/single-exe/packAssets.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+sd=$(dirname "$0")
+
+cd "$sd"/..
+
+tar -cvf single-exe/assets.tar runtime README.md CHANGELOG.md node_modules/wasmoon/dist/glue.wasm

package/src/config/config.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 //import { Glob } from "bun";
 import { defaultAllSettings, OPTION_CHOICES, LOCAL_SETTINGS } from "./defaults.js";
+import { isHex3Encoding } from "../runtime/encodings.js";
 
 export class Config {
   constructor({ configDir = "" } = {}) {
@@ -105,7 +106,7 @@ function normalizeSetting(key, value) {
 function validateOption(option, value) {
   if (option === "encoding") {
     const encoding = String(value || "utf-8");
-    if (encoding === "hex3") return;
+    if (isHex3Encoding(encoding)) return;
     try { new TextDecoder(encoding); }
     catch { throw new Error(`Invalid encoding: ${value}`); }
   }

package/src/index.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
 
+let mainPromise = globalThis.assetsLoaderPromise ||
+                  Promise.resolve();
+
 const jsStart = globalThis.Bun ? Bun.nanoseconds() : Date.now() * 1e6;
 const checkpoints = [
   { name: "Bun Engine Boot", time: 0 },
@@ -99,6 +102,7 @@ import { Config } from "./config/config.js";
 import { defaultAllSettings, OPTION_CHOICES, LOCAL_SETTINGS } from "./config/defaults.js";
 import { cleanConfig } from "./config/clean.js";
 import { RuntimeRegistry, RTColorscheme, RTHelp } from "./runtime/registry.js";
+import { assetPath, hasInternalAssets, listInternalAssetDirs, readInternalAssetText } from "./runtime/assets.js";
 import { PluginManager } from "./plugins/manager.js";
 import { JsPluginManager, buildMicroGlobal, runAction, listActions } from "./plugins/js-bridge.js";
 import { Colorscheme } from "./config/colorscheme.js";
@@ -113,9 +117,11 @@ import { shellSplit } from "./shell/shell.js";
 import { styleToAnsi } from "./display/ansi-style.js";
 import { encodeBinaryToBuffer, decodeBinaryBytes } from "./buffer/fixed3-codec.js";
 import { writeBackup, removeBackup, applyBackup } from "./buffer/backup.js";
+import { isHex3Encoding } from "./runtime/encodings.js";
 import { createInterface } from "node:readline/promises";
 
 import pkg from "../package.json" with { type: "json" };
+import { isCompiledBinary, resolveCompiledBaseDir } from "./runtime/compiled.js";
 
 
 const __filename = fileURLToPath(import.meta.url);
@@ -159,7 +165,13 @@ Windows
 }
 
 const VERSION = pkg.version;
-const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const IS_COMPILED = isCompiledBinary(process.argv);
+const REPO_ROOT = IS_COMPILED
+  ? resolveCompiledBaseDir({ argv: process.argv })
+  : resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SINGLE_EXE_DIR = resolve(REPO_ROOT, "single-exe");
+const SINGLE_EXE_ENTRY = resolve(SINGLE_EXE_DIR, "entry.mjs");
+const DEFAULT_BUILD_OUTFILE = "bmi";
 const decoder = new TextDecoder();
 let _activeTtyStream = null; // set in App.start() for use by the global error handler
 
@@ -253,13 +265,44 @@ function isHttpUrl(value) {
 }
 
 function decodeTextBytesWithEncoding(bytes, encoding = "utf-8") {
-  if (normalizeEncodingLabel(encoding) === "hex3") {
-    return { text: encodeBinaryToBuffer(bytes).toString("latin1"), encoding: "hex3" };
+  const normalized = normalizeEncodingLabel(encoding);
+  if (normalized === "hex3gz") {
+    const decoded = decodeHex3Bytes(Bun.gunzipSync(bytes));
+    return { ...decoded, encoding: "hex3gz" };
+  }
+  if (normalized === "hex3zst") {
+    const decoded = decodeHex3Bytes(Bun.zstdDecompressSync(bytes));
+    return { ...decoded, encoding: "hex3zst" };
+  }
+  if (normalized === "hex3") {
+    return decodeHex3Bytes(bytes);
   }
-  const decoder = new TextDecoder(normalizeEncodingLabel(encoding));
+  const decoder = new TextDecoder(normalized);
   return { text: decoder.decode(bytes), encoding: decoder.encoding };
 }
 
+function encodeTextBytesWithEncoding(text, encoding = "utf-8") {
+  const normalized = normalizeEncodingLabel(encoding);
+  if (normalized === "hex3gz") {
+    return Bun.gzipSync(encodeHex3Text(text));
+  }
+  if (normalized === "hex3zst") {
+    return Bun.zstdCompressSync(encodeHex3Text(text));
+  }
+  if (normalized === "hex3") {
+    return encodeHex3Text(text);
+  }
+  return new TextEncoder().encode(String(text));
+}
+
+function decodeHex3Bytes(bytes) {
+  return { text: encodeBinaryToBuffer(bytes).toString("latin1"), encoding: "hex3" };
+}
+
+function encodeHex3Text(text) {
+  return decodeBinaryBytes(Buffer.from(text, "latin1"));
+}
+
 async function readTextFileWithEncoding(path, encoding = "utf-8") {
   const bytes = new Uint8Array(await Bun.file(path).arrayBuffer());
   return decodeTextBytesWithEncoding(bytes, encoding);
@@ -272,7 +315,7 @@ async function fetchTextWithEncoding(url, encoding = "utf-8") {
 
 function normalizeEncodingLabel(encoding = "utf-8") {
   const s = String(encoding || "utf-8");
-  if (s === "hex3") return "hex3";
+  if (isHex3Encoding(s)) return s.toLowerCase();
   return new TextDecoder(s).encoding;
 }
 
@@ -602,6 +645,8 @@ function parseArgs(argv) {
     cat: false,
     docs: false,
     changelog: false,
+    buildExe: false,
+    buildFor: "",
     configDir: "",
     debug: false,
     profile: false,
@@ -626,8 +671,16 @@ function parseArgs(argv) {
     else if (arg === "--hex3") {
       flags.settings.set("encoding", "hex3");
     }
+    else if (arg === "--hex3gz") {
+      flags.settings.set("encoding", "hex3gz");
+    }
+    else if (arg === "--hex3zst") {
+      flags.settings.set("encoding", "hex3zst");
+    }
     else if (arg === "--docs" || arg === "--readme") flags.docs = true;
     else if (arg === "--changelog") flags.changelog = true;
+    else if (arg === "--build-exe") flags.buildExe = true;
+    else if (arg === "--build-for") flags.buildFor = argv[++i] ?? "";
     else if (arg === "-debug") flags.debug = true;
     else if (arg === "-profile" || arg === "--profile") flags.profile = true;
     else if (arg === "-config-dir") flags.configDir = argv[++i] ?? "";
@@ -682,8 +735,9 @@ function usage() {
     "    Syntax-highlight file(s) and write to stdout, then exit (.md uses Bun.markdown.ansi)\n",
     "--xxd, --hexdump",
     "    Hex3 dump file(s) and write to stdout (same as --cat -encoding hex3)\n",
-    "--hex3",
-    "    Set -encoding hex3 for this session\n",
+    "--hex3, --hex3gz, --hex3zst",
+    "    Set -encoding hex3, hex3gz, or hex3zst for this session",
+    "    hex3 shows raw bytes; gz/zst variants compress the same hex3 view\n",
     "-help, -h, --help",
     "    Show this help & exit",
     "-version, -V, --version",
@@ -701,6 +755,50 @@ function usage() {
   ].join("\n");
 }
 
+async function buildExecutable(target = "") {
+  const outfile = resolve(process.cwd(), DEFAULT_BUILD_OUTFILE);
+  const normalizedTarget = String(target || "").trim();
+
+  const steps = [
+    {
+      label: "Pack assets",
+      cwd: SINGLE_EXE_DIR,
+      cmd: "bun",
+      args: ["./packAssets.sh"],
+    },
+    {
+      label: "Compile executable",
+      cwd: process.cwd(),
+      cmd: "bun",
+      args: [
+        "build",
+        "--compile",
+        "--bytecode",
+        "--minify",
+        SINGLE_EXE_ENTRY,
+        `--outfile=${DEFAULT_BUILD_OUTFILE}`,
+        ...(normalizedTarget ? [`--target=${normalizedTarget}`] : []),
+      ],
+    },
+  ];
+
+  for (const step of steps) {
+    console.log('');
+    console.log(Bun.markdown.ansi('## '+step.label));
+  
+    const result = child_process.spawnSync(step.cmd, step.args, {
+      cwd: step.cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+    if (result.status !== 0) {
+      process.exit(result.status ?? 1);
+    }
+  }
+
+  console.log(`Built executable: ${outfile}`);
+}
+
 function parseInput(args) {
   const files = [];
   const command = {
@@ -1283,9 +1381,9 @@ class BufferModel {
       if (this._backupRevision === backupRevision) this._backupRequested = false;
       this._forceKeepBackup = true;
     }
-    if (this.encoding === "hex3") {
+    if (isHex3Encoding(this.encoding)) {
       try {
-        await Bun.write(targetPath, decodeBinaryBytes(Buffer.from(text, "latin1")));
+        await Bun.write(targetPath, encodeTextBytesWithEncoding(text, this.encoding));
       } finally {
         this._forceKeepBackup = false;
       }
@@ -4143,7 +4241,7 @@ class App {
     if (!force && this.buffer?.readonly) { this.message = "Can't save under readonly mode"; return; }
     try {
       const enc = normalizeEncodingLabel(this.buffer?.encoding);
-      if (enc !== "utf-8" && enc !== "hex3") {
+      if (enc !== "utf-8" && !isHex3Encoding(enc)) {
         this.openYNPrompt("Save in UTF-8?(y,n)", async (answer) => {
           if (answer === "y") await this.saveUtf8();
         });
@@ -4560,7 +4658,8 @@ class App {
         const saveArgs = [...cmdArgs];
         const saveForce = saveArgs[0] === "-f" && (saveArgs.shift(), true);
         if (!saveForce && buf?.readonly) { this.message = "Can't save under readonly mode"; break; }
-        if (saveArgs.length > 0 && normalizeEncodingLabel(buf?.encoding) !== "utf-8" && normalizeEncodingLabel(buf?.encoding) !== "hex3") {
+        const bufferEncoding = normalizeEncodingLabel(buf?.encoding);
+        if (saveArgs.length > 0 && bufferEncoding !== "utf-8" && !isHex3Encoding(bufferEncoding)) {
           const target = resolve(expandHome(saveArgs[0]));
           this.openYNPrompt("Save in UTF-8?(y,n)", async (answer) => {
             if (answer === "y") {
@@ -5435,14 +5534,14 @@ const COMMAND_NAMES = [
 ];
 
 const SUPPORTED_ENCODING_LABELS = [
-  "hex3",
+  "hex3", "hex3gz", "hex3zst",
   "utf-8", "utf-16le", "utf-16be",
   "windows-1252", "iso-8859-1", "latin1",
   "big5", "gbk", "gb18030",
   "shift_jis", "sjis", "euc-jp", "iso-2022-jp",
   "euc-kr", "ks_c_5601-1987",
 ].filter((encoding) => {
-  if (encoding === "hex3") return true;
+  if (isHex3Encoding(encoding)) return true;
   try { new TextDecoder(encoding); return true; }
   catch { return false; }
 });
@@ -6703,18 +6802,38 @@ async function loadBuffers(files, command) {
 }
 
 async function printReadmeDocs() {
-  const readme = await Bun.file(join(REPO_ROOT, "README.md")).text();
+  const readme = readInternalAssetText("README.md") ?? await Bun.file(join(REPO_ROOT, "README.md")).text();
   process.stdout.write(Bun.markdown.ansi(readme, { hyperlinks: true }));
 }
 
 async function printChangelogDocs() {
-  const changelog = await Bun.file(join(REPO_ROOT, "CHANGELOG.md")).text();
+  const changelog = readInternalAssetText("CHANGELOG.md") ?? await Bun.file(join(REPO_ROOT, "CHANGELOG.md")).text();
   process.stdout.write(Bun.markdown.ansi(changelog, { hyperlinks: true }));
 }
 
 async function main() {
   addCheckpoint("Argument Parsing");
   const { flags, files: rawFiles } = parseArgs(process.argv.slice(2));
+  if (flags.buildExe && flags.buildFor) {
+    console.error("--build-exe and --build-for are separate paths; use only one");
+    process.exit(1);
+  }
+  if (flags.buildExe) {
+    if (IS_COMPILED) {
+      console.error("--build-exe is only available in the source tree");
+      process.exit(1);
+    }
+    await buildExecutable();
+    return;
+  }
+  if (flags.buildFor) {
+    if (IS_COMPILED) {
+      console.error("--build-for is only available in the source tree");
+      process.exit(1);
+    }
+    await buildExecutable(flags.buildFor);
+    return;
+  }
   if (flags.help) {
     console.log(usage());
     return;
@@ -6783,17 +6902,30 @@ async function main() {
 
   if (flags.plugin === "list") {
     const luaList = plugins.list();
-    const jsDirs = [
-      { dir: join(REPO_ROOT, "runtime", "jsplugins"), builtin: true },
-      { dir: join(config.configDir, "jsplug"),        builtin: false },
-    ];
     const jsItems = [];
-    for (const { dir, builtin } of jsDirs) {
-      if (!existsSync(dir)) continue;
-      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const builtinJsPluginNames = hasInternalAssets()
+      ? listInternalAssetDirs(assetPath("runtime", "jsplugins"))
+      : [];
+    if (builtinJsPluginNames.length > 0) {
+      for (const name of builtinJsPluginNames) {
+        jsItems.push({ name, builtin: true });
+      }
+    } else {
+      const builtinJsDir = join(REPO_ROOT, "runtime", "jsplugins");
+      if (existsSync(builtinJsDir)) {
+        for (const entry of readdirSync(builtinJsDir, { withFileTypes: true })) {
+          if (!entry.isDirectory()) continue;
+          if (existsSync(join(builtinJsDir, entry.name, `${entry.name}.js`)))
+            jsItems.push({ name: entry.name, builtin: true });
+        }
+      }
+    }
+    const userJsDir = join(config.configDir, "jsplug");
+    if (existsSync(userJsDir)) {
+      for (const entry of readdirSync(userJsDir, { withFileTypes: true })) {
         if (!entry.isDirectory()) continue;
-        if (existsSync(join(dir, entry.name, `${entry.name}.js`)))
-          jsItems.push({ name: entry.name, builtin });
+        if (existsSync(join(userJsDir, entry.name, `${entry.name}.js`)))
+          jsItems.push({ name: entry.name, builtin: false });
       }
     }
     const fmtTag = (p) => p.builtin ? " *(built-in)*" : "";
@@ -7380,6 +7512,10 @@ async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAUL
   }
 }
 
+
+mainPromise.then(r=>{
+
+
 main().catch((error) => {
   try {
     (_activeTtyStream ?? process.stdin).setRawMode?.(false);
@@ -7389,3 +7525,6 @@ main().catch((error) => {
     process.exit(1);
   }
 });
+
+
+})

package/src/lua/engine.js

@@ -1,21 +1,55 @@
+import { existsSync } from "node:fs";
+import { readInternalAssetBytes } from "../runtime/assets.js";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { isCompiledBinary, resolveCompiledBaseDir } from "../runtime/compiled.js";
+
+const SOURCE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
 export async function createLuaEngine() {
-  const wasmoon = await tryImport("wasmoon");
+  let wasmoon = null;
+  try {
+    wasmoon = await import("wasmoon");
+  } catch (error) {
+    if (
+      error?.code !== "ERR_MODULE_NOT_FOUND" &&
+      !/Cannot find package/.test(String(error?.message))
+    ) {
+      throw error;
+    }
+  }
   if (!wasmoon?.LuaFactory) {
     throw new Error("Lua support requires the WASM runtime `wasmoon`. Install it with `bun add wasmoon`.");
   }
 
-  const factory = new wasmoon.LuaFactory();
+  const wasmLocation = await resolveLuaWasmLocation();
+  const factory = new wasmoon.LuaFactory(wasmLocation);
   const lua = await factory.createEngine();
   return new WasmoonEngine(lua);
 }
 
-async function tryImport(name) {
-  try {
-    return await import(name);
-  } catch (error) {
-    if (error?.code === "ERR_MODULE_NOT_FOUND" || /Cannot find package/.test(String(error?.message))) return null;
-    throw error;
+async function resolveLuaWasmLocation() {
+  const wasmBytes = readInternalAssetBytes("node_modules/wasmoon/dist/glue.wasm");
+  if (wasmBytes) {
+    const wasmPath = join(tmpdir(), "bunmicro-wasmoon-glue.wasm");
+    try {
+      const existing = await Bun.file(wasmPath).bytes().catch(() => null);
+      if (!existing || existing.byteLength !== wasmBytes.byteLength) {
+        await Bun.write(wasmPath, wasmBytes);
+      }
+      return wasmPath;
+    } catch (error) {
+      console.error("# failed to stage bundled wasmoon wasm");
+      console.error(error);
+    }
   }
+
+  const fallbackPath = isCompiledBinary(process.argv)
+    ? join(resolveCompiledBaseDir({ argv: process.argv }), "node_modules", "wasmoon", "dist", "glue.wasm")
+    : join(SOURCE_ROOT, "node_modules", "wasmoon", "dist", "glue.wasm");
+
+  return existsSync(fallbackPath) ? fallbackPath : undefined;
 }
 
 class WasmoonEngine {

package/src/plugins/js-bridge.js

@@ -1,15 +1,50 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { readdir } from "node:fs/promises";
-import { join, basename, extname } from "node:path";
+import { dirname, join, basename, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
+import { assetPath, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetBytes } from "../runtime/assets.js";
 import { newMessage, newMessageAtLine, MTError, MTWarning, MTInfo } from "../buffer/message.js";
 import { Loc } from "../buffer/loc.js";
 
 // ── Action registry ──────────────────────────────────────────────────────────
 
 const ACTIONS = new Map();
+const INTERNAL_JSPLUGIN_STAGE_ROOT = join(tmpdir(), "bunmicro-jsplugins");
+let internalJsPluginStagePromise = null;
 
 function reg(name, fn) { ACTIONS.set(name, fn); }
 
+function stageInternalJsPlugins() {
+  if (!internalJsPluginStagePromise) {
+    internalJsPluginStagePromise = _stageInternalJsPlugins().catch((error) => {
+      console.error("# failed to stage internal JS plugins");
+      console.error(error);
+      return null;
+    });
+  }
+  return internalJsPluginStagePromise;
+}
+
+async function _stageInternalJsPlugins() {
+  const prefix = assetPath("runtime", "jsplugins");
+  const paths = listInternalAssetPaths(prefix);
+  if (paths.length === 0) return null;
+
+  mkdirSync(INTERNAL_JSPLUGIN_STAGE_ROOT, { recursive: true });
+  await Bun.write(join(INTERNAL_JSPLUGIN_STAGE_ROOT, "package.json"), JSON.stringify({ type: "module" }));
+
+  for (const assetPathName of paths) {
+    const bytes = readInternalAssetBytes(assetPathName);
+    if (!bytes) continue;
+    const stagedPath = join(INTERNAL_JSPLUGIN_STAGE_ROOT, ...assetPathName.split("/"));
+    mkdirSync(dirname(stagedPath), { recursive: true });
+    await Bun.write(stagedPath, bytes);
+  }
+
+  return INTERNAL_JSPLUGIN_STAGE_ROOT;
+}
+
 function _actIndentStr(buf) {
   if (buf?.Settings?.tabstospaces) return " ".repeat(buf?.Settings?.tabsize ?? 4);
   return "\t";
@@ -550,6 +585,10 @@ export class JsPluginManager {
   // Scan and load all JS plugins from given directories
   async loadFrom(dirs) {
     for (const { dir, builtin } of dirs) {
+      if (builtin && hasInternalAssets()) {
+        const loadedFromAssets = await this._loadFromInternalAssets(dir, builtin);
+        if (loadedFromAssets) continue;
+      }
       if (!existsSync(dir)) continue;
       const entries = await readdir(dir, { withFileTypes: true });
       for (const entry of entries) {
@@ -562,6 +601,30 @@ export class JsPluginManager {
     }
   }
 
+  async _loadFromInternalAssets(dir, builtin) {
+    const prefix = assetPath("runtime", "jsplugins");
+    const stageRoot = await stageInternalJsPlugins();
+    if (!stageRoot) return false;
+
+    const pluginNames = listInternalAssetDirs(prefix);
+    if (pluginNames.length === 0) return false;
+
+    let loadedAny = false;
+    for (const pluginName of pluginNames) {
+      const stagedMainPath = join(stageRoot, prefix, pluginName, `${pluginName}.js`);
+      if (!existsSync(stagedMainPath)) continue;
+      try {
+        await import(pathToFileURL(stagedMainPath).href);
+        this._loaded.push({ path: assetPath(prefix, pluginName, `${pluginName}.js`), name: pluginName, builtin, loaded: true });
+        loadedAny = true;
+      } catch (e) {
+        this._loaded.push({ path: assetPath(prefix, pluginName, `${pluginName}.js`), name: pluginName, builtin, loaded: false, error: e.message });
+        console.error(`[jsplugin] failed to load ${pluginName}: ${e.message}`);
+      }
+    }
+    return loadedAny;
+  }
+
   async _loadFile(path, name, builtin) {
     try {
       await import(path);

package/src/plugins/manager.js

@@ -4,6 +4,7 @@ import { basename, dirname, extname, join, sep } from "node:path";
 import { fetchHttp, downloadFile } from "../platform/commands.js";
 import { extractAndStrip } from "../platform/archive.js";
 import { createLuaEngine } from "../lua/engine.js";
+import { assetPath, hasInternalAssets, internalAssetSource, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetText } from "../runtime/assets.js";
 import { execCommand, runBackgroundShell, runCommand } from "../shell/shell.js";
 import { Loc } from "../buffer/loc.js";
 import { BTDefault, BTHelp, BTInfo, BTLog, BTRaw, BTScratch, byteOffset, BufferCore } from "../buffer/buffer.js";
@@ -107,10 +108,24 @@ export class PluginManager {
   }
 
   async scanBuiltinPlugins() {
+    const userNames = new Set(this.plugins.map((plugin) => plugin.name));
+    const internalPrefix = assetPath("runtime", "plugins");
+
+    if (hasInternalAssets()) {
+      const entries = listInternalAssetDirs(internalPrefix);
+      if (entries.length > 0) {
+        for (const entryName of entries) {
+          if (userNames.has(entryName)) continue;
+          const plugin = await scanPluginDirectoryFromAssets(assetPath(internalPrefix, entryName), entryName, true);
+          if (plugin) this.plugins.push(plugin);
+        }
+        return;
+      }
+    }
+
     const plugdir = join(this.repoRoot, "runtime", "plugins");
     if (!existsSync(plugdir)) return;
     const entries = await readdir(plugdir, { withFileTypes: true });
-    const userNames = new Set(this.plugins.map((plugin) => plugin.name));
     for (const entry of entries) {
       if (!entry.isDirectory() || userNames.has(entry.name)) continue;
       const plugin = await scanPluginDirectory(join(plugdir, entry.name), entry.name, true);
@@ -412,6 +427,16 @@ export class PluginManager {
   addPluginRuntimeFile(plugin, kind, relpath) {
     const owner = this.plugins.find((p) => p.name === plugin);
     if (!owner) return;
+    const internalPath = assetPath("runtime", "plugins", owner.dirName, relpath);
+    const internalText = readInternalAssetText(internalPath);
+    if (internalText != null) {
+      this.runtime.files[kind].push({
+        name: basename(relpath, extname(relpath)),
+        path: internalPath,
+        text: async () => internalText,
+      });
+      return;
+    }
     const path = join(this.repoRoot, "runtime", "plugins", owner.dirName, relpath);
     this.runtime.files[kind].push({ name: basename(path, extname(path)), path, text: async () => await readFile(path, "utf8") });
   }
@@ -589,6 +614,14 @@ async function scanPluginDirectory(dir, defaultName, builtin) {
 }
 
 function fileSource(path) {
+  const internalText = readInternalAssetText(path);
+  if (internalText != null) {
+    return {
+      name: basename(path),
+      path,
+      text: async () => internalText,
+    };
+  }
   return {
     name: basename(path),
     path,
@@ -596,6 +629,28 @@ function fileSource(path) {
   };
 }
 
+async function scanPluginDirectoryFromAssets(prefix, defaultName, builtin) {
+  const entries = listInternalAssetPaths(prefix);
+  const srcs = [];
+  let info = null;
+  let name = defaultName;
+  const base = `${assetPath(prefix)}/`;
+
+  for (const fullPath of entries) {
+    const rel = fullPath.slice(base.length);
+    if (!rel || rel.includes("/")) continue;
+    if (rel.endsWith(".lua")) {
+      srcs.push(internalAssetSource(fullPath));
+    } else if (rel.endsWith(".json")) {
+      const parsed = JSON.parse(readInternalAssetText(fullPath) ?? "null");
+      info = Array.isArray(parsed) ? parsed[0] : parsed;
+      if (info?.Name) name = info.Name;
+    }
+  }
+  if (!VALID_PLUGIN_NAME.test(name) || srcs.length === 0) return null;
+  return new Plugin({ name, dirName: basename(prefix), srcs, info, builtin });
+}
+
 function humanizeBytes(bytes) {
   const units = ["B", "KB", "MB", "GB", "TB"];
   let value = Number(bytes);

package/src/runtime/assets.js

@@ -0,0 +1,90 @@
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
+export function hasInternalAssets() {
+  return Boolean(getAssetStore());
+}
+
+export function assetPath(...parts) {
+  return parts
+    .flatMap((part) => String(part).split(/[\\/]+/))
+    .filter(Boolean)
+    .join("/");
+}
+
+export function listInternalAssetPaths(prefix = "") {
+  const store = getAssetStore();
+  if (!store) return [];
+
+  const normalizedPrefix = assetPath(prefix);
+  const entries = iterateAssetKeys(store);
+  if (!normalizedPrefix) {
+    return entries.sort();
+  }
+
+  const base = `${normalizedPrefix}/`;
+  return entries.filter((path) => path === normalizedPrefix || path.startsWith(base)).sort();
+}
+
+export function listInternalAssetDirs(prefix = "") {
+  const normalizedPrefix = assetPath(prefix);
+  const base = normalizedPrefix ? `${normalizedPrefix}/` : "";
+  const dirs = new Set();
+
+  for (const path of listInternalAssetPaths(prefix)) {
+    const rest = normalizedPrefix ? path.slice(base.length) : path;
+    const [dir] = rest.split("/");
+    if (dir) dirs.add(dir);
+  }
+
+  return [...dirs].sort();
+}
+
+export function getInternalAsset(path) {
+  const store = getAssetStore();
+  if (!store) return null;
+  const key = assetPath(path);
+  if (store instanceof Map) return store.get(key) ?? null;
+  return store[key] ?? store[path] ?? null;
+}
+
+export function readInternalAssetBytes(path) {
+  const value = getInternalAsset(path);
+  if (value == null) return null;
+  if (value instanceof Uint8Array) return value;
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (typeof value === "string") return textEncoder.encode(value);
+  return textEncoder.encode(String(value));
+}
+
+export function readInternalAssetText(path) {
+  const bytes = readInternalAssetBytes(path);
+  if (!bytes) return null;
+  return textDecoder.decode(bytes);
+}
+
+export function internalAssetSource(path) {
+  return {
+    name: path.split("/").pop() ?? path,
+    path,
+    async text() {
+      return readInternalAssetText(path) ?? "";
+    },
+  };
+}
+
+function getAssetStore() {
+  const store = globalThis.internalAssets;
+  if (!store) return null;
+  if (store instanceof Map) return store;
+  if (typeof store === "object") return store;
+  return null;
+}
+
+function iterateAssetKeys(store) {
+  if (store instanceof Map) return [...store.keys()].map(String);
+  return Object.keys(store);
+}

package/src/runtime/compiled.js

@@ -0,0 +1,25 @@
+import { basename, dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function isCompiledBinary(argv = process.argv) {
+  return Boolean(argv?.[1]?.startsWith?.("/$bunfs/"));
+}
+
+export function resolveCompiledBaseDir({ argv = process.argv, execPath = process.execPath } = {}) {
+  const bn = basename(execPath);
+  if (bn.startsWith("ld") || 
+      bn.startsWith("libld") ||
+      bn.startsWith("linker") ) {
+    const realArgv = readFileSync("/proc/self/cmdline", "utf8").match(/[^\0]+/g);
+    return dirname(realArgv?.[1] ?? execPath);
+  }
+  return dirname(execPath) || process.cwd();
+}
+
+export function resolveRepoRoot(importMetaUrl, options = {}) {
+  if (isCompiledBinary(options.argv)) {
+    return resolveCompiledBaseDir(options);
+  }
+  return resolve(dirname(fileURLToPath(importMetaUrl)), "..");
+}

package/src/runtime/encodings.js

@@ -0,0 +1,5 @@
+const HEX3_ENCODINGS = new Set(["hex3", "hex3gz", "hex3zst"]);
+
+export function isHex3Encoding(encoding) {
+  return HEX3_ENCODINGS.has(String(encoding || "utf-8").toLowerCase());
+}

package/src/runtime/registry.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
+import { assetPath, hasInternalAssets, listInternalAssetPaths, readInternalAssetBytes } from "./assets.js";
 
 export const RTColorscheme = 0;
 export const RTSyntax = 1;
@@ -29,6 +30,10 @@ export class RuntimeRegistry {
 
   async addRuntimeKind(kind, dir, extension, user) {
     if (user) await this.addDirectory(kind, join(this.configDir, dir), extension, true);
+    const internalPrefix = assetPath("runtime", dir);
+    if (hasInternalAssets() && await this.addInternalDirectory(kind, internalPrefix, extension, false)) {
+      return;
+    }
     await this.addDirectory(kind, join(this.repoRoot, "runtime", dir), extension, false);
   }
 
@@ -47,6 +52,31 @@ export class RuntimeRegistry {
     }
   }
 
+  async addInternalDirectory(kind, prefix, extension, real) {
+    const entries = listInternalAssetPaths(prefix);
+    if (entries.length === 0) return false;
+
+    const base = `${assetPath(prefix)}/`;
+    let added = false;
+    for (const path of entries) {
+      const rel = path.slice(base.length);
+      if (!rel || rel.includes("/")) continue;
+      if (!rel.endsWith(extension)) continue;
+
+      const data = readInternalAssetBytes(path);
+      if (!data) continue;
+      const file = new MemoryRuntimeFile(path, data);
+      if (!real && this.realFiles[kind].some((f) => f.name === file.name)) {
+        this.fallbackFiles[kind].push(file);
+        continue;
+      }
+      this.files[kind].push(file);
+      if (real) this.realFiles[kind].push(file);
+      added = true;
+    }
+    return added;
+  }
+
   addMemoryFile(kind, name, data) {
     this.files[kind].push(new MemoryRuntimeFile(name, data));
   }
@@ -85,14 +115,20 @@ class MemoryRuntimeFile {
     this.name = basename(name, extname(name));
     this.path = name;
     this.real = false;
-    this._data = String(data);
+    this._data = data;
   }
 
   async data() {
-    return new TextEncoder().encode(this._data);
+    if (this._data instanceof Uint8Array) return this._data;
+    if (ArrayBuffer.isView(this._data)) {
+      return new Uint8Array(this._data.buffer, this._data.byteOffset, this._data.byteLength);
+    }
+    if (this._data instanceof ArrayBuffer) return new Uint8Array(this._data);
+    return new TextEncoder().encode(String(this._data));
   }
 
   async text() {
-    return this._data;
+    if (typeof this._data === "string") return this._data;
+    return new TextDecoder().decode(await this.data());
   }
 }

package/tests/cmphex3b64.js

@@ -0,0 +1,95 @@
+import { randomBytes } from "node:crypto";
+import {
+  decodeBinaryStrict,
+  encodeBinary,
+} from "../src/buffer/fixed3-codec.js";
+
+const SIZES = [1024, 64 * 1024, 1024 * 1024];
+const ITERATIONS = {
+  1024: 20_000,
+  [64 * 1024]: 2_000,
+  [1024 * 1024]: 200,
+};
+
+function makeRandom(size) {
+  return randomBytes(size);
+}
+
+function makeAscii(size) {
+  const buf = Buffer.allocUnsafe(size);
+  for (let i = 0; i < size; i++) {
+    buf[i] = 0x20 + (i % 95);
+  }
+  return buf;
+}
+
+function mbps(bytes, ns) {
+  return (bytes / (1024 * 1024)) / (Number(ns) / 1e9);
+}
+
+function bench(name, fn, iters, payloadSize) {
+  const warmup = Math.min(200, Math.max(20, Math.floor(iters / 20)));
+  for (let i = 0; i < warmup; i++) fn();
+
+  const start = process.hrtime.bigint();
+  let sink = 0;
+  for (let i = 0; i < iters; i++) {
+    sink ^= fn();
+  }
+  const elapsed = process.hrtime.bigint() - start;
+
+  return {
+    name,
+    iters,
+    ms: Number(elapsed) / 1e6,
+    mbps: mbps(payloadSize * iters, elapsed),
+    sink,
+  };
+}
+
+function runCase(label, input) {
+  const fixedEncoded = encodeBinary(input);
+  const base64Encoded = input.toString("base64");
+
+  if (!decodeBinaryStrict(fixedEncoded).equals(input)) {
+    throw new Error(`hex3 roundtrip failed for ${label}`);
+  }
+  if (!Buffer.from(base64Encoded, "base64").equals(input)) {
+    throw new Error(`base64 roundtrip failed for ${label}`);
+  }
+
+  const iters = ITERATIONS[input.length] ?? Math.max(50, Math.floor(100 * 1024 * 1024 / input.length));
+
+  const results = [
+    bench(
+      "hex3 encode+decode",
+      () => {
+        const encoded = encodeBinary(input);
+        return decodeBinaryStrict(encoded).length;
+      },
+      iters,
+      input.length,
+    ),
+    bench(
+      "base64 encode+decode",
+      () => {
+        const encoded = input.toString("base64");
+        return Buffer.from(encoded, "base64").length;
+      },
+      iters,
+      input.length,
+    ),
+  ];
+
+  console.log(`\n${label} (${input.length.toLocaleString()} bytes, ${iters.toLocaleString()} iterations)`);
+  for (const r of results) {
+    console.log(
+      `${r.name.padEnd(22)} ${r.ms.toFixed(1).padStart(10)} ms  ${r.mbps.toFixed(1).padStart(8)} MiB/s  sink=${r.sink}`,
+    );
+  }
+}
+
+for (const size of SIZES) {
+  runCase("random", makeRandom(size));
+  runCase("ascii", makeAscii(size));
+}