jsmdcui 0.7.0 → 0.9.0

package/demos/maze.md

@@ -0,0 +1,149 @@
+```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! / 成功走出迷宮！🌟🏆🎉');
+    $('#character').val([
+      '',
+      '🎆🎇🎉 恭 喜 過 關 ！ 🎉🎇🎆',
+      '',
+      '🥳 你成功逃出迷宮了！ 🥳',
+      '👑 🏆 ⭐ 🌟 💫 🌈 🦄',
+      '👏👏👏  AMAZING!  👏👏👏',
+      '🎈 🎊 🎁 🪩 🎁 🎊 🎈',
+      '',
+      '🚀 ESCAPED THE MAZE! 🚀',
+      '',
+      'Press Ctrl-R to reset',
+      '按 Ctrl-R 重新開始',
+      ''
+    ].join('\n'));
+  } else {
+    const label = event.key === ' ' ? 'Space' : event.key;
+    $('#last-key').val(`${label} → ${direction} (${row}, ${col})`);
+  }
+}
+```

package/demos/todo-zh.md

@@ -18,10 +18,25 @@ Fly to the moon
 在上方輸入 Todo 文字，再選擇新增或移除。移除會刪除第一個文字完全相同的項目。
 
 - [新增 Todo](javascript:addTodo())
+- .
 - [移除 Todo](javascript:removeTodo())
+- .
 - [顯示已完成](javascript:showCompleted())
+- .
 - [顯示未完成](javascript:showPending())
 
+## 存檔／讀檔
+
+```text#todo-file
+todo_list.json
+```
+
+在上方輸入 JSON 檔案路徑。存檔會寫入人類可讀的 JSON；讀檔會在確認後取代目前的 Todo 清單。
+
+- [儲存 Todos](javascript:saveTodos())
+- .
+- [讀取 Todos](javascript:loadTodos())
+
 ## 操作結果：
 
 ```text#todo-status
@@ -51,6 +66,14 @@ function showItems(title, checked) {
   $('#todo-status').val(`找到 ${items.length} 個${title}項目`);
 }
 
+function todoFile() {
+  return $('#todo-file').val().trim();
+}
+
+function describeError(error) {
+  return error?.message || String(error);
+}
+
 export function addTodo() {
   const value = todoText();
   if (!value) {
@@ -89,4 +112,79 @@ export function showCompleted() {
 export function showPending() {
   showItems('未完成', false);
 }
+
+export async function saveTodos() {
+  const file = todoFile();
+  if (!file) {
+    $('#todo-status').val('存檔失敗：請先輸入 JSON 檔案路徑');
+    return;
+  }
+
+  try {
+    const obj = { todos: $('#todos').slice() };
+    const result = await rpc.saveTodoList(file, obj);
+    $('#todo-status').val(`已將 ${obj.todos.length} 個 Todo 儲存至 ${result.path}`);
+  } catch (error) {
+    $('#todo-status').val(`存檔失敗：${describeError(error)}`);
+  }
+}
+
+export async function loadTodos() {
+  const file = todoFile();
+  if (!file) {
+    $('#todo-status').val('讀檔失敗：請先輸入 JSON 檔案路徑');
+    return;
+  }
+  try {
+    const result = await rpc.loadTodoList(file);
+    const json = JSON.stringify(result.obj, null, 1);
+    if (!confirm(`要用「${file}」中的以下 JSON 取代目前的 Todo 清單嗎？\n\n${json}`)) {
+      $('#todo-status').val('已取消讀檔，目前的 Todos 未變更');
+      return;
+    }
+    const current = $('#todos').slice();
+    $('#todos').splice(0, current.length, ...result.obj.todos);
+    $('#todo-status').val(`已從 ${result.path} 讀取 ${result.obj.todos.length} 個 Todo`);
+  } catch (error) {
+    $('#todo-status').val(`讀檔失敗：${describeError(error)}`);
+  }
+}
+```
+
+```js back
+import { resolve } from 'node:path';
+
+function todoPath(input) {
+  const value = String(input ?? '').trim();
+  if (!value) throw new Error('請先輸入 JSON 檔案路徑');
+  return resolve(value);
+}
+
+function validateTodoObject(obj) {
+  if (!obj || typeof obj !== 'object' || !Array.isArray(obj.todos))
+    throw new Error('Todo JSON 必須是包含 todos 陣列的物件');
+
+  return {
+    todos: obj.todos.map((item, index) => {
+      if (!item || typeof item !== 'object' || typeof item.value !== 'string')
+        throw new Error(`第 ${index + 1} 個 Todo 項目必須包含字串 value`);
+      return { value: item.value, checked: Boolean(item.checked) };
+    }),
+  };
+}
+
+export async function saveTodoList(input, obj) {
+  const path = todoPath(input);
+  const validated = validateTodoObject(obj);
+  await Bun.write(path, JSON.stringify(validated, null, 1) + '\n');
+  return { path };
+}
+
+export async function loadTodoList(input) {
+  const path = todoPath(input);
+  const file = Bun.file(path);
+  if (!await file.exists()) throw new Error(`找不到 Todo 檔案：${path}`);
+  const obj = validateTodoObject(JSON.parse(await file.text()));
+  return { path, obj };
+}
 ```

package/demos/todo.md

@@ -18,10 +18,25 @@ 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())
 
+## Save / Load
+
+```text#todo-file
+todo_list.json
+```
+
+Enter a JSON file path above. Saving writes human-readable JSON; loading replaces the current Todo list after confirmation.
+
+- [Save Todos](javascript:saveTodos())
+- .
+- [Load Todos](javascript:loadTodos())
+
 ## Operation Result
 
 ```text#todo-status
@@ -52,6 +67,14 @@ function showItems(title, checked) {
   $('#todo-status').val(`Found ${items.length} ${title.toLowerCase()} ${noun}`);
 }
 
+function todoFile() {
+  return $('#todo-file').val().trim();
+}
+
+function describeError(error) {
+  return error?.message || String(error);
+}
+
 export function addTodo() {
   const value = todoText();
   if (!value) {
@@ -90,4 +113,79 @@ export function showCompleted() {
 export function showPending() {
   showItems('Pending', false);
 }
+
+export async function saveTodos() {
+  const file = todoFile();
+  if (!file) {
+    $('#todo-status').val('Save failed: enter a JSON file path first');
+    return;
+  }
+
+  try {
+    const obj = { todos: $('#todos').slice() };
+    const result = await rpc.saveTodoList(file, obj);
+    $('#todo-status').val(`Saved ${obj.todos.length} Todos to ${result.path}`);
+  } catch (error) {
+    $('#todo-status').val(`Save failed: ${describeError(error)}`);
+  }
+}
+
+export async function loadTodos() {
+  const file = todoFile();
+  if (!file) {
+    $('#todo-status').val('Load failed: enter a JSON file path first');
+    return;
+  }
+  try {
+    const result = await rpc.loadTodoList(file);
+    const json = JSON.stringify(result.obj, null, 1);
+    if (!confirm(`Replace the current Todo list with this JSON from “${file}”?\n\n${json}`)) {
+      $('#todo-status').val('Load cancelled; current Todos were not changed');
+      return;
+    }
+    const current = $('#todos').slice();
+    $('#todos').splice(0, current.length, ...result.obj.todos);
+    $('#todo-status').val(`Loaded ${result.obj.todos.length} Todos from ${result.path}`);
+  } catch (error) {
+    $('#todo-status').val(`Load failed: ${describeError(error)}`);
+  }
+}
+```
+
+```js back
+import { resolve } from 'node:path';
+
+function todoPath(input) {
+  const value = String(input ?? '').trim();
+  if (!value) throw new Error('Enter a JSON file path first');
+  return resolve(value);
+}
+
+function validateTodoObject(obj) {
+  if (!obj || typeof obj !== 'object' || !Array.isArray(obj.todos))
+    throw new Error('Todo JSON must be an object containing a todos array');
+
+  return {
+    todos: obj.todos.map((item, index) => {
+      if (!item || typeof item !== 'object' || typeof item.value !== 'string')
+        throw new Error(`Todo item ${index + 1} must contain a string value`);
+      return { value: item.value, checked: Boolean(item.checked) };
+    }),
+  };
+}
+
+export async function saveTodoList(input, obj) {
+  const path = todoPath(input);
+  const validated = validateTodoObject(obj);
+  await Bun.write(path, JSON.stringify(validated, null, 1) + '\n');
+  return { path };
+}
+
+export async function loadTodoList(input) {
+  const path = todoPath(input);
+  const file = Bun.file(path);
+  if (!await file.exists()) throw new Error(`Todo file not found: ${path}`);
+  const obj = validateTodoObject(JSON.parse(await file.text()));
+  return { path, obj };
+}
 ```

package/edit

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+':' //; sd=$(dirname "$(realpath "$0")")
+
+':' //; exec bun "$sd"/src/index.js --edit "$@"
+
+process.argv.splice(2,0,'--edit')
+
+await import('./src/index.js')

package/llm-maze.txt

@@ -0,0 +1,94 @@
+你正在透過 Bun.WebView 操作 jsmdcui TUI App。
+
+CDP 連線位址：
+
+ws://127.0.0.1:9222/devtools/browser/cdp-server
+
+可用操作：
+
+1. 取得完整純文字 UI：
+
+   await view.evaluate("micro.getAllText()")
+
+2. 取得包含 ANSI 樣式與 OSC 8 link 的完整 UI：
+
+   await view.evaluate("micro.getAllAnsiText()")
+
+3. 點擊 buffer 座標：
+
+   await view.click(column, line)
+
+   column 與 line 都是 1-based。
+   這是整份 buffer 的座標，不是螢幕 pixel。
+   不支援 selector click。
+
+4. 發送真正的鍵盤事件：
+
+   await view.press("ArrowUp")
+   await view.press("ArrowDown")
+   await view.press("ArrowLeft")
+   await view.press("ArrowRight")
+   await view.press("r", { modifiers: ["Control"] })
+
+5. 每次 click 或 press 後，重新取得 UI 快照確認結果。
+
+Maze 操作方式：
+
+先在 micro.getAllText() 中找到包含 "Put the cursor here" 的行，計算該文字的
+1-based column/line，然後 click 該位置，讓 Maze controls 取得焦點。
+
+Maze controls 取得焦點後：
+
+- ArrowUp：上
+- ArrowDown：下
+- ArrowLeft：左
+- ArrowRight：右
+- Ctrl-R：重新開始
+
+每次移動後可讀取狀態：
+
+await view.evaluate("$('#last-key').val()")
+
+取得完整迷宮畫面：
+
+await view.evaluate("$('#character').val()")
+
+看到狀態包含 "Escaped the maze" 代表成功。抵達終點時不會呼叫 alert；大型
+慶祝內容會直接顯示在 character 區域，並提示使用 Ctrl-R 重新開始。
+
+初始化與聚焦 controls 的範例：
+
+const view = new Bun.WebView({
+  backend: {
+    type: "chrome",
+    url: "ws://127.0.0.1:9222/devtools/browser/cdp-server",
+  },
+});
+
+const cell = await view.evaluate(`
+  (() => {
+    const lines = micro.getAllText().split("\\n");
+    const y = lines.findIndex(line =>
+      line.includes("Put the cursor here")
+    );
+
+    return {
+      x: lines[y].indexOf("Put the cursor here") + 1,
+      y: y + 1,
+    };
+  })()
+`);
+
+await view.click(cell.x, cell.y);
+await view.press("r", { modifiers: ["Control"] });
+
+alert 注意事項：
+
+Maze 抵達終點不會觸發 alert。不過 jsmdcui 其他操作若呼叫同步 alert()，CDP
+operation 會等待使用者直接在實際 terminal 按 Enter 關閉；alert 阻塞期間，無法
+再透過 view.press("Enter") 關閉它。無人值守自動化應避免觸發同步 alert，或預先
+提供替代的 dialog handling。
+
+操作完成後呼叫：
+
+view.close();

package/package.json

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

package/runmd.mjs

@@ -3,6 +3,7 @@
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { readInternalAssetText } from './src/runtime/assets.js'
+import { fenceEventMap } from './src/cui/fence-events.mjs'
 import { REPO_ROOT } from './single-exe/compiled.js'
 
 const csl=console.log
@@ -220,7 +221,7 @@ function escapeHtmlAttribute(value)
     .replaceAll(">", ">");
 }
 
-export function convertWuiTextareas(html)
+export function convertWuiTextareas(html, eventsById = new Map())
 {
   return String(html).replace(
     /<pre><code class="language-([^"]+)">([^]*?)<\/code><\/pre>/g,
@@ -230,10 +231,50 @@ export function convertWuiTextareas(html)
       const value = content.replace(/\n$/, "");
       const contentLines = value.split("\n");
       const cols = Math.max(1, ...contentLines.map(line => [...line].length));
+      const declaration = identity.id && eventsById.get(identity.id)?.tag === identity.tag
+        ? eventsById.get(identity.id)
+        : null;
+      const keydownHandler = declaration?.events.get("keydown");
+      const keydownCode = keydownHandler
+        ? [
+            "const __mdcuiKeyCode=Number(event.keyCode||event.which||0);",
+            "const __mdcuiCodeLetter=/^Key[A-Z]$/.test(event.code||\"\")?event.code.charCodeAt(3):0;",
+            "const __mdcuiLetterCode=__mdcuiKeyCode>=65&&__mdcuiKeyCode<=90?__mdcuiKeyCode:__mdcuiCodeLetter;",
+            "const __mdcuiAltGraph=!!event.getModifierState&&event.getModifierState(\"AltGraph\");",
+            "const __mdcuiLetter=!__mdcuiAltGraph&&(event.ctrlKey||event.altKey||event.metaKey)&&__mdcuiLetterCode>=65&&__mdcuiLetterCode<=90;",
+            "if(__mdcuiLetter)Object.defineProperty(event,\"key\",{configurable:true,value:String.fromCharCode(__mdcuiLetterCode+(event.shiftKey?0:32))});",
+            "this.__mdcuiIdentifiedKeydown=!!event.key&&event.key!==\"Unidentified\";",
+            "this.__mdcuiUnidentifiedKeydown=event.key===\"Unidentified\"?{keyCode:__mdcuiKeyCode,ctrlKey:!!event.ctrlKey,shiftKey:!!event.shiftKey,altKey:!!event.altKey,metaKey:!!event.metaKey,altGraph:__mdcuiAltGraph}:null;",
+            "clearTimeout(this.__mdcuiKeydownReset);",
+            "this.__mdcuiKeydownReset=setTimeout(()=>{this.__mdcuiIdentifiedKeydown=false;this.__mdcuiUnidentifiedKeydown=null},0);",
+            "if(event.key!==\"Unidentified\"){\n",
+            "Object.defineProperty(event,\"toJSON\",{configurable:true,value:function(){const t=this.target||{};return{type:String(this.type||\"\"),key:String(this.key||\"\"),code:String(this.code||\"\"),raw:String(this.raw||\"\"),ctrlKey:!!this.ctrlKey,shiftKey:!!this.shiftKey,altKey:!!this.altKey,metaKey:!!this.metaKey,repeat:!!this.repeat,defaultPrevented:!!this.defaultPrevented,target:{id:String(t.id||\"\"),tagName:String(t.tagName||\"\"),className:String(t.className||\"\"),value:String(t.value??\"\")}}}});",
+            keydownHandler.modifiers.includes("prevent")
+              ? "event.preventDefault();"
+              : "",
+            keydownHandler.code,
+            "\n}",
+          ].join("")
+        : "";
+      const beforeInputCode = keydownHandler
+        ? [
+            "if(!this.__mdcuiIdentifiedKeydown&&event.data!=null&&event.data!==\"\"){",
+            "const m=this.__mdcuiUnidentifiedKeydown||{};",
+            "const letter=!m.altGraph&&(m.ctrlKey||m.altKey||m.metaKey)&&m.keyCode>=65&&m.keyCode<=90?String.fromCharCode(m.keyCode+(m.shiftKey?0:32)):String(event.data);",
+            "Object.defineProperties(event,{key:{configurable:true,value:letter},ctrlKey:{configurable:true,value:!!m.ctrlKey},shiftKey:{configurable:true,value:!!m.shiftKey},altKey:{configurable:true,value:!!m.altKey},metaKey:{configurable:true,value:!!m.metaKey}});",
+            "this.onkeydown(event)",
+            "}",
+          ].join("")
+        : "";
+      const inlineEventAttrs = [
+        keydownCode ? `onkeydown="${escapeHtmlAttribute(keydownCode)}"` : "",
+        beforeInputCode ? `onbeforeinput="${escapeHtmlAttribute(beforeInputCode)}"` : "",
+      ];
       const attrs = [
         `data-mdcui-tag="${identity.tag}"`,
         `data-mdcui-language="${escapeHtmlAttribute(info)}"`,
         identity.id ? `id="${escapeHtmlAttribute(identity.id)}"` : "",
+        ...inlineEventAttrs,
         `class="${escapeHtmlAttribute([
           `language-${info}`,
           ...identity.classes,
@@ -306,6 +347,7 @@ export function wrapWuiHeadingSections(html)
 
 export async function createWui(md,mdpath) // HTML
 {
+  const eventsById = fenceEventMap(md)
   
   const opts = {
     headings: { ids: true }
@@ -335,7 +377,7 @@ export async function createWui(md,mdpath) // HTML
     }
   )
 
-  md = convertWuiTextareas(md)
+  md = convertWuiTextareas(md, eventsById)
   md = wrapWuiHeadingSections(md)
   
   const mdb = path.basename(mdpath);

package/runtime/help/cdp.md

@@ -22,6 +22,11 @@
 //   Once running, status bar shows:  CDP@<port> server running
 //   Running cdp again shows:         CDP@<port> already running
 //
+// ── Maze demo from the source tree ─────────────────────────────────────────
+//
+//   Start the maze, local CDP server, and automatic solver together:
+//     bun src/index.js --cdp-maze
+//
 // ── Connecting ─────────────────────────────────────────────────────────────
 //
 //   Bun.WebView: