jsmdcui 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,234 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.7.0] - 2026-07-20
+
+This update adds native Kitty image rendering, turns heading task lists into
+Array-style collections in both interfaces, and keeps TUI layout, interaction,
+and checkbox styling consistent at every terminal width.
+
+### Added
+
+- Display local Markdown images at their rendered TUI positions with the
+  Kitty graphics protocol. Image rows are reserved according to intrinsic
+  dimensions, and placements follow scrolling, resizing, and split panes.
+- With `--allow-url` and Kitty mode enabled, download HTTP(S) Markdown images
+  through the existing `curl`, `wget`, then Bun `fetch` fallback chain. Relative
+  image URLs in downloaded Markdown resolve against the original document URL.
+- Keep Bun's normal linked `📷` fallback for missing, unsupported, and
+  unauthorized remote images, and scope Kitty cleanup to image IDs owned by
+  jsmdcui.
+- Set Kitty's `C=1` placement flag so displaying an image cannot advance the
+  terminal cursor and trigger an unwanted scroll at the bottom of the screen.
+- Add `.push()`, `.pop()`, `.shift()`, `.unshift()`, and `.splice()` to heading
+  selectors in both the TUI and WUI. The methods follow their
+  `Array.prototype` argument and return-value conventions, operate on direct
+  items in the first task list belonging to the heading, and remove nested
+  content together with its parent item.
+- Allow inserted task items to be passed as strings for unchecked items or as
+  `{ value, checked }` objects, and preserve an emptied TUI list's insertion
+  point so later mutations still target the same list.
+- Add read-only heading `.slice(start, end)`, returning fresh
+  `{ value, checked }` snapshots that include both checked and unchecked direct
+  task items.
+- Add `demos/todo.md` and `demos/todo-zh.md`, runnable Todo examples that use
+  text controls and the new list methods to add and remove items and display
+  completed or pending tasks.
+- Move secondary examples under `demos/` and add automatic
+  `--demo-<filename>` discovery, so newly bundled `demos/<filename>.md` files
+  need no parser changes. Keep `--demo` mapped to the root `testapp.md` and
+  retain the existing image-processor aliases.
+- Add `--demo-list` to list the root demo and every automatically discovered
+  Markdown example from bundled assets or the source tree's `demos/` directory.
+- Add `clean.sh` as a convenience helper for removing generated Markdown
+  companion files from the project directory.
+
+### Changed
+
+- Document the Array-style heading task-list API, its return values, nested-item
+  behavior, existing-list requirement, and non-persistent rendered-state
+  semantics in the README and bundled help.
+- Use the complete pane content width consistently for Markdown rendering,
+  soft wrapping, cursor and mouse mapping, and Kitty image sizing instead of
+  reserving the terminal's final column.
+
+### Fixed
+
+- Fix soft wrapping at affected terminal widths shifting the visual cursor by
+  one row, which could activate the preceding Markdown action and leave the
+  final action unresponsive.
+- Update the Bun Markdown ANSI glyph and style together when toggling a task
+  checkbox, so checked items become green and unchecked items no longer retain
+  the checked color.
+
+## [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

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,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/clean.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+sd=$(dirname "$0")
+
+rm "$sd"/*.md.* "$sd"/*.md-* 2>/dev/null
+rm "$sd"/demos/*.md.* "$sd"/demos/*.md-* 2>/dev/null
+rm "$sd"/tests/*.md.* "$sd"/tests/*.md-* 2>/dev/null
+
+echo "Removed all *.md.* *.md-* from repo root and demos/ folder"