jsmdcui 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,143 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.5.0] - 2026-07-16
+
+This update adds cross-environment form-like text blocks and a small
+jQuery-style selector API, while keeping the same Markdown source usable in
+both the terminal and browser interfaces.
+
+### Added
+
+- Add a minimal global `$` API to terminal frontend evaluation, JavaScript
+  plugins, generated browser frontend modules, and `javascript:` links.
+- Support tag, ID, class, and combined selectors such as `$('text')`,
+  `$('#answer')`, `$('.field')`, and `$('text#answer.field')`.
+- Add `.val()` and `.val(value)` for reading and replacing block contents.
+  Getters always return a string and use an empty string for missing elements,
+  invalid selectors, or lookup errors. Setters support chaining and resize
+  terminal blocks to fit multiline values.
+- Recognize both raw Markdown fenced blocks and rendered Bun ANSI blocks,
+  including ASCII and Unicode frame characters.
+- Add editable terminal `text` blocks. Content after the protected `│ ` or
+  `| ` prefix can be edited, while frame characters, line joins, inserted
+  newlines, and multiline pastes remain protected.
+- Add interactive terminal text-block resizing. Activating the lower-left
+  frame corner adds an empty content row; activating the upper-left corner
+  removes only a trailing empty row and never deletes non-empty content.
+- Add the optional frontend lifecycle callback
+  `onMdcuiExit({ reason, path, $ })`. The terminal awaits it before closing an
+  mdcui buffer and invokes it at most once per buffer.
+- Add Markdown syntax completions for fenced block language identifiers.
+
+### Changed
+
+- Convert `text` and `textarea` fenced blocks into native browser
+  `<textarea>` elements while preserving their ID, classes, original language
+  metadata, and selector compatibility.
+- Prefer native `document.querySelector()` in the browser `$` implementation,
+  then fall back to mdcui metadata and the original `pre > code` structure.
+- Automatically wrap and resize generated browser textareas on page load,
+  input, `.val(value)`, and window resize. Initial `rows` and `cols` are
+  derived from the Markdown content.
+- Generate complete HTML5 documents for WUI output, including `<!doctype
+  html>`, UTF-8 metadata, a responsive viewport, a document title, and
+  `lang="zh-TW"`.
+- Enable `softwrap` by default.
+- Close modified mdcui buffers without displaying a save prompt. Applications
+  can use `onMdcuiExit` to collect edited field values or call backend RPC
+  functions before closing.
+- Update the bundled example with editable text fields, selector API examples,
+  answer validation, and manual text-box resizing instructions.
+
+### Fixed
+
+- Keep terminal text-block frame prefixes intact during editing and prevent
+  Delete at the end of a content row from merging it with the next row.
+- Preserve browser textarea IDs and classes during Markdown-to-HTML
+  conversion, including compatibility metadata for original `text` selectors.
+- Keep README and built-in help lifecycle documentation synchronized.
+
+## [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. |
@@ -97,6 +100,11 @@ Create `app.md`:
 
 - [Say hello](javascript:sayHello())
 - [Get server time](javascript:showServerTime())
+- [Update text box](javascript:updateText())
+
+```text#myid.myclass
+Editable in both TUI and WUI
+```
 
 ```js front
 export function sayHello() {
@@ -108,6 +116,10 @@ export async function showServerTime() {
   const time = await rpc.getServerTime();
   alert(time);
 }
+
+export function updateText() {
+  $('#myid').val($('.myclass').val() + ' ✓');
+}
 ```
 
 ```js back
@@ -124,12 +136,37 @@ bun src/index.js app.md
 bun src/index.js --wui app.md
 ```
 
+### Text blocks
+
+Both `text` and `textarea` fenced blocks define editable text fields:
+
+````md
+```text#message.note
+Initial value
+```
+````
+
+The same Markdown works in both interfaces. In the browser WUI it becomes a
+native `<textarea>` with the declared ID and classes. Long text wraps
+automatically, and the field height is recalculated when the user types, the
+window is resized, or frontend code calls `.val(value)`.
+
+In the terminal TUI, only content after the protected `│ ` or `| ` prefix can
+be edited. The frame prefix cannot be deleted, Enter cannot insert a newline,
+Delete at the end of a row cannot join the next row, and multiline paste is
+blocked. Activate the lower-left frame corner to add a row. Activate the
+upper-left frame corner to remove the trailing row only when it is empty;
+non-empty content is never removed.
+
 The three UI building blocks are:
 
 - Regular Markdown provides headings, text, lists, task checkboxes, code, and
   links.
 - A `js front` block contains UI code. Exported functions can use
   `alert`, `confirm`, `prompt`, and the generated `rpc` client.
+- A front module may export `async function onMdcuiExit({ reason, path, $ })`.
+  The terminal UI awaits it before closing an `mdcui` buffer. Modified
+  `mdcui` buffers close without a save prompt.
 - A `js back` block exports trusted backend functions. In the browser WUI,
   `rpc` publishes only exported functions whose exported names do not start
   with `_`. Call a published function from the front end with
@@ -146,6 +183,22 @@ Use a `javascript:` Markdown link to run front-end code:
 [Button label](javascript:exportedFunction())
 ```
 
+Use `onMdcuiExit` when a terminal Markdown app needs to submit or otherwise
+process edited fields before it closes:
+
+```js
+export async function onMdcuiExit({ reason, path, $ }) {
+  await rpc.saveDraft({
+    reason,
+    path,
+    message: $('#message').val(),
+  });
+}
+```
+
+The callback is optional, may be asynchronous, and is called at most once for
+each mdcui buffer.
+
 The front and back code blocks are extracted and are not shown in the rendered
 UI. In the terminal, `rpc` calls the generated backend module directly. In the
 browser, it sends the call to the relative `rpc` endpoint under the printed
@@ -153,8 +206,9 @@ UUID URL (`/<uuid>/rpc`).
 
 ## Terminal interaction
 
-Markdown files automatically use `mdcui` mode. The rendered buffer is
-read-only, but navigation, selection, search, and copy remain available.
+Markdown files automatically use `mdcui` mode. Most rendered content remains
+protected, while `text` block content rows can be edited. Navigation,
+selection, search, and copy remain available.
 
 | Input | Result |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.3.0",
+  "version": "0.5.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}`))
 }
 
@@ -188,6 +189,54 @@ export function createTui(md,TERMINAL_WIDTH=30) // ANSI Colors
   )
 }
 
+function parseWuiControlIdentity(info)
+{
+  const match = String(info ?? "").match(/^([A-Za-z_][\w:-]*)(?:#([A-Za-z_][\w:-]*))?((?:\.[A-Za-z_][\w:-]*)*)$/);
+  if (!match || !["text", "textarea"].includes(match[1])) return null;
+  return {
+    tag: match[1],
+    id: match[2] || "",
+    classes: match[3] ? match[3].slice(1).split(".") : [],
+  };
+}
+
+function escapeHtmlAttribute(value)
+{
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll('"', """)
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+export function convertWuiTextareas(html)
+{
+  return String(html).replace(
+    /<pre><code class="language-([^"]+)">([^]*?)<\/code><\/pre>/g,
+    (whole, info, content) => {
+      const identity = parseWuiControlIdentity(info);
+      if (!identity) return whole;
+      const value = content.replace(/\n$/, "");
+      const contentLines = value.split("\n");
+      const cols = Math.max(1, ...contentLines.map(line => [...line].length));
+      const attrs = [
+        `data-mdcui-tag="${identity.tag}"`,
+        `data-mdcui-language="${escapeHtmlAttribute(info)}"`,
+        identity.id ? `id="${escapeHtmlAttribute(identity.id)}"` : "",
+        `class="${escapeHtmlAttribute([
+          `language-${info}`,
+          ...identity.classes,
+        ].join(" "))}"`,
+        `rows="${Math.max(1, contentLines.length)}"`,
+        `cols="${cols}"`,
+        'wrap="soft"',
+        'style="box-sizing:border-box;max-width:100%;width:100%;resize:vertical;overflow-y:hidden"',
+      ].filter(Boolean).join(" ");
+      return `<textarea ${attrs}>${value}</textarea>`;
+    },
+  );
+}
+
 export async function createWui(md,mdpath) // HTML
 {
   
@@ -208,16 +257,31 @@ export async function createWui(md,mdpath) // HTML
     'class="task-list-item-checkbox" disabled',
     'class="task-list-item-checkbox"'
   )
+
+  md = convertWuiTextareas(md)
   
   const mdb = path.basename(mdpath);
   
-  
-  md += `
-
-<scr`+`ipt type="module" src="./${mdb}.front.js">
-</scr`+`ipt>
-
-  `;
+  const moduleScript = `<scr`+`ipt type="module" src="./${mdb}.front.js"></scr`+`ipt>`;
+  if (!/^\s*<!doctype html>/i.test(md)) {
+    md = `<!doctype html>
+<html lang="zh-TW">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtmlAttribute(mdb)}</title>
+</head>
+<body>
+${md}
+${moduleScript}
+</body>
+</html>
+`;
+  } else if (/<\/body\s*>/i.test(md)) {
+    md = md.replace(/<\/body\s*>/i, `${moduleScript}\n</body>`);
+  } else {
+    md += `\n${moduleScript}\n`;
+  }
   
   
   await Bun.write(mdpath+".html",md)

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. |
@@ -97,6 +100,11 @@ Create `app.md`:
 
 - [Say hello](javascript:sayHello())
 - [Get server time](javascript:showServerTime())
+- [Update text box](javascript:updateText())
+
+```text#myid.myclass
+Editable in both TUI and WUI
+```
 
 ```js front
 export function sayHello() {
@@ -108,6 +116,10 @@ export async function showServerTime() {
   const time = await rpc.getServerTime();
   alert(time);
 }
+
+export function updateText() {
+  $('#myid').val($('.myclass').val() + ' ✓');
+}
 ```
 
 ```js back
@@ -124,12 +136,37 @@ bun src/index.js app.md
 bun src/index.js --wui app.md
 ```
 
+### Text blocks
+
+Both `text` and `textarea` fenced blocks define editable text fields:
+
+````md
+```text#message.note
+Initial value
+```
+````
+
+The same Markdown works in both interfaces. In the browser WUI it becomes a
+native `<textarea>` with the declared ID and classes. Long text wraps
+automatically, and the field height is recalculated when the user types, the
+window is resized, or frontend code calls `.val(value)`.
+
+In the terminal TUI, only content after the protected `│ ` or `| ` prefix can
+be edited. The frame prefix cannot be deleted, Enter cannot insert a newline,
+Delete at the end of a row cannot join the next row, and multiline paste is
+blocked. Activate the lower-left frame corner to add a row. Activate the
+upper-left frame corner to remove the trailing row only when it is empty;
+non-empty content is never removed.
+
 The three UI building blocks are:
 
 - Regular Markdown provides headings, text, lists, task checkboxes, code, and
   links.
 - A `js front` block contains UI code. Exported functions can use
   `alert`, `confirm`, `prompt`, and the generated `rpc` client.
+- A front module may export `async function onMdcuiExit({ reason, path, $ })`.
+  The terminal UI awaits it before closing an `mdcui` buffer. Modified
+  `mdcui` buffers close without a save prompt.
 - A `js back` block exports trusted backend functions. In the browser WUI,
   `rpc` publishes only exported functions whose exported names do not start
   with `_`. Call a published function from the front end with
@@ -146,6 +183,22 @@ Use a `javascript:` Markdown link to run front-end code:
 [Button label](javascript:exportedFunction())
 ```
 
+Use `onMdcuiExit` when a terminal Markdown app needs to submit or otherwise
+process edited fields before it closes:
+
+```js
+export async function onMdcuiExit({ reason, path, $ }) {
+  await rpc.saveDraft({
+    reason,
+    path,
+    message: $('#message').val(),
+  });
+}
+```
+
+The callback is optional, may be asynchronous, and is called at most once for
+each mdcui buffer.
+
 The front and back code blocks are extracted and are not shown in the rendered
 UI. In the terminal, `rpc` calls the generated backend module directly. In the
 browser, it sends the call to the relative `rpc` endpoint under the printed
@@ -153,8 +206,9 @@ UUID URL (`/<uuid>/rpc`).
 
 ## Terminal interaction
 
-Markdown files automatically use `mdcui` mode. The rendered buffer is
-read-only, but navigation, selection, search, and copy remain available.
+Markdown files automatically use `mdcui` mode. Most rendered content remains
+protected, while `text` block content rows can be edited. Navigation,
+selection, search, and copy remain available.
 
 | Input | Result |
 | --- | --- |

package/runtime/syntax/markdown.yaml

@@ -47,3 +47,15 @@ rules:
         start: "`"
         end: "`"
         rules: []
+
+
+# keywords
+# javascript alert confirm prompt rpc 
+# front back 
+# console log error JSON stringify parse
+# async await Promise 
+# textarea text password search 
+# email url tel number range color
+# date time datetime-local month week 
+# checkbox radio file hidden image button submit reset
+

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

@@ -38,7 +38,7 @@ export const DEFAULT_COMMON_SETTINGS = {
   scrollspeed: 2,
   showchars: "",
   smartpaste: true,
-  softwrap: false,
+  softwrap: true,
   splitbottom: true,
   splitright: true,
   statusformatl: "$(filename) $(modified)$(overwrite)($(line),$(col)) $(status.paste)| ft:$(opt:filetype) | $(opt:fileformat) | $(opt:encoding)",
@@ -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 };