jsmdcui 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable user-visible changes to jsmdcui are documented here.
+
+## [0.3.0] - 2026-07-16
+
+Initial usable release, based on the bunmicro terminal editor.
+
+### Added
+
+- Open local Markdown files as interactive, read-only terminal interfaces while
+  retaining navigation, selection, search, copy, mouse support, and automatic
+  reflow when the terminal is resized.
+- Open HTTP(S) Markdown files in the terminal without generating local
+  companion files or executing their `javascript:` links.
+- Start a browser interface with `--wui [FILE.md]`. Browser pages support normal
+  links, clickable `javascript:` actions, heading anchors, and task checkboxes
+  that can be toggled for the current page session.
+- Build interactive Markdown apps with `js front`, `js back`, and
+  `javascript:` links. Frontend actions can use `alert`, `confirm`, `prompt`,
+  and call published backend functions through `rpc`.
+- Activate local terminal actions with `Enter`, `Space`, or a left click, with
+  visible reporting for synchronous and asynchronous frontend errors.
+- Generate five companion files beside each local Markdown source:
+  `.front.js`, `.back.js`, `.html`, `-rpc.js`, and `-server.js`.
+- Print terminal output with `--cat`, print the bundled example source with
+  `--testapp.md`, and choose a WUI port with the `PORT` environment variable.
+- Provide the `jsmdcui`, `tui`, and `wui` launchers, Bun scripts for common
+  development tasks, bundled runtime assets, and experimental single-executable
+  build commands.
+- Retain the normal bunmicro-based editor for non-Markdown buffers, including
+  file editing, syntax highlighting, search and replace, undo and redo, tabs,
+  split panes, clipboard support, themes, and shell commands.
+- Show this README as the built-in `Ctrl-G` help page.
+
+### Changed
+
+- Local `.md` files now enter read-only Markdown UI mode automatically. Starting
+  jsmdcui without a file still opens the normal terminal editor.
+- Opening or rendering a local Markdown file regenerates its five companion
+  files in terminal, `--cat`, and `--wui` modes.
+- Running `--wui` without a file uses `testapp.md` in the current directory when
+  present, otherwise the bundled demo, and writes generated files in the current
+  directory.
+- Every WUI start prints a fresh UUID-based page URL. Requests without the
+  trailing slash redirect to the canonical page URL.
+- `js front` and `js back` blocks are removed from the displayed Markdown and
+  written to their generated modules.
+
+### Fixed
+
+- Preserved Markdown ANSI colors in the terminal UI and prevented the rendered
+  document background from obscuring the editor theme.
+- Correctly detected links at the active terminal cell and loaded the matching
+  generated frontend module.
+- Restored terminal display state after `alert`, `confirm`, and `prompt`.
+- Reported frontend errors instead of letting them crash or silently fail.
+- Corrected generated module paths and imports, supported bundled runtime
+  templates, and removed redundant file generation.
+- Made JavaScript plugin commands available through command lookup and
+  completion, and added `js`, `py`, and `sh` choices for `eval` completion.
+
+### Security
+
+- Browser RPC discovery and calls expose only exported backend functions whose
+  exported names do not begin with `_`. This restriction applies to WUI RPC;
+  the local TUI imports the backend module directly.
+- WUI pages use a fresh UUID path on each start. This reduces accidental
+  discovery but is not authentication or authorization.
+- The WUI has no login or HTTPS, may be reachable through the machine's network
+  interfaces, and permits cross-origin RPC responses. Anyone who can reach it
+  and obtains the complete URL can call every backend function published by the
+  Markdown app.
+- Frontend code runs in the browser, while terminal frontend code and backend
+  code can run with the permissions of the jsmdcui process. Only open or serve
+  Markdown apps from trusted sources.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2016-2020: Zachary Yedidia, et al.
+Copyright (c) 2026 Dr. John (醫者小智)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# Introduction
+- jsmdcui stands for:
+- JavaScript Markdown Cross-environment User Interface
+- The goal is to use Markdown as a Common UI for Terminals and Web Browsers
+  * TUI = Terminal User Interface
+  * WUI = Web User Interface
+- .
+- It's based on bunmicro, a terminal text editor derived from the Micro text editor
+
+- Original projects:
+- https://github.com/jjtseng93/bunmicro
+- https://github.com/micro-editor/micro
+
+## Quick start
+
+jsmdcui requires [Bun](https://bun.com). On Android, install it in Termux:
+
+```sh
+npm install -g bun
+```
+
+On other platforms, follow the [official Bun installation guide](https://bun.com/docs/installation).
+
+Choose either of these two ways to run jsmdcui.
+
+> **Important:** Opening or rendering a local `.md` file writes or overwrites
+> five generated files beside it. Starting `--wui` without a file writes the
+> five files generated from `testapp.md` in the current directory. The source
+> Markdown is not changed, but you should run the demo in a directory where
+> overwriting generated files is safe.
+
+### Route 1: Run with npx
+
+This route requires both `npx` and `bun` on your `PATH`; no source checkout is
+required. Open the normal terminal editor:
+
+```sh
+npx jsmdcui
+```
+
+Or start the default browser demo:
+
+```sh
+npx jsmdcui --wui
+```
+
+If the current directory already contains `testapp.md`, that local file is used
+instead of the bundled demo. To open your own Markdown UI, pass its path:
+
+```sh
+npx jsmdcui app.md
+npx jsmdcui --wui app.md
+```
+
+### Route 2: Clone the source
+
+```sh
+git clone https://github.com/jjtseng93/jsmdcui.git
+cd jsmdcui
+bun src/index.js testapp.md
+```
+
+The last command opens the included demo in the terminal. Use the arrow keys to
+move, `Enter` or `Space` to activate an item, and `Ctrl-Q` to quit. To open the
+same demo in a browser instead:
+
+```sh
+bun src/index.js --wui testapp.md
+```
+
+After starting `--wui`, open the last printed `http://...` URL in a browser.
+Keep the command running while using the page, and press `Ctrl-C` in that
+terminal to stop the server.
+
+The command table below uses the cloned-source form. If you use npx, replace
+`bun src/index.js` with `npx jsmdcui`.
+
+| 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 --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 --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. |
+| `bun src/index.js` | Open the normal terminal editor with an empty buffer. |
+
+Run `npx jsmdcui --help` or `bun src/index.js --help` for all command-line
+options.
+
+## Write a Markdown UI
+
+Create `app.md`:
+
+````md
+# My app
+
+- [Say hello](javascript:sayHello())
+- [Get server time](javascript:showServerTime())
+
+```js front
+export function sayHello() {
+  const name = prompt("Your name:", "World");
+  if (name) alert(`Hello, ${name}!`);
+}
+
+export async function showServerTime() {
+  const time = await rpc.getServerTime();
+  alert(time);
+}
+```
+
+```js back
+export function getServerTime() {
+  return new Date().toISOString();
+}
+```
+````
+
+Open it in either UI:
+
+```sh
+bun src/index.js app.md
+bun src/index.js --wui app.md
+```
+
+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 `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
+  `await rpc.functionName(arg1, arg2)`.
+
+> An `_` prefix only hides a function from the browser WUI RPC interface. The
+> local terminal UI imports the backend module directly, so `_` is a naming
+> convention, not authentication or a security boundary. Use a name without
+> `_` for a function that must work through RPC in both UIs.
+
+Use a `javascript:` Markdown link to run front-end code:
+
+```md
+[Button label](javascript:exportedFunction())
+```
+
+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
+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.
+
+| Input | Result |
+| --- | --- |
+| Arrow keys, `Home`, `End`, `PageUp`, `PageDown` | Move through the rendered UI. |
+| `Enter` or `Space` | Activate the cell under the cursor. Put the cursor on a `javascript:` link to run it. |
+| Left click | Move to and activate the clicked cell. A `javascript:` link runs immediately. |
+| Mouse wheel | Scroll three rows at a time. |
+| `Shift` + arrow keys | Select rendered text. |
+| `Ctrl-C` | Copy the selection, or the current line when nothing is selected. |
+| `Ctrl-A` | Select all rendered text. |
+| `Ctrl-F` | Search; use `Ctrl-N` and `Ctrl-P` for the next and previous match. |
+| `Ctrl-G` | Open the editor help. |
+| `Alt-G` | Show or hide the shortcut bar. |
+| `Ctrl-Q` or `Alt-Q` | Close the current UI. |
+
+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.
+
+## Browser interaction
+
+The WUI uses normal browser mouse and keyboard behavior. Clicking a
+`javascript:` link calls its front-end function, regular links navigate
+normally, and task checkboxes can be toggled. `alert`, `confirm`, and `prompt`
+use the browser's built-in dialogs. Checkbox changes exist only in the current
+page: refreshing does not preserve them and does not update the Markdown file.
+
+The WUI uses port `3000` by default and accepts connections through the
+machine's available network interfaces. The printed `localhost` URL is for the
+same machine. From another device on the same network, replace `localhost` with
+the server machine's IP address and keep the same port and full path.
+
+Each server start prints a new random path. The old URL stops working after the
+server is stopped or restarted. Keep the process running while using the page,
+and press `Ctrl-C` in its terminal to stop it.
+
+## Generated files
+
+Opening a local Markdown UI generates these files beside the source file:
+
+```text
+app.md.front.js
+app.md.back.js
+app.md.html
+app.md-rpc.js
+app.md-server.js
+```
+
+They are regenerated from `app.md`, so edit the Markdown source rather than the
+generated files. The source directory must be writable.
+
+## Security
+
+A Markdown UI is an executable application, not a passive document. Starting a
+WUI loads its backend module, loading the page runs its frontend module, and
+activating a local terminal `javascript:` link runs frontend code. Backend and
+terminal code can read or change files, start programs, access the network, and
+read environment data with the permissions of the jsmdcui process. Only open
+or serve Markdown UI files that you trust.
+
+### WUI network exposure
+
+> **Warning:** The WUI is intended for local or trusted-network use. It is not
+> a production web server.
+
+- There is no login, per-user authorization, or HTTPS. Traffic and results are
+  sent over plain HTTP.
+- The server may be reachable from other devices through the machine's network
+  interfaces, even though the printed URL says `localhost`.
+- The random path makes the URL harder to guess, but it is not a password.
+  Anyone who can reach the server and obtains the complete URL can load the
+  page and call every backend function published through WUI RPC, using
+  arguments they choose.
+- A backend RPC function runs with the same operating-system permissions as
+  jsmdcui. Its code determines what files, commands, network services, or
+  secrets a visitor may be able to reach.
+- Do not share the complete URL, forward the port to the public internet, or
+  run the WUI on an untrusted network. Use a firewall when needed and stop the
+  server with `Ctrl-C` as soon as you finish.
+- Prefixing a backend export with `_` keeps it out of WUI RPC discovery and
+  calls, but it does not protect the backend module from trusted local code and
+  is not a substitute for authentication.
+
+## Development
+
+```sh
+npm run tui
+npm run wui
+npm run check
+```
+
+`testapp.md` is the main working example.
+
+                         testapp.md
+                              │
+               ┌──────────────┴──────────────┐
+               │                             │
+               ▼                             ▼
+          Browser HTML                    TUI ANSI
+               │                             │
+      javascript:foo()             extract javascript:
+               │                             │
+               ▼                             ▼
+       window.frontFunc()          evalFront(frontMod, text)
+               │                             │
+               └──────────────┬──────────────┘
+                              ▼
+                    testapp.md.front.js
+                              │
+                         rpc.someFunc()
+                  ┌───────────┴───────────┐
+                  │                       │
+               Browser                   TUI
+                  │                       │
+           RPC Proxy client       import * as rpc
+                  │               from back module
+                  ▼                       │
+              fetch rpc                   │
+                  │                       │
+                  ▼                       │
+             server.mjs                   │
+                  │                       │
+                  ▼                       │
+       evalBack(backMod, reqjson)         │
+                  │                       │
+                  └───────────┬───────────┘
+                              ▼
+                    testapp.md.back.js

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "jsmdcui",
+  "version": "0.3.0",
+  "description": "Markdown as a Common UI for Terminals and Web Browsers",
+  "type": "module",
+  "main": "./src/index.js",
+  "license": "MIT",
+  "bin": {
+    "jsmdcui": "./src/index.js"
+  },
+  "scripts": {
+    "start": "bun ./src/index.js",
+    "tui": "bun ./src/index.js ./testapp.md",
+    "wui": "bun ./runmd.mjs",
+    "check": "node --check ./src/index.js"
+  }
+}

package/project_structure.txt

@@ -0,0 +1,35 @@
+                         testapp.md
+                              │
+               ┌──────────────┴──────────────┐
+               │                             │
+               ▼                             ▼
+          Browser HTML                    TUI ANSI
+               │                             │
+      javascript:foo()             extract javascript:
+               │                             │
+               ▼                             ▼
+       window.frontFunc()          evalFront(frontMod, text)
+               │                             │
+               └──────────────┬──────────────┘
+                              ▼
+                    testapp.md.front.js
+                              │
+                         rpc.someFunc()
+                  ┌───────────┴───────────┐
+                  │                       │
+               Browser                   TUI
+                  │                       │
+           RPC Proxy client       import * as rpc
+                  │               from back module
+                  ▼                       │
+              fetch rpc                   │
+                  │                       │
+                  ▼                       │
+             server.mjs                   │
+                  │                       │
+                  ▼                       │
+       evalBack(backMod, reqjson)         │
+                  │                       │
+                  └───────────┬───────────┘
+                              ▼
+                    testapp.md.back.js

package/runmd.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env bun
+
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { readInternalAssetText } from './src/runtime/assets.js'
+import { REPO_ROOT } from './single-exe/compiled.js'
+
+const csl=console.log
+const mda=Bun.markdown.ansi
+const mdh=Bun.markdown.html
+const jss=JSON.stringify
+
+
+const TEST_ROW=9
+const TEST_COL=5
+
+
+function logWroteFile(label,path)
+{
+  csl(mda(`- Wrote to ${label} file: ${path}`))
+}
+
+async function readTemplate(pathname)
+{
+  return readInternalAssetText(pathname) ??
+         await Bun.file(path.join(REPO_ROOT, pathname)).text()
+}
+
+async function readMarkdownInput(mdpath)
+{
+  const file = Bun.file(mdpath);
+  if (await file.exists()) return await file.text();
+  const assetName = path.basename(mdpath);
+  const internalText = readInternalAssetText(assetName);
+  if (internalText != null) return internalText;
+  const fallbackPath = path.join(REPO_ROOT, assetName);
+  const fallback = Bun.file(fallbackPath);
+  if (await fallback.exists()) return await fallback.text();
+  throw new Error(`md file not found: ${mdpath}`);
+}
+
+
+export async function main(tuiWidth=30)
+{
+    const mdpath = process.argv.filter(i=>i.endsWith('.md'))[0] || 'testapp.md'
+
+
+	// 1. Read markdown file
+	console.error('Reading:',mdpath)
+	let md = await readMarkdownInput(mdpath)
+
+    // 2. Extract js files
+    md = await extractJs(md,mdpath);
+
+	// 3. Create Terminal UI
+	let tui = createTui(md,tuiWidth)
+	csl(mda("\n# TUI"))
+	csl(tui)
+	csl(mda('## TUI raw'))
+	csl(jss(tui))
+
+
+	// 4. Create Web UI
+	let wui = await createWui(md,mdpath)
+	csl(mda('\n# HTML'))
+	csl(wui)
+
+
+	// 5. Get character from point for TUI
+	let ch = charFromPoint(tui,TEST_ROW,TEST_COL)
+
+	csl(mda(
+	  '# Slicing row,col: '+TEST_ROW+','+TEST_COL
+	))
+
+	csl(jss(ch))
+
+
+    const serverPath = mdpath + "-server.js"
+    const svmod = await import(pathToFileURL(path.resolve(serverPath)).href)
+
+    csl("\n\n"+mda('# Server'))
+    svmod.main();
+}
+
+
+//  Exports
+
+
+export async function extractJs(md,mdpath)
+{
+  const mdb = path.basename(mdpath)
+
+  let sctagsp = mdpath + ".front.js"
+  let sctags = ""
+  // Gather frontend script tags
+  let reJs = /```js front[^]+?```/g  //  
+  md = md.replace( reJs,
+    i=>{
+      sctags+=i.slice(11,-3)+'\n\n'
+    
+      return '';
+      return i
+        .replace('```js front',"<scr"+"ipt>")
+        .slice(0,-3)+"</scr"+"ipt>"
+    }
+  )
+  
+  sctags = "#!/usr/bin/env bun" + `
+  
+    import { rpc as wuiRpcClient } from "./${mdb}-rpc.js";
+    let rpc = "${mdb}"
+    if(globalThis.process)
+      rpc = await import("./"+rpc+".back.js") ;
+    else
+      rpc = wuiRpcClient ;
+    
+  ` + sctags + `
+  
+    if (typeof window !== "undefined") 
+    {
+      // Browser
+      setTimeout( () => {
+        import("./${mdb}.front.js").then(mod=>{
+          Object.assign(window,mod);
+        })
+      }, 0 ) ;
+    }
+  ` ;
+  
+  await Bun.write(sctagsp,sctags);
+  logWroteFile("front", sctagsp)
+  
+  sctagsp = mdpath + ".back.js"
+  sctags = "#!/usr/bin/env bun\n\n"
+  // Gather backend script tags
+  reJs = /```js back[^]+?```/g  //  
+  md = md.replace( reJs,
+    i=>{
+      sctags+=i.slice(10,-3)+'\n\n'
+    
+      return '';
+    }
+  )
+  
+  await Bun.write(sctagsp,sctags);
+  logWroteFile("back", sctagsp)
+  
+  await writeRuntimeFiles(mdpath)
+  
+  return md
+}
+
+export async function writeRuntimeFiles(mdpath)
+{
+  const mdb = path.basename(mdpath)
+  const rpcPath = mdpath + "-rpc.js"
+  const serverPath = mdpath + "-server.js"
+  const rpcSource = await readTemplate("src/cui/rpc.mjs")
+  const serverSource = (await readTemplate("src/cui/server.mjs"))
+    .replaceAll("./rpc.mjs", `./${mdb}-rpc.js`)
+    .replaceAll("testapp.md", mdb)
+
+  await Bun.write(rpcPath, rpcSource)
+  logWroteFile("rpc", rpcPath)
+  await Bun.write(serverPath, serverSource)
+  logWroteFile("server", serverPath)
+
+  return serverPath
+}
+
+
+export function createTui(md,TERMINAL_WIDTH=30) // ANSI Colors
+{
+  md = (  Bun?.markdown?.ansi?.(
+            md,{
+              hyperlinks:true,
+              columns:TERMINAL_WIDTH
+            }
+          )
+       || md  )+'' ;
+       
+  return md ;
+       
+  return Bun.wrapAnsi(
+    md,
+    TERMINAL_WIDTH
+  )
+}
+
+export async function createWui(md,mdpath) // HTML
+{
+  
+  const opts = {
+    headings: { ids: true }
+  }
+  
+  md = (Bun?.markdown?.html?.(md,opts) || md)+'' ;
+  
+  // Restore single quotes
+  let reHrefs = /href="[^"]*?"/g  //  "
+  md = md.replace( reHrefs,
+    i=>i.replaceAll('&#x27;',"'")
+  )
+  
+  
+  md = md.replaceAll(
+    'class="task-list-item-checkbox" disabled',
+    'class="task-list-item-checkbox"'
+  )
+  
+  const mdb = path.basename(mdpath);
+  
+  
+  md += `
+
+<scr`+`ipt type="module" src="./${mdb}.front.js">
+</scr`+`ipt>
+
+  `;
+  
+  
+  await Bun.write(mdpath+".html",md)
+  logWroteFile("html", mdpath+".html")
+
+  return md;
+}
+
+export function charFromPoint(tui,row,col)
+{
+  tui = tui.split('\n')[row-1] || ""
+  return Bun.sliceAnsi(tui,col-1,col)
+}
+
+
+if(import.meta.main)
+  main().catch(e=>{
+    console.error(e?.message || e)
+    process.exit(127)
+  });