jsmdcui 0.8.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 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,
+adds a complete maze-solving example, and makes the optional Bun single-file
+executable bootstrap easier to reuse and more reliable across platforms.
+
+### Added
+
+- Add CDP automation support for reading the rendered ANSI document, activating
+  a 1-based terminal-buffer cell, and sending keyboard input through the TUI's
+  normal input parser and event pipeline. Key presses support Alt, Ctrl, Meta,
+  Shift, navigation keys, editing keys, text, and auto-repeat without emitting
+  duplicate input for paired CDP `keyDown` and `char` events.
+- Add `micro.getAllAnsiText()` and `micro.clickBufferCell(x, y)` to the JS
+  plugin bridge. MDCUI cell clicks now activate the same callbacks as mouse
+  input, while clicks in ordinary buffers retain the previous `goto` behavior.
+- Add `cdp-maze.js` and `llm-maze.txt`, a documented Bun.WebView example that
+  reads the maze from the running TUI, solves it with breadth-first search, and
+  completes it by clicking controls and sending arrow-key events through CDP.
+- Add `--cdp-maze` to open the bundled maze, start a local CDP server on port
+  9222, and automatically import and run the maze solver after a three-second
+  delay. The completed result is returned to the main program and displayed in
+  the TUI status message.
+- Add `--export-cdp-maze` to write or overwrite `./cdp-maze.js` from the
+  bundled asset first, with a source-tree fallback, then exit. Include the
+  solver in the single-executable asset archive.
+- Add a dedicated CDP automation section to the README and bundled help,
+  covering command-line and command-prompt startup, bind-address safety,
+  connection methods, and the maze solver workflow.
+- Add a reusable single-file executable guide covering asset packing, embedded
+  and external resource fallbacks, build commands, cross-compilation, Node.js
+  compatibility, and adapting the bootstrap to another project.
+
+### Changed
+
+- Move responsibility for awaiting bundled assets into the Bun-only
+  `single-exe/entry.mjs` bootstrap, then dynamically import the regular main
+  module. This keeps the main module free of Bun-specific asset-loader state
+  and preserves its uncompiled Node.js execution path.
+- Detect Bun's compiled virtual paths on both POSIX (`/$bunfs/`) and Windows
+  (`B:/~BUN`) when resolving single-executable resources, and consolidate
+  compiled-runtime handling in `single-exe/compiled.js`.
+- When initially launched with Node.js, restart under Bun with inherited stdio
+  and propagate its exit status instead of replacing the current process with
+  `process.execve()`.
+- Display the maze completion message inside the game instead of opening a
+  blocking alert, and include reset instructions in the result.
+- Export the maze solver as a reusable `runCdpMaze()` function while retaining
+  direct `bun cdp-maze.js` execution. Suppress its console result while stdin
+  is in terminal raw mode so TUI rendering is not corrupted.
+- Replace the manual two-process maze automation instructions with the single
+  `--cdp-maze` workflow in the README and bundled help.
+- Update the homepage and Kitty test images to use the smaller current demo and
+  maze screenshots; exclude the maze screenshot from the npm package.
+- Document theme preview from the TUI command prompt and state Bun 1.3.12 as
+  the minimum required version.
+
+### Fixed
+
+- Make CDP `view.click()` activate MDCUI links and controls at the requested
+  buffer coordinate instead of only moving the cursor there.
+- Allow CDP input dispatch without an explicit session ID by selecting the
+  implicit target, matching other single-target CDP operations.
+- Wait until the embedded asset archive is ready before starting the compiled
+  application, preventing startup from racing bundled resource loading.
+
 ## [0.8.0] - 2026-07-20
 
 This update adds portable inline keydown handling to Markdown text controls,

package/README.md

@@ -1,5 +1,10 @@
 ![Demo](https://raw.githubusercontent.com/jjtseng93/jsmdcui/main/demo.jpg)
 
+- Maze Game
+  * The TUI can be controlled through the Chrome DevTools Protocol (CDP). Codex successfully solved this maze using it.
+
+![Maze Game](https://raw.githubusercontent.com/jjtseng93/jsmdcui/main/maze.jpg)
+
 # Demo App
 ## My app
 
@@ -36,7 +41,8 @@ npx jsmdcui@latest README.md
 
 ## Quick start
 
-jsmdcui requires [Bun](https://bun.com). On Android, install it in Termux:
+jsmdcui requires [Bun ≥ 1.3.12](https://bun.com).
+ On Android, install it in Termux:
 
 ```sh
 npm install -g bun
@@ -94,6 +100,13 @@ npx jsmdcui --demo-imgtool-zh
 npx jsmdcui --demo-maze
 ```
 
+To watch jsmdcui start the maze with a local CDP server and solve it
+automatically after three seconds, run:
+
+```sh
+npx jsmdcui --cdp-maze
+```
+
 ```sh
 # WUI(Web User Interface) Demo
 npx jsmdcui --wui
@@ -147,14 +160,19 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js --cat app.md` | Render the terminal version to stdout, write five generated files beside it, and exit. |
 | `bun src/index.js --testapp.md` | Write the bundled `testapp.md` source to stdout and exit. |
 | `bun src/index.js --export-readme` | Write or overwrite `./README.md` with the bundled README source and exit. |
+| `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`. |
+| `bun src/index.js --cdp-maze` | Load the maze demo, start CDP on `127.0.0.1:9222`, and run the bundled solver after three seconds. |
 | `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. |
 
@@ -537,6 +555,10 @@ selection, search, and copy remain available.
 | `Alt-G` | Show or hide the shortcut bar. |
 | `Ctrl-Q` or `Alt-Q` | Close the current UI. |
 
+To preview another color theme, press `Ctrl-E` or click on `€`, type `theme `, then use `Tab`
+and the arrow keys to browse the available themes. Press `Enter` to switch to
+the selected theme, or `Esc` to cancel and restore the previous one.
+
 The terminal automatically reflows the Markdown when its width changes.
 Only `javascript:` links execute in the TUI; ordinary web links behave as
 normal links in the browser.
@@ -554,6 +576,63 @@ supported HTTP(S) images with Kitty graphics, combine the options:
 bun src/index.js --kitty --allow-url https://example.com/app.md
 ```
 
+### CDP control for TUI automation
+
+The terminal UI can expose a Chrome DevTools Protocol (CDP) server, so another
+Bun process can inspect the terminal buffer, click buffer coordinates, and send
+real keyboard events to the running TUI.
+
+Start CDP from the command line when launching jsmdcui:
+
+```sh
+bun src/index.js --remote-debugging-port=9222 demos/maze.md
+bun src/index.js --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 demos/maze.md
+```
+
+Or start it from inside the TUI editor command prompt(Ctrl-E or €):
+
+```text
+Ctrl-E  cdp
+Ctrl-E  cdp 9000
+Ctrl-E  cdp --address=127.0.0.1
+Ctrl-E  cdp 9000 --public
+```
+
+The default bind address is `127.0.0.1` and the default port is `9222`.
+Use `--public` or `--address=0.0.0.0` only on a trusted network.
+
+Once CDP is running, control the TUI with `Bun.WebView`. For more info, enter
+jsmdcui and use `Ctrl-E` or `€` → `help cdp`.
+
+The cli flag `--cdp-maze` is a combination of 
+  1. Start the demos/maze.md
+  2. Start a local CDP server
+  3. Wait three seconds
+  4. Run the solver cdp-maze.js automatically
+  
+The solver was
+generated from the `llm-maze.txt` instructions; it focuses the maze controls,
+resets the game, reads the maze from the TUI, solves it with breadth-first
+search, and sends arrow-key input until the maze is escaped:
+
+```sh
+npx jsmdcui@latest --cdp-maze
+```
+
+From the source tree, run:
+
+```sh
+bun src/index.js --cdp-maze
+```
+
+Useful automation methods used by `cdp-maze.js`:
+
+- `view.evaluate(js)`
+  - `view.evaluate("micro.getAllText()")`
+  - `view.evaluate("micro.getAllAnsiText()")`
+- `view.click(column, line)`
+- `view.press(key, options)`
+
 ## Browser interaction
 
 The WUI uses normal browser mouse and keyboard behavior. Clicking a
@@ -666,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/cdp-maze.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env bun
+
+// Generated from llm-maze.txt instructions.
+// Start the maze TUI first:
+//   bun src/index.js --remote-debugging-port=9222 demos/maze.md
+// Then run:
+//   bun cdp-maze.js
+
+const DEFAULT_CDP_URL = "ws://127.0.0.1:9222/devtools/browser/cdp-server";
+
+const dirs = [
+  [1, 0, "ArrowDown"],
+  [-1, 0, "ArrowUp"],
+  [0, 1, "ArrowRight"],
+  [0, -1, "ArrowLeft"],
+];
+
+function parseMaze(text) {
+  return text.trimEnd().split("\n").map(line => {
+    const cells = [];
+
+    for (let i = 0; i < line.length;) {
+      const ch = String.fromCodePoint(line.codePointAt(i));
+
+      if (ch === "🧱" || ch === "😀") {
+        cells.push(ch);
+        i += ch.length;
+      } else if (line[i] === " ") {
+        cells.push(" ");
+        i += 2;
+      } else {
+        cells.push(ch);
+        i += ch.length;
+      }
+    }
+
+    return cells;
+  });
+}
+
+function solveMaze(grid) {
+  let start;
+
+  for (let row = 0; row < grid.length; row++) {
+    for (let col = 0; col < grid[row].length; col++) {
+      if (grid[row][col] === "😀") start = [row, col];
+    }
+  }
+
+  if (!start) throw new Error("Maze start not found");
+
+  const queue = [{ row: start[0], col: start[1], path: [] }];
+  const seen = new Set([start.join(",")]);
+
+  while (queue.length) {
+    const { row, col, path } = queue.shift();
+
+    for (const [dr, dc, key] of dirs) {
+      const nextRow = row + dr;
+      const nextCol = col + dc;
+
+      if (
+        nextRow < 0 ||
+        nextRow >= grid.length ||
+        nextCol < 0 ||
+        nextCol >= grid[row].length
+      ) {
+        if (path.length > 0) return path.concat(key);
+        continue;
+      }
+
+      if (nextCol >= grid[nextRow].length) continue;
+      if (grid[nextRow][nextCol] === "🧱") continue;
+
+      const id = `${nextRow},${nextCol}`;
+      if (seen.has(id)) continue;
+
+      seen.add(id);
+      queue.push({
+        row: nextRow,
+        col: nextCol,
+        path: path.concat(key),
+      });
+    }
+  }
+
+  throw new Error("No path found");
+}
+
+export async function runCdpMaze(cdpUrl = DEFAULT_CDP_URL) {
+  const view = new Bun.WebView({
+    backend: {
+      type: "chrome",
+      url: cdpUrl,
+    },
+  });
+
+  try {
+    const control = await view.evaluate(`
+    (() => {
+      const lines = micro.getAllText().split("\\n");
+      const y = lines.findIndex(line =>
+        line.includes("Put the cursor here")
+      );
+
+      return {
+        x: lines[y].indexOf("Put the cursor here") + 1,
+        y: y + 1,
+      };
+    })()
+  `);
+
+    await view.click(control.x, control.y);
+    await view.press("r", { modifiers: ["Control"] });
+    await Bun.sleep(100);
+
+    const mazeText = await view.evaluate(`$("#character").val()`);
+    const path = solveMaze(parseMaze(mazeText));
+
+    for (const key of path) {
+      await view.press(key);
+      await Bun.sleep(100);
+
+      const status = await view.evaluate(`$("#last-key").val()`);
+      if (status.includes("Escaped the maze")) break;
+      if (status.includes("Wall")) {
+        throw new Error(`Hit a wall after ${key}: ${status}`);
+      }
+    }
+
+    const result = await view.evaluate(`$("#last-key").val()`);
+    if (!process.stdin.isRaw) console.log(result);
+    return result;
+  } finally {
+    view.close();
+  }
+}
+
+if (import.meta.main) {
+  await runCdpMaze(Bun.argv[2] ?? DEFAULT_CDP_URL);
+}

package/demos/maze.md

@@ -126,7 +126,8 @@ export function handle(event) {
   if (row === GOAL.row && col === GOAL.col) {
     completed = true;
     $('#last-key').val('🎉🏆🌟 Escaped the maze! / 成功走出迷宮！🌟🏆🎉');
-    alert([
+    $('#character').val([
+      '',
       '🎆🎇🎉 恭 喜 過 關 ！ 🎉🎇🎆',
       '',
       '🥳 你成功逃出迷宮了！ 🥳',
@@ -135,6 +136,10 @@ export function handle(event) {
       '🎈 🎊 🎁 🪩 🎁 🎊 🎈',
       '',
       '🚀 ESCAPED THE MAZE! 🚀',
+      '',
+      'Press Ctrl-R to reset',
+      '按 Ctrl-R 重新開始',
+      ''
     ].join('\n'));
   } else {
     const label = event.key === ' ' ? 'Space' : event.key;

package/llm-maze.txt

@@ -0,0 +1,94 @@
+你正在透過 Bun.WebView 操作 jsmdcui TUI App。
+
+CDP 連線位址：
+
+ws://127.0.0.1:9222/devtools/browser/cdp-server
+
+可用操作：
+
+1. 取得完整純文字 UI：
+
+   await view.evaluate("micro.getAllText()")
+
+2. 取得包含 ANSI 樣式與 OSC 8 link 的完整 UI：
+
+   await view.evaluate("micro.getAllAnsiText()")
+
+3. 點擊 buffer 座標：
+
+   await view.click(column, line)
+
+   column 與 line 都是 1-based。
+   這是整份 buffer 的座標，不是螢幕 pixel。
+   不支援 selector click。
+
+4. 發送真正的鍵盤事件：
+
+   await view.press("ArrowUp")
+   await view.press("ArrowDown")
+   await view.press("ArrowLeft")
+   await view.press("ArrowRight")
+   await view.press("r", { modifiers: ["Control"] })
+
+5. 每次 click 或 press 後，重新取得 UI 快照確認結果。
+
+Maze 操作方式：
+
+先在 micro.getAllText() 中找到包含 "Put the cursor here" 的行，計算該文字的
+1-based column/line，然後 click 該位置，讓 Maze controls 取得焦點。
+
+Maze controls 取得焦點後：
+
+- ArrowUp：上
+- ArrowDown：下
+- ArrowLeft：左
+- ArrowRight：右
+- Ctrl-R：重新開始
+
+每次移動後可讀取狀態：
+
+await view.evaluate("$('#last-key').val()")
+
+取得完整迷宮畫面：
+
+await view.evaluate("$('#character').val()")
+
+看到狀態包含 "Escaped the maze" 代表成功。抵達終點時不會呼叫 alert；大型
+慶祝內容會直接顯示在 character 區域，並提示使用 Ctrl-R 重新開始。
+
+初始化與聚焦 controls 的範例：
+
+const view = new Bun.WebView({
+  backend: {
+    type: "chrome",
+    url: "ws://127.0.0.1:9222/devtools/browser/cdp-server",
+  },
+});
+
+const cell = await view.evaluate(`
+  (() => {
+    const lines = micro.getAllText().split("\\n");
+    const y = lines.findIndex(line =>
+      line.includes("Put the cursor here")
+    );
+
+    return {
+      x: lines[y].indexOf("Put the cursor here") + 1,
+      y: y + 1,
+    };
+  })()
+`);
+
+await view.click(cell.x, cell.y);
+await view.press("r", { modifiers: ["Control"] });
+
+alert 注意事項：
+
+Maze 抵達終點不會觸發 alert。不過 jsmdcui 其他操作若呼叫同步 alert()，CDP
+operation 會等待使用者直接在實際 terminal 按 Enter 關閉；alert 阻塞期間，無法
+再透過 view.press("Enter") 關閉它。無人值守自動化應避免觸發同步 alert，或預先
+提供替代的 dialog handling。
+
+操作完成後呼叫：
+
+view.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.8.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/cdp.md

@@ -22,6 +22,11 @@
 //   Once running, status bar shows:  CDP@<port> server running
 //   Running cdp again shows:         CDP@<port> already running
 //
+// ── Maze demo from the source tree ─────────────────────────────────────────
+//
+//   Start the maze, local CDP server, and automatic solver together:
+//     bun src/index.js --cdp-maze
+//
 // ── Connecting ─────────────────────────────────────────────────────────────
 //
 //   Bun.WebView: