jsmdcui 0.6.3 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.8.0] - 2026-07-20
+
+This update adds portable inline keydown handling to Markdown text controls,
+including mobile software-keyboard fallback behavior, and makes interactive
+prompts safe across every TUI frontend action path.
+
+### Added
+
+- Add quoted `@keydown="..."` attributes to named `text` and `textarea`
+  fences. The TUI preserves source event metadata and evaluates it before key
+  handling; the WUI emits a native inline event attribute. Add `.prevent` to
+  apply `event.preventDefault()` before the handler runs. Keyup is intentionally
+  not exposed because traditional terminals do not report key releases
+  reliably.
+- In the WUI, automatically map `beforeinput.data` back through `onkeydown`
+  when a mobile software keyboard reports `event.key` as `Unidentified`.
+  Unidentified events are hidden from application handlers, while identified
+  desktop keydowns are marked briefly to prevent duplicate calls.
+- Add native multiline editing to TUI `textarea` controls. Enter splits a body
+  row and expands the frame; Backspace at the start of a later row and Delete
+  at the end of a row join adjacent body rows without exposing frame borders.
+- Add the `bun ./edit` launcher as a short equivalent of
+  `bun src/index.js --edit`, opening Markdown as ordinary editable UTF-8 source.
+- Add the automatically discovered `--demo-maze` example, demonstrating
+  portable `@keydown.prevent` controls with keyboard and arrow-key navigation;
+  add `Ctrl-R` as a keyboard shortcut for resetting the maze.
+
+### Changed
+
+- Install protected `alert`, `confirm`, and `prompt` globals once for the TUI
+  lifetime and share them across OSC 8 actions, fenced keyboard handlers, and
+  JS plugins. Restore Bun's original globals when the TUI stops.
+- Make `micro.alert()`, `micro.confirm()`, and `micro.prompt()` synchronous like
+  their native counterparts, and update the bundled JS plugin examples so they
+  do not `await` these calls.
+- Add TUI `.val(value)` replacements to Undo/Redo history, including multiline
+  layout, ANSI rendering metadata, image positions, and task-list anchors.
+
+### Fixed
+
+- Prevent `alert()` called from a keydown handler from competing with the TUI
+  for stdin by suspending raw mode and screen rendering around native prompts.
+- Restore the terminal's previous raw-mode and input-listener state after a
+  protected prompt, including setup, prompt, and cleanup error paths.
+- Index fenced keyboard-event regions once and use binary lookup for each key,
+  instead of rescanning the rendered Markdown document on every keypress.
+- Open Windows controlling-terminal input through read-only `CONIN$` when stdin
+  is redirected, so piped Markdown retains keyboard and protected-prompt input.
+- Preserve `ctrlKey`, `shiftKey`, `altKey`, and `metaKey` when the WUI maps an
+  unidentified mobile keydown through its `beforeinput` fallback.
+- Recover modified A-Z keys in the WUI from key codes 65-90 or physical
+  `KeyA`-`KeyZ` codes, including Android browsers that transform Alt-S into
+  `ß`; exclude AltGraph so international text composition remains intact.
+- Add matching non-enumerable `event.toJSON()` methods to TUI and WUI keydown
+  events, allowing `JSON.stringify(event)` to produce portable event details.
+- Keep fenced-block IDs visible to collision checking when the info string also
+  contains inline event attributes such as `@keydown="..."`.
+- When the WUI's default port 3000 is already in use, retry with port 0 so the
+  operating system selects an available port, and print that actual port in the
+  generated URL. Other server startup errors continue to fail normally.
+
+## [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
@@ -87,6 +89,11 @@ npx jsmdcui --demo-imgtool
 npx jsmdcui --demo-imgtool-zh
 ```
 
+```sh
+# Maze game demo
+npx jsmdcui --demo-maze
+```
+
 ```sh
 # WUI(Web User Interface) Demo
 npx jsmdcui --wui
@@ -121,22 +128,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` | Convert Markdown images to PNG with `Bun.Image` and display them using the standard Kitty graphics protocol 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. |
@@ -228,20 +244,90 @@ 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 TUI, `text` remains a single-line control while `textarea` supports
+native multiline editing. Enter splits the current body row and grows the
+frame, Backspace at the start of a later row joins it to the previous row, and
+Delete at the end of a row joins the following row. When the expanded control
+does not fit on screen, the document viewport scrolls to keep the cursor
+visible. The closing border and following Markdown content move with the
+resized control.
+
+A named `text` or `textarea` block can run inline front-end code before it
+handles a key by placing a quoted HTML-style `@keydown` attribute after its
+identity:
+
+````md
+```text#command.field @keydown="handleCommand(event)"
+Initial value
+```
+
+```js front
+export function handleCommand(event) {
+  if (event.key !== 'Enter') return;
+  event.preventDefault();
+  alert(`Command: ${$('#command').val()}`);
+}
+```
+````
+
+The block must have a unique ID. In the WUI, jsmdcui writes the code directly
+to the generated textarea's native `onkeydown` attribute. Mobile browsers may
+report ordinary software-keyboard letters as `Unidentified`, so the WUI also
+generates an `onbeforeinput` fallback. The unidentified event is hidden from
+the handler; `beforeinput.data` becomes `event.key`, then the same keydown code
+runs once. The fallback also preserves `ctrlKey`, `shiftKey`, `altKey`, and
+`metaKey` from the unidentified keydown. A short zero-delay timer distinguishes
+it from the `beforeinput` that normally follows an already identified keydown,
+preventing duplicate calls.
+
+On Android browsers, `Alt-E`, `Alt-N`, `Alt-U`, and `Alt-I` may be consumed or
+transformed by the software keyboard and therefore cannot always be observed
+reliably by a keydown handler. Avoid relying on these combinations for portable
+WUI controls.
+
+In the TUI, the full source info string is kept in an event table before Bun
+renders it. The keydown statements run with a synthetic `event` before the
+text control handles the key. Both interfaces expose `event.key`, modifier
+flags, `event.target.id`, and `event.target.value`. Use `event`, the native
+inline-handler variable, rather than Vue's `$event` alias. Double quotes
+delimit the handler; use single-quoted JavaScript strings inside it or escape
+an embedded double quote as `\"`.
+
+Both interfaces add a non-enumerable `event.toJSON()` method with matching
+keyboard, modifier, prevention, and target fields. `JSON.stringify(event)`
+calls it automatically, so the resulting JSON is portable between the TUI and
+WUI.
+
+A keydown handler can call `event.preventDefault()` to stop text insertion or
+cursor movement. The `.prevent` modifier applies this automatically:
+
+````md
+```text#command @keydown.prevent="handleCommand(event)"
+```
+````
+
+`@keydown` is the only keyboard event exposed by jsmdcui. Traditional terminal
+input does not report physical key releases reliably, so jsmdcui does not
+provide or emulate `@keyup` in either interface.
+
 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.
+be edited, and the frame prefix cannot be deleted. Multiline paste remains
+blocked. For single-line `text` controls, 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.
+
+TUI text-control changes made through `.val(value)` participate in the same
+history as direct editing. `Ctrl-Z` undoes the replacement and `Ctrl-Y` redoes
+it, including multiline frame resizing and its associated rendered metadata.
 
 ### 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.
+`## 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 +392,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:
@@ -321,23 +458,29 @@ 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. |
+| `.val(value)` | Replace text-block contents, resize multiline values, and record Undo/Redo history. | 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:
+The 3 UI building blocks are:
 
-- Regular Markdown provides headings, text, lists, task checkboxes, code, and
+- 1. `Regular Markdown` provides headings, text, lists, task checkboxes, code, and
   links.
-- A `js front` block contains UI code. Exported functions can use
+- 2. `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,
+  * 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.
+- 3. `js back` block exports trusted backend functions. In the browser WUI,
   `rpc` publishes only exported functions whose exported names do not start
   with `_`. Call a published function from the front end with
   `await rpc.functionName(arg1, arg2)`.
@@ -398,6 +541,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
@@ -407,15 +563,35 @@ 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
-same machine. From another device on the same network, replace `localhost` with
-the server machine's IP address and keep the same port and full path.
+The WUI first tries port `3000` and accepts connections through the machine's
+available network interfaces. If port `3000` is already in use, the operating
+system selects an available port instead; the printed URL always contains the
+actual port. Set `PORT` to request another fixed port. The printed `localhost`
+URL is for the same machine. From another device on the same network, replace
+`localhost` with the server machine's IP address and keep the printed port and
+full path.
 
 Each server start prints a new random path. The old URL stops working after the
 server is stopped or restarted. Keep the process running while using the page,
 and press `Ctrl-C` in its terminal to stop it.
 
+## Editing Markdown source
+
+From a cloned repository, use the `edit` launcher to open a Markdown file as
+ordinary editable UTF-8 source instead of rendering it as a Markdown UI:
+
+```sh
+bun ./edit app.md
+```
+
+This is equivalent to:
+
+```sh
+bun src/index.js --edit app.md
+```
+
+Additional file and cursor arguments are forwarded unchanged.
+
 ## Generated files
 
 Opening a local Markdown UI generates these files beside the source file:
@@ -431,6 +607,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/demos/maze.md

@@ -0,0 +1,144 @@
+```text#character
+🧱😀🧱🧱🧱🧱🧱🧱🧱🧱🧱🧱
+🧱  🧱                🧱
+🧱  🧱🧱🧱  🧱  🧱🧱🧱🧱
+🧱      🧱  🧱        🧱
+🧱🧱🧱  🧱🧱🧱🧱🧱  🧱🧱
+🧱  🧱      🧱        🧱
+🧱  🧱🧱🧱  🧱  🧱  🧱🧱
+🧱      🧱      🧱    🧱
+🧱  🧱🧱🧱🧱🧱🧱🧱  🧱🧱
+🧱          🧱        🧱
+🧱  🧱  🧱🧱🧱  🧱🧱🧱🧱
+🧱  🧱                🧱
+🧱🧱🧱🧱🧱🧱🧱🧱🧱  🧱🧱
+```
+
+```text#controls @keydown.prevent="handle(event)"
+Put the cursor here, then press:
+將遊標放在這裡，然後按：
+
+L't half of QWERTY  ← move left
+R't half of QWERTY  → move right
+T / Y               ↑ move up
+Space               ↓ move down
+
+鍵盤左半邊 ← 向左移動
+鍵盤右半邊 → 向右移動
+T / Y 向上移動
+空白鍵向下移動
+
+Arrow keys   ←↑→↓ / 正常方向移動
+Ctrl-R       Reset maze / 重新開始
+
+Do not hit 🧱 / 不能撞牆
+```
+
+```text#last-key
+Waiting for input / 等待輸入
+```
+
+[🔄 Reset maze / 重新開始](javascript:reset())
+
+```js front
+const LEFT_KEYS = new Set([
+  ...'`12345qwerasdfgzxcvb',
+  'escape', 'tab',
+]);
+const RIGHT_KEYS = new Set([
+  ...'67890-=uiop[]\\hjkl;\'nm,./',
+  'backspace', 'enter', 'delete',
+  'home', 'end', 'pageup', 'pagedown',
+]);
+const MAZE = [
+  '# ##########',
+  '# #        #',
+  '# ### # ####',
+  '#   # #    #',
+  '### ##### ##',
+  '# #   #    #',
+  '# ### # # ##',
+  '#   #   #  #',
+  '# ####### ##',
+  '#     #    #',
+  '# # ### ####',
+  '# #        #',
+  '######### ##',
+];
+const GOAL = { row: MAZE.length - 1, col: 9 };
+const player = { row: 0, col: 1 };
+let completed = false;
+
+function drawMaze() {
+  const screen = MAZE.map((line, row) => [...line].map((cell, col) => {
+    if (row === player.row && col === player.col) return '😀';
+    return cell === '#' ? '🧱' : '  ';
+  }).join('')).join('\n');
+  $('#character').val(screen);
+}
+
+export function reset() {
+  player.row = 0;
+  player.col = 1;
+  completed = false;
+  drawMaze();
+  $('#last-key').val('Waiting for input / 等待輸入');
+}
+
+export function handle(event) {
+  const key = String(event.key ?? '').toLowerCase();
+  if (event.ctrlKey && key === 'r') {
+    reset();
+    return;
+  }
+  if (completed) return;
+
+  let row = player.row;
+  let col = player.col;
+  let direction;
+
+  if (key === 't' || key === 'y' || key === 'arrowup') {
+    row--;
+    direction = 'up / 上';
+  } else if (key === ' ' || key === 'arrowdown') {
+    row++;
+    direction = 'down / 下';
+  } else if (key === 'arrowleft' || LEFT_KEYS.has(key)) {
+    col--;
+    direction = 'left / 左';
+  } else if (key === 'arrowright' || RIGHT_KEYS.has(key)) {
+    col++;
+    direction = 'right / 右';
+  } else {
+    $('#last-key').val(`Ignored / 忽略：${event.key}`);
+    return;
+  }
+
+  if (MAZE[row]?.[col] !== ' ') {
+    $('#last-key').val(`${event.key === ' ' ? 'Space' : event.key} → 🧱 Wall / 撞牆`);
+    return;
+  }
+
+  player.row = row;
+  player.col = col;
+  drawMaze();
+
+  if (row === GOAL.row && col === GOAL.col) {
+    completed = true;
+    $('#last-key').val('🎉🏆🌟 Escaped the maze! / 成功走出迷宮！🌟🏆🎉');
+    alert([
+      '🎆🎇🎉 恭 喜 過 關 ！ 🎉🎇🎆',
+      '',
+      '🥳 你成功逃出迷宮了！ 🥳',
+      '👑 🏆 ⭐ 🌟 💫 🌈 🦄',
+      '👏👏👏  AMAZING!  👏👏👏',
+      '🎈 🎊 🎁 🪩 🎁 🎊 🎈',
+      '',
+      '🚀 ESCAPED THE MAZE! 🚀',
+    ].join('\n'));
+  } else {
+    const label = event.key === ' ' ? 'Space' : event.key;
+    $('#last-key').val(`${label} → ${direction} (${row}, ${col})`);
+  }
+}
+```

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