jsmdcui 0.8.0 → 0.10.1

package/runtime/help/help.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/runtime/jsplugins/cdp/cdp-server.js

@@ -554,8 +554,30 @@ async function dispatch(ctx, state, method, params, sessionId, emit) {
       return {};
     }
     case "Input.dispatchKeyEvent": {
-      if (params.type === "keyDown" || params.type === "char") {
-        await ctx.press?.(params.key ?? params.text, { modifiers: params.modifiers ?? 0 });
+      const target = getSessionTarget(state, sessionId);
+      const key = params.key ?? params.text ?? "";
+      const signature = `${params.code ?? key}:${params.modifiers ?? 0}`;
+      if (params.type === "rawKeyDown" || params.type === "keyDown") {
+        if (target.cdpKeyDown !== signature || params.autoRepeat) {
+          await ctx.press?.(key, {
+            modifiers: params.modifiers ?? 0,
+            text: params.text ?? "",
+            code: params.code ?? "",
+            repeat: !!params.autoRepeat,
+          });
+          target.cdpKeyDown = signature;
+        }
+      } else if (params.type === "char") {
+        if (!target.cdpKeyDown) {
+          await ctx.press?.(key, {
+            modifiers: params.modifiers ?? 0,
+            text: params.text ?? "",
+            code: params.code ?? "",
+            repeat: !!params.autoRepeat,
+          });
+        }
+      } else if (params.type === "keyUp") {
+        target.cdpKeyDown = null;
       }
       return {};
     }
@@ -695,6 +717,8 @@ function navigateTarget(state, target, url, emit, options = {}) {
 }
 
 function getSessionTarget(state, sessionId) {
+  if (!sessionId) return getImplicitTarget(state);
+
   const targetId = state.sessions.get(sessionId);
   const target = state.targets.get(targetId);
   if (!target) throw new Error(`No target for session: ${sessionId}`);

package/runtime/jsplugins/cdp/cdp.js

@@ -34,6 +34,8 @@ Flat buffer helpers (all 1-based line numbers, omit → cursor line):
   micro.getLine(n?)            micro.putLine(text, n?)     micro.delLine(n?)
   micro.getLines(from?, to?)   micro.getLinesCount()
   micro.getAllText()           — entire buffer as one string (lines joined by "\n")
+  micro.getAllAnsiText()       — rendered ANSI document, or plain text when unavailable
+  micro.clickBufferCell(x, y)  — activate a 1-based MDCUI cell, or goto in other buffers
   micro.putAllText(text)       — replace entire buffer content; pushes undo
   micro.getSelection()         micro.putSelection(text)
 
@@ -82,7 +84,7 @@ micro.on("init", () => {
         },
         async click(x,y,opt){
           x=x||1 ; y=y||1 ;
-          await micro.cmd.goto(y+':'+x);
+          await micro.clickBufferCell(x, y);
         },
         async scroll(dx,dy){
           const pane = micro.CurPane();
@@ -111,54 +113,8 @@ micro.on("init", () => {
           bp.Insert(text);
         },
         async press(key, options){
-          const bp = micro.CurPane();
-          if (!bp) return;
-
-          // modifiers bitmask: Alt=1, Ctrl=2, Meta=4, Shift=8
-          const mod = options?.modifiers ?? 0;
-          const ctrl  = !!(mod & 2);
-          const shift = !!(mod & 8);
-
-          if (ctrl) {
-            const ctrlMap = {
-              a: () => micro.action.SelectAll(),
-              c: () => micro.action.Copy(),
-              x: () => micro.action.Cut(),
-              v: () => micro.action.Paste(),
-              z: () => micro.action.Undo(),
-              y: () => micro.action.Redo(),
-              s: () => micro.action.Save(),
-            };
-            const h = ctrlMap[key.toLowerCase()];
-            if (h) await h();
-            return;
-          }
-
-          const arrowAction = shift
-            ? { ArrowUp: 'SelectUp', ArrowDown: 'SelectDown', ArrowLeft: 'SelectLeft', ArrowRight: 'SelectRight' }
-            : { ArrowUp: 'CursorUp', ArrowDown: 'CursorDown', ArrowLeft: 'CursorLeft', ArrowRight: 'CursorRight' };
-
-          const keyMap = {
-            ...arrowAction,
-            Enter:     () => micro.action.InsertNewline(),
-            Backspace: () => micro.action.Backspace(),
-            Delete:    () => micro.action.Delete(),
-            Tab:       () => micro.action.InsertTab(),
-            Escape:    () => micro.action.Escape(),
-            Home:      () => shift ? micro.action.SelectToStartOfLine() : micro.action.StartOfLine(),
-            End:       () => shift ? micro.action.SelectToEndOfLine()   : micro.action.EndOfLine(),
-            PageUp:    () => shift ? micro.action.SelectPageUp()        : micro.action.CursorPageUp(),
-            PageDown:  () => shift ? micro.action.SelectPageDown()      : micro.action.CursorPageDown(),
-          };
-
-          const entry = keyMap[key];
-          if (typeof entry === 'string') {
-            await micro.action[entry]();
-          } else if (typeof entry === 'function') {
-            await entry();
-          } else if (key.length === 1) {
-            bp.Insert(key);
-          }
+          const raw = cdpKeyToTerminalInput(key, options);
+          if (raw) await micro._dispatchRawInput(raw);
         },
       }
     
@@ -193,3 +149,53 @@ function toInteger(value) {
   const number = Number(value);
   return Number.isFinite(number) ? Math.trunc(number) : 0;
 }
+
+function cdpKeyToTerminalInput(key, options = {}) {
+  const modifiers = Number(options.modifiers) || 0;
+  const alt = !!(modifiers & 1);
+  const ctrl = !!(modifiers & 2);
+  const meta = !!(modifiers & 4);
+  const shift = !!(modifiers & 8);
+  const modifierCode = 1 + (shift ? 1 : 0) + (alt || meta ? 2 : 0) + (ctrl ? 4 : 0);
+  const value = String(key ?? options.text ?? "");
+
+  const cursorFinal = {
+    ArrowUp: "A",
+    ArrowDown: "B",
+    ArrowRight: "C",
+    ArrowLeft: "D",
+    Home: "H",
+    End: "F",
+  }[value];
+  if (cursorFinal) {
+    return modifierCode === 1
+      ? `\x1b[${cursorFinal}`
+      : `\x1b[1;${modifierCode}${cursorFinal}`;
+  }
+
+  if (value === "PageUp" || value === "PageDown" || value === "Delete") {
+    const number = value === "PageUp" ? 5 : value === "PageDown" ? 6 : 3;
+    return modifierCode === 1
+      ? `\x1b[${number}~`
+      : `\x1b[${number};${modifierCode}~`;
+  }
+
+  if (value === "Tab") return shift ? "\x1b[Z" : "\t";
+  if (value === "Enter") return alt || meta ? "\x1b\r" : "\r";
+  if (value === "Backspace") return "\x7f";
+  if (value === "Escape") return "\x1b";
+
+  let text = typeof options.text === "string" && options.text
+    ? options.text
+    : value === "Space" ? " " : value;
+  if ([...text].length !== 1) return "";
+
+  if (ctrl) {
+    const code = text.toUpperCase().charCodeAt(0);
+    if (code >= 64 && code <= 95) text = String.fromCharCode(code & 31);
+  } else if (shift && /^[a-z]$/.test(text)) {
+    text = text.toUpperCase();
+  }
+
+  return alt || meta ? `\x1b${text}` : text;
+}

package/runtime/jsplugins/chapter/chapter.js

@@ -35,6 +35,8 @@ Flat buffer helpers (all 1-based line numbers, omit → cursor line):
   micro.getLine(n?)            micro.putLine(text, n?)     micro.delLine(n?)
   micro.getLines(from?, to?)   micro.getLinesCount()
   micro.getAllText()           — entire buffer as one string (lines joined by "\n")
+  micro.getAllAnsiText()       — rendered ANSI document, or plain text when unavailable
+  micro.clickBufferCell(x, y)  — activate a 1-based MDCUI cell, or goto in other buffers
   micro.putAllText(text)       — replace entire buffer content; pushes undo
   micro.getSelection()         micro.putSelection(text)
 
@@ -107,4 +109,3 @@ micro.on("init", () => {
   });
 
 });
-

package/runtime/jsplugins/example/example.js

@@ -35,6 +35,8 @@ Flat buffer helpers (all 1-based line numbers, omit → cursor line):
   micro.getLine(n?)            micro.putLine(text, n?)     micro.delLine(n?)
   micro.getLines(from?, to?)   micro.getLinesCount()
   micro.getAllText()           — entire buffer as one string (lines joined by "\n")
+  micro.getAllAnsiText()       — rendered ANSI document, or plain text when unavailable
+  micro.clickBufferCell(x, y)  — activate a 1-based MDCUI cell, or goto in other buffers
   micro.putAllText(text)       — replace entire buffer content; pushes undo
   micro.getSelection()         micro.putSelection(text)