jsmdcui 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [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,67 @@ 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
+
+Single-file distributions can define one of these default modes:
+
+- `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 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:
+
+```sh
+bun src/index.js --build-exe --define MDCUI_DEFAULT_EDIT=true
+```
+
+### Ship `testapp.md` as a standalone application
+
+To turn your finished Markdown UI into a standalone executable, save it as the
+repository-root `testapp.md`, then build with both demo constants:
+
+```sh
+bun src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+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.
+
+To make a no-argument launch start the browser UI instead, build with
+`MDCUI_DEFAULT_DEMO_WUI`:
+
+```sh
+bun src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO_WUI=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+This adds `--wui` when the executable is launched without arguments.
+
+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.
+
 ## Development
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.9.0",
+  "version": "0.10.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,39 @@ 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"),
+} = {})
 {
-    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)
+	}
 
 
     /*

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,67 @@ 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
+
+Single-file distributions can define one of these default modes:
+
+- `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 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:
+
+```sh
+bun src/index.js --build-exe --define MDCUI_DEFAULT_EDIT=true
+```
+
+### Ship `testapp.md` as a standalone application
+
+To turn your finished Markdown UI into a standalone executable, save it as the
+repository-root `testapp.md`, then build with both demo constants:
+
+```sh
+bun src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+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.
+
+To make a no-argument launch start the browser UI instead, build with
+`MDCUI_DEFAULT_DEMO_WUI`:
+
+```sh
+bun src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO_WUI=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+This adds `--wui` when the executable is launched without arguments.
+
+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.
+
 ## Development
 
 ```sh

package/single-exe/README.md

@@ -31,6 +31,51 @@ executable to the current directory. To pass a Bun compilation target, use:
 bun ./src/index.js --build-for <target>
 ```
 
+Any additional arguments after `--build-exe`, or after the target passed to
+`--build-for`, are forwarded to the `bun build` command:
+
+```shell
+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:
+
+```shell
+bun ./src/index.js --build-exe \
+  --define MDCUI_DEFAULT_EDIT=true
+```
+
+To build a bundled terminal demo that replaces its local copy:
+
+```shell
+bun ./src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+`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:
+
+```shell
+bun ./src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO_WUI=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
 To perform the same steps manually, run these commands from `single-exe/`:
 
 ```shell

package/single-exe/compiled.js

@@ -38,10 +38,11 @@ export function getDirnameFromUrl(importMetaUrl) {
   return dirname(fileURLToPath(importMetaUrl));
 }
 
-export async function buildExecutable(target = "",build_outfile="single.exe") {
+export async function buildExecutable(target = "",build_outfile="single.exe", bunArgs = []) {
  
   const outfile = resolve(process.cwd(), build_outfile);
   const normalizedTarget = String(target || "").trim();
+  const extraBunArgs = Array.from(bunArgs ?? [], String);
   if(!globalThis.Bun || IS_COMPILED)
   {
     console.log("Build exe can only be run by Bun in the source tree");
@@ -71,6 +72,7 @@ export async function buildExecutable(target = "",build_outfile="single.exe") {
         `--outfile=${outfile}`,
         `--metafile-md=${outfile}.meta.md`,
         ...(normalizedTarget ? [`--target=${normalizedTarget}`] : []),
+        ...extraBunArgs,
       ],
     },
   ];
@@ -145,8 +147,8 @@ export async function buildEarlyExit(argv,build_outfile) {
       console.error("Missing target value for --build-for");
       process.exit(2);
     }
-    process.exit(await buildExe(target,build_outfile));
+    process.exit(await buildExe(target, build_outfile, argv.slice(buildForIndex + 2)));
   }
 
-  process.exit(await buildExe(null,build_outfile));
+  process.exit(await buildExe(null, build_outfile, argv.slice(buildExeIndex + 1)));
 }

package/src/index.js

@@ -181,6 +181,11 @@ const VERSION = pkg.version;
 const SINGLE_EXE_DIR = resolve(REPO_ROOT, "single-exe");
 const SINGLE_EXE_ENTRY = resolve(SINGLE_EXE_DIR, "entry.mjs");
 const DEFAULT_BUILD_OUTFILE = "mdcui";
+const MDCUI_DEFAULT_EDIT_ENABLED = typeof MDCUI_DEFAULT_EDIT !== "undefined";
+const MDCUI_DEFAULT_DEMO_ENABLED = typeof MDCUI_DEFAULT_DEMO !== "undefined";
+const MDCUI_DEFAULT_DEMO_WUI_ENABLED = typeof MDCUI_DEFAULT_DEMO_WUI !== "undefined";
+const MDCUI_OVERWRITE_DEMO_ENABLED = typeof MDCUI_OVERWRITE_DEMO !== "undefined";
+let defaultEdit = false;
 const decoder = new TextDecoder();
 let _activeTtyStream = null; // set in App.start() for use by the global error handler
 
@@ -340,7 +345,7 @@ function normalizeEncodingLabel(encoding = "utf-8") {
 
 function encodingForPath(pathOrUrl, encoding = DEFAULT_SETTINGS.encoding, inferMdcui = true) {
   const normalized = normalizeEncodingLabel(encoding);
-  if (normalized !== "utf-8" || !inferMdcui) return normalized;
+  if (normalized !== "utf-8" || !inferMdcui || defaultEdit) return normalized;
   let pathname = String(pathOrUrl ?? "").replace(/[?#].*$/, "");
   try {
     if (isHttpUrl(pathname)) pathname = new URL(pathname).pathname;
@@ -1092,6 +1097,8 @@ function parseArgs(argv) {
     clean: false,
     check: false,
     cat: false,
+    wui: false,
+    printUi: false,
     docs: false,
     exportReadme: false,
     exportCdpMaze: false,
@@ -1099,6 +1106,7 @@ function parseArgs(argv) {
     testapp: false,
     demoList: false,
     demo: null,
+    overwriteDemo: false,
     allowUrl: false,
     buildExe: false,
     buildFor: "",
@@ -1122,6 +1130,8 @@ function parseArgs(argv) {
     else if (arg === "-clean") flags.clean = true;
     else if (arg === "--check") flags.check = true;
     else if (arg === "--cat" || arg === "-cat" || arg === "--ccat" || arg === "-ccat" || arg === "--bat" || arg === "-bat" || arg === "--glow" || arg === "-glow") flags.cat = true;
+    else if (arg === "--wui") flags.wui = true;
+    else if (arg === "--print-ui") flags.printUi = true;
     else if (arg === "--xxd" || arg === "--hexdump") {
       flags.cat = true;
       flags.settings.set("encoding", "hex3");
@@ -1138,12 +1148,16 @@ function parseArgs(argv) {
     else if (arg === "--edit") {
       flags.settings.set("encoding", "utf-8");
     }
+    else if (arg === "--mdcui" || arg === "--tui") {
+      flags.settings.set("encoding", "mdcui");
+    }
     else if (arg === "--docs" || arg === "--readme") flags.docs = true;
     else if (arg === "--export-readme") flags.exportReadme = true;
     else if (arg === "--export-cdp-maze") flags.exportCdpMaze = true;
     else if (arg === "--changelog") flags.changelog = true;
     else if (arg === "--testapp.md") flags.testapp = true;
     else if (arg === "--demo-list") flags.demoList = true;
+    else if (arg === "--overwrite-demo") flags.overwriteDemo = true;
     else if (arg === "--cdp-maze") {
       flags.cdpMaze = true;
       flags.demo = { option: arg, filename: "maze.md", asset: "demos/maze.md" };
@@ -1195,17 +1209,56 @@ function parseArgs(argv) {
 function usage() {
   return [
     `Usage:
-  ${pkg.name} [OPTIONS] [FILE.md]
+  ${pkg.name} [OPTIONS] [FILE]
+    
+Execute .md:
+  ${pkg.name} [FILE.md]
   ${pkg.name} --wui [FILE.md]
+Develop .md:
+  ${pkg.name} --edit [FILE.md]
+  ${pkg.name} --check <FILE.md>
 
 Modes:
-  --check FILE.md
-      Check heading and fenced-block IDs for collisions, print details, and exit
-      Exits 0 when IDs are unique, 1 on collisions, and 2 on usage/read errors
+  --tui, --mdcui, -encoding mdcui
+    .md files use this by default
+    Execute a Markdown App
+      Create a Terminal UI
+    Generate & overwrite
+      .front.js, .back.js, 
+      .html, -rpc.js, -server.js
+      beside the .md file
+      
   --wui [FILE.md]
-      Generate or overwrite Markdown UI files beside FILE.md and start the server
-      Without FILE.md, use the existing ./testapp.md without overwriting it
+    Execute a Markdown App
+      Create a Web UI
+      Start a web server
+    Generate & overwrite 
+      .front.js, .back.js, 
+      .html, -rpc.js, -server.js
+      beside the .md file
+      
+    Without FILE.md, 
+    default to ./testapp.md
       If ./testapp.md is missing, write the bundled demo there first
+    Combine with any --demo option to start that demo as a Web UI
+      
+  --print-ui
+    Must be combined with --wui
+    Print the generated TUI, raw ANSI, and HTML before starting the server
+    
+  --kitty
+    Display Markdown images with Kitty graphics and the jsgotty MIME extension
+  --kitty-compat
+    Display Markdown images with Kitty graphics without the non-standard MIME U field
+      
+  --edit
+    Open files as editable UTF-8 text
+    Override .md mdcui detection
+    
+  --check <FILE.md>
+    Check heading and fenced-block IDs for collisions, print details, and exit
+    Exits 0 when IDs are unique, 1 on collisions, and 2 on usage/read errors
+      
   --cat, --ccat, --bat, --glow
       Render file(s) and write to stdout, then exit (.md uses mdcui/createTui)
       A local .md file also writes or overwrites five generated files beside it
@@ -1214,15 +1267,6 @@ Modes:
   --hex3, --hex3gz, --hex3zst
       Set -encoding hex3, hex3gz, or hex3zst for this session
       hex3 shows raw bytes; gz/zst variants compress the same hex3 view
-  --edit
-      Open files as editable UTF-8 text, overriding .md mdcui detection
-  -encoding mdcui
-      Render Markdown through runmd.mjs#createTui; .md files use this automatically
-      Writes .front.js, .back.js, .html, -rpc.js, and -server.js beside the .md file
-  --kitty
-      Display Markdown images with Kitty graphics and the jsgotty MIME extension
-  --kitty-compat
-      Display Markdown images with Kitty graphics without the non-standard MIME U field
 
 Settings:
   -SETTING VALUE
@@ -1230,54 +1274,73 @@ Settings:
   -options
       List all setting names and defaults, then exit.
 
-CDP:
+CDP(Chrome DevTools Protocol):
   --cdp-maze
       Open the maze demo, start CDP on localhost:9222, and solve it automatically
+  --export-cdp-maze
+      Write or overwrite ./cdp-maze.js with the bundled CDP maze solver & exit
+      
   --remote-debugging-port=PORT
       Start CDP (Chrome DevTools Protocol) server on PORT at launch
   --remote-debugging-address=ADDRESS
       Bind CDP server to ADDRESS (default: 127.0.0.1); use 0.0.0.0 for all interfaces
 
 Information:
-  -help, -h, --help
+  --help, -h, -help
       Show this help & exit
-  -version, -V, --version
+  --version, -V, -version
       Show version+backend info & exit
-  --docs, --readme
+      
+  --readme, --docs
       Show ${pkg.name}'s README.md & exit
   --export-readme
       Write or overwrite ./README.md with the bundled README.md & exit
-  --export-cdp-maze
-      Write or overwrite ./cdp-maze.js with the bundled CDP maze solver & exit
+      
   --changelog
       Show CHANGELOG.md & exit
-  -profile, --profile
+  --profile, -profile
       Print startup performance profile and exit
 
 Demo:
   --testapp.md
-      Write the bundled testapp.md to stdout & exit
+      Print the bundled testapp.md to stdout & exit
   --demo-list
-      List the bundled demos and their command-line options, then exit
+      List the bundled demos & exit
+      
   --demo
-      Use the existing ./testapp.md without overwriting it, or write the bundled demo if missing
+      Execute an existing ./testapp.md
+      Or write the bundled demo if missing
       Open it in the TUI and write 5 generated files beside it
+      
   --demo-<filename>
-      Load demos/<filename>.md, preserving an existing ./<filename>.md or writing the bundled copy
+      Execute an existing <filename>.md
+      Or write the bundled demos/<filename>.md if missing
       Open it in the TUI and write 5 generated files beside it
       For example: --demo-select, --demo-todo, or --demo-todo-zh
+      
   --demo-imgtool
       Alias for --demo-image-processor
   --demo-imgtool-zh
       Alias for --demo-image-processor.zh-TW
 
+  --overwrite-demo
+      Overwrite an existing local demo with the bundled copy; combine with any --demo option
+      
 Remote Markdown:
   --allow-url
       Download HTTP(S) Markdown and, with Kitty mode, its HTTP(S) images; allow its code to run
 
-Experimental:
-  --build-exe                   Build a Bun single-file executable and exit
-  --build-for <target>          Build a Bun single-file executable for target`
+Experimental single-exe:
+  --build-exe [BUN_ARGS...]
+      Build a Bun single-file executable & exit
+  --build-for <target> [BUN_ARGS...]
+      Build a Bun single-file executable for target & exit
+  
+  [BUN_ARGS...]
+      --define MDCUI_XXX=true
+        More info in --readme
+      https://bun.com/docs/bundler/executables
+`
   ].join("\n");
 }
 
@@ -8073,19 +8136,42 @@ function printDemoList() {
   console.log("  --demo-imgtool-zh  --demo-image-processor.zh-TW");
 }
 
-async function main() {
-  if (process.argv[2] === "--wui") {
-    process.argv.splice(2, 1);
-    const runmd = await import("../runmd.mjs");
-    await runmd.main();
-    return;
+async function prepareDemo(flags, rawFiles) {
+  if (!flags.demo) return true;
+  if (flags.demo.error) {
+    console.error(`Invalid demo option ${flags.demo.option}: ${flags.demo.error}`);
+    process.exitCode = 2;
+    return false;
+  }
+  let demoSource;
+  try {
+    demoSource = await bundledMarkdownSource(flags.demo.asset);
+  } catch {
+    console.error(`Unknown demo ${flags.demo.option}: ${flags.demo.asset} was not found`);
+    process.exitCode = 2;
+    return false;
+  }
+  const demoPath = resolve(flags.demo.filename);
+  if (flags.overwriteDemo || !(await Bun.file(demoPath).exists())) {
+    await Bun.write(demoPath, demoSource);
   }
+  rawFiles.splice(0, rawFiles.length, demoPath);
+  return true;
+}
 
+async function main() {
   addCheckpoint("Argument Parsing");
   
   await buildEarlyExit(null,DEFAULT_BUILD_OUTFILE)
+  defaultEdit = await Bun.file(join(REPO_ROOT, "src", "MDCUI_DEFAULT_EDIT")).exists();
   
-  const { flags, files: rawFiles } = parseArgs(process.argv.slice(2));
+  const runtimeArgs = process.argv.slice(2);
+  const noRuntimeArgs = runtimeArgs.length === 0;
+  if (MDCUI_DEFAULT_EDIT_ENABLED) runtimeArgs.unshift("--edit");
+  if (noRuntimeArgs && MDCUI_DEFAULT_DEMO_ENABLED) runtimeArgs.push("--demo");
+  if (noRuntimeArgs && MDCUI_DEFAULT_DEMO_WUI_ENABLED) runtimeArgs.push("--wui");
+  if (MDCUI_OVERWRITE_DEMO_ENABLED) runtimeArgs.push("--overwrite-demo");
+  const { flags, files: rawFiles } = parseArgs(runtimeArgs);
   kittyImageMode = flags.kittyMode;
   allowRemoteKittyImages = flags.allowUrl;
 
@@ -8096,7 +8182,7 @@ async function main() {
   if (flags.version) {
     const ttsCmd = detectTtsCmd();
     console.log(pkg.name+":",pkg.description)
-    console.log("  Rewritten by: Dr. John (醫者小智)")
+    console.log("  Made by: Dr. John (醫者小智)")
     console.log("")
     console.log("Version:", VERSION);
     console.log("Runtime:", `Bun ${Bun.version}`);
@@ -8104,6 +8190,11 @@ async function main() {
     console.log("Http client:",detectHttpBackend());
     console.log("TTS:", ttsCmd ? ttsCmd.cmd[0] : "not found");
     console.log({SUPPORTED_ENCODING_LABELS})
+    console.log("Distribution settings:");
+    console.log("  MDCUI_DEFAULT_EDIT:", (MDCUI_DEFAULT_EDIT_ENABLED || defaultEdit) ? "enabled" : "disabled");
+    console.log("  MDCUI_DEFAULT_DEMO:", MDCUI_DEFAULT_DEMO_ENABLED ? "enabled" : "disabled");
+    console.log("  MDCUI_DEFAULT_DEMO_WUI:", MDCUI_DEFAULT_DEMO_WUI_ENABLED ? "enabled" : "disabled");
+    console.log("  MDCUI_OVERWRITE_DEMO:", MDCUI_OVERWRITE_DEMO_ENABLED ? "enabled" : "disabled");
     const clipboard = new ClipboardManager();
     let osc52Available = false;
     if (process.stdin.isTTY && process.stdout.isTTY) {
@@ -8118,6 +8209,16 @@ async function main() {
     console.log("Clipboard:", backends);
     return;
   }
+  if (flags.wui) {
+    if (!(await prepareDemo(flags, rawFiles))) return;
+    const runmd = await import("../runmd.mjs");
+    await runmd.main(30, {
+      mdpath: rawFiles[0] ?? null,
+      overwriteDemo: flags.overwriteDemo && rawFiles.length === 0,
+      printUi: flags.printUi,
+    });
+    return;
+  }
   if (flags.check) {
     if (rawFiles.length !== 1) {
       console.error("Usage: jsmdcui --check FILE.md");
@@ -8162,24 +8263,7 @@ async function main() {
     return;
   }
   if (flags.demo) {
-    if (flags.demo.error) {
-      console.error(`Invalid demo option ${flags.demo.option}: ${flags.demo.error}`);
-      process.exitCode = 2;
-      return;
-    }
-    let demoSource;
-    try {
-      demoSource = await bundledMarkdownSource(flags.demo.asset);
-    } catch {
-      console.error(`Unknown demo ${flags.demo.option}: ${flags.demo.asset} was not found`);
-      process.exitCode = 2;
-      return;
-    }
-    const demoPath = resolve(flags.demo.filename);
-    if (!(await Bun.file(demoPath).exists())) {
-      await Bun.write(demoPath, demoSource);
-    }
-    rawFiles.splice(0, rawFiles.length, demoPath);
+    if (!(await prepareDemo(flags, rawFiles))) return;
   }
   if (flags.options) {
     for (const [key, value] of Object.entries(defaultAllSettings()).sort(([a], [b]) => a.localeCompare(b))) {
@@ -8192,6 +8276,7 @@ async function main() {
   const config = await new Config({ configDir: flags.configDir }).init();
   config.applyCliSettings(flags.settings);
   const encodingExplicit = flags.settings.has("encoding") || Object.hasOwn(config.parsedSettings, "encoding");
+  const inputFiletype = flags.settings.has("filetype") ? String(flags.settings.get("filetype")) : null;
   syncEditorSettings(config);
 
   addCheckpoint("Runtime Registry Init");
@@ -8203,7 +8288,14 @@ async function main() {
   const syntaxDefinitions = await loadSyntaxDefinitions(runtime);
 
   if (flags.cat) {
-    await catFiles(rawFiles, colorscheme, syntaxDefinitions, config.getGlobalOption("encoding"), !encodingExplicit);
+    await catFiles(
+      rawFiles,
+      colorscheme,
+      syntaxDefinitions,
+      config.getGlobalOption("encoding"),
+      !encodingExplicit,
+      inputFiletype,
+    );
     return;
   }
 
@@ -8268,6 +8360,7 @@ async function main() {
     runtime,
     jsPlugins,
     encodingExplicit,
+    inputFiletype,
     allowUrl: flags.allowUrl,
     kittyMode: flags.kittyMode,
   };
@@ -8725,9 +8818,12 @@ function getSelectionText(buf, selection) {
 
 function attachSyntax(buffer, context, path, text) {
   buffer._syntaxContext = context;
-  const def = detectBufferSyntax(context.syntaxDefinitions, path, text);
+  const explicitFiletype = context.inputFiletype;
+  const def = explicitFiletype == null
+    ? detectBufferSyntax(context.syntaxDefinitions, path, text)
+    : context.syntaxDefinitions?.find((candidate) => candidate.filetype === explicitFiletype) ?? null;
   buffer.syntaxDefinition = def;
-  buffer.filetype = def?.filetype ?? "unknown";
+  buffer.filetype = explicitFiletype == null ? (def?.filetype ?? "unknown") : String(explicitFiletype);
   buffer.Settings.filetype = buffer.filetype;
   buffer.highlighter = def ? new Highlighter(def, context.syntaxDefinitions ?? []) : null;
   buffer._highlightCache = null;
@@ -8805,7 +8901,7 @@ function syncEditorSettings(config) {
   }
 }
 
-async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAULT_SETTINGS.encoding, inferMdcui = true) {
+async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAULT_SETTINGS.encoding, inferMdcui = true, filetype = null) {
   const targets = files.length > 0 ? files.map((f) => ({ path: f, stdin: false })) : [{ path: null, stdin: true }];
   for (const { path: filePath, stdin } of targets) {
     let content;
@@ -8836,7 +8932,7 @@ async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAUL
       process.stdout.write(ansiContent ?? content);
       if (!(ansiContent ?? content).endsWith("\n")) process.stdout.write("\n");
       continue;
-    } else if (effectivePath && /\.md$/i.test(effectivePath)) {
+    } else if (filetype == null && effectivePath && /\.md$/i.test(effectivePath)) {
       process.stdout.write(
         Bun.markdown.ansi(content,{
           hyperlinks:true
@@ -8845,11 +8941,13 @@ async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAUL
       continue;
     }
     const lines = normalizeBufferText(content).split("\n");
-    const def = detectSyntax(syntaxDefinitions, {
-      path: effectivePath ?? "",
-      firstLine: lines[0] ?? "",
-      lines: lines.slice(0, 50),
-    });
+    const def = filetype == null
+      ? detectSyntax(syntaxDefinitions, {
+          path: effectivePath ?? "",
+          firstLine: lines[0] ?? "",
+          lines: lines.slice(0, 50),
+        })
+      : syntaxDefinitions.find((candidate) => candidate.filetype === filetype) ?? null;
     const highlighter = def ? new Highlighter(def, syntaxDefinitions) : null;
     if (!highlighter) {
       process.stdout.write(content);

package/tests/cat-markdown.test.js

@@ -78,3 +78,62 @@ test("--edit overrides the .md mdcui default with utf8", async () => {
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("--mdcui and --tui are equivalent to -encoding mdcui", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-cat-mdcui-"));
+  const markdownPath = join(dir, "sample.md");
+  await writeFile(markdownPath, "# Heading\n\n- one\n- two\n");
+
+  try {
+    const flag = Bun.spawnSync([bunBin, tui, "-cat", "--mdcui", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const encoding = Bun.spawnSync([bunBin, tui, "-cat", "-encoding", "mdcui", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const tuiFlag = Bun.spawnSync([bunBin, tui, "-cat", "--tui", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(flag.exitCode).toBe(0);
+    expect(encoding.exitCode).toBe(0);
+    expect(tuiFlag.exitCode).toBe(0);
+    expect(flag.stdout.toString()).toBe(encoding.stdout.toString());
+    expect(tuiFlag.stdout.toString()).toBe(encoding.stdout.toString());
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("-filetype forces syntax highlighting independently of the filename", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-cat-filetype-"));
+  const textPath = join(dir, "sample.txt");
+  await writeFile(textPath, "const answer = 42;\n");
+
+  try {
+    const automatic = Bun.spawnSync([bunBin, tui, "-cat", textPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const javascript = Bun.spawnSync([bunBin, tui, "-cat", "-filetype", "javascript", textPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(automatic.exitCode).toBe(0);
+    expect(javascript.exitCode).toBe(0);
+    expect(automatic.stdout.toString()).not.toContain("\x1b[");
+    expect(javascript.stdout.toString()).toContain("\x1b[");
+    expect(Bun.stripANSI(javascript.stdout.toString()).trimEnd()).toBe("const answer = 42;");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/tests/demo.test.js

@@ -2,6 +2,7 @@ import { expect, test } from "bun:test";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { readMarkdownInput } from "../runmd.mjs";
 
 const tui = join(import.meta.dir, "..", "tui");
 const bunBin = Bun.which("bun") || process.argv0;
@@ -14,8 +15,8 @@ test("--help describes the non-overwriting demo behavior", () => {
 
   expect(result.exitCode).toBe(0);
   const output = result.stdout.toString();
-  expect(output).toContain("use the existing ./testapp.md without overwriting it");
-  expect(output).toContain("If ./testapp.md is missing, write the bundled demo there first");
+  expect(output).toContain("Execute an existing ./testapp.md");
+  expect(output).toContain("Or write the bundled demo if missing");
   expect(output).toContain("--demo-<filename>");
   expect(output).toContain("demos/<filename>.md");
   expect(output.match(/Open it in the TUI and write 5 generated files beside it/g)?.length).toBe(2);
@@ -97,6 +98,44 @@ test("--demo preserves an existing testapp.md", async () => {
   }
 });
 
+test("--overwrite-demo replaces an existing demo with the bundled copy", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-overwrite-"));
+  const existing = "# Replace my demo\n";
+  try {
+    await writeFile(join(dir, "testapp.md"), existing);
+    const result = Bun.spawnSync(
+      [bunBin, tui, "--overwrite-demo", "--demo", "-cat", "-encoding", "utf8"],
+      {
+        cwd: dir,
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+
+    expect(result.exitCode).toBe(0);
+    const written = await readFile(join(dir, "testapp.md"), "utf8");
+    expect(written).toContain("計算機");
+    expect(written).not.toBe(existing);
+    expect(Bun.stripANSI(result.stdout.toString())).toContain("計算機");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("WUI demo loading can overwrite an existing testapp.md", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-wui-demo-overwrite-"));
+  const demoPath = join(dir, "testapp.md");
+  try {
+    await writeFile(demoPath, "# Replace my WUI demo\n");
+    const source = await readMarkdownInput(demoPath, true);
+
+    expect(source).toContain("計算機");
+    expect(await readFile(demoPath, "utf8")).toBe(source);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("--demo-<filename> automatically loads a matching demos file", async () => {
   const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-generic-"));
   try {