jsmdcui 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.4.0] - 2026-07-16
+
+This release separates executable Markdown UI views from ordinary editable
+buffers, makes encoding behavior predictable across opens, tabs, splits, and
+reopens, and adds explicit demo and trusted-remote execution modes.
+
+### Added
+
+- Add `--demo`. It outputs and overwrites `./testapp.md`, opens it as a terminal
+  Markdown UI, and writes the five generated companion files beside it.
+- Add `--allow-url` for trusted remote Markdown apps. It downloads an HTTP(S)
+  resource into the current directory, opens the downloaded copy through the
+  normal local Markdown UI pipeline, writes the five generated companion files,
+  and permits its embedded frontend and backend code to run.
+- Add regression coverage for global encoding handling, mdcui backup isolation,
+  the bundled demo workflow, implicit Markdown rendering, and explicit UTF-8
+  editing.
+
+### Changed
+
+- Treat `mdcui` buffers as independent, derived, read-only views. Every mdcui
+  open creates a new buffer instead of entering the same-path editable-buffer
+  cache.
+- Continue sharing ordinary buffers opened from the same absolute path.
+  UTF-8 and other non-mdcui views share content, modification state, saves, and
+  reopens.
+- Re-evaluate buffer sharing after `reopen`:
+  - reopening an mdcui view as a normal encoding joins an existing same-path
+    editable buffer, or registers itself when no such buffer exists;
+  - reopening a shared editable view as mdcui detaches only the current pane
+    into a new mdcui buffer and leaves the other shared panes unchanged.
+- Make interactive `open`, `tab`, `vsplit`, and `hsplit` operations perform
+  fresh `.md` automatic detection for files that are not already represented
+  by a normal cached buffer.
+- Ignore a top-level global `encoding` value read from `settings.json`.
+  Encoding is selected per invocation or buffer; command-line encoding options
+  remain effective for the current run and are not persisted.
+- Organize `--testapp.md` and `--demo` under a dedicated `Demo` section in
+  `--help`, and document commands that overwrite source or generated files.
+
+### Fixed
+
+- Fix `.md` files opened from inside the editor failing to enter mdcui mode.
+- Fix encoding changes leaking between independent mdcui tabs.
+- Fix `reopen mdcui` mutating every pane that shared the original editable
+  buffer.
+- Fix mdcui-to-UTF-8 reopens remaining outside the normal same-path buffer
+  cache.
+- Delay applying an explicit reopen encoding until the reopen is confirmed, so
+  canceling the save prompt does not alter the shared buffer.
+
+### Security
+
+- Exclude mdcui buffers completely from crash-recovery backups: they do not
+  create, apply, prompt for, or remove backups. This prevents a derived
+  read-only view from consuming or deleting a backup belonging to an editable
+  view of the same Markdown source.
+- Remote HTTP(S) Markdown remains non-executable and does not write companion
+  files by default.
+- `--allow-url` is an explicit trust boundary. It writes downloaded content and
+  generated JavaScript/HTML files into the current directory, may overwrite
+  files with the same names, and runs code from the remote document with the
+  permissions of the jsmdcui process. Use it only with trusted URLs and in a
+  directory where those writes are safe.
+
+## [0.3.1] - 2026-07-16
+
+### Added
+
+- Add `--edit` to open Markdown files as editable UTF-8 source instead of
+  automatically entering mdcui mode.
+- Add `--cat` regression coverage for implicit mdcui rendering and explicit
+  UTF-8 overrides.
+
+### Fixed
+
+- Prevent an explicit encoding choice from being replaced by automatic mdcui
+  detection.
+- Correct terminal raw-mode handling around log and prompt output.
+
 ## [0.3.0] - 2026-07-16
 
 Initial usable release, based on the bunmicro terminal editor.

package/README.md

@@ -78,8 +78,11 @@ The command table below uses the cloned-source form. If you use npx, replace
 | Command | Result |
 | --- | --- |
 | `bun src/index.js app.md` | Render `app.md` as a read-only terminal UI and write five generated files beside it. |
+| `bun src/index.js --edit app.md` | Open `app.md` as editable UTF-8 source, overriding automatic Markdown UI detection. |
 | `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 --demo` | Outputs & overwrites `./testapp.md`, opens it in the terminal UI, and writes 5 generated files beside it. |
+| `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory, write 5 generated files, and allow its embedded code to run. Only use trusted URLs. |
 | `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise use 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. |
 | `PORT=8080 bun src/index.js --wui app.md` | Start the browser UI on another port. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Markdown as a Common UI for Terminals and Web Browsers",
   "type": "module",
   "main": "./src/index.js",

package/runmd.mjs

@@ -17,6 +17,7 @@ const TEST_COL=5
 
 function logWroteFile(label,path)
 {
+  if(!process.stdin.isRaw)
   csl(mda(`- Wrote to ${label} file: ${path}`))
 }
 

package/runtime/help/help.md

@@ -78,8 +78,11 @@ The command table below uses the cloned-source form. If you use npx, replace
 | Command | Result |
 | --- | --- |
 | `bun src/index.js app.md` | Render `app.md` as a read-only terminal UI and write five generated files beside it. |
+| `bun src/index.js --edit app.md` | Open `app.md` as editable UTF-8 source, overriding automatic Markdown UI detection. |
 | `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 --demo` | Outputs & overwrites `./testapp.md`, opens it in the terminal UI, and writes 5 generated files beside it. |
+| `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory, write 5 generated files, and allow its embedded code to run. Only use trusted URLs. |
 | `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise use 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. |
 | `PORT=8080 bun src/index.js --wui app.md` | Start the browser UI on another port. |

package/src/buffer/backup.js

@@ -5,9 +5,14 @@ import { existsSync, statSync, unlinkSync } from "node:fs";
 import { mkdir, writeFile, readFile, rename } from "node:fs/promises";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
+import { isMdcuiEncoding } from "../runtime/encodings.js";
 
 export const BACKUP_SUFFIX = ".micro-backup";
 
+function isMdcuiBuffer(buf) {
+  return isMdcuiEncoding(buf?.encoding ?? buf?.Settings?.encoding);
+}
+
 export function getBackupDir(buf, configDir) {
   const raw = String(buf?.Settings?.backupdir ?? "");
   if (!raw) return join(configDir, "backups");
@@ -49,7 +54,7 @@ export function determineBackupPath(backupDirPath, absPath) {
 }
 
 export async function writeBackup(buf, configDir, path = buf?.AbsPath ?? buf?.path, { force = false } = {}) {
-  if ((!force && !buf?.Settings?.backup) || !path || buf.type !== "default") return false;
+  if (isMdcuiBuffer(buf) || (!force && !buf?.Settings?.backup) || !path || buf.type !== "default") return false;
   const dir = getBackupDir(buf, configDir);
   await mkdir(dir, { recursive: true });
   const { name, resolveName } = determineBackupPath(dir, path);
@@ -66,7 +71,7 @@ export async function writeBackup(buf, configDir, path = buf?.AbsPath ?? buf?.pa
 }
 
 export function removeBackup(buf, configDir, path = buf?.AbsPath ?? buf?.path) {
-  if (buf?.Settings?.permbackup || buf?._forceKeepBackup) return;
+  if (isMdcuiBuffer(buf) || buf?.Settings?.permbackup || buf?._forceKeepBackup) return;
   if (!path || buf.type !== "default") return;
   const dir = getBackupDir(buf, configDir);
   const { name, resolveName } = determineBackupPath(dir, path);
@@ -77,7 +82,7 @@ export function removeBackup(buf, configDir, path = buf?.AbsPath ?? buf?.path) {
 // promptFn(msg) -> Promise<string>
 // Returns { recovered: bool, abort: bool }
 export async function applyBackup(buf, configDir, promptFn) {
-  if (!buf?.Settings?.backup || buf?.Settings?.permbackup) return { recovered: false, abort: false };
+  if (isMdcuiBuffer(buf) || !buf?.Settings?.backup || buf?.Settings?.permbackup) return { recovered: false, abort: false };
   if (!buf.path || buf.type !== "default") return { recovered: false, abort: false };
 
   const dir = getBackupDir(buf, configDir);

package/src/config/config.js

@@ -27,6 +27,9 @@ export class Config {
     const text = await readFile(path, "utf8");
     if (text.trimStart().startsWith("null") || text.trim() === "") return;
     this.parsedSettings = Bun.JSON5.parse(text);
+    // jsmdcui chooses the input encoding per invocation/buffer. A persisted
+    // global encoding must neither affect startup nor survive the next save.
+    delete this.parsedSettings.encoding;
     this.applyParsedSettings(this.parsedSettings);
   }
 

package/src/config/defaults.js

@@ -98,7 +98,7 @@ export const OPTION_CHOICES = {
 
 // Settings that are buffer-local only and must never be written to the global config file.
 // Mirrors Go micro's config.LocalSettings.
-export const LOCAL_SETTINGS = new Set(["readonly", "filetype", "fileformat"]);
+export const LOCAL_SETTINGS = new Set(["readonly", "filetype", "fileformat", "encoding"]);
 
 export function defaultAllSettings() {
   return { ...DEFAULT_COMMON_SETTINGS, ...DEFAULT_GLOBAL_ONLY_SETTINGS };

package/src/index.js

@@ -304,14 +304,14 @@ function encodeHex3Text(text) {
   return decodeBinaryBytes(Buffer.from(text, "latin1"));
 }
 
-async function readTextFileWithEncoding(path, encoding = "utf-8") {
+async function readTextFileWithEncoding(path, encoding = "utf-8", inferMdcui = true) {
   const bytes = new Uint8Array(await Bun.file(path).arrayBuffer());
-  return decodeAndRenderTextBytes(bytes, encodingForPath(path, encoding), process.stdout.columns || 80, path);
+  return decodeAndRenderTextBytes(bytes, encodingForPath(path, encoding, inferMdcui), process.stdout.columns || 80, path);
 }
 
-async function fetchTextWithEncoding(url, encoding = "utf-8") {
+async function fetchTextWithEncoding(url, encoding = "utf-8", inferMdcui = true) {
   const bytes = await fetchHttpBytes(url);
-  return decodeAndRenderTextBytes(new Uint8Array(bytes), encodingForPath(url, encoding));
+  return decodeAndRenderTextBytes(new Uint8Array(bytes), encodingForPath(url, encoding, inferMdcui));
 }
 
 function normalizeEncodingLabel(encoding = "utf-8") {
@@ -321,9 +321,9 @@ function normalizeEncodingLabel(encoding = "utf-8") {
   return new TextDecoder(s).encoding;
 }
 
-function encodingForPath(pathOrUrl, encoding = DEFAULT_SETTINGS.encoding) {
+function encodingForPath(pathOrUrl, encoding = DEFAULT_SETTINGS.encoding, inferMdcui = true) {
   const normalized = normalizeEncodingLabel(encoding);
-  if (normalized !== "utf-8") return normalized;
+  if (normalized !== "utf-8" || !inferMdcui) return normalized;
   let pathname = String(pathOrUrl ?? "").replace(/[?#].*$/, "");
   try {
     if (isHttpUrl(pathname)) pathname = new URL(pathname).pathname;
@@ -869,6 +869,8 @@ function parseArgs(argv) {
     docs: false,
     changelog: false,
     testapp: false,
+    demo: false,
+    allowUrl: false,
     buildExe: false,
     buildFor: "",
     configDir: "",
@@ -901,9 +903,14 @@ function parseArgs(argv) {
     else if (arg === "--hex3zst") {
       flags.settings.set("encoding", "hex3zst");
     }
+    else if (arg === "--edit") {
+      flags.settings.set("encoding", "utf-8");
+    }
     else if (arg === "--docs" || arg === "--readme") flags.docs = true;
     else if (arg === "--changelog") flags.changelog = true;
     else if (arg === "--testapp.md") flags.testapp = true;
+    else if (arg === "--demo") flags.demo = true;
+    else if (arg === "--allow-url") flags.allowUrl = true;
     else if (arg === "--build-exe") flags.buildExe = true;
     else if (arg === "--build-for") flags.buildFor = argv[++i] ?? "";
     else if (arg === "-debug") flags.debug = true;
@@ -946,6 +953,8 @@ 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
@@ -971,11 +980,19 @@ Information:
       Show ${pkg.name}'s README.md & exit
   --changelog
       Show CHANGELOG.md & exit
-  --testapp.md
-      Write testapp.md to stdout & exit
   -profile, --profile
       Print startup performance profile and exit
 
+Demo:
+  --testapp.md
+      Write the bundled testapp.md to stdout & exit
+  --demo
+      Outputs & overwrites ./testapp.md, opens it in the TUI, and writes 5 generated files
+
+Remote Markdown:
+  --allow-url
+      Download HTTP(S) Markdown to cwd, write 5 generated files, and 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`
@@ -1129,7 +1146,7 @@ class BufferModel {
     let text = "";
     let readonly = false;
     let modTimeMs = null;
-    let encoding = context.config?.globalSettings?.encoding ?? DEFAULT_SETTINGS.encoding;
+    let encoding = context.inputEncoding ?? context.config?.globalSettings?.encoding ?? DEFAULT_SETTINGS.encoding;
     let ansiStyleLines = null;
     let ansiText = null;
     let sourceText = null;
@@ -1140,7 +1157,7 @@ class BufferModel {
       if (info.isDirectory()) throw new Error(`${path} is a directory`);
       readonly = !canWritePath(path);
       modTimeMs = info.mtimeMs;
-      const decoded = await readTextFileWithEncoding(path, encoding);
+      const decoded = await readTextFileWithEncoding(path, encoding, !context.encodingExplicit);
       text = decoded.text;
       encoding = decoded.encoding;
       ansiStyleLines = decoded.ansiStyleLines ?? null;
@@ -1536,7 +1553,7 @@ class BufferModel {
   async reopen(context = {}) {
     if (!this.path) return;
     if (isHttpUrl(this.path)) {
-      const decoded = await fetchTextWithEncoding(this.path, this.Settings.encoding ?? this.encoding);
+      const decoded = await fetchTextWithEncoding(this.path, this.Settings.encoding ?? this.encoding, false);
       const text = decoded.text;
       this.encoding = decoded.encoding;
       this.Settings.encoding = decoded.encoding;
@@ -1568,7 +1585,7 @@ class BufferModel {
     }
     const info = statSync(this.path);
     if (info.isDirectory()) throw new Error(`${this.path} is a directory`);
-    const decoded = await readTextFileWithEncoding(this.path, this.Settings.encoding ?? this.encoding);
+    const decoded = await readTextFileWithEncoding(this.path, this.Settings.encoding ?? this.encoding, false);
     const text = decoded.text;
     this.encoding = decoded.encoding;
     this.Settings.encoding = decoded.encoding;
@@ -4624,7 +4641,7 @@ class App {
   async openInPane(path) {
     try {
       const previous = this.pane.buffer;
-      const buffer = await loadBufferForPath(path, this.context);
+      const buffer = await loadBufferForPath(path, this.context, {}, { interactive: true });
       this.pane.buffer = buffer;
       this.pane.selection = null;
       if (previous !== buffer) this._closeBufferIfUnused(previous);
@@ -4637,7 +4654,7 @@ class App {
 
   async openFile(path) {
     try {
-      const buffer = await loadBufferForPath(path, this.context);
+      const buffer = await loadBufferForPath(path, this.context, {}, { interactive: true });
       if (isEmptyUntitledBuffer(this.buffer)) {
         const previous = this.pane.buffer;
         this.pane.buffer = buffer;
@@ -4655,6 +4672,34 @@ class App {
     }
   }
 
+  reconcileReopenedBuffer(buffer) {
+    if (!buffer || isHttpUrl(buffer.path)) return buffer;
+    const map = this.context?._openBuffers;
+    if (!map) return buffer;
+    const absPath = resolve(buffer.AbsPath || buffer.path);
+
+    if (isMdcuiEncoding(buffer.encoding)) {
+      if (map.get(absPath) === buffer) map.delete(absPath);
+      buffer._openBufferMap = null;
+      return buffer;
+    }
+
+    const existing = map.get(absPath);
+    if (existing && existing !== buffer && !isMdcuiEncoding(existing.encoding)) {
+      for (const tab of this.tabs) {
+        for (const pane of tab.panes()) {
+          if (pane.buffer === buffer) pane.buffer = existing;
+          if (pane.prevBuffer === buffer) pane.prevBuffer = existing;
+        }
+      }
+      return existing;
+    }
+
+    buffer._openBufferMap = map;
+    map.set(absPath, buffer);
+    return buffer;
+  }
+
   async save({ force = false } = {}) {
     if (isEditLockedBuffer(this.buffer)) { this.message = "Can't save under readonly mode"; return; }
     if (!force && this.buffer?.readonly) { this.message = "Can't save under readonly mode"; return; }
@@ -5110,9 +5155,10 @@ class App {
       }
       case "reopen": {
         if (!buf?.path) { this.message = "No file to reopen"; break; }
+        let requestedEncoding = null;
         if (cmdArgs[0]) {
           try {
-            buf.SetOption("encoding", cmdArgs[0]);
+            requestedEncoding = normalizeEncodingLabel(cmdArgs[0]);
           } catch (error) {
             this.message = String(error.message || error);
             break;
@@ -5120,9 +5166,24 @@ class App {
         }
         const doReopen = async () => {
           try {
+            if (isMdcuiEncoding(requestedEncoding)) {
+              const detachedContext = { ...this.context, inputEncoding: "mdcui", encodingExplicit: true };
+              const reopened = await loadBufferForPath(buf.path, detachedContext);
+              const previous = this.pane.buffer;
+              this.pane.buffer = reopened;
+              this.pane.selection = null;
+              if (previous !== reopened) this._closeBufferIfUnused(previous);
+              await this.context.plugins?.run("onBufferOpen", reopened);
+              await this.context.jsPlugins?.run("onBufferOpen", reopened);
+              this.message = `Reopened ${reopened.name} as ${reopened.encoding}`;
+              this.render();
+              return;
+            }
+            if (requestedEncoding) buf.SetOption("encoding", requestedEncoding);
             await buf.reopen(this.context);
-            if (this.pane?.buffer === buf) this.pane.selection = null;
-            this.message = `Reopened ${buf.name} as ${buf.encoding}`;
+            const reopened = this.reconcileReopenedBuffer(buf);
+            if (this.pane?.buffer === reopened) this.pane.selection = null;
+            this.message = `Reopened ${reopened.name} as ${reopened.encoding}`;
           } catch (error) {
             this.message = String(error.message || error);
           }
@@ -5228,7 +5289,7 @@ class App {
       case "vsplit": {
         let newBuf;
         if (cmdArgs.length > 0) {
-          try { newBuf = await loadBufferForPath(resolve(expandHome(cmdArgs[0])), this.context); }
+          try { newBuf = await loadBufferForPath(resolve(expandHome(cmdArgs[0])), this.context, {}, { interactive: true }); }
           catch (err) { this.message = err.message; break; }
         } else {
           newBuf = new BufferModel({ command: {} });
@@ -5241,7 +5302,7 @@ class App {
       case "hsplit": {
         let newBuf;
         if (cmdArgs.length > 0) {
-          try { newBuf = await loadBufferForPath(resolve(expandHome(cmdArgs[0])), this.context); }
+          try { newBuf = await loadBufferForPath(resolve(expandHome(cmdArgs[0])), this.context, {}, { interactive: true }); }
           catch (err) { this.message = err.message; break; }
         } else {
           newBuf = new BufferModel({ command: {} });
@@ -6528,11 +6589,25 @@ function commandHasStartupJump(command = {}) {
   return commandHasStartCursor(command) || Boolean(command.searchRegex);
 }
 
-async function loadBufferForPath(pathOrUrl, context, command = {}) {
+async function loadBufferForPath(pathOrUrl, context, command = {}, { interactive = false } = {}) {
+  const loadContext = interactive
+    ? { ...context, inputEncoding: defaultAllSettings().encoding, encodingExplicit: false }
+    : context;
+  if (isHttpUrl(pathOrUrl) && loadContext.allowUrl) {
+    const url = new URL(pathOrUrl);
+    let name;
+    try { name = decodeURIComponent(basename(url.pathname)); }
+    catch { name = basename(url.pathname); }
+    if (!name) name = "remote.md";
+    if (!name.toLowerCase().endsWith(".md")) name += ".md";
+    const localPath = resolve(name);
+    await Bun.write(localPath, await fetchHttpBytes(pathOrUrl));
+    return await loadBufferForPath(localPath, loadContext, command, { interactive });
+  }
   let buffer;
   if (isHttpUrl(pathOrUrl)) {
-    let encoding = context.config?.globalSettings?.encoding ?? DEFAULT_SETTINGS.encoding;
-    const decoded = await fetchTextWithEncoding(pathOrUrl, encoding);
+    let encoding = loadContext.inputEncoding ?? loadContext.config?.globalSettings?.encoding ?? DEFAULT_SETTINGS.encoding;
+    const decoded = await fetchTextWithEncoding(pathOrUrl, encoding, !loadContext.encodingExplicit);
     const text = decoded.text;
     encoding = decoded.encoding;
     const urlPath = pathOrUrl.replace(/[?#].*$/, "");
@@ -6548,13 +6623,18 @@ async function loadBufferForPath(pathOrUrl, context, command = {}) {
       mdcuiRenderWidth: decoded.mdcuiRenderWidth ?? 0,
     });
     buffer._configDir = context?.config?.configDir ?? null;
-    attachSyntax(buffer, context, urlPath, text);
+    attachSyntax(buffer, loadContext, urlPath, text);
   } else {
     if (!context._openBuffers) context._openBuffers = new Map();
     const absPath = resolve(pathOrUrl);
     const existing = context._openBuffers.get(absPath);
-    if (existing) return existing;
-    buffer = await BufferModel.fromFile(absPath, command, context);
+    const requestedEncoding = encodingForPath(
+      absPath,
+      loadContext.inputEncoding ?? loadContext.config?.globalSettings?.encoding ?? DEFAULT_SETTINGS.encoding,
+      !loadContext.encodingExplicit,
+    );
+    if (existing && !isMdcuiEncoding(existing.encoding) && !isMdcuiEncoding(requestedEncoding)) return existing;
+    buffer = await BufferModel.fromFile(absPath, command, loadContext);
     // Check for crash-recovery backup before returning the buffer.
     const promptFn = context._termPrompt;
     if (promptFn && buffer._configDir) {
@@ -6565,8 +6645,12 @@ async function loadBufferForPath(pathOrUrl, context, command = {}) {
         attachSyntax(buffer, context, absPath, buffer.lines.join("\n"));
       }
     }
-    buffer._openBufferMap = context._openBuffers;
-    context._openBuffers.set(absPath, buffer);
+    // mdcui is a derived, read-only view. Keep every view independent and out
+    // of the same-path cache used by normal editable buffers.
+    if (!isMdcuiEncoding(buffer.encoding)) {
+      buffer._openBufferMap = context._openBuffers;
+      context._openBuffers.set(absPath, buffer);
+    }
   }
   if (DEFAULT_SETTINGS.savecursor && !commandHasStartupJump(command) && context?.cursorStates?.[pathOrUrl]) {
     const saved = context.cursorStates[pathOrUrl];
@@ -7272,8 +7356,11 @@ async function printChangelogDocs() {
 }
 
 async function printTestappSource() {
-  const testapp = readInternalAssetText("testapp.md") ?? await Bun.file(join(REPO_ROOT, "testapp.md")).text();
-  process.stdout.write(testapp);
+  process.stdout.write(await bundledTestappSource());
+}
+
+async function bundledTestappSource() {
+  return readInternalAssetText("testapp.md") ?? await Bun.file(join(REPO_ROOT, "testapp.md")).text();
 }
 
 async function main() {
@@ -7331,6 +7418,11 @@ async function main() {
     await printTestappSource();
     return;
   }
+  if (flags.demo) {
+    const demoPath = resolve("testapp.md");
+    await Bun.write(demoPath, await bundledTestappSource());
+    rawFiles.splice(0, rawFiles.length, demoPath);
+  }
   if (flags.options) {
     for (const [key, value] of Object.entries(defaultAllSettings()).sort(([a], [b]) => a.localeCompare(b))) {
       console.log(`-${key} value`);
@@ -7341,6 +7433,7 @@ async function main() {
   addCheckpoint("Config Initialization");
   const config = await new Config({ configDir: flags.configDir }).init();
   config.applyCliSettings(flags.settings);
+  const encodingExplicit = flags.settings.has("encoding") || Object.hasOwn(config.parsedSettings, "encoding");
   syncEditorSettings(config);
 
   addCheckpoint("Runtime Registry Init");
@@ -7352,7 +7445,7 @@ async function main() {
   const syntaxDefinitions = await loadSyntaxDefinitions(runtime);
 
   if (flags.cat) {
-    await catFiles(rawFiles, colorscheme, syntaxDefinitions, config.getGlobalOption("encoding"));
+    await catFiles(rawFiles, colorscheme, syntaxDefinitions, config.getGlobalOption("encoding"), !encodingExplicit);
     return;
   }
 
@@ -7410,7 +7503,7 @@ async function main() {
 
   const { files, command } = parseInput(rawFiles);
   const jsPlugins = new JsPluginManager();
-  const context = { colorscheme, syntaxDefinitions, config, runtime, jsPlugins };
+  const context = { colorscheme, syntaxDefinitions, config, runtime, jsPlugins, encodingExplicit, allowUrl: flags.allowUrl };
   jsPlugins.setContext(context);
   buildMicroGlobal(jsPlugins);   // sets globalThis.micro
 
@@ -7922,30 +8015,34 @@ function syncEditorSettings(config) {
   }
 }
 
-async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAULT_SETTINGS.encoding) {
+async function catFiles(files, colorscheme, syntaxDefinitions, encoding = DEFAULT_SETTINGS.encoding, inferMdcui = true) {
   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;
     let ansiContent = null;
     let effectivePath = filePath;
+    let effectiveEncoding = normalizeEncodingLabel(encoding);
     if (stdin) {
       const chunks = [];
       for await (const chunk of process.stdin) chunks.push(chunk);
       const decoded = await decodeAndRenderTextBytes(Buffer.concat(chunks), encoding);
       content = decoded.text;
       ansiContent = decoded.ansiText ?? null;
+      effectiveEncoding = decoded.encoding;
     } else if (isHttpUrl(filePath)) {
-      const decoded = await fetchTextWithEncoding(filePath, encoding);
+      const decoded = await fetchTextWithEncoding(filePath, encoding, inferMdcui);
       content = decoded.text;
       ansiContent = decoded.ansiText ?? null;
+      effectiveEncoding = decoded.encoding;
       // Use the URL pathname for syntax/md detection (strip query/hash)
       try { effectivePath = new URL(filePath).pathname; } catch { effectivePath = filePath; }
     } else {
-      const decoded = await readTextFileWithEncoding(filePath, encoding);
+      const decoded = await readTextFileWithEncoding(filePath, encoding, inferMdcui);
       content = decoded.text;
       ansiContent = decoded.ansiText ?? null;
+      effectiveEncoding = decoded.encoding;
     }
-    if (isMdcuiEncoding(encoding)) {
+    if (isMdcuiEncoding(effectiveEncoding)) {
       process.stdout.write(ansiContent ?? content);
       if (!(ansiContent ?? content).endsWith("\n")) process.stdout.write("\n");
       continue;

package/tests/backup.test.js

@@ -130,4 +130,29 @@ describe("backup lifecycle", () => {
     expect(await writeBackup(buf, root, buf.AbsPath, { force: true })).toBe(true);
     expect(existsSync(determineBackupPath(backupDir, buf.AbsPath).name)).toBe(true);
   });
+
+  test("mdcui buffers never write, recover, or remove backups", async () => {
+    const root = await tempDir();
+    const backupDir = join(root, "backups");
+    await mkdir(backupDir);
+    const buf = buffer("/tmp/file.md", "rendered markdown");
+    buf.Settings.backupdir = backupDir;
+    buf.encoding = "mdcui";
+    buf.Settings.encoding = "mdcui";
+    const target = determineBackupPath(backupDir, buf.AbsPath);
+
+    expect(await writeBackup(buf, root)).toBe(false);
+    expect(await writeBackup(buf, root, buf.AbsPath, { force: true })).toBe(false);
+    expect(existsSync(target.name)).toBe(false);
+
+    await writeFile(target.name, "utf8 editor recovery");
+    let prompted = false;
+    expect(await applyBackup(buf, root, async () => { prompted = true; return "recover"; }))
+      .toEqual({ recovered: false, abort: false });
+    expect(prompted).toBe(false);
+    expect(buf.lines).toEqual(["rendered markdown"]);
+
+    removeBackup(buf, root);
+    expect(existsSync(target.name)).toBe(true);
+  });
 });

package/tests/cat-markdown.test.js

@@ -0,0 +1,79 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tui = join(import.meta.dir, "..", "tui");
+
+test("cat renders .md files once with the implicit mdcui encoding", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-cat-"));
+  const markdownPath = join(dir, "sample.md");
+  await writeFile(markdownPath, "# Heading\n\n- one\n- two\n");
+
+  try {
+    const implicit = Bun.spawnSync([tui, "-cat", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const explicit = Bun.spawnSync([tui, "-cat", "-encoding", "mdcui", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(implicit.exitCode).toBe(0);
+    expect(explicit.exitCode).toBe(0);
+    expect(implicit.stdout.toString()).toBe(explicit.stdout.toString());
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an explicit utf8 encoding overrides the .md mdcui default", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-cat-utf8-"));
+  const markdownPath = join(dir, "sample.md");
+  await writeFile(markdownPath, "# Heading\n\n```js front\nalert('kept')\n```\n");
+
+  try {
+    const result = Bun.spawnSync([tui, "-cat", "-encoding", "utf8", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(Bun.stripANSI(result.stdout.toString())).toContain("alert('kept')");
+    expect(existsSync(markdownPath + ".front.js")).toBe(false);
+    expect(existsSync(markdownPath + ".html")).toBe(false);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("--edit overrides the .md mdcui default with utf8", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-cat-edit-"));
+  const markdownPath = join(dir, "sample.md");
+  await writeFile(markdownPath, "# Heading\n\n```js front\nalert('editable')\n```\n");
+
+  try {
+    const edit = Bun.spawnSync([tui, "-cat", "--edit", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const utf8 = Bun.spawnSync([tui, "-cat", "-encoding", "utf8", markdownPath], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(edit.exitCode).toBe(0);
+    expect(edit.stdout.toString()).toBe(utf8.stdout.toString());
+    expect(Bun.stripANSI(edit.stdout.toString())).toContain("alert('editable')");
+    expect(existsSync(markdownPath + ".front.js")).toBe(false);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/tests/config-settings.test.js

@@ -0,0 +1,52 @@
+import { afterEach, 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 { Config } from "../src/config/config.js";
+
+const tempDirs = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+async function loadConfig(settings) {
+  const configDir = await mkdtemp(join(tmpdir(), "jsmdcui-config-"));
+  tempDirs.push(configDir);
+  await writeFile(join(configDir, "settings.json"), JSON.stringify(settings), "utf8");
+  return await new Config({ configDir }).init();
+}
+
+test("Config.init discards top-level encoding from settings.json in memory", async () => {
+  const config = await loadConfig({
+    encoding: "big5",
+    ruler: false,
+    "ft:markdown": { encoding: "big5", tabsize: 2 },
+  });
+
+  expect(config.getGlobalOption("encoding")).toBe("utf-8");
+  expect(config.parsedSettings).not.toHaveProperty("encoding");
+  expect(config.parsedSettings["ft:markdown"].encoding).toBe("big5");
+});
+
+test("Config.saveSettings removes the top-level encoding discarded during init", async () => {
+  const config = await loadConfig({
+    encoding: "big5",
+    ruler: false,
+    "ft:markdown": { encoding: "big5", tabsize: 2 },
+  });
+
+  await config.saveSettings();
+  const saved = JSON.parse(await readFile(join(config.configDir, "settings.json"), "utf8"));
+  expect(saved).toEqual({ ruler: false, "ft:markdown": { encoding: "big5", tabsize: 2 } });
+});
+
+test("CLI encoding applies to the current invocation but saveSettings never persists it", async () => {
+  const config = await loadConfig({ ruler: false });
+  config.applyCliSettings(new Map([["encoding", "big5"]]));
+
+  expect(config.getGlobalOption("encoding")).toBe("big5");
+  await config.saveSettings();
+  const saved = JSON.parse(await readFile(join(config.configDir, "settings.json"), "utf8"));
+  expect(saved).toEqual({ ruler: false });
+});

package/tests/demo.test.js

@@ -0,0 +1,24 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tui = join(import.meta.dir, "..", "tui");
+
+test("--demo writes bundled testapp.md to cwd before opening it", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-"));
+  try {
+    const result = Bun.spawnSync([tui, "--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("# jsmdcui");
+    expect(Bun.stripANSI(result.stdout.toString())).toContain("jsmdcui");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});