jsmdcui 0.4.0 → 0.6.3

package/CHANGELOG.md

@@ -2,6 +2,231 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.6.3] - 2026-07-18
+
+This update enforces unique heading IDs at the Markdown source level and
+clarifies the portable fenced-block identity contract shared by the TUI and
+WUI.
+
+### Changed
+
+- Treat duplicate Markdown headings that generate the same base ID as a
+  source-level collision. Later headings no longer pass `--check` merely
+  because Bun would silently assign generated suffixes such as `-1` or `-2`
+  that the Markdown author cannot see.
+- Document that a selectable fenced-block declaration requires a tag and uses
+  the `tag#id.class` identity form. The officially supported portable control
+  tags are currently limited to `text` and `textarea` so the same Markdown
+  behaves consistently in both the TUI and WUI.
+- Clarify that selector queries may omit the tag or classes after a valid
+  declaration.
+- Expand checker and TUI selector regression coverage across tag/no-tag and
+  class/no-class combinations, heading-to-heading, heading-to-block, and
+  block-to-block ID collisions.
+
+### Fixed
+
+- Fix duplicate source headings incorrectly passing the checker after Bun
+  automatically changed the generated ID of later headings.
+
+## [0.6.2] - 2026-07-18
+
+This update makes Markdown ID-collision checks match the full TUI `$()` block
+selector and gives check results clearer final status banners.
+
+### Changed
+
+- Extend `--check FILE.md` from `text` and `textarea` controls to every
+  explicitly named fenced block accepted by the TUI `$()` selector, including
+  identities such as `hello#myid` and `json#config`.
+- Report separate heading and fenced-block declaration counts, and describe
+  arbitrary block tags and their source lines in collision details.
+- Replace the previous success label with a large green `PASSED` banner and
+  add a matching large red `FAILED` banner at the bottom of failed reports.
+  Both true-color foregrounds are generated with
+  `Bun.color(..., "ansi-16m")`, with standard ANSI fallbacks.
+- Update the README and bundled help to clarify that generated heading IDs
+  share the selector namespace with all explicitly named fenced blocks, not
+  only editable text controls.
+
+### Fixed
+
+- Fix `--check` overlooking collisions between a heading and a non-text
+  fenced block even though TUI `$().val()` could select both declarations.
+- Add regression coverage for arbitrary fenced-block IDs and the colored
+  `PASSED` and `FAILED` terminal statuses.
+
+## [0.6.1] - 2026-07-18
+
+This update adds Markdown UI ID-collision diagnostics and bundles a practical
+Bun.Image processor demo in English and Traditional Chinese.
+
+### Added
+
+- Add `--check FILE.md` to inspect Markdown heading and text-control IDs
+  without opening a UI or writing generated companion files. The report uses
+  `Bun.markdown.ansi()` headings and nested lists, identifies every collision
+  by ID, source type, line number, and original declaration, and exits with
+  status `0` for unique IDs, `1` for collisions, or `2` for usage and read
+  errors.
+- Add `image-processor.md` and `image-processor.zh-TW.md`, runnable Bun.Image
+  tools for the TUI and WUI. They support image metadata inspection, resizing,
+  fit and resampling filters, enlargement prevention, EXIF auto-orientation,
+  rotation, vertical and horizontal mirroring, brightness and saturation
+  adjustment, and JPEG or PNG output options.
+- Add detailed image-processing status fields. Successful writes show the
+  output path, dimensions, byte count, and all selected option values; failed
+  metadata reads and writes show the available error details and stack.
+- Add `--demo-imgtool` and `--demo-imgtool-zh`. Each command preserves an
+  existing local processor Markdown file or writes its bundled language
+  version when missing, then opens it in the TUI.
+- Bundle both image processor Markdown files in the single-executable asset
+  archive and add regression coverage for ID checks and both demo languages.
+
+### Changed
+
+- Consolidate bundled demo Markdown loading behind one
+  `bundledMarkdownSource(filename)` implementation shared by `testapp.md`,
+  `select.md`, and both image processor variants.
+- Document that heading selector values include the complete visible label.
+  Selection parsers should use deliberate substring, prefix, or token checks
+  when labels contain explanatory text instead of assuming exact identifiers.
+- Document that generated heading IDs and explicitly named controls share the
+  same selector namespace and that every selectable ID should be unique.
+
+### Fixed
+
+- Prevent explanatory text in image processor task-list labels from breaking
+  yes/no, fit, filter, and output-format selection parsing.
+- Fix the English image processor status update silently targeting a heading
+  after `## Write Status` generated the same `#write-status` ID as its text
+  control.
+- Catch image metadata and processing failures at both frontend and backend
+  boundaries so errors are displayed in the appropriate status field.
+
+## [0.6.0] - 2026-07-18
+
+This update turns Markdown headings and task lists into cross-environment form
+controls, improves the safety and consistency of the bundled demo workflow,
+and adds a way to export the bundled README as a runnable Markdown app.
+
+### Added
+
+- Add `--export-readme` to write or overwrite `./README.md` with the bundled
+  README source and exit.
+- Add terminal task-checkbox activation. Activating a protected mdcui row at
+  or after its `☐` or `☒` toggles that checkbox and still allows the remaining
+  default cell callback to run. JavaScript links continue to take priority.
+- Add hierarchical `<section>` wrappers to generated WUI HTML. Every h1-h6
+  opens a section; an equal or higher-level heading closes the applicable open
+  sections, while lower-level headings create nested sections. Content before
+  the first heading remains outside the generated sections.
+- Add heading lookup to the TUI `$` API using the IDs generated by
+  `Bun.markdown.html(..., { headings: { ids: true } })`.
+- Add `$('#heading-id').html()` in TUI to return a heading's inner HTML, and
+  `$('#heading-id').line()` to return its current 1-based terminal row or `0`
+  when it cannot be found. Line lookup follows text-block row additions,
+  removals, and multiline `.val(value)` replacements.
+- Add `.html()` getters to WUI `$` selections. Any successfully selected DOM
+  element returns its `innerHTML`; missing or invalid selections return an
+  empty string.
+- Add heading-based task-list values in both interfaces. `.val()` reads the
+  first task-list group directly following the selected heading, stops at the
+  next heading, and ignores nested task items. IDs beginning with `select`
+  return the first checked value or `null`; other IDs return all checked values
+  as an array or `[]`.
+- Add `select.md`, a runnable multilevel heading and task-list example with
+  links that display single-select and multiple-select values through
+  `alert()`.
+- Bundle `select.md` in packaged assets and add `--demo-select`. The command
+  preserves an existing `./select.md`, writes the bundled copy when missing,
+  opens it in the TUI, and generates its five companion files.
+
+### Changed
+
+- Make `--demo` preserve an existing `./testapp.md`. The bundled source is now
+  written only when the file is missing, then opened in the terminal UI.
+- Make `--wui` without a file follow the same source-file rule: use an existing
+  `./testapp.md`, or write the bundled demo there when missing, before creating
+  the generated companion files.
+- Wrap generated WUI task-checkbox text in `<label>` so clicking the associated
+  text toggles the checkbox. Direct text and immediately following paragraph
+  elements are included; unrelated tags and nested lists remain outside.
+- Extend the 0.5 `$().val()` contract: text and textarea controls retain their
+  string getter/setter behavior, while heading selections now return scalar,
+  array, or `null` task-list values according to the heading ID.
+- Add a demo screenshot and expand the README and built-in help with clearer
+  TUI/WUI startup, demo preservation, and README export instructions.
+
+### Fixed
+
+- Ensure WUI fallback to the bundled `testapp.md` materializes the Markdown
+  source in the current working directory instead of generating only its
+  companion files.
+- Protect comments and `script`, `style`, `pre`, `code`, `textarea`, and
+  `template` regions while wrapping WUI headings, preventing heading-like HTML
+  strings inside those regions from changing the section hierarchy.
+- Keep TUI heading lookup independent of ANSI heading text and duplicate
+  labels by mapping Bun-generated heading order and level to Bun's current
+  h1-h6 ANSI signatures.
+
+## [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

package/README.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,52 @@ 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
+> 5 generated files beside it. Starting `--wui` without a file 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
+```
+
+```sh
+# Heading and task-list selector demo
+npx jsmdcui --demo-select
+```
 
 ```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 +107,37 @@ 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.
 
-The command table below uses the cloned-source form. If you use npx, replace
-`bun src/index.js` with `npx jsmdcui`.
+### Usage table
+
+- 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 --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 --export-readme` | Write or overwrite `./README.md` with the bundled README source and 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-select` | Use local `select.md` when present, otherwise write the bundled selector demo; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --demo-imgtool` | Use local `image-processor.md` when present, otherwise write the bundled Bun.Image processor; open it in the terminal UI and write five generated files beside it. |
+| `bun src/index.js --demo-imgtool-zh` | Use local `image-processor.zh-TW.md` when present, otherwise write the bundled Traditional Chinese Bun.Image processor; open it in the terminal UI and write five 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` | 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,10 +150,19 @@ 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
+```
 
 ```js front
 export function sayHello() {
@@ -111,6 +174,10 @@ export async function showServerTime() {
   const time = await rpc.getServerTime();
   alert(time);
 }
+
+export function updateText() {
+  $('#myid').val($('.myclass').val() + ' ✓');
+}
 ```
 
 ```js back
@@ -127,12 +194,149 @@ 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:
+
+````md
+```text#message.note
+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
+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.
+
+### 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 the first
+task list directly following that heading and stops at the next heading. 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 bundled `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 select.md
+bun src/index.js --wui 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. |
+
+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
   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
@@ -149,6 +353,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
@@ -156,14 +376,15 @@ 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 |
 | --- | --- |
 | 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. |
@@ -181,9 +402,10 @@ normal links in the browser.
 
 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
@@ -209,6 +431,26 @@ 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.
 
+### 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