jsmdcui 0.7.0 → 0.8.0

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/help.md

@@ -89,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
@@ -134,7 +139,7 @@ bun src/index.js --wui testapp.md
 | --- | --- |
 | `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-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. |
@@ -239,12 +244,81 @@ 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
 
@@ -384,7 +458,7 @@ 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. |
@@ -397,16 +471,16 @@ The available selector methods are:
 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)`.
@@ -489,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:

package/runtime/jsplugins/cdp/cdp.js

@@ -44,7 +44,10 @@ Other micro APIs:
                                  e.g. for command "js 1+1": args.raw = "js 1+1", args.raw.slice(3) = "1+1"
   micro.RegisterAction(name, fn) — register bindable action
   micro.TermMessage(msg)       — show msg in editor status row
-  micro.alert(msg)             — suspend editor, print msg, wait for Enter
+  micro.alert(msg)             — synchronous; suspend editor, print msg, wait for Enter
+                                 e.g. micro.alert("Done") (do not await)
+  micro.confirm(msg)           — synchronous boolean result
+  micro.prompt(msg, default?)  — synchronous string or null result
   micro.Log(...args)           — console.log passthrough
   micro.GetOption(name)        micro.SetOption(name, value)
   micro.cmd.save()             — call any editor command via proxy
@@ -169,7 +172,7 @@ micro.on("init", () => {
       const addr = isPublic ? `0.0.0.0:${port}` : `127.0.0.1:${port}`;
       micro.TermMessage(`CDP@${addr} server running 伺服器啟動了`)
 
-      //await micro.alert(CdpServer)
+      //micro.alert(CdpServer)
     }  //  server not running
     else
     {

package/runtime/jsplugins/chapter/chapter.js

@@ -43,7 +43,10 @@ Other micro APIs:
   micro.MakeCommand(name, fn)  — register Ctrl+E command; fn(bp, args[])
   micro.RegisterAction(name, fn) — register bindable action
   micro.TermMessage(msg)       — show msg in editor status row
-  micro.alert(msg)             — suspend editor, print msg, wait for Enter
+  micro.alert(msg)             — synchronous; suspend editor, print msg, wait for Enter
+                                 e.g. micro.alert("Done") (do not await)
+  micro.confirm(msg)           — synchronous boolean result
+  micro.prompt(msg, default?)  — synchronous string or null result
   micro.Log(...args)           — console.log passthrough
   micro.GetOption(name)        micro.SetOption(name, value)
   micro.cmd.save()             — call any editor command via proxy
@@ -105,4 +108,3 @@ micro.on("init", () => {
 
 });
 
-

package/runtime/jsplugins/example/example.js

@@ -45,7 +45,10 @@ Other micro APIs:
                                  e.g. for command "js 1+1": args.raw = "js 1+1", args.raw.slice(3) = "1+1"
   micro.RegisterAction(name, fn) — register bindable action
   micro.TermMessage(msg)       — show msg in editor status row
-  micro.alert(msg)             — suspend editor, print msg, wait for Enter
+  micro.alert(msg)             — synchronous; suspend editor, print msg, wait for Enter
+                                 e.g. micro.alert("Done") (do not await)
+  micro.confirm(msg)           — synchronous boolean result
+  micro.prompt(msg, default?)  — synchronous string or null result
   micro.Log(...args)           — console.log passthrough
   micro.GetOption(name)        micro.SetOption(name, value)
   micro.cmd.save()             — call any editor command via proxy
@@ -58,14 +61,14 @@ Other micro APIs:
 
 micro.on("init", () => {
   // Register a custom Ctrl+E command
-  micro.MakeCommand("showpath", async (bp, args) =>
+  micro.MakeCommand("showpath", (bp, args) =>
   {
     //micro.TermMessage("Hello from JS plugin! Args: " + args.join(", "));
 
-    //await micro.alert(micro.getLine())
+    //micro.alert(micro.getLine())
     const path = bp?.Buf?.Path || "(no path)";
     const loc = bp?.CursorLocation?.() || "+1.0:1";
-    await micro.alert(`${path}\n${loc}`)
+    micro.alert(`${path}\n${loc}`)
     
   });
   
@@ -75,12 +78,12 @@ micro.on("init", () => {
     // args.raw is the full original input string, e.g. "js console.log('hi')"
     // slice(3) skips the "js " prefix (2-char name + 1 space)
     const scriptText = args.raw?.slice(3) ?? args.join(" ");
-    await micro.alert(await eval(scriptText));
+    micro.alert(await eval(scriptText));
   });
   
 
   // greet: shows a message via micro.alert (leaves editor, shows text, Enter returns)
-  micro.MakeCommand("greet", async (bp, args) => 
+  micro.MakeCommand("greet", (bp, args) =>
   {
     const name = args.length ? 
                args.join(" ") : "world";
@@ -89,7 +92,7 @@ micro.on("init", () => {
       '# Hello\n- '+name
     );
     
-    await micro.alert(s);
+    micro.alert(s);
   });
 
   // Register a custom action (can be bound to a key in keybindings.json)

package/runtime/syntax/markdown.yaml

@@ -52,6 +52,7 @@ rules:
 # keywords
 # javascript alert confirm prompt rpc 
 # front back 
+# export function keydown 
 # console log error JSON stringify parse
 # async await Promise 
 # textarea text password search 

package/src/cui/fence-events.mjs

@@ -0,0 +1,106 @@
+const IDENTITY_RE = /^([A-Za-z_][\w:-]*)(?:#([A-Za-z_][\w:-]*))?((?:\.[A-Za-z_][\w:-]*)*)$/;
+
+function parseIdentity(value) {
+  const match = String(value ?? "").match(IDENTITY_RE);
+  if (!match) return null;
+  return {
+    tag: match[1],
+    id: match[2] || null,
+    classes: match[3] ? match[3].slice(1).split(".") : [],
+  };
+}
+
+function parseEventAttributes(text) {
+  const events = new Map();
+  let offset = 0;
+  while (offset < text.length) {
+    while (/\s/.test(text[offset] ?? "")) offset++;
+    if (offset >= text.length || text[offset] !== "@") break;
+    offset++;
+    const nameStart = offset;
+    while (/[A-Za-z0-9_.:-]/.test(text[offset] ?? "")) offset++;
+    const name = text.slice(nameStart, offset);
+    while (/\s/.test(text[offset] ?? "")) offset++;
+    if (!name || text[offset] !== "=") break;
+    offset++;
+    while (/\s/.test(text[offset] ?? "")) offset++;
+    if (text[offset] !== '"') break;
+    offset++;
+
+    let code = "";
+    let closed = false;
+    while (offset < text.length) {
+      const ch = text[offset++];
+      if (ch === '"') {
+        closed = true;
+        break;
+      }
+      if (ch === "\\" && offset < text.length) {
+        const next = text[offset++];
+        code += next === '"' || next === "\\" ? next : `\\${next}`;
+      } else {
+        code += ch;
+      }
+    }
+    if (!closed) break;
+    const [eventName, ...modifiers] = name.split(".");
+    if (eventName === "keydown")
+      events.set(eventName, { code, modifiers: [...new Set(modifiers.filter(Boolean))] });
+  }
+  return events;
+}
+
+export function parseFenceDeclarations(markdown) {
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  const declarations = [];
+  let fence = null;
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (fence) {
+      const closing = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
+      if (closing && closing[1][0] === fence.marker && closing[1].length >= fence.length)
+        fence = null;
+      continue;
+    }
+
+    const opening = line.match(/^ {0,3}(`{3,}|~{3,})([^]*)$/);
+    if (!opening) continue;
+    fence = { marker: opening[1][0], length: opening[1].length };
+    const info = String(opening[2] ?? "").trim();
+    const firstSpace = info.search(/\s/);
+    const identityText = firstSpace < 0 ? info : info.slice(0, firstSpace);
+    const attributesText = firstSpace < 0 ? "" : info.slice(firstSpace);
+    const identity = parseIdentity(identityText);
+    if (!identity) continue;
+    declarations.push({
+      ...identity,
+      identity: identityText,
+      events: parseEventAttributes(attributesText),
+      line: index + 1,
+      source: line.trim(),
+    });
+  }
+
+  return declarations;
+}
+
+export function fenceEventMap(markdown) {
+  const result = new Map();
+  for (const declaration of parseFenceDeclarations(markdown)) {
+    if (
+      !["text", "textarea"].includes(declaration.tag)
+      || !declaration.id
+      || declaration.events.size === 0
+      || result.has(declaration.id)
+    ) continue;
+    result.set(declaration.id, declaration);
+  }
+  return result;
+}
+
+export function inlineFenceEventCode(handler) {
+  if (!handler) return "";
+  const prefix = handler.modifiers.includes("prevent") ? "event.preventDefault();" : "";
+  return prefix + handler.code;
+}

package/src/cui/id-collision.mjs

@@ -1,3 +1,5 @@
+import { parseFenceDeclarations } from "./fence-events.mjs";
+
 function markdownHeadingDeclarations(markdown) {
   const lines = String(markdown).split(/\r?\n/);
   const declarations = [];
@@ -51,34 +53,14 @@ function markdownHeadingDeclarations(markdown) {
 }
 
 function fencedBlockDeclarations(markdown) {
-  const lines = String(markdown).split(/\r?\n/);
-  const declarations = [];
-  let fence = null;
-
-  for (let index = 0; index < lines.length; index++) {
-    const line = lines[index];
-    if (!fence) {
-      const opening = line.match(/^ {0,3}(`{3,}|~{3,})\s*(\S+)?\s*$/);
-      if (!opening) continue;
-      fence = { marker: opening[1][0], length: opening[1].length };
-      const identity = String(opening[2] ?? "").match(/^([A-Za-z_][\w:-]*)(?:#([A-Za-z_][\w:-]*))?(?:\.[A-Za-z_][\w:-]*)*$/);
-      if (identity?.[2]) {
-        declarations.push({
-          id: identity[2],
-          kind: `${identity[1]} fenced block`,
-          line: index + 1,
-          source: line.trim(),
-        });
-      }
-      continue;
-    }
-
-    const closing = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
-    if (closing && closing[1][0] === fence.marker && closing[1].length >= fence.length)
-      fence = null;
-  }
-
-  return declarations;
+  return parseFenceDeclarations(markdown)
+    .filter((declaration) => declaration.id)
+    .map((declaration) => ({
+      id: declaration.id,
+      kind: `${declaration.tag} fenced block`,
+      line: declaration.line,
+      source: declaration.source,
+    }));
 }
 
 export function checkMarkdownIdCollisions(markdown) {

package/src/cui/kitty-images.mjs

@@ -117,6 +117,10 @@ function stableImageId(pathname, line, data) {
   return (hash >>> 0) % 2147483646 + 1;
 }
 
+async function convertToKittyPng(data) {
+  return Buffer.from(await new Bun.Image(data).png().toBuffer());
+}
+
 export function fitKittyImageToWidth(image, maxCols) {
   const originalCols = Math.max(1, Math.trunc(Number(image?.cols) || 1));
   const originalRows = Math.max(1, Math.trunc(Number(image?.rows) || 1));
@@ -151,8 +155,14 @@ export async function prepareKittyImages(ansiText, markdownPath, terminalCols =
         if (!(await file.exists())) throw new Error("missing image");
         data = Buffer.from(await file.arrayBuffer());
       }
-      const size = imageSize(data);
+      let size = imageSize(data);
       if (!size?.width || !size?.height) throw new Error("unsupported image");
+      if (options.kittyMode === "compat" && size.mime !== "image/png") {
+        data = await convertToKittyPng(data);
+        size = imageSize(data);
+        if (size?.mime !== "image/png" || !size.width || !size.height)
+          throw new Error("PNG conversion failed");
+      }
       const estimatedCols = Math.max(1, Math.round(size.width / 8));
       const cols = Math.min(maxCols, estimatedCols);
       const rows = Math.max(1, Math.round((cols * size.height) / size.width / 2));

package/src/cui/rpc.mjs

@@ -451,15 +451,18 @@ function safeFrontValue(value)
   };
 }
 
-export async function evalFront(mod, text) 
+export async function evalFront(mod, text, scope = {})
 {
 try{
 
     text = text.replace(/^javascript:/, "");
 
-    const entries = Object.entries(mod).filter(([name]) => name !== "$");
+    const entryMap = new Map(Object.entries(mod).filter(([name]) => name !== "$"));
     if (typeof globalThis.$ === "function")
-      entries.push(["$", globalThis.$]);
+      entryMap.set("$", globalThis.$);
+    for (const [name, value] of Object.entries(scope))
+      entryMap.set(name, value);
+    const entries = [...entryMap];
     const names = entries.map(([name]) => name);
     const values = entries.map(([, value]) => safeFrontValue(value));
 

package/src/cui/server.mjs

@@ -50,7 +50,7 @@ export function main()
 
 const basePath = "/" + crypto.randomUUID()
 const pathname = basePath + "/"
-const server = Bun.serve({
+const serverOptions = {
   port: Number(process.env.PORT || 3000),
   development: {
     hmr: true,
@@ -101,7 +101,18 @@ const server = Bun.serve({
   fetch() {
     return new Response("Not Found", { status: 404 });
   },
-});
+};
+
+let server;
+try {
+  server = Bun.serve(serverOptions);
+} catch (error) {
+  const addressInUse = error?.code === "EADDRINUSE"
+    || error?.cause?.code === "EADDRINUSE"
+    || /EADDRINUSE|address already in use/i.test(String(error?.message || error));
+  if (serverOptions.port !== 3000 || !addressInUse) throw error;
+  server = Bun.serve({ ...serverOptions, port: 0 });
+}
 
 console.error(mda("- Bun RPC server listening on"));
 console.log(`http://localhost:${server.port}${pathname}`);