buninu 0.3.1 → 0.4.0

package/apps/jsmdcui/single-exe/README.md

@@ -1,473 +1,396 @@
-# Bun Single-File Executable Bootstrap
+# Single-file executable bootstrap
 
-Build a Bun application and its runtime assets into one executable while
-keeping the regular main module free of Bun-specific asset imports.
+Bundles a project's runtime assets into one `bun build --compile` binary, so
+the executable carries its own `demos/`, `runtime/`, templates and so on.
 
-You can copy and adapt this build setup for your own project by changing its
-main-module path and asset list as described below.
+Assets are declared once, in `package.json`:
 
-- 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.
-
-> This workflow is optional; the standard methods in the root README remain
-> available. Bun's Android build is currently not supported.
-
-## Quick start for jsmdcui
-
-From the repository root, build for the current platform:
-
-```shell
-bun ./src/index.js --build-exe
-./mdcui --version
+```json
+{
+  "assets": ["demos", "runtime", "README.md", "src/cui/server.mjs"]
+}
 ```
 
-`--build-exe` runs `packAssets.sh` automatically and writes the `mdcui`
-executable to the current directory. To pass a Bun compilation target, use:
+Paths are relative to the project root. Folders are packed recursively; only
+regular files are stored, so symlinks and empty folders leave no trace.
 
-```shell
-bun ./src/index.js --build-for <target>
-```
+## The two back ends
 
-Any additional arguments after `--build-exe`, or after the target passed to
-`--build-for`, are forwarded to the `bun build` command:
+The default packs everything into a gzipped `assets.tar` that is embedded as a
+single file and unpacked into memory at startup. Setting `ASSETS_BUNFS=1` at
+build time switches to `bun build --compile --asset`, which stores the files
+individually inside the binary's virtual filesystem instead.
 
-```shell
-bun ./src/index.js --build-exe --sourcemap
-bun ./src/index.js --build-for <target> --sourcemap
-```
+Reading code never sees the difference — `assetsHelper` answers the same keys
+either way. The trade is binary size against startup cost:
 
-Bun expects `--define` values to be JSON-style literals, so strings normally
-need quotes. `stringifyNonPrimitiveDefineValues()` converts a bare value with
-`JSON.stringify()` before it reaches Bun. jsmdcui uses it for
-`global.MDCUI_MAIN`.
-
-`global.MDCUI_MAIN` is a jsmdcui application convention, not a name reserved by
-the single-executable helpers. An adopting project can use
-`global.MY_EMBEDDED_APP`, or any other build expression, as long as it updates
-its own call sites and passes the same name to
-`stringifyNonPrimitiveDefineValues()`.
-
-The jsmdcui switch defines below are presence-based: `=0` and `=false` still
-enable them. Omit a switch define to disable it; examples consistently use
-`=1`.
-
-- `MDCUI_DEFAULT_EDIT=1`: editable-text default.
-- `MDCUI_DEFAULT_DEMO=1`: no-argument `testapp.md` TUI.
-- `MDCUI_DEFAULT_DEMO_WUI=1`: no-argument `testapp.md` WUI.
-- `MDCUI_OVERWRITE_DEMO=1`: overwrite modifier; it does not select a demo.
-- `global.MDCUI_MAIN=<path>.md`: embed a custom Markdown app and its generated
-  front, RPC, back, HTML, and server modules.
-- `global.MDCUI_MAIN_BASE`: generated internally from `MDCUI_MAIN`; do not pass
-  it manually.
-
-Put defines after `--build-exe` (or after the `--build-for` target), and choose
-at most one `MDCUI_DEFAULT_*` mode.
-
-| Build defines | No-argument launch | Switch UI |
+| | tar (default) | `ASSETS_BUNFS=1` |
 | --- | --- | --- |
-| `MDCUI_DEFAULT_EDIT=1` | text editor | `./mdcui --tui app.md` |
-| `MDCUI_DEFAULT_DEMO=1` | `testapp.md` TUI | `./mdcui --wui --demo` |
-| `MDCUI_DEFAULT_DEMO_WUI=1` | `testapp.md` WUI | `./mdcui --tui --demo` |
-| `global.MDCUI_MAIN=../中文工具.md` | custom TUI | `./mdcui --wui --demo-中文工具` |
-| MAIN plus `MDCUI_DEFAULT_DEMO_WUI=1` | custom WUI | `./mdcui --tui --demo-中文工具` |
-
-For a custom TUI-default executable:
-
-```shell
-bun ./src/index.js --build-exe \
-  --define global.MDCUI_MAIN=../中文工具.md
-```
-
-For a custom WUI-default executable:
+| Stored as | one gzipped archive | individual files, uncompressed |
+| Size, for jsgotty's 3.45 MB of assets | **0.70 MB** | 3.45 MB |
+| Work before `main` runs | decode the archive, copy every file into memory | **none** |
+| Startup cost, same assets | ~16 ms | **0 ms** |
+| Resident memory | whole payload, always | only what is read |
+| Maturity | in use | experimental |
+
+Text compresses well, so the tar usually wins on size by a wide margin — the
+numbers above are mostly one 1.6 MB bundle and its source map. What it costs is
+paid on every run, whether or not the program touches a single asset. Reach for
+`ASSETS_BUNFS=1` when that startup work, or holding the whole payload in memory,
+matters more than the extra megabytes on disk.
+
+## Adopting it in another project
+
+Copy `single-exe/` to the project root. Nothing inside it hard-codes its own
+name or depth, so it can be renamed or moved — but the importing code has to
+follow, so staying at the root is the easy path. Three edits point it at the
+project around it.
+
+1. **`assetsPacker.js`, the first two lines.** They are the only place the
+   asset root is written down, and a static import specifier cannot be
+   computed, so both must be literal:
+
+   ```js
+   import pkg from "../package.json" with { type: "json" };
+   export const ASSETS_ROOT = "..";
+   ```
+
+2. **`entry.mjs`, the import of the program.** It names what to start, and
+   entry.mjs is the compiled entry point in both back ends:
+
+   ```js
+   await import("../src/index.js");
+   ```
+
+   **Keep the `await`.** It reads like a formality — nothing here needs the
+   module object — but together with the `await globalThis.assetsLoaderPromise`
+   line above it, it is the only top-level `await` the compiled program writes
+   anywhere, and `--bytecode` reads exactly that to decide the program starts
+   asynchronously. Turn both into `.then(…)` and the build produces an
+   executable that exits 0 without running a line.
+   [Why](#the-await-in-entrymjs-is-load-bearing) explains the trap.
+
+3. **`package.json`.** Add the `assets` array shown above.
+
+Everything else — `compiled.js`, `assetsHelper.js`, `assetsLoader.mjs` — is
+project independent, with one exception: `buildHtmlBundleImageMap` defaults its
+attribute name to jsmdcui's `data-mdcui-src`, so pass your own.
+
+Node's own entry path must not import `assetsLoader.mjs` or `entry.mjs`; those
+are Bun only. `assetsHelper.js` and `compiled.js` run under Node 20.11+.
+
+## Reading assets
+
+Import from `assetsHelper.js`. Keys are the same package-relative paths that
+appear in `package.json`.
+
+| Function | Returns |
+| --- | --- |
+| `readInternalAssetText(path)` | string, or `null` when not embedded |
+| `readInternalAssetBytes(path)` | `Uint8Array`, or `null` |
+| `readAssetText(path)` | string, falling back to the file on disk |
+| `readAssetBytes(path)` | `Uint8Array`, same fallback |
+| `hasInternalAssets()` | whether this package has anything embedded |
+| `listInternalAssetPaths(prefix?)` | every embedded path under `prefix` |
+| `listInternalAssetDirs(prefix?)` | the immediate child names under `prefix` |
+| `assetPath(...parts)` | joins parts into a key |
+| `getAssetKey(path)` | the key as stored, namespace included |
+| `assetDiskPath(path)` | where the disk fallback reads that key from |
+| `SELF` | this package's namespace, `assets/<name>@<version>` |
+
+The read functions are synchronous for embedded assets on both back ends.
+`readAssetText` / `readAssetBytes` are async only because of the disk
+fallback, which is what makes the same code work from a source checkout.
+
+**Only the read functions fall back to disk.** The listing functions report
+what is embedded and nothing else, so from a source checkout they return an
+empty array. Branch on `hasInternalAssets()` and read the directory yourself:
 
-```shell
-bun ./src/index.js --build-exe \
-  --define global.MDCUI_MAIN=../中文工具.md \
-  --define MDCUI_DEFAULT_DEMO_WUI=1
+```js
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readAssetText, hasInternalAssets, listInternalAssetDirs } from "../single-exe/assetsHelper.js";
+import { REPO_ROOT } from "../single-exe/compiled.js";
+
+//  Embedded or on disk, this one already works either way.
+const page = await readAssetText("templates/page.html");
+
+//  Listing does not, so pick the source.
+const demos = hasInternalAssets()
+  ? listInternalAssetDirs("demos")
+  : readdirSync(join(REPO_ROOT, "demos"));
 ```
 
-Explicit runtime arguments suppress automatic demo/WUI selection, so switching
-UI must repeat `--demo` or `--demo-中文工具`. The main basename must end in
-lowercase `.md`; its demo name allows Unicode letters/numbers (including
-Chinese), dots, underscores, and hyphens, but no whitespace.
+## Building
 
-The custom demo uses embedded TUI front/RPC or the embedded WUI server when its
-local Markdown byte length matches the embedded asset. Missing or overwritten
-demos use embedded modules after the asset is written. A differing byte length
-warns and selects filesystem companion modules.
+`compiled.js` exports the build entry points. Wire `buildEarlyExit` into the
+CLI and it handles `--build-exe` and `--build-for <target>`:
 
-To perform the same steps manually, run these commands from `single-exe/`:
+```js
+import { buildEarlyExit, IS_COMPILED, REPO_ROOT } from "./single-exe/compiled.js";
 
-```shell
-bun ./packAssets.sh
-bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=mdcui
+await buildEarlyExit(process.argv, "myapp");
 ```
 
-## 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
-```
+`REPO_ROOT` is the project root in a checkout and the executable's own folder
+once compiled, which is where `--assets-extract` writes. `IS_COMPILED` tells
+the two apart.
 
-`assets.tar` is generated by `packAssets.sh`; it does not need to exist before
-the first packing step.
+### Chaining file/folder assets across dependencies
 
-### 2. Point `entry.mjs` at the main program
+A build first bundles once to write a metafile, then treats every
+`assetsPacker.js` appearing in its `inputs` as a participant. Each package
+vendors its own `single-exe/`, and its `assetsHelper` imports its
+`assetsPacker`, so a packer lands in that graph exactly when the package is
+reachable from the entry point. There is no registration step, and anything
+tree-shaken away brings nothing with it.
 
-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:
+The packers then run one after another, each adding its files under its own
+`assets/<name>@<version>/` namespace — appending into the shared `assets.tar`
+by default, or copying into the shared `build/assets` tree under
+`ASSETS_BUNFS=1`. Only once every packer has finished does the real compile
+run, so the archive is complete and, by default, compressed by then.
 
-```js
-#!/usr/bin/env bun
+That namespace is why `ASSETS_BUNFS=1` stages every package into one fixed
+`build/assets`. `--asset` keeps only the **basename** of the path it is given
+and preserves everything below it, so the folder's own name becomes the root
+inside the binary:
 
-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
+--asset ./build/assets   with   build/assets/jsgotty@1.1.6/static/index.html
+                          ->    assets/jsgotty@1.1.6/static/index.html
 ```
 
-### 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
-```
+Pass `./build/assets/jsgotty@1.1.6` instead and `build/assets/` is gone: the
+files land at `jsgotty@1.1.6/...` and every package gets its own root. One
+folder named `assets`, everyone copying into it, is what makes the keys come
+out the same as the ones the tar back end writes.
 
-Do not retain jsmdcui's `demos`, `runtime`, `src/cui`, or `testapp.md` entries
-unless the adopting project actually contains and needs them.
+`assetsPacker.js` also runs standalone; `--help` documents its flags.
 
-### 4. Read embedded assets with an external fallback
+## Why the loader hands over a Promise
 
-Import `readAssetText()` or `readAssetBytes()` from `assetsHelper.js`. They
-first read the embedded asset and automatically fall back to the same path
-under `REPO_ROOT` when the asset is not embedded:
+`entry.mjs` imports `assetsLoader.mjs`, awaits `globalThis.assetsLoaderPromise`,
+and only then imports the main program. The indirection is deliberate: the
+loader carries a Bun-only import,
 
 ```js
-import {
-  readAssetBytes,
-  readAssetText,
-} from "../single-exe/assetsHelper.js";
-
-// Embedded asset first; external REPO_ROOT/templates/page.html fallback.
-const source = await readAssetText("templates/page.html");
-
-// The same fallback behavior, returned as Uint8Array.
-const image = await readAssetBytes("images/photo.png");
+import assets from "./assets.tar" with { type: "file" };
 ```
 
-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. Use `readInternalAssetBytes()` when a
-resource should be returned as embedded bytes without the fallback.
-Use `listInternalAssetPaths()` to list embedded asset paths and
-`listInternalAssetDirs()` to list embedded directories.
+and if the main program imported the loader, that dependency would land in its
+module graph. Node could then no longer load the program at all — not even to
+fall back to reading the assets from disk.
 
-#### Reuse images from a compiled HTML bundle
+Keeping the loader behind `entry.mjs` means the main program never mentions it,
+so Node 20.11+ runs the same file directly against on-disk assets while Bun
+runs it through the bootstrap. The Promise is that boundary, not a workaround
+for missing top-level await.
 
-Bun exposes an imported HTML entry as a `homepage` object in a compiled
-executable. Its `index` points to the compiled HTML and its `files` array lists
-the content-hashed assets under Bun's compiled virtual filesystem: paths
-normally begin with `/$bunfs/root/` on POSIX systems and `B:/~BUN/` on
-Windows. The helpers can turn image references preserved in that HTML into a
-lazy path map without copying the image bytes into `internalAssets`. Always use
-the path returned by `homepage.files`; do not hard-code either platform prefix.
+`ASSETS_BUNFS=1` sidesteps the question: there is no tar to load, so the build
+writes `.bunfs-entry.mjs` next to `entry.mjs` — the same file with the loader
+import removed — compiles that, and deletes it afterwards. A copy rather than a
+stub, because entry.mjs may do more than import the program: a CommonJS main
+that starts itself from `require.main === module` needs the exported starter
+called instead, and that call has to survive.
 
-Before compiling, preserve each original image reference in a custom
-attribute. Its name belongs to the adopting project; it is not fixed by the
-helper. This example chooses `data-original-image`. Bun rewrites `src` but
-leaves the custom attribute intact:
-
-```html
-<!-- Input -->
-<img src="./images/photo.jpg" data-original-image="./images/photo.jpg">
+## The `await` in entry.mjs is load-bearing
 
-<!-- Compiled HTML -->
-<img src="/photo-abcd1234.jpg" data-original-image="./images/photo.jpg">
-```
+`--bytecode` decides whether a program starts asynchronously by looking for a
+top-level `await` **written in some file's own source**. The bundler moves a
+module into a lazy init function whenever something dynamically imports it, and
+a module moved that way takes its top-level `await` with it — what stays behind
+is an `await init_x()` the bundler wrote itself, which does not count. If no
+file wrote one, the executable is evaluated on the synchronous path, its
+suspended startup is dropped, and it exits 0 having run nothing. No error, at
+any `--minify` setting, however small the program.
 
-Export the imported HTML bundle from a module that both the web server and
-terminal runtime can load:
+`entry.mjs` is immune because it writes two of its own:
 
 ```js
-import homepage from "./index.html";
-
-export { homepage };
+await globalThis.assetsLoaderPromise;
+await import("../src/index.js");
 ```
 
-Build and cache the map only in a compiled executable. Guard the import first:
-a source-tree launch does not necessarily have the generated server or HTML
-module.
+One is enough, and every other `await` in the graph — all of
+`assetsLoader.mjs`'s, for one — sits inside a function and cannot help. Turn
+both of these into `.then(…)` and the flag is gone. It is also why bunfs builds
+compile a copy of this file rather than handing the main program to `bun build`
+directly: a main program that reaches top-level await only through its imports
+writes none of its own.
 
-```js
-import {
-  buildHtmlBundleImageMap,
-  canonicalHtmlBundleImageHref,
-} from "../single-exe/assetsHelper.js";
-import { IS_COMPILED } from "../single-exe/compiled.js";
+Upstream: `src/bundler/linker_context/postProcessJSChunk.rs` skips exactly the
+modules the bundler moved, still true on oven-sh/bun `main` at 8eb5b6e2b5
+(2026-08-22). Until that changes, treat both `await`s as API.
 
-let imageMapPromise = null;
-const imageSourceAttribute = "data-original-image";
+## Environment variables
 
-function getBundledImageMap() {
-  if (!IS_COMPILED || !global.MY_EMBEDDED_APP) return null;
+| Variable | When | Effect |
+| --- | --- | --- |
+| `ASSETS_BUNFS=1` | build | use `--asset` instead of the tar |
+| `ASSETS_NO_GZIP=1` | build | leave `assets.tar` uncompressed |
+| `ASSETS_DEBUG=1` | run | print how long unpacking took |
 
-  imageMapPromise ??= import(global.MY_EMBEDDED_APP + "-server.js")
-    .then(module => buildHtmlBundleImageMap(
-      module.homepage,
-      imageSourceAttribute,
-    ));
+## Runtime flags
 
-  return imageMapPromise;
-}
+| Flag | Effect |
+| --- | --- |
+| `--assets-list` | print every embedded path and exit |
+| `--assets-extract` | write the assets next to the executable and exit |
+| `--assets-external` | ignore embedded assets and read from disk |
 
-const images = await getBundledImageMap();
-const key = canonicalHtmlBundleImageHref(originalImageHref);
-const bundledPath = images?.get(key);
-const bytes = bundledPath ? await Bun.file(bundledPath).bytes() : null;
-```
+These are handled by `assetsLoader.mjs`, so they exist in tar builds only.
 
-`global.MY_EMBEDDED_APP` is only an example build-time module selector. Name it
-to match the adopting application, replace it with a direct static import, or
-use another compiled-only condition. The helper does not inspect or require
-`global.MDCUI_MAIN`; that is jsmdcui's own convention. When using a Bun
-`--define`, use the same expression at the call site, for example
-`--define global.MY_EMBEDDED_APP=...`.
+## Advanced usage
 
-`buildHtmlBundleImageMap(homepage, sourceAttribute)` reads the compiled HTML
-once and returns a `Map<string, string>` from canonical original image
-references to Bun compiled virtual paths on either platform. The second
-argument is the custom attribute name. It defaults to `"data-mdcui-src"` only
-for jsmdcui's convenience:
-
-```js
-const images = await buildHtmlBundleImageMap(homepage);
-```
+### Forwarding arguments to `bun build`
 
-Adopting projects can choose any valid HTML attribute name and pass it
-explicitly:
+Anything after `--build-exe`, or after the target given to `--build-for`, is
+passed straight through to `bun build`:
 
-```html
-<img src="./photo.jpg" data-original-image="./photo.jpg">
+```shell
+bun ./src/index.js --build-exe --sourcemap
+bun ./src/index.js --build-for bun-linux-x64 --sourcemap
 ```
 
-```js
-const images = await buildHtmlBundleImageMap(
-  homepage,
-  "data-original-image",
-);
-```
+Order matters. The flags have to come after the build switch, or Bun consumes
+them before the program ever starts:
 
-The helper decodes HTML attribute entities and percent encoding so the HTML
-reference can match the equivalent original caller reference. Image bytes
-remain lazy and are read only when the caller uses the returned path.
+```shell
+# Wrong: Bun parses this define before any of your code runs
+bun --define MY_APP=../app.md ./src/index.js --build-exe
 
-For lower-level lookup, `findHtmlBundleAsset(homepage, publicPath, options)`
-matches a rewritten public path such as `/photo-abcd1234.jpg` to its
-`homepage.files` entry. `findHtmlBundleImageAsset()` restricts the lookup to
-`image/*`, and `htmlBundleImageAssetPath()` returns only the corresponding
-Bun compiled virtual path.
+# Right
+bun ./src/index.js --build-exe --define MY_APP=../app.md
+```
 
-### 5. Add the optional build commands to the regular CLI
+### `--define` with a string value
 
-Before normal argument parsing, call `buildEarlyExit` from the regular main
-module:
+**Bun expects `--define` values to be JSON literals, so a string has to arrive
+already quoted.** A bare path is read as an identifier and the build fails or
+inlines something unintended. Quoting it through a shell is awkward, so
+`compiled.js` exports a helper that does it:
 
 ```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:
+import { buildEarlyExit, stringifyNonPrimitiveDefineValues } from "./single-exe/compiled.js";
 
-```shell
-bun ./src/index.js --build-exe
-bun ./src/index.js --build-for <target>
+stringifyNonPrimitiveDefineValues(process.argv, "MY_APP");
+await buildEarlyExit(process.argv, "my-bin");
 ```
 
-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/`:
+Call it before `buildEarlyExit`, once per define name you want treated as a
+string. It rewrites the value in place:
 
-```shell
-bun ./packAssets.sh
-bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=my-bin
+```js
+["--define", "MY_APP=../app.md"]      // what the user typed
+["--define", 'MY_APP="../app.md"']    // what Bun receives
 ```
 
-#### Passing --define to bun build
+`--define=MY_APP=../app.md` works the same way. Numbers, booleans, `null` and
+`undefined` are left alone, so only genuine strings get quoted.
 
-`buildEarlyExit()` forwards build arguments to Bun, whose define parser expects
-strings to be quoted literals. To accept a bare value such as a path, call the below
-helper to normalize it before `buildEarlyExit()`:
+### Images from an imported HTML bundle
 
-```js
-import {
-  buildEarlyExit,
-  stringifyNonPrimitiveDefineValues,
-} from "../single-exe/compiled.js";
+A compiled binary exposes an imported HTML entry as a `homepage` object:
+`homepage.index` is the compiled HTML and `homepage.files` lists the
+content-hashed assets by their path inside the binary. `assetsHelper` can map
+the *original* image references back to those paths, without copying any image
+bytes into memory.
 
-stringifyNonPrimitiveDefineValues(process.argv, "MY_STRING_DEFINE");
-await buildEarlyExit(process.argv, "my-bin");
-```
+Bun rewrites `src` during the build, so keep the original reference in a custom
+attribute of your own choosing:
 
-```shell
-# Wrong: Bun parses the define before the helper runs.
-bun --define MY_STRING_DEFINE=../app.md ./src/index.js --build-exe
+```html
+<!-- source -->
+<img src="./images/photo.jpg" data-original-image="./images/photo.jpg">
 
-# Correct
-bun ./src/index.js --build-exe --define MY_STRING_DEFINE=../app.md
+<!-- compiled -->
+<img src="/photo-abcd1234.jpg" data-original-image="./images/photo.jpg">
 ```
 
-Before normalization:
+Then build the map once, in a compiled binary only:
 
 ```js
-["--define", "MY_STRING_DEFINE=../app.md"]
-```
+import { buildHtmlBundleImageMap, canonicalHtmlBundleImageHref } from "../single-exe/assetsHelper.js";
+import { IS_COMPILED } from "../single-exe/compiled.js";
 
-After normalization:
+const images = IS_COMPILED
+  ? await buildHtmlBundleImageMap(homepage, "data-original-image")
+  : null;
 
-```js
-["--define", 'MY_STRING_DEFINE="../app.md"']
+const path = images?.get(canonicalHtmlBundleImageHref(originalHref));
+const bytes = path ? await Bun.file(path).bytes() : null;
 ```
 
-The inline form works too:
-`--define=MY_STRING_DEFINE=../app.md` becomes
-`--define=MY_STRING_DEFINE="../app.md"`.
+`buildHtmlBundleImageMap` returns a `Map` from canonical original reference to
+the path inside the binary; it decodes HTML entities and percent encoding so a
+reference written either way still matches. Reading stays lazy — the bytes are
+only touched when you use the returned path.
 
+Lower level, if you already hold a rewritten public path such as
+`/photo-abcd1234.jpg`: `findHtmlBundleAsset(homepage, publicPath, options)`
+finds its `homepage.files` entry, `findHtmlBundleImageAsset()` restricts that
+to `image/*`, and `htmlBundleImageAssetPath()` returns just the path.
 
-### 6. Verify both execution paths
+Never hard-code `/$bunfs/root/` or `B:/~BUN/`; always use the path that
+`homepage.files` reports.
 
-Verify the compiled asset archive and then run the program normally:
+## jsmdcui specifics
 
-```shell
-./my-bin --assets-list
-./my-bin
-```
+The rest of this file is generic. These names belong to jsmdcui itself and are
+not reserved by the bootstrap — an adopting project picks its own.
 
-Also run the uncompiled main module with Node.js 20.11 or newer to verify that
-all required files have a working external fallback:
+Embedding a Markdown app has its own flags, and they are what you normally
+want:
 
 ```shell
-node ./src/index.js
+bun ./src/index.js --build-md-exe ./中文工具.md
+bun ./src/index.js --build-md-for bun-linux-x64 ./中文工具.md
 ```
 
-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:
+Each expands into the plain build switch plus the define, so the low-level form
+below is only needed when you want to combine it with other defines or drive
+the build yourself:
 
-```js
-import assets from "./assets.tar" with { type: "file" };
+```shell
+--build-md-exe ./app.md        ->  --build-exe --define global.MDCUI_MAIN=./app.md
+--build-md-for <p> ./app.md    ->  --build-for <p> --define global.MDCUI_MAIN=./app.md
 ```
 
-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.
+`global.MDCUI_MAIN` embeds a custom Markdown app together with its generated
+front, RPC, back, HTML and server modules. It is a string define, so it goes
+through `stringifyNonPrimitiveDefineValues(process.argv, "global.MDCUI_MAIN")`.
+`global.MDCUI_MAIN_BASE` is derived from it during the build; never pass it by
+hand.
 
-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.
+The switch defines are presence-based — `=0` and `=false` still enable them, so
+omit a switch to disable it. Choose at most one `MDCUI_DEFAULT_*` mode.
 
-## 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`
-- `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.
-
-## 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`
+| Build define | No-argument launch | Switch UI at runtime |
+| --- | --- | --- |
+| `MDCUI_DEFAULT_EDIT=1` | text editor | `./mdcui --tui app.md` |
+| `MDCUI_DEFAULT_DEMO=1` | `testapp.md` TUI | `./mdcui --wui --demo` |
+| `MDCUI_DEFAULT_DEMO_WUI=1` | `testapp.md` WUI | `./mdcui --tui --demo` |
+| `global.MDCUI_MAIN=../中文工具.md` | custom TUI | `./mdcui --wui --demo-中文工具` |
+| the above plus `MDCUI_DEFAULT_DEMO_WUI=1` | custom WUI | `./mdcui --tui --demo-中文工具` |
 
-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).
+`MDCUI_OVERWRITE_DEMO=1` is a modifier, not a mode; it does not select a demo.
 
-## CLI Flags
+```shell
+# custom TUI-default executable
+bun ./src/index.js --build-md-exe ../中文工具.md
 
-- `--assets-list`
-  - Lists all entries inside bundled `assets.tar`
-  - Exits early before the main program starts
+# custom WUI-default executable, where the second define needs the long form
+bun ./src/index.js --build-md-exe ../中文工具.md \
+  --define MDCUI_DEFAULT_DEMO_WUI=1
+```
 
-- `--assets-extract`
-  - Extracts bundled assets to the same directory as the executable
-  - Exits early before the main program starts
+Explicit runtime arguments suppress the automatic demo/WUI selection, so
+switching UI has to repeat `--demo` or `--demo-中文工具`. The main basename must
+end in lowercase `.md`; the demo name it derives allows Unicode letters and
+numbers, dots, underscores and hyphens, but no whitespace.
 
-- `--assets-external`
-  - 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
+The custom demo uses the embedded TUI front/RPC, or the embedded WUI server,
+when the local Markdown byte length matches the embedded asset. A missing or
+overwritten demo uses the embedded modules after the asset is written. A
+differing byte length warns and falls back to the filesystem companions.