jsmdcui 0.5.0 → 0.7.0

package/runmd.mjs

@@ -6,6 +6,7 @@ import { readInternalAssetText } from './src/runtime/assets.js'
 import { REPO_ROOT } from './single-exe/compiled.js'
 
 const csl=console.log
+const cse=console.error
 const mda=Bun.markdown.ansi
 const mdh=Bun.markdown.html
 const jss=JSON.stringify
@@ -18,7 +19,7 @@ const TEST_COL=5
 function logWroteFile(label,path)
 {
   if(!process.stdin.isRaw)
-  csl(mda(`- Wrote to ${label} file: ${path}`))
+  cse(mda(`- Wrote to ${label} file: ${path}`))
 }
 
 async function readTemplate(pathname)
@@ -27,16 +28,23 @@ async function readTemplate(pathname)
          await Bun.file(path.join(REPO_ROOT, pathname)).text()
 }
 
-async function readMarkdownInput(mdpath)
+export 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;
+  if (internalText != null) {
+    await Bun.write(mdpath, internalText);
+    return internalText;
+  }
   const fallbackPath = path.join(REPO_ROOT, assetName);
   const fallback = Bun.file(fallbackPath);
-  if (await fallback.exists()) return await fallback.text();
+  if (await fallback.exists()) {
+    const fallbackText = await fallback.text();
+    await Bun.write(mdpath, fallbackText);
+    return fallbackText;
+  }
   throw new Error(`md file not found: ${mdpath}`);
 }
 
@@ -55,32 +63,35 @@ export async function main(tuiWidth=30)
 
 	// 3. Create Terminal UI
 	let tui = createTui(md,tuiWidth)
-	csl(mda("\n# TUI"))
-	csl(tui)
-	csl(mda('## TUI raw'))
-	csl(jss(tui))
+	cse(mda("\n# TUI"))
+	cse(tui)
+	cse(mda('## TUI raw'))
+	cse(jss(tui))
 
 
 	// 4. Create Web UI
 	let wui = await createWui(md,mdpath)
-	csl(mda('\n# HTML'))
-	csl(wui)
+	cse(mda('\n# HTML'))
+	cse(wui)
 
 
+    /*
 	// 5. Get character from point for TUI
 	let ch = charFromPoint(tui,TEST_ROW,TEST_COL)
 
-	csl(mda(
+	cse(mda(
 	  '# Slicing row,col: '+TEST_ROW+','+TEST_COL
 	))
 
-	csl(jss(ch))
+	cse(jss(ch))
+	
+	*/
 
 
     const serverPath = mdpath + "-server.js"
     const svmod = await import(pathToFileURL(path.resolve(serverPath)).href)
 
-    csl("\n\n"+mda('# Server'))
+    cse("\n\n"+mda('# Server'))
     svmod.main();
 }
 
@@ -237,6 +248,62 @@ export function convertWuiTextareas(html)
   );
 }
 
+export function wrapWuiHeadingSections(html)
+{
+  const input = String(html);
+  const bodyStart = input.match(/<body\b[^>]*>/i);
+  if (bodyStart?.index != null) {
+    const contentStart = bodyStart.index + bodyStart[0].length;
+    const bodyEnd = input.slice(contentStart).search(/<\/body\s*>/i);
+    if (bodyEnd >= 0) {
+      const contentEnd = contentStart + bodyEnd;
+      return input.slice(0, contentStart) +
+        wrapWuiHeadingSections(input.slice(contentStart, contentEnd)) +
+        input.slice(contentEnd);
+    }
+  }
+
+  let markerPrefix = "MDCUI_HEADING_OPAQUE_";
+  while (input.includes(markerPrefix)) markerPrefix = "_" + markerPrefix;
+  const opaqueHtml = [];
+  const searchable = input.replace(
+    /<!--[^]*?-->|<(script|style|pre|code|textarea|template)\b[^>]*>[^]*?<\/\1\s*>/gi,
+    (whole) => {
+      const marker = `\0${markerPrefix}${opaqueHtml.length}\0`;
+      opaqueHtml.push({ marker, html: whole });
+      return marker;
+    }
+  );
+
+  const heading = /<h([1-6])\b[^>]*>[^]*?<\/h\1\s*>/gi;
+  const openLevels = [];
+  let output = "";
+  let cursor = 0;
+  let match;
+
+  while ((match = heading.exec(searchable)) !== null) {
+    const level = Number(match[1]);
+    output += searchable.slice(cursor, match.index);
+    while (openLevels.length && openLevels.at(-1) >= level) {
+      output += "</section>\n";
+      openLevels.pop();
+    }
+    output += `<section>\n${match[0]}`;
+    openLevels.push(level);
+    cursor = heading.lastIndex;
+  }
+
+  output += searchable.slice(cursor);
+  while (openLevels.length) {
+    output += "</section>\n";
+    openLevels.pop();
+  }
+  for (const opaque of opaqueHtml) {
+    output = output.replace(opaque.marker, opaque.html);
+  }
+  return output;
+}
+
 export async function createWui(md,mdpath) // HTML
 {
   
@@ -258,18 +325,37 @@ export async function createWui(md,mdpath) // HTML
     'class="task-list-item-checkbox"'
   )
 
+  const taskItemStart = '(<li\\b(?=[^>]*\\bclass="[^"]*\\btask-list-item\\b[^"]*")[^>]*>\\s*)'
+  const taskCheckbox = '(<input\\b(?=[^>]*\\btype="checkbox")[^>]*>)'
+  md = md.replace(
+    new RegExp(taskItemStart + taskCheckbox + '([^<]*(?:<p>[^]*?<\\/p>[^<]*)*)', 'g'),
+    (whole, itemStart, checkbox, content) => {
+      if (!content.trim()) return whole
+      return `${itemStart}<label>${checkbox}${content}</label>`
+    }
+  )
+
   md = convertWuiTextareas(md)
+  md = wrapWuiHeadingSections(md)
   
   const mdb = path.basename(mdpath);
   
+  const responsiveImageStyle = `<style>
+img {
+  max-width: 100%;
+  height: auto;
+}
+</style>`;
   const moduleScript = `<scr`+`ipt type="module" src="./${mdb}.front.js"></scr`+`ipt>`;
-  if (!/^\s*<!doctype html>/i.test(md)) {
+  const isFullHtmlDocument = /^\s*<!doctype html>/i.test(md);
+  if (!isFullHtmlDocument) {
     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>
+  ${responsiveImageStyle}
 </head>
 <body>
 ${md}
@@ -277,10 +363,17 @@ ${moduleScript}
 </body>
 </html>
 `;
-  } else if (/<\/body\s*>/i.test(md)) {
-    md = md.replace(/<\/body\s*>/i, `${moduleScript}\n</body>`);
   } else {
-    md += `\n${moduleScript}\n`;
+    if (/<\/head\s*>/i.test(md)) {
+      md = md.replace(/<\/head\s*>/i, `${responsiveImageStyle}\n</head>`);
+    } else {
+      md = `${responsiveImageStyle}\n${md}`;
+    }
+    if (/<\/body\s*>/i.test(md)) {
+      md = md.replace(/<\/body\s*>/i, `${moduleScript}\n</body>`);
+    } else {
+      md += `\n${moduleScript}\n`;
+    }
   }
   
   

package/runtime/help/help.md

@@ -1,3 +1,20 @@
+![Demo](https://raw.githubusercontent.com/jjtseng93/jsmdcui/main/demo.jpg)
+
+# Demo App
+## My app
+
+- [Say hello](javascript:sayHello())
+- [Get server time](javascript:showServerTime())
+- [Update text box](javascript:updateText())
+- [Show selected](javascript:alert(JSON.stringify($('#my-app').val())))
+- [x] task1
+- [x] task2
+- [ ] unselected task
+
+```text#myid.myclass
+Editable in both TUI and WUI
+```
+
 # Introduction
 - jsmdcui stands for:
 - JavaScript Markdown Cross-environment User Interface
@@ -10,6 +27,12 @@
 - Original projects:
 - https://github.com/jjtseng93/bunmicro
 - https://github.com/micro-editor/micro
+- .
+- This README is itself a runnable app.
+
+```sh
+npx jsmdcui@latest README.md
+```
 
 ## Quick start
 
@@ -24,28 +47,54 @@ On other platforms, follow the [official Bun installation guide](https://bun.com
 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
+> 5 generated files beside it. 
+> Starting `--wui` without a file or starting all the `--demo`s writes the
+> 5 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:
+- 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:
+#### Start `testapp.md` as the TUI/WUI demo
+- If `testapp.md` is missing, the bundled copy is written to the current working directory
+- If `testapp.md` already exists, it will be used and won't be overwritten.
+
+```sh
+# TUI(Terminal User Interface) Demo
+npx jsmdcui --demo
+```
+
+List every bundled demo and its command-line option:
 
 ```sh
+npx jsmdcui --demo-list
+```
+
+```sh
+# Bun.Image processor demo
+npx jsmdcui --demo-imgtool
+```
+
+```sh
+# Traditional Chinese Bun.Image processor demo
+npx jsmdcui --demo-imgtool-zh
+```
+
+```sh
+# WUI(Web User Interface) Demo
 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:
+#### Open your own Markdown CUI App
 
 ```sh
 npx jsmdcui app.md
@@ -60,30 +109,46 @@ 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:
+- The last command opens the included demo in the terminal
+- Use arrow keys to move around
+- `Enter`, `Space`, or mouse click 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.
+- After starting `--wui`, open the last printed `http://...` URL in a browser.
+- Keep the command running while using the CUI App, and press `Ctrl-C` in that terminal to stop the server.
+
+### Usage table
 
-The command table below uses the cloned-source form. If you use npx, replace
-`bun src/index.js` with `npx jsmdcui`.
+- The command table below assumes you're running from a cloned repository 
+- If you use npx, replace `bun src/index.js` with `npx jsmdcui`
+
+- I've also provided short aliases
+  * bun ./tui = bun src/index.js
+  * bun ./wui = bun src/index.js --wui
 
 | 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 --kitty app.md` | Display Markdown images with Kitty graphics and the jsgotty MIME extension. |
+| `bun src/index.js --kitty-compat app.md` | Display Markdown images with Kitty graphics without the non-standard MIME `U` field. |
+| `bun src/index.js --kitty --allow-url URL.md` | Download trusted HTTP(S) Markdown and its HTTP(S) images, then display supported images with Kitty graphics. |
+| `JSMDCUI_KITTY_DEBUG=1 bun src/index.js --kitty app.md` | Enable Kitty image placement logging to `kitty-placement.log`. |
+| `bun src/index.js --check app.md` | Check heading and fenced-block IDs for collisions, print line-by-line details, and exit. |
 | `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 --export-readme` | Write or overwrite `./README.md` with the bundled README source and exit. |
+| `bun src/index.js --demo-list` | List `testapp.md` and every bundled `demos/*.md` example with its command-line option, then exit. |
+| `bun src/index.js --demo` | Use local `testapp.md` when present, otherwise write the bundled demo; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --demo-<filename>` | Load `demos/<filename>.md`; preserve an existing local copy or write the bundled copy, then open it and generate its five companion files. New files added under `demos/` work automatically. |
+| `bun src/index.js --demo-imgtool` | Compatibility alias for `--demo-image-processor`. |
+| `bun src/index.js --demo-imgtool-zh` | Compatibility alias for `--demo-image-processor.zh-TW`. |
+| `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory and, with Kitty mode enabled, download its HTTP(S) images; write 5 generated files and allow embedded code to run. Only use trusted URLs. |
+| `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise write 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. |
@@ -96,11 +161,15 @@ options.
 Create `app.md`:
 
 ````md
-# My app
+## My app
 
 - [Say hello](javascript:sayHello())
 - [Get server time](javascript:showServerTime())
 - [Update text box](javascript:updateText())
+- [Show selected](javascript:alert(JSON.stringify($('#my-app').val())))
+- [x] task1
+- [x] task2
+- [ ] unselected task
 
 ```text#myid.myclass
 Editable in both TUI and WUI
@@ -136,6 +205,11 @@ bun src/index.js app.md
 bun src/index.js --wui app.md
 ```
 
+- The resulting App UI is shown at the beginning of this README.md
+- Run this demo app directly by:
+  * bun src/index.js README.md
+  * If you didn't clone the repo, use --export-readme to write README.md to the current folder
+
 ### Text blocks
 
 Both `text` and `textarea` fenced blocks define editable text fields:
@@ -146,6 +220,20 @@ Initial value
 ```
 ````
 
+A fenced-block declaration must include a tag. Its supported identity syntax is
+`tag`, optionally followed by `#id` and one or more `.class` names, for
+example `text#message.note` or `textarea#notes.readonly`. Tags, IDs, and class
+names must begin with an ASCII letter or underscore; their remaining
+characters may also include digits, `_`, `-`, and `:`. Declarations such as
+`#message` and `#message.note` have no tag and are therefore not recognized as
+selectable fenced blocks.
+
+The currently supported fenced-block tags are only `text` and `textarea` so
+the same control works consistently in both the TUI and WUI. Selector queries
+may omit the tag or classes after a valid declaration, so all of
+`$('text#message.note')`, `$('text#message')`, `$('#message.note')`, and
+`$('#message')` can select the example above.
+
 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
@@ -158,6 +246,157 @@ 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.
 
+### Heading task lists and selector API
+
+Headings can act as form-group selectors. jsmdcui uses the IDs generated by
+`Bun.markdown.html(..., { headings: { ids: true } })`; for example,
+`## Select Color` becomes `#select-color`. A heading selection reads direct
+task items from the first list following that heading and stops at the next
+heading. In the TUI, the first rendered `☐` or `☒` establishes that list and
+its indentation. Nested task items are not included in the outer list's value.
+
+Heading IDs share the same selector namespace as all explicitly named fenced
+blocks, not only `text` and `textarea`, so avoid name collisions between them.
+For example, `## Write Status` generates `#write-status` and must not be used
+together with a block such as `text#write-status` or
+`textarea#write-status`.
+Otherwise, `$('#write-status')` may select the heading instead of the block and
+updates can appear to do nothing. Rename either declaration so every
+selectable ID is unique.
+
+Duplicate source headings are also treated as collisions when they generate
+the same base ID. Although Bun would automatically rename later headings with
+suffixes such as `-1` and `-2`, those implicit selector names are not visible
+in the Markdown source and should not be relied on. Give each heading a name
+that produces a unique ID before rendering.
+
+Run `bun src/index.js --check app.md` (or `jsmdcui --check app.md`) to
+check these IDs without opening either UI or writing generated files. The
+command prints each collision with its source type, line number, and original
+declaration, then exits immediately. Its exit status is `0` when all IDs are
+unique, `1` when collisions are found, and `2` for invalid arguments or read
+errors.
+
+If the heading ID begins with `select`, `.val()` behaves like a single select:
+it returns the first checked item or `null`. Other heading IDs behave like a
+multiple select and return all checked items as an array, or `[]` when none are
+checked.
+
+Heading values contain the complete visible label, including any explanatory
+text. When interpreting a selection, prefer `value.includes(...)` (or another
+deliberate prefix/token parser) unless labels are guaranteed to be exact,
+stable identifiers. For example, `yes（flip vertically）` should not be tested
+with `value === "yes"`.
+
+````md
+## Select Color
+
+- [ ] Red
+- [x] Green
+- [ ] Blue
+
+## Features
+
+- [x] Search
+- [ ] Notifications
+- [x] Offline mode
+
+```js front
+export function showValues() {
+  alert(JSON.stringify({
+    color: $('#select-color').val(),
+    features: $('#features').val(),
+  }));
+}
+```
+````
+
+The same getter works in TUI and WUI:
+
+```js
+$('#select-color').val() // "Green"
+$('#features').val()     // ["Search", "Offline mode"]
+```
+
+The first direct task list belonging to a heading can also be changed with
+Array-style methods. String arguments create unchecked items. Pass an object
+to choose the initial checked state:
+
+```js
+$('#features').push('Export')
+$('#features').unshift({ value: 'Import', checked: true })
+$('#features').splice(1, 2, 'Replacement')
+$('#features').slice(0, 2)
+$('#features').pop()
+$('#features').shift()
+```
+
+Like the corresponding `Array.prototype` methods, `.push(...items)` and
+`.unshift(...items)` accept multiple items and return the new number of direct
+items. `.pop()` and `.shift()` return the removed item's visible label, or
+`undefined` when the list is empty. Nested task items are part of their parent
+item: they are not counted separately, and are removed together with that
+parent. These methods change the rendered TUI/WUI state; they do not rewrite
+the source Markdown file. A heading must already have a task list before items
+can be added.
+
+`.splice(start, deleteCount, ...items)` follows `Array.prototype.splice()`:
+negative indexes count from the end, omitting `deleteCount` removes through the
+end, and the return value is an array containing the removed visible labels.
+
+`.slice(start, end)` is read-only and follows `Array.prototype.slice()`. It
+returns fresh item snapshots, including unchecked items, so changing the
+returned array or its objects does not change the rendered list:
+
+```js
+$('#features').slice()
+// [
+//   { value: 'Search', checked: true },
+//   { value: 'Notifications', checked: false },
+// ]
+```
+
+`demos/todo.md` and `demos/todo-zh.md` are runnable Todo examples that
+demonstrate `.push()`,
+`.splice()`, `.slice()`, and `{ value, checked }` snapshots using editable text
+controls instead of `prompt()` dialogs. Materialize one in the current
+directory with its demo flag, or open the source-tree copy directly:
+
+```sh
+bun src/index.js --demo-todo
+bun src/index.js --demo-todo-zh
+bun src/index.js demos/todo.md
+bun src/index.js --wui demos/todo-zh.md
+```
+
+The bundled `demos/select.md` is a multilevel runnable example. Use `--demo-select`
+to write it into the current directory when missing and open it in the TUI, or
+open it explicitly in either interface:
+
+```sh
+bun src/index.js --demo-select
+bun src/index.js demos/select.md
+bun src/index.js --wui demos/select.md
+```
+
+The available selector methods are:
+
+| Method | TUI | WUI |
+| --- | --- | --- |
+| `.val()` | Read text blocks or heading task-list values. | Read textareas/controls or heading task-list values. |
+| `.val(value)` | Replace text-block contents and resize multiline values. | Set textarea/control values and resize textareas. |
+| `.html()` | Return a selected heading's inner HTML. | Return any successfully selected DOM element's `innerHTML`. |
+| `.line()` | Return a heading's current 1-based TUI row, or `0` if missing. | Not available. |
+| `.push(...items)` | Append unchecked strings or `{ value, checked }` task items; return the new direct-item count. | Same. |
+| `.pop()` | Remove and return the last direct task item's label, or `undefined`. | Same. |
+| `.shift()` | Remove and return the first direct task item's label, or `undefined`. | Same. |
+| `.unshift(...items)` | Prepend unchecked strings or `{ value, checked }` task items; return the new direct-item count. | Same. |
+| `.splice(start, deleteCount, ...items)` | Remove and insert direct task items; return the removed labels as an array. | Same. |
+| `.slice(start, end)` | Return `{ value, checked }` snapshots without changing the direct task items. | Same. |
+
+TUI heading rows are recalculated after text-block rows are added, removed, or
+replaced with multiline `.val(value)` content.
+
 The three UI building blocks are:
 
 - Regular Markdown provides headings, text, lists, task checkboxes, code, and
@@ -213,8 +452,8 @@ 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. |
+| `Enter` or `Space` | Activate the cell under the cursor. Put the cursor on a `javascript:` link to run it, or on or to the right of `☐` or `☒` to toggle that task. |
+| Left click | Move to and activate the clicked cell. A `javascript:` link runs immediately; clicking on or to the right of `☐` or `☒` toggles that task. |
 | 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. |
@@ -228,13 +467,27 @@ 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.
 
+Local Markdown images are displayed automatically in terminals that support
+the Kitty graphics protocol. Relative image paths are resolved from the
+Markdown file's directory. jsmdcui reads the image dimensions, reserves the
+corresponding terminal rows, and updates the placement when the document is
+scrolled, resized, or shown in a split pane. Unsupported or missing images, as
+well as remote images not authorized with `--allow-url`, retain Bun's normal
+linked `📷` fallback. To download trusted remote Markdown and display its
+supported HTTP(S) images with Kitty graphics, combine the options:
+
+```sh
+bun src/index.js --kitty --allow-url https://example.com/app.md
+```
+
 ## 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.
+normally, and task checkboxes can be toggled by clicking either the checkbox or
+its associated text. `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
@@ -260,6 +513,33 @@ 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.
 
+From the project directory, remove generated `*.md.*` and `*.md-*` companion
+files while keeping the Markdown source files:
+
+```sh
+bun ./clean.sh
+```
+
+### Generated heading sections
+
+WUI output wraps each h1-h6 and its content in a hierarchical `<section>`.
+Lower-level headings create nested sections; the next equal or higher-level
+heading closes the applicable sections. Content before the first heading stays
+outside all generated sections.
+
+```html
+<section>
+  <h1 id="chapter">Chapter</h1>
+  <section>
+    <h2 id="topic">Topic</h2>
+  </section>
+</section>
+```
+
+This structure provides stable boundaries for CSS, DOM queries, and heading
+task-list values. Heading-like text inside comments, scripts, styles, code,
+textareas, and templates is protected and does not create sections.
+
 ## Security
 
 A Markdown UI is an executable application, not a passive document. Starting a

package/single-exe/packAssets.sh

@@ -4,4 +4,4 @@ sd=$(dirname "$0")
 
 cd "$sd"/..
 
-tar -cvf single-exe/assets.tar runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md
+tar -cvf single-exe/assets.tar demos runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md