jsmdcui 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.11.1] - 2026-07-26
+
+### Changed
+
+- Accept a bare `global.MDCUI_MAIN` path in forwarded build arguments by
+  automatically encoding non-primitive define values as JavaScript strings.
+
+## [0.11.0] - 2026-07-26
+
+This release adds custom Markdown-app embedding for Bun single-file
+executables, with explicit per-buffer selection between embedded and
+filesystem modules in both TUI and WUI.
+
+### Added
+
+- Add the build-time `global.MDCUI_MAIN` string define for embedding a custom
+  Markdown app together with its generated front, RPC, back, HTML, and server
+  modules. Build preparation resolves and validates the source, copies it into
+  the bundled demos, derives `global.MDCUI_MAIN_BASE`, and selects the app on a
+  no-argument launch.
+- Add a bundling mode to `extractJs()` and `createWui()`. It emits a
+  browser-only `.tmpfs.js` front module and a `.tmpfi.js` installer that exposes
+  the front exports on `window`, then makes the bundled HTML load that entry.
+- Add embedded WUI server startup and report whether WUI is starting an
+  embedded or external server before launch.
+- Add `micro.CurPane().Buf.MdcuiModuleSource`, returning `embedded` or
+  `external`, and show the value in the bundled `showpath` example.
+- Allow Unicode letters and numbers, including Chinese, in custom demo names
+  while continuing to reject whitespace and path separators.
+- Show `global.MDCUI_MAIN` and the generated `global.MDCUI_MAIN_BASE` in
+  `--version` distribution settings.
+
+### Changed
+
+- Track embedded-module selection per buffer. The configured demo uses
+  embedded TUI front/RPC and WUI server modules when its local byte length
+  matches the bundled Markdown. Missing or overwritten copies are written
+  first and then use embedded modules; other files and changed-size demos use
+  filesystem companions.
+- Document presence-based `MDCUI_*` defines with `=1`, supported build-flag
+  combinations, and commands for switching a TUI-default build to WUI or a
+  WUI-default build to TUI.
+
+### Fixed
+
+- Bundle and load the configured app's front, RPC, back, server, and dependency
+  graph so custom apps with companion imports can run from a single
+  executable.
+- Keep unrelated Markdown buffers on external modules instead of reusing the
+  embedded main app's front and RPC modules.
+- Use the bundled file's byte length after `MDCUI_OVERWRITE_DEMO` replaces a
+  stale local demo, ensuring that the overwritten app selects embedded
+  modules.
+- Install WUI front exports on `window` without relying on the generated front
+  module's process-dependent or self-import path.
+
 ## [0.10.1] - 2026-07-25
 
 ### Fixed

package/README.md

@@ -757,54 +757,94 @@ both are equivalent to `-encoding mdcui`.
 
 ### Build-time distribution constants
 
-Single-file distributions can define one of these default modes:
+The following switch defines are presence-based: the program checks whether
+they were passed, not whether their values are true. Consequently, `=0` and
+`=false` still enable a switch. Omit a define entirely to disable it. Examples
+use `=1` to make this explicit.
+
+- `MDCUI_DEFAULT_EDIT=1`: open files as editable text by default.
+- `MDCUI_DEFAULT_DEMO=1`: add `--demo` when launched without arguments.
+- `MDCUI_DEFAULT_DEMO_WUI=1`: add `--wui` when launched without arguments.
+- `MDCUI_OVERWRITE_DEMO=1`: add `--overwrite-demo`; this modifies a selected
+  demo but does not select one by itself.
+- `global.MDCUI_MAIN=<path>.md`: embed a custom Markdown application and its
+  generated front, RPC, back, HTML, and server modules. When this define is
+  forwarded after `--build-exe` or `--build-for`, a non-primitive value such as
+  a bare path is automatically encoded as a JavaScript string. An explicitly
+  quoted string remains supported.
+- `global.MDCUI_MAIN_BASE`: internal define generated automatically from
+  `global.MDCUI_MAIN`; do not pass it manually.
+
+Place every build define after `--build-exe`, or after the target argument of
+`--build-for`. Choose at most one of `MDCUI_DEFAULT_EDIT`,
+`MDCUI_DEFAULT_DEMO`, and `MDCUI_DEFAULT_DEMO_WUI`.
+
+| Build defines | No-argument launch | Open the same app in the other UI |
+| --- | --- | --- |
+| none | normal CLI/TUI | `./mdcui --wui app.md` |
+| `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` | embedded custom TUI | `./mdcui --wui --demo-中文工具` |
+| MAIN plus `MDCUI_DEFAULT_DEMO_WUI=1` | embedded custom WUI | `./mdcui --tui --demo-中文工具` |
 
-- `MDCUI_DEFAULT_EDIT`: open files as editable text by default.
-- `MDCUI_DEFAULT_DEMO`: add `--demo` when launched without arguments.
-- `MDCUI_DEFAULT_DEMO_WUI`: add `--wui` when launched without arguments.
+Any explicit runtime argument suppresses the no-argument demo/WUI injection.
+That is why the commands in the last column repeat `--demo` or
+`--demo-中文工具`; `./mdcui --wui` by itself does not implicitly select a custom
+main application.
 
-Choose only one of the three default-mode constants for a distribution.
-`MDCUI_OVERWRITE_DEMO` is an optional modifier for the demo or WUI mode.
-These are presence-based constants, so their build values do not require
-shell-quoted strings:
+To package `../中文工具.md` as a TUI by default:
 
 ```sh
-bun src/index.js --build-exe --define MDCUI_DEFAULT_EDIT=true
-```
+bun src/index.js --build-exe \
+  --define global.MDCUI_MAIN=../中文工具.md
 
-### Ship `testapp.md` as a standalone application
+./mdcui
+./mdcui --wui --demo-中文工具
+```
 
-To turn your finished Markdown UI into a standalone executable, save it as the
-repository-root `testapp.md`, then build with both demo constants:
+To package the same application as a WUI by default and explicitly switch back
+to its TUI:
 
 ```sh
 bun src/index.js --build-exe \
-  --define MDCUI_DEFAULT_DEMO=true \
-  --define MDCUI_OVERWRITE_DEMO=true
+  --define global.MDCUI_MAIN=../中文工具.md \
+  --define MDCUI_DEFAULT_DEMO_WUI=1
+
+./mdcui
+./mdcui --tui --demo-中文工具
 ```
 
-The build first packs `testapp.md` into the executable and writes the resulting
-`mdcui` binary in the current directory. In that binary,
-`MDCUI_DEFAULT_DEMO` adds `--demo` when the user launches it without arguments,
-and `MDCUI_OVERWRITE_DEMO` adds `--overwrite-demo`. Consequently, running
-`./mdcui` writes the bundled application to `./testapp.md`, replacing an older
-copy, and starts it as the terminal UI.
+The `MDCUI_MAIN` basename must end with lowercase `.md`. Its demo-name portion
+must start with a Unicode letter or number and may contain Unicode
+letters/numbers (including Chinese), combining marks, dots, underscores, and
+hyphens. Whitespace and path separators are not allowed.
+
+When the configured custom demo is selected and its local Markdown byte length
+matches the embedded copy, TUI uses the embedded front/RPC modules and WUI uses
+the embedded server. A missing demo, or one selected with
+`MDCUI_OVERWRITE_DEMO=1`, is first written from the embedded copy and then uses
+embedded modules. A different byte length prints a warning and uses filesystem
+companion modules. Directly opening `./mdcui app.md` or
+`./mdcui --wui app.md` has no demo provenance and therefore uses filesystem
+modules even if the basename matches `MDCUI_MAIN`.
 
-To make a no-argument launch start the browser UI instead, build with
-`MDCUI_DEFAULT_DEMO_WUI`:
+To retain the older repository-root `testapp.md` distribution instead, build a
+TUI with:
 
 ```sh
 bun src/index.js --build-exe \
-  --define MDCUI_DEFAULT_DEMO_WUI=true \
-  --define MDCUI_OVERWRITE_DEMO=true
+  --define MDCUI_DEFAULT_DEMO=1 \
+  --define MDCUI_OVERWRITE_DEMO=1
 ```
 
-This adds `--wui` when the executable is launched without arguments.
+For a default WUI, replace `MDCUI_DEFAULT_DEMO` with
+`MDCUI_DEFAULT_DEMO_WUI`.
 
 You can rename and distribute the resulting binary. It contains the Bun
-runtime, jsmdcui, the packed runtime assets, and your `testapp.md`; the target
-directory must remain writable because launching the application creates
-`testapp.md` and its generated companion files there.
+runtime, jsmdcui, the packed runtime assets, and the configured demo or custom
+main application. The target directory must remain writable because launching
+an application creates its Markdown file and generated companion files there.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Markdown as a Common UI for Terminals and Web Browsers",
   "type": "module",
   "main": "./src/index.js",

package/runmd.mjs

@@ -54,6 +54,7 @@ export async function main(tuiWidth=30, {
   mdpath: requestedMdpath = null,
   overwriteDemo = process.argv.includes("--overwrite-demo"),
   printUi = process.argv.includes("--print-ui"),
+  useBundledMdcuiServer = false,
 } = {})
 {
     const explicitMdpath = process.argv.find(i=>i.endsWith('.md'))
@@ -99,7 +100,20 @@ export async function main(tuiWidth=30, {
 
 
     const serverPath = mdpath + "-server.js"
-    const svmod = await import(pathToFileURL(path.resolve(serverPath)).href)
+    const useEmbeddedMdcuiServer = Boolean(
+      global.MDCUI_MAIN && useBundledMdcuiServer
+    )
+    cse(
+      `[mdcui] Starting ${useEmbeddedMdcuiServer ? "embedded" : "external"} `
+      + `WUI server: ${
+        useEmbeddedMdcuiServer
+          ? String(global.MDCUI_MAIN)
+          : path.resolve(serverPath)
+      }`
+    )
+    const svmod = useEmbeddedMdcuiServer
+      ? await import(global.MDCUI_MAIN + "-server.js")
+      : await import(pathToFileURL(path.resolve(serverPath)).href)
 
     cse("\n\n"+mda('# Server'))
     svmod.main();
@@ -109,7 +123,7 @@ export async function main(tuiWidth=30, {
 //  Exports
 
 
-export async function extractJs(md,mdpath)
+export async function extractJs(md,mdpath,{ bundling = false } = {})
 {
   const mdb = path.basename(mdpath)
 
@@ -128,16 +142,23 @@ export async function extractJs(md,mdpath)
     }
   )
   
+  const frontSource = sctags
   sctags = "#!/usr/bin/env bun" + `
   
     import { rpc as wuiRpcClient } from "./${mdb}-rpc.js";
-    let rpc = "${mdb}"
+    let rpc = null
     if(globalThis.process)
-      rpc = await import("./"+rpc+".back.js") ;
+    {
+      rpc = await import(
+        "./" +
+        (global.MDCUI_MAIN_BASE||"${mdb}") +
+        ".back.js"
+      ) ;
+    }
     else
       rpc = wuiRpcClient ;
     
-  ` + sctags + `
+  ` + frontSource + `
   
     if (typeof window !== "undefined") 
     {
@@ -152,6 +173,28 @@ export async function extractJs(md,mdpath)
   
   await Bun.write(sctagsp,sctags);
   logWroteFile("front", sctagsp)
+
+  if (bundling) {
+    const bundledFrontSource = "#!/usr/bin/env bun" + `
+
+      import { rpc as wuiRpcClient } from "./${mdb}-rpc.js";
+      const rpc = wuiRpcClient;
+
+    ` + frontSource
+    const bundledFrontPath = mdpath + ".tmpfs.js"
+    await Bun.write(bundledFrontPath, bundledFrontSource)
+    logWroteFile("bundling front", bundledFrontPath)
+
+    const bundledImportPath = mdpath + ".tmpfi.js"
+    await Bun.write(
+      bundledImportPath,
+      `import * as frontMod from "./${mdb}.tmpfs.js";
+
+Object.assign(window, frontMod);
+`,
+    )
+    logWroteFile("bundling import", bundledImportPath)
+  }
   
   sctagsp = mdpath + ".back.js"
   sctags = "#!/usr/bin/env bun\n\n"
@@ -354,7 +397,7 @@ export function wrapWuiHeadingSections(html)
   return output;
 }
 
-export async function createWui(md,mdpath) // HTML
+export async function createWui(md,mdpath,{ bundling = false } = {}) // HTML
 {
   const eventsById = fenceEventMap(md)
   
@@ -397,7 +440,8 @@ img {
   height: auto;
 }
 </style>`;
-  const moduleScript = `<scr`+`ipt type="module" src="./${mdb}.front.js"></scr`+`ipt>`;
+  const moduleEntry = bundling ? `${mdb}.tmpfi.js` : `${mdb}.front.js`;
+  const moduleScript = `<scr`+`ipt type="module" src="./${moduleEntry}"></scr`+`ipt>`;
   const isFullHtmlDocument = /^\s*<!doctype html>/i.test(md);
   if (!isFullHtmlDocument) {
     md = `<!doctype html>

package/runtime/help/help.md

@@ -757,54 +757,94 @@ both are equivalent to `-encoding mdcui`.
 
 ### Build-time distribution constants
 
-Single-file distributions can define one of these default modes:
+The following switch defines are presence-based: the program checks whether
+they were passed, not whether their values are true. Consequently, `=0` and
+`=false` still enable a switch. Omit a define entirely to disable it. Examples
+use `=1` to make this explicit.
+
+- `MDCUI_DEFAULT_EDIT=1`: open files as editable text by default.
+- `MDCUI_DEFAULT_DEMO=1`: add `--demo` when launched without arguments.
+- `MDCUI_DEFAULT_DEMO_WUI=1`: add `--wui` when launched without arguments.
+- `MDCUI_OVERWRITE_DEMO=1`: add `--overwrite-demo`; this modifies a selected
+  demo but does not select one by itself.
+- `global.MDCUI_MAIN=<path>.md`: embed a custom Markdown application and its
+  generated front, RPC, back, HTML, and server modules. When this define is
+  forwarded after `--build-exe` or `--build-for`, a non-primitive value such as
+  a bare path is automatically encoded as a JavaScript string. An explicitly
+  quoted string remains supported.
+- `global.MDCUI_MAIN_BASE`: internal define generated automatically from
+  `global.MDCUI_MAIN`; do not pass it manually.
+
+Place every build define after `--build-exe`, or after the target argument of
+`--build-for`. Choose at most one of `MDCUI_DEFAULT_EDIT`,
+`MDCUI_DEFAULT_DEMO`, and `MDCUI_DEFAULT_DEMO_WUI`.
+
+| Build defines | No-argument launch | Open the same app in the other UI |
+| --- | --- | --- |
+| none | normal CLI/TUI | `./mdcui --wui app.md` |
+| `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` | embedded custom TUI | `./mdcui --wui --demo-中文工具` |
+| MAIN plus `MDCUI_DEFAULT_DEMO_WUI=1` | embedded custom WUI | `./mdcui --tui --demo-中文工具` |
 
-- `MDCUI_DEFAULT_EDIT`: open files as editable text by default.
-- `MDCUI_DEFAULT_DEMO`: add `--demo` when launched without arguments.
-- `MDCUI_DEFAULT_DEMO_WUI`: add `--wui` when launched without arguments.
+Any explicit runtime argument suppresses the no-argument demo/WUI injection.
+That is why the commands in the last column repeat `--demo` or
+`--demo-中文工具`; `./mdcui --wui` by itself does not implicitly select a custom
+main application.
 
-Choose only one of the three default-mode constants for a distribution.
-`MDCUI_OVERWRITE_DEMO` is an optional modifier for the demo or WUI mode.
-These are presence-based constants, so their build values do not require
-shell-quoted strings:
+To package `../中文工具.md` as a TUI by default:
 
 ```sh
-bun src/index.js --build-exe --define MDCUI_DEFAULT_EDIT=true
-```
+bun src/index.js --build-exe \
+  --define global.MDCUI_MAIN=../中文工具.md
 
-### Ship `testapp.md` as a standalone application
+./mdcui
+./mdcui --wui --demo-中文工具
+```
 
-To turn your finished Markdown UI into a standalone executable, save it as the
-repository-root `testapp.md`, then build with both demo constants:
+To package the same application as a WUI by default and explicitly switch back
+to its TUI:
 
 ```sh
 bun src/index.js --build-exe \
-  --define MDCUI_DEFAULT_DEMO=true \
-  --define MDCUI_OVERWRITE_DEMO=true
+  --define global.MDCUI_MAIN=../中文工具.md \
+  --define MDCUI_DEFAULT_DEMO_WUI=1
+
+./mdcui
+./mdcui --tui --demo-中文工具
 ```
 
-The build first packs `testapp.md` into the executable and writes the resulting
-`mdcui` binary in the current directory. In that binary,
-`MDCUI_DEFAULT_DEMO` adds `--demo` when the user launches it without arguments,
-and `MDCUI_OVERWRITE_DEMO` adds `--overwrite-demo`. Consequently, running
-`./mdcui` writes the bundled application to `./testapp.md`, replacing an older
-copy, and starts it as the terminal UI.
+The `MDCUI_MAIN` basename must end with lowercase `.md`. Its demo-name portion
+must start with a Unicode letter or number and may contain Unicode
+letters/numbers (including Chinese), combining marks, dots, underscores, and
+hyphens. Whitespace and path separators are not allowed.
+
+When the configured custom demo is selected and its local Markdown byte length
+matches the embedded copy, TUI uses the embedded front/RPC modules and WUI uses
+the embedded server. A missing demo, or one selected with
+`MDCUI_OVERWRITE_DEMO=1`, is first written from the embedded copy and then uses
+embedded modules. A different byte length prints a warning and uses filesystem
+companion modules. Directly opening `./mdcui app.md` or
+`./mdcui --wui app.md` has no demo provenance and therefore uses filesystem
+modules even if the basename matches `MDCUI_MAIN`.
 
-To make a no-argument launch start the browser UI instead, build with
-`MDCUI_DEFAULT_DEMO_WUI`:
+To retain the older repository-root `testapp.md` distribution instead, build a
+TUI with:
 
 ```sh
 bun src/index.js --build-exe \
-  --define MDCUI_DEFAULT_DEMO_WUI=true \
-  --define MDCUI_OVERWRITE_DEMO=true
+  --define MDCUI_DEFAULT_DEMO=1 \
+  --define MDCUI_OVERWRITE_DEMO=1
 ```
 
-This adds `--wui` when the executable is launched without arguments.
+For a default WUI, replace `MDCUI_DEFAULT_DEMO` with
+`MDCUI_DEFAULT_DEMO_WUI`.
 
 You can rename and distribute the resulting binary. It contains the Bun
-runtime, jsmdcui, the packed runtime assets, and your `testapp.md`; the target
-directory must remain writable because launching the application creates
-`testapp.md` and its generated companion files there.
+runtime, jsmdcui, the packed runtime assets, and the configured demo or custom
+main application. The target directory must remain writable because launching
+an application creates its Markdown file and generated companion files there.
 
 ## Development
 

package/runtime/jsplugins/example/example.js

@@ -69,8 +69,10 @@ micro.on("init", () => {
 
     //micro.alert(micro.getLine())
     const path = bp?.Buf?.Path || "(no path)";
+    const moduleSource =
+      micro.CurPane()?.Buf?.MdcuiModuleSource || "external";
     const loc = bp?.CursorLocation?.() || "+1.0:1";
-    micro.alert(`${path}\n${loc}`)
+    micro.alert(`${path}\nMdcuiModuleSource: ${moduleSource}\n${loc}`)
     
   });
   

package/single-exe/README.md

@@ -39,42 +39,58 @@ bun ./src/index.js --build-exe --sourcemap
 bun ./src/index.js --build-for <target> --sourcemap
 ```
 
-The following presence-based build constants select distribution defaults:
-
-- `MDCUI_DEFAULT_EDIT`: open files as editable text by default.
-- `MDCUI_DEFAULT_DEMO`: add `--demo` when launched without arguments.
-- `MDCUI_DEFAULT_DEMO_WUI`: add `--wui` when launched without arguments.
-
-Choose only one of these three default-mode constants for each build.
-`MDCUI_OVERWRITE_DEMO` is an optional modifier for a demo or WUI build.
-
-For example, build a default text editor with:
+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`.
+
+The 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 |
+| --- | --- | --- |
+| `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 MDCUI_DEFAULT_EDIT=true
+  --define global.MDCUI_MAIN=../中文工具.md
 ```
 
-To build a bundled terminal demo that replaces its local copy:
+For a custom WUI-default executable:
 
 ```shell
 bun ./src/index.js --build-exe \
-  --define MDCUI_DEFAULT_DEMO=true \
-  --define MDCUI_OVERWRITE_DEMO=true
+  --define global.MDCUI_MAIN=../中文工具.md \
+  --define MDCUI_DEFAULT_DEMO_WUI=1
 ```
 
-`MDCUI_DEFAULT_DEMO=true` makes an executable launched without arguments behave
-as if `--demo` was passed. `MDCUI_OVERWRITE_DEMO=true` makes every selected demo
-replace an existing local copy; it does not select a demo by itself.
-
-For a browser UI that automatically adds `--wui` when launched without
-arguments, use `MDCUI_DEFAULT_DEMO_WUI` instead:
+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.
 
-```shell
-bun ./src/index.js --build-exe \
-  --define MDCUI_DEFAULT_DEMO_WUI=true \
-  --define MDCUI_OVERWRITE_DEMO=true
-```
+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.
 
 To perform the same steps manually, run these commands from `single-exe/`:
 
@@ -221,6 +237,47 @@ bun ./packAssets.sh
 bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=my-bin
 ```
 
+#### Passing --define to bun build
+
+`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()`:
+
+```js
+import {
+  buildEarlyExit,
+  stringifyNonPrimitiveDefineValues,
+} from "../single-exe/compiled.js";
+
+stringifyNonPrimitiveDefineValues(process.argv, "MY_STRING_DEFINE");
+await buildEarlyExit(process.argv, "my-bin");
+```
+
+```shell
+# Wrong: Bun parses the define before the helper runs.
+bun --define MY_STRING_DEFINE=../app.md ./src/index.js --build-exe
+
+# Correct
+bun ./src/index.js --build-exe --define MY_STRING_DEFINE=../app.md
+```
+
+Before normalization:
+
+```js
+["--define", "MY_STRING_DEFINE=../app.md"]
+```
+
+After normalization:
+
+```js
+["--define", 'MY_STRING_DEFINE="../app.md"']
+```
+
+The inline form works too:
+`--define=MY_STRING_DEFINE=../app.md` becomes
+`--define=MY_STRING_DEFINE="../app.md"`.
+
+
 ### 6. Verify both execution paths
 
 Verify the compiled asset archive and then run the program normally: