jsmdcui 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 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

package/README.md

@@ -47,9 +47,10 @@ 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
-> 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
+> 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
@@ -72,9 +73,10 @@ npx jsmdcui
 npx jsmdcui --demo
 ```
 
+List every bundled demo and its command-line option:
+
 ```sh
-# Heading and task-list selector demo
-npx jsmdcui --demo-select
+npx jsmdcui --demo-list
 ```
 
 ```sh
@@ -121,22 +123,31 @@ bun src/index.js --wui testapp.md
 
 ### Usage table
 
-- The command table below uses the cloned-source form. 
+- 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 --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-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 --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. |
@@ -239,9 +250,10 @@ non-empty content is never removed.
 
 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.
+`## 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.
@@ -306,14 +318,65 @@ $('#select-color').val() // "Green"
 $('#features').val()     // ["Search", "Offline mode"]
 ```
 
-The bundled `select.md` is a multilevel runnable example. Use `--demo-select`
+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 select.md
-bun src/index.js --wui select.md
+bun src/index.js demos/select.md
+bun src/index.js --wui demos/select.md
 ```
 
 The available selector methods are:
@@ -324,6 +387,12 @@ The available selector methods are:
 | `.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.
@@ -398,6 +467,19 @@ 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
@@ -431,6 +513,13 @@ 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>`.

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"

package/{image-processor.md → demos/image-processor.md}

@@ -1,4 +1,5 @@
 #!/usr/bin/env jsmdcui
+
 # Bun.Image Processor
 
 Paste the path to a local image below (for example, `/home/me/photo.jpg`). The output file will be written next to the source as `original.resized.jpg` or `original.resized.png`; the source image will not be overwritten.

package/{image-processor.zh-TW.md → demos/image-processor.zh-TW.md}

@@ -1,4 +1,5 @@
 #!/usr/bin/env jsmdcui
+
 # Bun.Image Processor
 
 先把本機圖片路徑貼到下方（例如 `/home/me/photo.jpg`）。輸出檔會放在原圖旁邊，檔名為 `original.resized.jpg` 或 `original.resized.png`；原圖不會被覆寫。

package/{select.md → demos/select.md}

@@ -1,3 +1,5 @@
+#!/usr/bin/env jsmdcui
+
 # Select and Task List Demo
 
 Use `Enter` or `Space` to toggle a task item in the TUI, then activate these

package/demos/todo-zh.md

@@ -0,0 +1,92 @@
+#!/usr/bin/env jsmdcui
+
+# Todo List
+
+## Todos
+
+- [ ] canvas support
+- [x] push/pop/splice/slice list items
+- [x] image by --kitty
+- [ ] clean up codebase
+
+## Actions
+
+```text#todo-input
+Fly to the moon
+```
+
+在上方輸入 Todo 文字，再選擇新增或移除。移除會刪除第一個文字完全相同的項目。
+
+- [新增 Todo](javascript:addTodo())
+- [移除 Todo](javascript:removeTodo())
+- [顯示已完成](javascript:showCompleted())
+- [顯示未完成](javascript:showPending())
+
+## 操作結果：
+
+```text#todo-status
+尚未操作
+```
+
+## Filtered Result
+
+```text#todo-result
+點按「顯示已完成」或「顯示未完成」查看結果
+```
+
+```js front
+function todoText() {
+  return $('#todo-input').val().trim();
+}
+
+function showItems(title, checked) {
+  const items = $('#todos')
+    .slice()
+    .filter(item => item.checked === checked);
+
+  const output = items.length
+    ? items.map(item => `${item.checked ? '✓' : '○'} ${item.value}`).join('\n')
+    : '（沒有項目）';
+  $('#todo-result').val(`${title}\n${output}`);
+  $('#todo-status').val(`找到 ${items.length} 個${title}項目`);
+}
+
+export function addTodo() {
+  const value = todoText();
+  if (!value) {
+    $('#todo-status').val('新增失敗：請先輸入 Todo 文字');
+    return;
+  }
+
+  const length = $('#todos').push(value);
+  $('#todo-input').val('');
+  $('#todo-status').val(`已新增「${value}」，目前共有 ${length} 個 Todo`);
+}
+
+export function removeTodo() {
+  const value = todoText();
+  if (!value) {
+    $('#todo-status').val('移除失敗：請輸入要移除的 Todo 文字');
+    return;
+  }
+
+  const items = $('#todos').slice();
+  const index = items.findIndex(item => item.value === value);
+  if (index < 0) {
+    $('#todo-status').val(`移除失敗：找不到「${value}」`);
+    return;
+  }
+
+  const removed = $('#todos').splice(index, 1);
+  $('#todo-input').val('');
+  $('#todo-status').val(`已移除「${removed[0]}」`);
+}
+
+export function showCompleted() {
+  showItems('已完成', true);
+}
+
+export function showPending() {
+  showItems('未完成', false);
+}
+```

package/demos/todo.md

@@ -0,0 +1,93 @@
+#!/usr/bin/env jsmdcui
+
+# Todo List
+
+## Todos
+
+- [ ] canvas support
+- [x] push/pop/splice/slice list items
+- [x] image by --kitty
+- [ ] clean up codebase
+
+## Actions
+
+```text#todo-input
+Fly to the moon
+```
+
+Enter Todo text above, then choose Add or Remove. Remove deletes the first item whose text matches exactly.
+
+- [Add Todo](javascript:addTodo())
+- [Remove Todo](javascript:removeTodo())
+- [Show Completed](javascript:showCompleted())
+- [Show Pending](javascript:showPending())
+
+## Operation Result
+
+```text#todo-status
+No action yet
+```
+
+## Filtered Result
+
+```text#todo-result
+Select “Show Completed” or “Show Pending” to view matching items
+```
+
+```js front
+function todoText() {
+  return $('#todo-input').val().trim();
+}
+
+function showItems(title, checked) {
+  const items = $('#todos')
+    .slice()
+    .filter(item => item.checked === checked);
+
+  const output = items.length
+    ? items.map(item => `${item.checked ? '✓' : '○'} ${item.value}`).join('\n')
+    : '(No items)';
+  const noun = items.length === 1 ? 'item' : 'items';
+  $('#todo-result').val(`${title}\n${output}`);
+  $('#todo-status').val(`Found ${items.length} ${title.toLowerCase()} ${noun}`);
+}
+
+export function addTodo() {
+  const value = todoText();
+  if (!value) {
+    $('#todo-status').val('Add failed: enter Todo text first');
+    return;
+  }
+
+  const length = $('#todos').push(value);
+  $('#todo-input').val('');
+  $('#todo-status').val(`Added “${value}”; ${length} Todos total`);
+}
+
+export function removeTodo() {
+  const value = todoText();
+  if (!value) {
+    $('#todo-status').val('Remove failed: enter the Todo text to remove');
+    return;
+  }
+
+  const items = $('#todos').slice();
+  const index = items.findIndex(item => item.value === value);
+  if (index < 0) {
+    $('#todo-status').val(`Remove failed: could not find “${value}”`);
+    return;
+  }
+
+  const removed = $('#todos').splice(index, 1);
+  $('#todo-input').val('');
+  $('#todo-status').val(`Removed “${removed[0]}”`);
+}
+
+export function showCompleted() {
+  showItems('Completed', true);
+}
+
+export function showPending() {
+  showItems('Pending', false);
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Markdown as a Common UI for Terminals and Web Browsers",
   "type": "module",
   "main": "./src/index.js",

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)
@@ -62,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();
 }
 
@@ -336,14 +340,22 @@ export async function createWui(md,mdpath) // HTML
   
   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}
@@ -351,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`;
+    }
   }