jsmdcui 0.7.0 → 0.9.0

package/single-exe/README.md

@@ -1,27 +1,231 @@
-# This is completely optional
-- I still recommend using the methods in the root README.md
-- Bun's Android build is currently not supported
+# Bun Single-File Executable Bootstrap
 
-# Usage
-- First run `bun ./packAssets.sh` to bundle the assets into `assets.tar`
-- Then run the build script like this
+Build a Bun application and its runtime assets into one executable while
+keeping the regular main module free of Bun-specific asset imports.
 
-  ```shell
-  bun build --compile --bytecode --minify ./entry.mjs --outfile=binname
-  ```
+You can copy and adapt this build setup for your own project by changing its
+main-module path and asset list as described below.
 
-- You'll get a binname executable
+- Bundle an asset tree alongside the application code in one executable.
+- Keep the regular main module available to the Node.js ESM execution path.
+- Read embedded resources first with an optional external-file fallback.
+- List, extract, or bypass embedded assets with built-in CLI flags.
+- Build for the current platform or pass a Bun cross-compilation target.
 
-# Single Executable Intro
+> This workflow is optional; the standard methods in the root README remain
+> available. Bun's Android build is currently not supported.
 
-This folder contains the Bun single-exe bootstrap used by the project.
+## Quick start for jsmdcui
+
+From the repository root, build for the current platform:
+
+```shell
+bun ./src/index.js --build-exe
+./mdcui --version
+```
+
+`--build-exe` runs `packAssets.sh` automatically and writes the `mdcui`
+executable to the current directory. To pass a Bun compilation target, use:
+
+```shell
+bun ./src/index.js --build-for <target>
+```
+
+To perform the same steps manually, run these commands from `single-exe/`:
+
+```shell
+bun ./packAssets.sh
+bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=mdcui
+```
+
+## Adapting this folder to another project
+
+This folder is a reusable starting point, not a drop-in package. The current
+`entry.mjs` and `packAssets.sh` contain jsmdcui paths, so another project must
+complete the following integration steps.
+
+The adopting project needs Bun for packing and compiling, a `tar` command for
+`packAssets.sh`, and an ES-module setup. Keep `"type": "module"` in
+`package.json`, or rename the copied `.js` modules to `.mjs` and update their
+imports. The supported uncompiled Node path requires Node.js 20.11 or newer
+because `compiled.js` uses `import.meta.dirname`.
+
+`assetsHelper.js` and `compiled.js` are Node-compatible under those conditions.
+`assetsLoader.mjs` and `entry.mjs` are Bun-only and must not be imported by the
+regular Node entry path.
+
+### 1. Copy the bootstrap directory
+
+Copy the entire `single-exe/` directory to the root of the other project and
+keep its name and relative position unless you also update the paths in
+`compiled.js` and `packAssets.sh`. A typical layout is:
+
+```text
+my-project/
+├── single-exe/
+│   ├── assetsHelper.js
+│   ├── assetsLoader.mjs
+│   ├── compiled.js
+│   ├── entry.mjs
+│   └── packAssets.sh
+└── src/
+    └── index.js
+```
+
+`assets.tar` is generated by `packAssets.sh`; it does not need to exist before
+the first packing step.
+
+### 2. Point `entry.mjs` at the main program
+
+Keep the asset loader as the first import and change the path passed to the
+final `await import()` so it points to the other project's real entry module:
+
+```js
+#!/usr/bin/env bun
+
+import "./assetsLoader.mjs";
+await globalThis.assetsLoaderPromise;
+await import("../src/index.js");
+```
+
+> **Important:** Keep the final import dynamic. Do not replace it with a static
+> `import "../src/index.js"`, because static dependencies are evaluated before
+> the asset Promise is awaited.
+
+Only the Bun single-file executable build should use this bootstrap entry.
+Continue to run the regular main module directly when using Node:
+
+```shell
+node ./src/index.js
+```
+
+### 3. Choose which files to embed
+
+Edit the resource list in `packAssets.sh`; the script runs `tar` for you. It
+changes to the project root, writes `single-exe/assets.tar`, and packs every
+listed runtime resource required by the compiled program. Paths stored in the
+archive become the lookup keys used by `assetsHelper.js`; use keys such as
+`public/app.css`, without a leading `./`. The normal `--build-exe` and
+`--build-for` flows invoke this script automatically, so you do not need to run
+`tar` yourself.
+
+For example:
+
+```sh
+#!/bin/sh
+
+script_dir=$(dirname "$0")
+cd "$script_dir/.." || exit 1
+
+tar -cvf single-exe/assets.tar public templates README.md
+```
+
+Do not retain jsmdcui's `demos`, `runtime`, `src/cui`, or `testapp.md` entries
+unless the adopting project actually contains and needs them.
+
+### 4. Read embedded assets with an external fallback
+
+Import the Node-compatible helpers from `assetsHelper.js`. They return `null`
+when the embedded store is unavailable or a path is not present:
+
+```js
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readInternalAssetText } from "../single-exe/assetsHelper.js";
+import { REPO_ROOT } from "../single-exe/compiled.js";
+
+async function readResourceText(path) {
+  return readInternalAssetText(path) ??
+    await readFile(resolve(REPO_ROOT, path), "utf8");
+}
+```
+
+In the source tree, `REPO_ROOT` is the project root. In a compiled executable,
+it is the executable's directory, which is also where `--assets-extract`
+places the external resource tree. Apply the same embedded-first fallback to
+every file that must work in both modes. Use `readInternalAssetBytes()` when
+a resource should be returned as bytes instead of decoded text.
+Use `listInternalAssetPaths()` to list embedded asset paths and
+`listInternalAssetDirs()` to list embedded directories.
+
+### 5. Add the optional build commands to the regular CLI
+
+Before normal argument parsing, call `buildEarlyExit` from the regular main
+module:
+
+```js
+const compiledHelper = await import("../single-exe/compiled.js").catch(() => null);
+await compiledHelper?.buildEarlyExit?.(process.argv, "my-bin");
+```
+
+The second argument is the output filename; it defaults to `single.exe` when
+omitted. This enables:
+
+```shell
+bun ./src/index.js --build-exe
+bun ./src/index.js --build-for <target>
+```
+
+Both commands run `packAssets.sh` before `bun build`. The second form passes
+`<target>` through as Bun's `--target=<target>` value.
+
+Alternatively, build manually from inside `single-exe/`:
+
+```shell
+bun ./packAssets.sh
+bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=my-bin
+```
+
+### 6. Verify both execution paths
+
+Verify the compiled asset archive and then run the program normally:
+
+```shell
+./my-bin --assets-list
+./my-bin
+```
+
+Also run the uncompiled main module with Node.js 20.11 or newer to verify that
+all required files have a working external fallback:
+
+```shell
+node ./src/index.js
+```
+
+Use `./my-bin --assets-extract` to write the packed tree beside the executable.
+After extraction, `./my-bin --assets-external` skips the embedded store and is
+useful for testing the external-resource path.
+
+### Why `assetsLoaderPromise` is used
+
+A more tightly coupled ESM design could export the assets with top-level
+`await`, then make the main module import `assetsLoader.mjs` directly. This
+project deliberately does not do that because `assetsLoader.mjs` contains
+Bun's compiled-file import:
+
+```js
+import assets from "./assets.tar" with { type: "file" };
+```
+
+If the regular main module imported `assetsLoader.mjs`, that Bun-specific
+`type: "file"` dependency would enter the main module graph. Node would then be
+unable to load the program before it could select an external-file fallback.
+
+Instead, only Bun's `entry.mjs` imports the Bun-specific loader, awaits its
+Promise, and then dynamically imports the regular main module. The main module
+does not import the loader, inspect the Promise, or contain Bun bootstrap code.
+Under the supported Node.js 20.11+ ESM path, Node runs that clean main module
+directly with external files. The Promise is therefore an intentional
+Node-compatibility boundary inside the Bun-only bootstrap, not a failure to use
+a more modern dependency or top-level-`await` design.
 
 ## 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`
-- The main program waits for `assetsLoaderPromise` if it exists
+- `entry.mjs` awaits `assetsLoaderPromise`
+- `entry.mjs` dynamically imports the main program after the assets are ready
 
 That keeps the main program bootable even if asset loading reports errors.
 
@@ -32,6 +236,12 @@ That keeps the main program bootable even if asset loading reports errors.
 - Asset loading never rejects the bootstrap promise
 - When loading succeeds, the archive is available through `globalThis.internalAssets`
 
+This loader is not zero-copy: it materializes every bundled file in memory and
+keeps the resulting bytes in `globalThis.internalAssets`. Large asset archives
+can therefore increase startup and ongoing RAM usage. For workloads where that
+matters, I also wrote an experimental Linux-only zero-copy hack:
+[bun-assets-zerocopy](https://github.com/jjtseng93/bun-assets-zerocopy).
+
 ## CLI Flags
 
 - `--assets-list`
@@ -46,35 +256,3 @@ That keeps the main program bootable even if asset loading reports errors.
   - Skips loading bundled assets into `globalThis.internalAssets`
   - Forces the main program and runtime helpers to use the external file tree
   - Keeps the bootstrap alive while leaving `internalAssets` falsy
-
-## Adapting this folder
-
-This single-exe folder is intended for reuse by other projects. Usually you
-only need to edit these project-specific files first:
-
-- `entry.mjs`
-- `packAssets.sh`
-
-Then the main program can import `buildEarlyExit` from `compiled.js` and call
-it before normal CLI parsing. `--build-exe` and `--build-for <target>` will run
-`packAssets.sh` first, so `assets.tar` is generated as part of the build flow.
-
-```js
-const compiledHelper = await import("./single-exe/compiled.js").catch(() => null);
-await compiledHelper?.buildEarlyExit?.(process.argv, "my-bin");
-```
-
-- `--build-exe` builds with no Bun target.
-- `--build-for <target>` passes `<target>` to `bun build --target=<target>`.
-- The second argument is the output filename. If omitted, it defaults to `single.exe`.
-
-The main program should also switch its repo/resource root when running as a
-compiled binary. Use `IS_COMPILED` and `REPO_ROOT` from
-`compiled.js`; when compiled, treat the executable directory as the repo root
-used for external fallback files such as `static/`, `README.md`, or other files
-packed by `packAssets.sh`.
-
-```js
-const compiledHelper = await import("./single-exe/compiled.js").catch(() => null);
-const repoRoot = compiledHelper?.REPO_ROOT
-```

package/single-exe/compiled.js

@@ -12,9 +12,12 @@ const SINGLE_EXE_DIR = resolve(REPO_ROOT, "single-exe");
 const SINGLE_EXE_ENTRY = resolve(SINGLE_EXE_DIR, "entry.mjs");
 
 
-export function isCompiledBinary() {
-  const argv = process.argv
-  return Boolean(argv?.[1]?.startsWith?.("/$bunfs/"));
+export function isCompiledBinary(argv = process.argv) {
+  const entry = argv?.[1];
+  return Boolean(
+    entry?.startsWith?.("/$bunfs/") ||
+    entry?.startsWith?.("B:/~BUN")
+  );
 }
 
 export function getExeDirname() {

package/single-exe/entry.mjs

@@ -3,7 +3,8 @@
 // 1. Injects assets to global.internalAssets
 //   as { "./path/in/tar":file.bytes() }
 // 2. Sets global.assetsLoaderPromise
-import "./assetsLoader.mjs"
-
-import "../src/index.js"
+// 3. Starts the main program only after the assets are ready
+import "./assetsLoader.mjs";
 
+await globalThis.assetsLoaderPromise;
+await import("../src/index.js");

package/single-exe/packAssets.sh

@@ -4,4 +4,4 @@ sd=$(dirname "$0")
 
 cd "$sd"/..
 
-tar -cvf single-exe/assets.tar demos runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md
+tar -cvf single-exe/assets.tar demos runtime README.md CHANGELOG.md cdp-maze.js src/cui/server.mjs src/cui/rpc.mjs testapp.md

package/src/cui/fence-events.mjs

@@ -0,0 +1,106 @@
+const IDENTITY_RE = /^([A-Za-z_][\w:-]*)(?:#([A-Za-z_][\w:-]*))?((?:\.[A-Za-z_][\w:-]*)*)$/;
+
+function parseIdentity(value) {
+  const match = String(value ?? "").match(IDENTITY_RE);
+  if (!match) return null;
+  return {
+    tag: match[1],
+    id: match[2] || null,
+    classes: match[3] ? match[3].slice(1).split(".") : [],
+  };
+}
+
+function parseEventAttributes(text) {
+  const events = new Map();
+  let offset = 0;
+  while (offset < text.length) {
+    while (/\s/.test(text[offset] ?? "")) offset++;
+    if (offset >= text.length || text[offset] !== "@") break;
+    offset++;
+    const nameStart = offset;
+    while (/[A-Za-z0-9_.:-]/.test(text[offset] ?? "")) offset++;
+    const name = text.slice(nameStart, offset);
+    while (/\s/.test(text[offset] ?? "")) offset++;
+    if (!name || text[offset] !== "=") break;
+    offset++;
+    while (/\s/.test(text[offset] ?? "")) offset++;
+    if (text[offset] !== '"') break;
+    offset++;
+
+    let code = "";
+    let closed = false;
+    while (offset < text.length) {
+      const ch = text[offset++];
+      if (ch === '"') {
+        closed = true;
+        break;
+      }
+      if (ch === "\\" && offset < text.length) {
+        const next = text[offset++];
+        code += next === '"' || next === "\\" ? next : `\\${next}`;
+      } else {
+        code += ch;
+      }
+    }
+    if (!closed) break;
+    const [eventName, ...modifiers] = name.split(".");
+    if (eventName === "keydown")
+      events.set(eventName, { code, modifiers: [...new Set(modifiers.filter(Boolean))] });
+  }
+  return events;
+}
+
+export function parseFenceDeclarations(markdown) {
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  const declarations = [];
+  let fence = null;
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (fence) {
+      const closing = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
+      if (closing && closing[1][0] === fence.marker && closing[1].length >= fence.length)
+        fence = null;
+      continue;
+    }
+
+    const opening = line.match(/^ {0,3}(`{3,}|~{3,})([^]*)$/);
+    if (!opening) continue;
+    fence = { marker: opening[1][0], length: opening[1].length };
+    const info = String(opening[2] ?? "").trim();
+    const firstSpace = info.search(/\s/);
+    const identityText = firstSpace < 0 ? info : info.slice(0, firstSpace);
+    const attributesText = firstSpace < 0 ? "" : info.slice(firstSpace);
+    const identity = parseIdentity(identityText);
+    if (!identity) continue;
+    declarations.push({
+      ...identity,
+      identity: identityText,
+      events: parseEventAttributes(attributesText),
+      line: index + 1,
+      source: line.trim(),
+    });
+  }
+
+  return declarations;
+}
+
+export function fenceEventMap(markdown) {
+  const result = new Map();
+  for (const declaration of parseFenceDeclarations(markdown)) {
+    if (
+      !["text", "textarea"].includes(declaration.tag)
+      || !declaration.id
+      || declaration.events.size === 0
+      || result.has(declaration.id)
+    ) continue;
+    result.set(declaration.id, declaration);
+  }
+  return result;
+}
+
+export function inlineFenceEventCode(handler) {
+  if (!handler) return "";
+  const prefix = handler.modifiers.includes("prevent") ? "event.preventDefault();" : "";
+  return prefix + handler.code;
+}

package/src/cui/id-collision.mjs

@@ -1,3 +1,5 @@
+import { parseFenceDeclarations } from "./fence-events.mjs";
+
 function markdownHeadingDeclarations(markdown) {
   const lines = String(markdown).split(/\r?\n/);
   const declarations = [];
@@ -51,34 +53,14 @@ function markdownHeadingDeclarations(markdown) {
 }
 
 function fencedBlockDeclarations(markdown) {
-  const lines = String(markdown).split(/\r?\n/);
-  const declarations = [];
-  let fence = null;
-
-  for (let index = 0; index < lines.length; index++) {
-    const line = lines[index];
-    if (!fence) {
-      const opening = line.match(/^ {0,3}(`{3,}|~{3,})\s*(\S+)?\s*$/);
-      if (!opening) continue;
-      fence = { marker: opening[1][0], length: opening[1].length };
-      const identity = String(opening[2] ?? "").match(/^([A-Za-z_][\w:-]*)(?:#([A-Za-z_][\w:-]*))?(?:\.[A-Za-z_][\w:-]*)*$/);
-      if (identity?.[2]) {
-        declarations.push({
-          id: identity[2],
-          kind: `${identity[1]} fenced block`,
-          line: index + 1,
-          source: line.trim(),
-        });
-      }
-      continue;
-    }
-
-    const closing = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
-    if (closing && closing[1][0] === fence.marker && closing[1].length >= fence.length)
-      fence = null;
-  }
-
-  return declarations;
+  return parseFenceDeclarations(markdown)
+    .filter((declaration) => declaration.id)
+    .map((declaration) => ({
+      id: declaration.id,
+      kind: `${declaration.tag} fenced block`,
+      line: declaration.line,
+      source: declaration.source,
+    }));
 }
 
 export function checkMarkdownIdCollisions(markdown) {

package/src/cui/kitty-debug.mjs

@@ -1,7 +1,7 @@
 import { appendFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-export const KITTY_DEBUG_LOG = resolve(import.meta.dir, "../..", "kitty-placement.log");
+export const KITTY_DEBUG_LOG = resolve(import.meta.dirname, "../..", "kitty-placement.log");
 export const KITTY_DEBUG_ENABLED = /^(1|true|yes|on)$/i.test(
   String(process.env.JSMDCUI_KITTY_DEBUG ?? ""),
 );

package/src/cui/kitty-images.mjs

@@ -117,6 +117,10 @@ function stableImageId(pathname, line, data) {
   return (hash >>> 0) % 2147483646 + 1;
 }
 
+async function convertToKittyPng(data) {
+  return Buffer.from(await new Bun.Image(data).png().toBuffer());
+}
+
 export function fitKittyImageToWidth(image, maxCols) {
   const originalCols = Math.max(1, Math.trunc(Number(image?.cols) || 1));
   const originalRows = Math.max(1, Math.trunc(Number(image?.rows) || 1));
@@ -151,8 +155,14 @@ export async function prepareKittyImages(ansiText, markdownPath, terminalCols =
         if (!(await file.exists())) throw new Error("missing image");
         data = Buffer.from(await file.arrayBuffer());
       }
-      const size = imageSize(data);
+      let size = imageSize(data);
       if (!size?.width || !size?.height) throw new Error("unsupported image");
+      if (options.kittyMode === "compat" && size.mime !== "image/png") {
+        data = await convertToKittyPng(data);
+        size = imageSize(data);
+        if (size?.mime !== "image/png" || !size.width || !size.height)
+          throw new Error("PNG conversion failed");
+      }
       const estimatedCols = Math.max(1, Math.round(size.width / 8));
       const cols = Math.min(maxCols, estimatedCols);
       const rows = Math.max(1, Math.round((cols * size.height) / size.width / 2));

package/src/cui/rpc.mjs

@@ -451,15 +451,18 @@ function safeFrontValue(value)
   };
 }
 
-export async function evalFront(mod, text) 
+export async function evalFront(mod, text, scope = {})
 {
 try{
 
     text = text.replace(/^javascript:/, "");
 
-    const entries = Object.entries(mod).filter(([name]) => name !== "$");
+    const entryMap = new Map(Object.entries(mod).filter(([name]) => name !== "$"));
     if (typeof globalThis.$ === "function")
-      entries.push(["$", globalThis.$]);
+      entryMap.set("$", globalThis.$);
+    for (const [name, value] of Object.entries(scope))
+      entryMap.set(name, value);
+    const entries = [...entryMap];
     const names = entries.map(([name]) => name);
     const values = entries.map(([, value]) => safeFrontValue(value));
 

package/src/cui/server.mjs

@@ -50,7 +50,7 @@ export function main()
 
 const basePath = "/" + crypto.randomUUID()
 const pathname = basePath + "/"
-const server = Bun.serve({
+const serverOptions = {
   port: Number(process.env.PORT || 3000),
   development: {
     hmr: true,
@@ -101,7 +101,18 @@ const server = Bun.serve({
   fetch() {
     return new Response("Not Found", { status: 404 });
   },
-});
+};
+
+let server;
+try {
+  server = Bun.serve(serverOptions);
+} catch (error) {
+  const addressInUse = error?.code === "EADDRINUSE"
+    || error?.cause?.code === "EADDRINUSE"
+    || /EADDRINUSE|address already in use/i.test(String(error?.message || error));
+  if (serverOptions.port !== 3000 || !addressInUse) throw error;
+  server = Bun.serve({ ...serverOptions, port: 0 });
+}
 
 console.error(mda("- Bun RPC server listening on"));
 console.log(`http://localhost:${server.port}${pathname}`);