jsmdcui 0.8.0 → 0.10.1

package/src/index.js

@@ -1,8 +1,5 @@
 #!/usr/bin/env bun
 
-let mainPromise = globalThis.assetsLoaderPromise ||
-                  Promise.resolve();
-
 const jsStart = globalThis.Bun ? Bun.nanoseconds() : Date.now() * 1e6;
 const checkpoints = [
   { name: "Bun Engine Boot", time: 0 },
@@ -147,7 +144,12 @@ if(!globalThis.Bun)
     //console.log(process.argv)
 
     console.error('Ran by node, changed to run by bun')
-    process.execve(bunbinary,process.argv,process.env);
+    const launched = child_process.spawnSync(bunbinary, process.argv.slice(1), {
+      stdio: "inherit",
+      env: process.env,
+    });
+    if (launched.error) throw launched.error;
+    process.exit(launched.status ?? 1);
   }
   catch(e){
     console.log(`
@@ -179,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
 
@@ -338,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;
@@ -1090,12 +1097,16 @@ function parseArgs(argv) {
     clean: false,
     check: false,
     cat: false,
+    wui: false,
+    printUi: false,
     docs: false,
     exportReadme: false,
+    exportCdpMaze: false,
     changelog: false,
     testapp: false,
     demoList: false,
     demo: null,
+    overwriteDemo: false,
     allowUrl: false,
     buildExe: false,
     buildFor: "",
@@ -1103,6 +1114,7 @@ function parseArgs(argv) {
     debug: false,
     profile: false,
     plugin: "",
+    cdpMaze: false,
     cdpPort: 0,
     cdpAddress: "",
     kittyMode: "off",
@@ -1118,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");
@@ -1134,11 +1148,20 @@ 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" };
+    }
     else if (arg === "--demo") {
       flags.demo = { option: arg, filename: "testapp.md", asset: "testapp.md" };
     }
@@ -1178,23 +1201,64 @@ function parseArgs(argv) {
     }
   }
 
+  if (flags.cdpMaze && !flags.cdpPort) flags.cdpPort = 9222;
+
   return { flags, files };
 }
 
 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
@@ -1203,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
@@ -1219,50 +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
+      
   --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");
 }
 
@@ -8003,6 +8081,12 @@ async function exportReadme() {
   console.log(`Wrote ${readmePath}`);
 }
 
+async function exportCdpMaze() {
+  const outputPath = resolve("cdp-maze.js");
+  await Bun.write(outputPath, await bundledMarkdownSource("cdp-maze.js"));
+  console.log(`Wrote ${outputPath}`);
+}
+
 async function printChangelogDocs() {
   const changelog = readInternalAssetText("CHANGELOG.md") ?? await Bun.file(join(REPO_ROOT, "CHANGELOG.md")).text();
   process.stdout.write(Bun.markdown.ansi(changelog, { hyperlinks: true }));
@@ -8052,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;
 
@@ -8075,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}`);
@@ -8083,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) {
@@ -8097,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");
@@ -8124,6 +8246,10 @@ async function main() {
     await exportReadme();
     return;
   }
+  if (flags.exportCdpMaze) {
+    await exportCdpMaze();
+    return;
+  }
   if (flags.changelog) {
     await printChangelogDocs();
     return;
@@ -8137,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))) {
@@ -8167,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");
@@ -8178,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;
   }
 
@@ -8243,6 +8360,7 @@ async function main() {
     runtime,
     jsPlugins,
     encodingExplicit,
+    inputFiletype,
     allowUrl: flags.allowUrl,
     kittyMode: flags.kittyMode,
   };
@@ -8370,6 +8488,23 @@ async function main() {
     if (flags.cdpAddress) cdpArgs.push(`--address=${flags.cdpAddress}`);
     await app.handleCommand(`cdp ${cdpArgs.join(" ")}`);
   }
+
+  if (flags.cdpMaze) {
+    const solverHost = !flags.cdpAddress || flags.cdpAddress === "0.0.0.0"
+      ? "127.0.0.1"
+      : flags.cdpAddress;
+    const solverUrl = `ws://${solverHost}:${flags.cdpPort}/devtools/browser/cdp-server`;
+    setTimeout(async () => {
+      try {
+        const { runCdpMaze } = await import("../cdp-maze.js");
+        app.message = await runCdpMaze(solverUrl);
+        app.render?.();
+      } catch (error) {
+        app.message = `CDP maze solver failed: ${error?.message || error}`;
+        app.render?.();
+      }
+    }, 3000);
+  }
   
   if (flags.profile) {
     addCheckpoint("Clipboard Probing");
@@ -8683,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;
@@ -8763,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;
@@ -8794,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
@@ -8803,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);
@@ -8837,9 +8977,6 @@ async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAUL
 }
 
 
-mainPromise.then(r=>{
-
-
 main().catch((error) => {
   try {
     (_activeTtyStream ?? process.stdin).setRawMode?.(false);
@@ -8849,6 +8986,3 @@ main().catch((error) => {
     process.exit(1);
   }
 });
-
-
-})

package/src/lua/engine.js

@@ -2,7 +2,6 @@ import { existsSync } from "node:fs";
 import { readInternalAssetBytes } from "../runtime/assets.js";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { isCompiledBinary, resolveCompiledBaseDir } from "../runtime/compiled.js";
 import { REPO_ROOT } from "../../single-exe/compiled.js";
 
 export async function createLuaEngine() {
@@ -44,9 +43,7 @@ async function resolveLuaWasmLocation() {
     }
   }
 
-  const fallbackPath = isCompiledBinary(process.argv)
-    ? join(resolveCompiledBaseDir({ argv: process.argv }), wasmAssetPath)
-    : join(REPO_ROOT, wasmAssetPath);
+  const fallbackPath = join(REPO_ROOT, wasmAssetPath);
 
   return existsSync(fallbackPath) ? fallbackPath : undefined;
 }

package/src/plugins/js-bridge.js

@@ -4,6 +4,7 @@ import { dirname, join, basename, extname } from "node:path";
 import { pathToFileURL } from "node:url";
 import { tmpdir } from "node:os";
 import { assetPath, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetBytes } from "../runtime/assets.js";
+import { isMdcuiEncoding } from "../runtime/encodings.js";
 import { newMessage, newMessageAtLine, MTError, MTWarning, MTInfo } from "../buffer/message.js";
 import { Loc } from "../buffer/loc.js";
 
@@ -1405,6 +1406,48 @@ export function buildMicroGlobal(jsManager) {
       return app?.buffer?.lines.join("\n") ?? "";
     },
 
+    // Returns the rendered ANSI document when available, otherwise plain text.
+    getAllAnsiText() {
+      const buffer = getApp()?.buffer;
+      return typeof buffer?._mdcuiAnsiText === "string"
+        ? buffer._mdcuiAnsiText
+        : buffer?.lines.join("\n") ?? "";
+    },
+
+    // Activates a 1-based rendered-buffer cell in MDCUI; otherwise falls back to goto.
+    async clickBufferCell(column = 1, line = 1) {
+      const app = getApp();
+      const buffer = app?.buffer;
+      if (!app || !buffer) return false;
+
+      const targetLine = Math.max(1, Math.trunc(Number(line)) || 1);
+      const targetColumn = Math.max(1, Math.trunc(Number(column)) || 1);
+      if (!isMdcuiEncoding(buffer.encoding ?? buffer.Settings?.encoding)) {
+        await app.handleCommand(`goto ${targetLine}:${targetColumn}`);
+        app.render?.();
+        return true;
+      }
+
+      const y = Math.min(targetLine - 1, Math.max(0, buffer.lines.length - 1));
+      const x = Math.min(targetColumn - 1, String(buffer.lines[y] ?? "").length);
+      buffer.cursor = { x, y };
+      const handled = await app.handleMdcuiCellCallback(buffer, y, x, "mouse");
+      app.render?.();
+      return handled;
+    },
+
+    // Sends terminal input through the App's normal parser and event pipeline.
+    async _dispatchRawInput(raw) {
+      const app = getApp();
+      if (!app) return false;
+      const bytes = typeof raw === "string"
+        ? new TextEncoder().encode(raw)
+        : raw;
+      await app._dispatchInput(bytes);
+      app.render?.();
+      return true;
+    },
+
     // Replaces the entire buffer content with text (may contain newlines).
     putAllText(text) {
       const app = getApp();

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/compiled-runtime.test.js

@@ -0,0 +1,8 @@
+import { expect, test } from "bun:test";
+import { isCompiledBinary as isSingleExeCompiled } from "../single-exe/compiled.js";
+
+test("single-exe recognizes Bun compiled virtual paths", () => {
+  expect(isSingleExeCompiled(["bun", "/$bunfs/root/app.js"])).toBe(true);
+  expect(isSingleExeCompiled(["bun", "B:/~BUN/root/app.js"])).toBe(true);
+  expect(isSingleExeCompiled(["bun", "/project/src/index.js"])).toBe(false);
+});