jsmdcui 0.3.0

package/runtime/help/copypaste.md

@@ -0,0 +1,149 @@
+Copy and paste are essential features in micro but can be
+confusing to get right especially when running micro over SSH
+because there are multiple methods. This help document will explain
+the various methods for copying and pasting, how they work,
+and the best methods for doing so over SSH.
+
+# OSC 52 (terminal clipboard)
+
+If possible, setting the `clipboard` option to `terminal` will give
+best results because it will work over SSH and locally. However, there
+is limited support among terminal emulators for the terminal clipboard
+(which uses the OSC 52 protocol to communicate clipboard contents).
+Here is a list of terminal emulators and their status:
+
+* `Kitty`: supported, but only writing is enabled by default. To enable
+   reading, add `read-primary` and `read-clipboard` to the
+   `clipboard_control` option.
+
+* `iTerm2`: only copying (writing to clipboard) is supported. Must be enabled in
+   `Preferences->General-> Selection->Applications in terminal may access clipboard`.
+   You can use `Command-v` to paste.
+
+* `st`: supported.
+
+* `rxvt-unicode`: not natively supported, but there is a Perl extension
+   [here](https://anti.teamidiot.de/static/nei/*/Code/urxvt/).
+
+* `xterm`: supported, but disabled by default. It can be enabled by putting
+   the following in `.Xresources` or `.Xdefaults`:
+   `XTerm*disallowedWindowOps: 20,21,SetXprop`.
+
+* `gnome-terminal`: does not support OSC 52.
+
+* `alacritty`: supported. Since 0.13.0, reading has been disabled by default.
+   To reenable it, set the `terminal.osc52` option to `CopyPaste`.
+
+* `foot`: supported.
+
+* `wezterm`: only copying (writing to clipboard) is supported.
+
+
+**Summary:** If you want copy and paste to work over SSH, then you
+should set `clipboard` to `terminal`, and make sure your terminal
+supports OSC 52.
+
+# Pasting
+
+## Recommendations (TL;DR)
+
+The recommended method of pasting is the following:
+
+* If you are not working over SSH, use the micro keybinding (`Ctrl-v`
+  by default) to perform pastes. If on Linux, install `xclip` or
+  `xsel` beforehand.
+
+* If you are working over SSH, use the terminal keybinding
+  (`Ctrl-Shift-v` or `Command-v`) to perform pastes. If your terminal
+  does not support bracketed paste, when performing a paste first
+  enable the `paste` option, and when finished disable the option.
+
+## Micro paste events
+
+Micro is an application that runs within the terminal. This means
+that the terminal sends micro events, such as key events, mouse
+events, resize events, and paste events. Micro's default keybinding
+for paste is `Ctrl-v`. This means that when micro receives the key
+event saying `Ctrl-v` has been pressed from the terminal, it will
+attempt to access the system clipboard and effect a paste. The
+system clipboard will be accessed through `pbpaste` on MacOS
+(installed by default), `xclip` or `xsel` on Linux (these
+applications must be installed by the user) or a system call on
+Windows.
+
+## Terminal paste events
+
+For certain keypresses, the terminal will not send an event to
+micro and will instead do something itself. In this document,
+such keypresses will be called "terminal keybindings." Often
+there will be a terminal keybinding for pasting and copying. On
+MacOS these are Command-v and Command-c and on Linux `Ctrl-Shift-v`
+and `Ctrl-Shift-c`. When the terminal keybinding for paste is
+executed, your terminal will access the system clipboard, and send
+micro either a paste event or a list of key events (one key for each
+character in the paste), depending on whether or not your terminal
+supports sending paste events (called bracketed paste).
+
+If your terminal supports bracketed paste, then it will send a paste
+event and everything will work well. However, if your terminal
+sends a list of key events, this can cause issues because micro
+will think you manually entered each character and may add closing
+brackets or automatic indentation, which will mess up the pasted
+text. To avoid this, you can temporarily enable the `paste` option
+while you perform the paste. When paste option is on, micro will
+aggregate lists of multiple key events into larger paste events.
+It is a good idea to disable the `paste` option during normal use
+as occasionally if you are typing quickly, the terminal will send
+the key events as lists of characters that were in fact manually
+entered.
+
+## Pasting over SSH
+
+When working over SSH, micro is running on the remote machine and
+your terminal is running on your local machine. Therefore if you
+would like to paste, using `Ctrl-v` (micro's keybinding) will not
+work because when micro attempts to access the system clipboard,
+it will access the remote machine's clipboard rather than the local
+machine's clipboard. On the other hand, the terminal keybinding
+for paste will access your local clipboard and send the text over
+the network as a paste event, which is what you want.
+
+# Copying
+
+# Recommendations (TL;DR)
+
+The recommended method of copying is the following:
+
+* If you are not working over SSH, use the micro keybinding (`Ctrl-c` by
+  default) to perform copies. If on Linux, install `xclip` or `xsel`
+  beforehand.
+
+* If you are working over SSH, use the terminal keybinding
+  (`Ctrl-Shift-c` or `Command-c`) to perform copies. You must first disable
+  the `mouse` option to perform a terminal selection, and you may wish
+  to disable line numbers and diff indicators (`ruler` and `diffgutter`
+  options) and close other splits. This method will only be able to copy
+  characters that are displayed on the screen (you will not be able to
+  copy more than one page's worth of characters).
+
+Copying follows a similar discussion to the one above about pasting.
+The primary difference is before performing a copy, the application
+doing the copy must be told what text needs to be copied.
+
+Micro has a keybinding (`Ctrl-c`) for copying and will access the system
+clipboard to perform the copy. The text that micro will copy into is
+the text that is currently selected in micro (usually such text is
+displayed with a white background). When the `mouse` option is enabled,
+the mouse can be used to select text, as well as other keybindings,
+such as ShiftLeft, etc...
+
+The terminal also has a keybinding (`Ctrl-Shift-c` or `Command-c`) to perform
+a copy, and the text that it copies is the text selected by the terminal's
+selection (*not* micro's selection). To select text with the terminal
+selection, micro's mouse support must first be disabled by turning the
+`mouse` option off. The terminal, unlike micro, has no sense of different
+buffers/splits and what the different characters being displayed are. This
+means that for copying multiple lines using the terminal selection, you
+should first disable line numbers and diff indicators (turn off the `ruler`
+and `diffgutter` options), otherwise they might be part of your selection
+and copied.

package/runtime/help/defaultkeys.md

@@ -0,0 +1,148 @@
+# Default Keys
+
+Below are simple charts of the default hotkeys and their functions. For more
+information about binding custom hotkeys or changing default bindings, please
+run `> help keybindings`
+
+Please remember that *all* keys here are rebindable! If you don't like it, you
+can change it!
+
+### Power user
+
+| Key       | Description of function                                                                           |
+|---------- |-------------------------------------------------------------------------------------------------- |
+| Ctrl-e    | Open a command prompt for running commands (see `> help commands` for a list of valid commands).  |
+| Tab       | In command prompt, it will autocomplete if possible.                                              |
+| Ctrl-b    | Run a shell command (this will close micro while your command executes).                          |
+
+### Navigation
+
+| Key                         | Description of function                                                                   |
+|---------------------------- |------------------------------------------------------------------------------------------ |
+| Arrows                      | Move the cursor around                                                                    |
+| Shift-arrows                | Move and select text                                                                      |
+| Alt(Ctrl on Mac)-LeftArrow  | Move to the beginning of the current line                                                 |
+| Alt(Ctrl on Mac)-RightArrow | Move to the end of the current line                                                       |
+| Home                        | Move to the beginning of text on the current line                                         |
+| End                         | Move to the end of the current line                                                       |
+| Ctrl(Alt on Mac)-LeftArrow  | Move cursor one word left                                                                 |
+| Ctrl(Alt on Mac)-RightArrow | Move cursor one word right                                                                |
+| Alt-{                       | Move cursor to previous empty line, or beginning of document                              |
+| Alt-}                       | Move cursor to next empty line, or end of document                                        |
+| PageUp                      | Move cursor up one page                                                                   |
+| PageDown                    | Move cursor down one page                                                                 |
+| Ctrl-Home or Ctrl-UpArrow   | Move cursor to start of document                                                          |
+| Ctrl-End or Ctrl-DownArrow  | Move cursor to end of document                                                            |
+| Ctrl-l                      | Jump to a line in the file (prompts with #)                                               |
+| Ctrl-w                      | Cycle between splits in the current tab (use `> vsplit` or `> hsplit` to create a split)  |
+
+### Tabs
+
+| Key          | Description of function   |
+|------------- |-------------------------- |
+| Ctrl-t       | Open a new tab            |
+| Alt-, Alt-p  | Previous tab              |
+| Alt-. Alt-t  | Next tab                  |
+
+### Find Operations
+
+| Key       | Description of function                   |
+|---------- |------------------------------------------ |
+| Ctrl-f    | Find (opens prompt)                       |
+| Ctrl-n    | Find next instance of current search      |
+| Ctrl-p    | Find previous instance of current search  |
+
+| Alt-h     | Open command prompt to replace keywords   |
+
+Note: `Ctrl-n` and `Ctrl-p` should be used from the main buffer, not from inside
+the search prompt. After `Ctrl-f`, press enter to complete the search and then
+you can use `Ctrl-n` and `Ctrl-p` to cycle through matches.
+
+### File Operations
+
+| Key           | Description of function                                           |
+|-------------- |------------------------------------------------------------------ |
+| Ctrl-q Alt-q  | Close current file (quits micro if this is the last file open)    |
+| Ctrl-o        | Open a file (prompts for filename)                                |
+| Ctrl-s        | Save current file                                                 |
+
+### Text operations
+
+| Key                                 | Description of function                   |
+|------------------------------------ |------------------------------------------ |
+| Ctrl(Alt on Mac)-Shift-RightArrow   | Select word right                         |
+| Ctrl(Alt on Mac)-Shift-LeftArrow    | Select word left                          |
+| Alt(Ctrl on Mac)-Shift-LeftArrow    | Select to start of current line           |
+| Alt(Ctrl on Mac)-Shift-RightArrow   | Select to end of current line             |
+| Shift-Home                          | Select to start of current line           |
+| Shift-End                           | Select to end of current line             |
+| Ctrl-Shift-UpArrow                  | Select to start of file                   |
+| Ctrl-Shift-DownArrow                | Select to end of file                     |
+| Ctrl-x                              | Cut selected text                         |
+| Ctrl-c                              | Copy selected text                        |
+| Ctrl-v                              | Paste                                     |
+| Ctrl-k                              | Cut current line                          |
+| Ctrl-d                              | Duplicate current line                    |
+| Ctrl-z                              | Undo                                      |
+| Ctrl-y                              | Redo                                      |
+| Alt-UpArrow Alt-k                   | Move current line or selected lines up    |
+| Alt-DownArrow Alt-j                 | Move current line or selected lines down  |
+| Alt-Backspace or Alt-Ctrl-h         | Delete word left                          |
+| Ctrl-a                              | Select all                                |
+| Alt-s                               | Enter Selection mode                      |
+| Alt-c                               | Toggle comment for lines                  |
+| Tab                                 | Indent selected text                      |
+| Alt-d                               | Dedent selected text                      |
+| Shift-Tab                           | Unindent selected text                    |
+
+### Macros(not implemented yet)
+
+| Key       | Description of function                                                           |
+|---------- |---------------------------------------------------------------------------------- |
+| Ctrl-u    | Toggle macro recording (press Ctrl-u to start recording and press again to stop)  |
+| Ctrl-j    | Run latest recorded macro                                                         |
+
+### Multiple cursors(not implemented yet)
+
+| Key               | Description of function                                                                       |
+|------------------ |---------------------------------------------------------------------------------------------- |
+| Alt-n             | Create new multiple cursor from selection (will select current word if no current selection)  |
+| Alt-Shift-Up      | Spawn a new cursor on the line above the current one                                          |
+| Alt-Shift-Down    | Spawn a new cursor on the line below the current one                                          |
+| Alt-p             | Remove latest multiple cursor                                                                 |
+| Alt-c             | Remove all multiple cursors (cancel)                                                          |
+| Alt-x             | Skip multiple cursor selection                                                                |
+| Alt-m             | Spawn a new cursor at the beginning of every line in the current selection                    |
+| Ctrl-MouseLeft    | Place a multiple cursor at any location                                                       |
+
+### Other
+
+| Key       | Description of function                                                               |
+|---------- |-------------------------------------------------------------------------------------- |
+| Ctrl-g    | Open help file                                                                        |
+| Ctrl-h    | Backspace (old terminals do not support the backspace key and use Ctrl+H instead)     |
+| Ctrl-r    | Toggle the line number ruler                                                          |
+
+### Emacs style actions
+- not implemented yet
+
+| Key       | Description of function   |
+|---------- |-------------------------- |
+| Alt-f     | Next word                 |
+| Alt-b     | Previous word             |
+| Alt-a     | Move to start of line     |
+| Alt-e     | Move to end of line       |
+
+### Function keys.
+- not implemented yet
+
+Warning! The function keys may not work in all terminals!
+
+| Key   | Description of function   |
+|------ |-------------------------- |
+| F1    | Open help                 |
+| F2    | Save                      |
+| F3    | Find                      |
+| F4    | Quit                      |
+| F7    | Find                      |
+| F10   | Quit                      |

package/runtime/help/help.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