jsmdcui 0.9.0 → 0.11.1

package/CHANGELOG.md

@@ -2,6 +2,125 @@
 
 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
+
+- Resolve and prepare `--demo` and `--demo-*` selections before entering WUI
+  mode, so combinations such as `--wui --demo-todo` serve the selected demo
+  instead of falling back to `testapp.md`.
+
+## [0.10.0] - 2026-07-24
+
+This update adds distribution-oriented defaults for shipping jsmdcui as a text
+editor, terminal application, or browser application; makes WUI startup and
+demo replacement explicit; and improves command-line control over rendering,
+syntax highlighting, and single-executable builds.
+
+### Added
+
+- Add `--mdcui` and `--tui` as aliases for `-encoding mdcui`, allowing an
+  explicit terminal Markdown UI request to override an editor-oriented
+  distribution default.
+- Add `--overwrite-demo` as a modifier for `--demo` and the automatically
+  discovered `--demo-*` commands. It replaces an existing local demo with the
+  bundled copy before opening it.
+- Add `--print-ui` for WUI launches. The generated TUI preview, raw ANSI, and
+  HTML are printed only when this flag is present.
+- Add the `src/MDCUI_DEFAULT_EDIT` distribution marker. When present, Markdown
+  files open as editable UTF-8 text by default while `--mdcui` remains
+  available explicitly.
+- Add presence-based single-executable build constants:
+  `MDCUI_DEFAULT_EDIT`, `MDCUI_DEFAULT_DEMO`, and
+  `MDCUI_DEFAULT_DEMO_WUI` select an editor, no-argument TUI demo, or
+  no-argument WUI demo default. `MDCUI_OVERWRITE_DEMO` optionally makes a
+  bundled demo replace its local copy.
+- Add distribution documentation for shipping a customized root
+  `testapp.md` as a standalone terminal or browser application.
+- Add regression coverage for the `--mdcui` alias, forced CLI filetypes,
+  non-overwriting and overwriting demos, and WUI demo replacement.
+
+### Changed
+
+- Parse `--wui` through the normal command-line argument flow, so it can appear
+  before or after the Markdown filename.
+- Make WUI startup quieter by default. It continues to report file generation
+  and the server URL, while full generated UI output is opt-in through
+  `--print-ui`.
+- Make direct `runmd.mjs` launches recognize `--overwrite-demo` and
+  `--print-ui`. Demo replacement is limited to the implicit `testapp.md`;
+  explicitly named Markdown files are protected from replacement.
+- Forward every extra argument after `--build-exe`, or after the target passed
+  to `--build-for`, to the underlying `bun build` command.
+- Align the `start`, `tui`, and `wui` package scripts with the repository
+  launchers, and add a `clean` package script.
+- Recommend choosing only one of the three `MDCUI_DEFAULT_*` distribution
+  modes per build, with `MDCUI_OVERWRITE_DEMO` treated as an optional modifier.
+- Show effective `MDCUI_*` distribution settings in `--version` output,
+  including `MDCUI_DEFAULT_EDIT` enabled through either its build constant or
+  the `src/MDCUI_DEFAULT_EDIT` marker.
+
+### Fixed
+
+- Make `-filetype <name>` actually override automatic syntax detection in
+  editor buffers and `--cat`, including input read from stdin.
+
 ## [0.9.0] - 2026-07-21
 
 This update expands Chrome DevTools Protocol automation for the terminal UI,

package/README.md

@@ -163,6 +163,7 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js --export-cdp-maze` | Write or overwrite `./cdp-maze.js` with the bundled CDP maze solver and exit. |
 | `bun src/index.js --demo-list` | List `testapp.md` and every bundled `demos/*.md` example with its command-line option, then exit. |
 | `bun src/index.js --demo` | Use local `testapp.md` when present, otherwise write the bundled demo; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --overwrite-demo --demo` | Replace an existing local `testapp.md` with the bundled copy before opening it. `--overwrite-demo` can modify any `--demo-*` option. |
 | `bun src/index.js --demo-<filename>` | Load `demos/<filename>.md`; preserve an existing local copy or write the bundled copy, then open it and generate its five companion files. New files added under `demos/` work automatically. |
 | `bun src/index.js --demo-imgtool` | Compatibility alias for `--demo-image-processor`. |
 | `bun src/index.js --demo-imgtool-zh` | Compatibility alias for `--demo-image-processor.zh-TW`. |
@@ -170,6 +171,8 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory and, with Kitty mode enabled, download its HTTP(S) images; write 5 generated files and allow embedded code to run. Only use trusted URLs. |
 | `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise write the bundled demo; write five generated files in the current directory, then print and serve a random URL. |
 | `bun src/index.js --wui app.md` | Write five generated files beside `app.md`, then print and serve a random URL. |
+| `bun src/index.js --wui --demo-<filename>` | Load the selected bundled demo and serve it as a Web UI. |
+| `bun src/index.js --wui --print-ui app.md` | Also print the generated TUI, raw ANSI, and HTML before starting the WUI server. |
 | `PORT=8080 bun src/index.js --wui app.md` | Start the browser UI on another port. |
 | `bun src/index.js` | Open the normal terminal editor with an empty buffer. |
 
@@ -742,6 +745,107 @@ or serve Markdown UI files that you trust.
   calls, but it does not protect the backend module from trusted local code and
   is not a substitute for authentication.
 
+## Distribution
+
+### Text editor distribution
+
+Distributions intended primarily as text editors can include an empty
+`src/MDCUI_DEFAULT_EDIT` file. When this marker exists, opening a `.md` file uses the
+normal editable UTF-8 view instead of automatically entering `mdcui` mode.
+Markdown UI support remains available explicitly with `--mdcui` or `--tui`;
+both are equivalent to `-encoding mdcui`.
+
+### Build-time distribution constants
+
+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-中文工具` |
+
+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.
+
+To package `../中文工具.md` as a TUI by default:
+
+```sh
+bun src/index.js --build-exe \
+  --define global.MDCUI_MAIN=../中文工具.md
+
+./mdcui
+./mdcui --wui --demo-中文工具
+```
+
+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 global.MDCUI_MAIN=../中文工具.md \
+  --define MDCUI_DEFAULT_DEMO_WUI=1
+
+./mdcui
+./mdcui --tui --demo-中文工具
+```
+
+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 retain the older repository-root `testapp.md` distribution instead, build a
+TUI with:
+
+```sh
+bun src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO=1 \
+  --define MDCUI_OVERWRITE_DEMO=1
+```
+
+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 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
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.9.0",
+  "version": "0.11.1",
   "description": "Markdown as a Common UI for Terminals and Web Browsers",
   "type": "module",
   "main": "./src/index.js",
@@ -9,9 +9,11 @@
     "jsmdcui": "./src/index.js"
   },
   "scripts": {
-    "start": "bun ./src/index.js",
-    "tui": "bun ./src/index.js ./testapp.md",
-    "wui": "bun ./runmd.mjs",
-    "check": "node --check ./src/index.js"
+    "start": "bun ./src/index.js --demo",
+    "tui": "bun ./tui",
+    "wui": "bun ./wui",
+    "edit": "bun ./edit",
+    "check": "bun ./src/index.js --check",
+    "clean": "bun ./clean.sh"
   }
 }

package/runmd.mjs

@@ -29,10 +29,10 @@ async function readTemplate(pathname)
          await Bun.file(path.join(REPO_ROOT, pathname)).text()
 }
 
-export async function readMarkdownInput(mdpath)
+export async function readMarkdownInput(mdpath, overwriteDemo = false)
 {
   const file = Bun.file(mdpath);
-  if (await file.exists()) return await file.text();
+  if (!overwriteDemo && await file.exists()) return await file.text();
   const assetName = path.basename(mdpath);
   const internalText = readInternalAssetText(assetName);
   if (internalText != null) {
@@ -50,30 +50,40 @@ export async function readMarkdownInput(mdpath)
 }
 
 
-export async function main(tuiWidth=30)
+export async function main(tuiWidth=30, {
+  mdpath: requestedMdpath = null,
+  overwriteDemo = process.argv.includes("--overwrite-demo"),
+  printUi = process.argv.includes("--print-ui"),
+  useBundledMdcuiServer = false,
+} = {})
 {
-    const mdpath = process.argv.filter(i=>i.endsWith('.md'))[0] || 'testapp.md'
+    const explicitMdpath = process.argv.find(i=>i.endsWith('.md'))
+    const mdpath = requestedMdpath || explicitMdpath || 'testapp.md'
 
 
 	// 1. Read markdown file
 	console.error('Reading:',mdpath)
-	let md = await readMarkdownInput(mdpath)
+	let md = await readMarkdownInput(mdpath, overwriteDemo && !requestedMdpath && !explicitMdpath)
 
     // 2. Extract js files
     md = await extractJs(md,mdpath);
 
 	// 3. Create Terminal UI
 	let tui = createTui(md,tuiWidth)
-	cse(mda("\n# TUI"))
-	cse(tui)
-	cse(mda('## TUI raw'))
-	cse(jss(tui))
+	if (printUi) {
+	  cse(mda("\n# TUI"))
+	  cse(tui)
+	  cse(mda('## TUI raw'))
+	  cse(jss(tui))
+	}
 
 
 	// 4. Create Web UI
 	let wui = await createWui(md,mdpath)
-	cse(mda('\n# HTML'))
-	cse(wui)
+	if (printUi) {
+	  cse(mda('\n# HTML'))
+	  cse(wui)
+	}
 
 
     /*
@@ -90,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();
@@ -100,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)
 
@@ -119,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") 
     {
@@ -143,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"
@@ -345,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)
   
@@ -388,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

@@ -163,6 +163,7 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js --export-cdp-maze` | Write or overwrite `./cdp-maze.js` with the bundled CDP maze solver and exit. |
 | `bun src/index.js --demo-list` | List `testapp.md` and every bundled `demos/*.md` example with its command-line option, then exit. |
 | `bun src/index.js --demo` | Use local `testapp.md` when present, otherwise write the bundled demo; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --overwrite-demo --demo` | Replace an existing local `testapp.md` with the bundled copy before opening it. `--overwrite-demo` can modify any `--demo-*` option. |
 | `bun src/index.js --demo-<filename>` | Load `demos/<filename>.md`; preserve an existing local copy or write the bundled copy, then open it and generate its five companion files. New files added under `demos/` work automatically. |
 | `bun src/index.js --demo-imgtool` | Compatibility alias for `--demo-image-processor`. |
 | `bun src/index.js --demo-imgtool-zh` | Compatibility alias for `--demo-image-processor.zh-TW`. |
@@ -170,6 +171,8 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory and, with Kitty mode enabled, download its HTTP(S) images; write 5 generated files and allow embedded code to run. Only use trusted URLs. |
 | `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise write the bundled demo; write five generated files in the current directory, then print and serve a random URL. |
 | `bun src/index.js --wui app.md` | Write five generated files beside `app.md`, then print and serve a random URL. |
+| `bun src/index.js --wui --demo-<filename>` | Load the selected bundled demo and serve it as a Web UI. |
+| `bun src/index.js --wui --print-ui app.md` | Also print the generated TUI, raw ANSI, and HTML before starting the WUI server. |
 | `PORT=8080 bun src/index.js --wui app.md` | Start the browser UI on another port. |
 | `bun src/index.js` | Open the normal terminal editor with an empty buffer. |
 
@@ -742,6 +745,107 @@ or serve Markdown UI files that you trust.
   calls, but it does not protect the backend module from trusted local code and
   is not a substitute for authentication.
 
+## Distribution
+
+### Text editor distribution
+
+Distributions intended primarily as text editors can include an empty
+`src/MDCUI_DEFAULT_EDIT` file. When this marker exists, opening a `.md` file uses the
+normal editable UTF-8 view instead of automatically entering `mdcui` mode.
+Markdown UI support remains available explicitly with `--mdcui` or `--tui`;
+both are equivalent to `-encoding mdcui`.
+
+### Build-time distribution constants
+
+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-中文工具` |
+
+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.
+
+To package `../中文工具.md` as a TUI by default:
+
+```sh
+bun src/index.js --build-exe \
+  --define global.MDCUI_MAIN=../中文工具.md
+
+./mdcui
+./mdcui --wui --demo-中文工具
+```
+
+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 global.MDCUI_MAIN=../中文工具.md \
+  --define MDCUI_DEFAULT_DEMO_WUI=1
+
+./mdcui
+./mdcui --tui --demo-中文工具
+```
+
+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 retain the older repository-root `testapp.md` distribution instead, build a
+TUI with:
+
+```sh
+bun src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO=1 \
+  --define MDCUI_OVERWRITE_DEMO=1
+```
+
+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 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
 
 ```sh

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}`)
     
   });