jsmdcui 0.6.3 → 0.7.0

package/src/index.js

@@ -98,13 +98,15 @@ import { mkdir } from "node:fs/promises";
 import { dirname, basename, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import process from "node:process";
-import { toggleTaskCheckboxBeforeColumn } from "./cui/task-checkbox.mjs";
+import { toggleTaskCheckboxBeforeColumn, updateAnsiTaskCheckbox } from "./cui/task-checkbox.mjs";
 import { checkMarkdownIdCollisions, formatMarkdownIdCheckAnsi } from "./cui/id-collision.mjs";
+import { fitKittyImageToWidth, prepareKittyImages } from "./cui/kitty-images.mjs";
+import { logKittyPlacement } from "./cui/kitty-debug.mjs";
 import { Config } from "./config/config.js";
 import { defaultAllSettings, OPTION_CHOICES, LOCAL_SETTINGS } from "./config/defaults.js";
 import { cleanConfig } from "./config/clean.js";
 import { RuntimeRegistry, RTColorscheme, RTHelp } from "./runtime/registry.js";
-import { assetPath, hasInternalAssets, listInternalAssetDirs, readInternalAssetText } from "./runtime/assets.js";
+import { assetPath, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetText } from "./runtime/assets.js";
 //import { PluginManager } from "./plugins/manager.js";
 import { JsPluginManager, buildMicroGlobal, runAction, listActions } from "./plugins/js-bridge.js";
 import { Colorscheme } from "./config/colorscheme.js";
@@ -119,6 +121,10 @@ import { shellSplit } from "./shell/shell.js";
 import { styleToAnsi } from "./display/ansi-style.js";
 import { encodeBinaryToBuffer, decodeBinaryBytes } from "./buffer/fixed3-codec.js";
 import { writeBackup, removeBackup, applyBackup } from "./buffer/backup.js";
+
+let kittyImageMode = "off";
+let allowRemoteKittyImages = false;
+const remoteMarkdownSources = new Map();
 import { isHex3Encoding, isMdcuiEncoding } from "./runtime/encodings.js";
 import { createInterface } from "node:readline/promises";
 
@@ -313,7 +319,12 @@ async function readTextFileWithEncoding(path, encoding = "utf-8", inferMdcui = t
 
 async function fetchTextWithEncoding(url, encoding = "utf-8", inferMdcui = true) {
   const bytes = await fetchHttpBytes(url);
-  return decodeAndRenderTextBytes(new Uint8Array(bytes), encodingForPath(url, encoding, inferMdcui));
+  return decodeAndRenderTextBytes(
+    new Uint8Array(bytes),
+    encodingForPath(url, encoding, inferMdcui),
+    process.stdout.columns || 80,
+    url,
+  );
 }
 
 function normalizeEncodingLabel(encoding = "utf-8") {
@@ -337,20 +348,30 @@ async function decodeAndRenderTextBytes(bytes, encoding = "utf-8", width = proce
   const decoded = decodeTextBytesWithEncoding(bytes, encoding);
   if (!isMdcuiEncoding(decoded.encoding)) return decoded;
   const renderWidth = Math.max(1, Math.trunc(Number(width) || 80));
-  const { rendered, tuiSourceText } = await renderMdcui(decoded.text, renderWidth, mdpath);
+  const { rendered, tuiSourceText, images } = await renderMdcui(decoded.text, renderWidth, mdpath, mdpath);
   const styled = parseAnsiStyledText(rendered);
-  return { text: styled.text, encoding: "mdcui", sourceText: decoded.text, tuiSourceText, ansiText: rendered, ansiStyleLines: styled.styleLines, mdcuiRenderWidth: renderWidth };
+  return { text: styled.text, encoding: "mdcui", sourceText: decoded.text, tuiSourceText, ansiText: rendered, ansiStyleLines: styled.styleLines, mdcuiImages: images, mdcuiRenderWidth: renderWidth };
 }
 
-async function renderMdcui(markdown, width = process.stdout.columns || 80, mdpath = null) {
+async function renderMdcui(markdown, width = process.stdout.columns || 80, mdpath = null, imageBasePath = mdpath) {
   const runmd = await import("../runmd.mjs");
   let md = String(markdown);
   if (mdpath && !isHttpUrl(mdpath)) {
     md = await runmd.extractJs(md, mdpath);
     await runmd.createWui(md, mdpath);
   }
+  const tui = runmd.createTui(md, Math.max(1, Math.trunc(Number(width) || 80)));
+  const resolvedImageBasePath = mdpath && !isHttpUrl(mdpath)
+    ? remoteMarkdownSources.get(resolve(mdpath)) ?? imageBasePath
+    : imageBasePath;
+  const prepared = kittyImageMode === "off"
+    ? { rendered: tui, images: [] }
+    : await prepareKittyImages(tui, resolvedImageBasePath, width, {
+      allowUrl: allowRemoteKittyImages,
+    });
   return {
-    rendered: runmd.createTui(md, Math.max(1, Math.trunc(Number(width) || 80))),
+    rendered: prepared.rendered,
+    images: prepared.images,
     tuiSourceText: md,
   };
 }
@@ -590,6 +611,12 @@ function resizeMdcuiTextBlock(buf, y, x) {
     ansiLines.splice(row, deleteCount, ...replacement);
     buf._mdcuiAnsiText = ansiLines.join("\n");
   }
+  if (Array.isArray(buf._mdcuiImages)) {
+    const delta = replacement.length - deleteCount;
+    buf._mdcuiImages = buf._mdcuiImages
+      .filter((image) => image.line < row || image.line >= row + deleteCount)
+      .map((image) => image.line >= row + deleteCount ? { ...image, line: image.line + delta } : image);
+  }
 
   if (insertAt >= 0) {
     if (buf.cursor.y >= insertAt) buf.cursor.y++;
@@ -955,10 +982,8 @@ function parseArgs(argv) {
     exportReadme: false,
     changelog: false,
     testapp: false,
-    demo: false,
-    demoSelect: false,
-    demoImgtool: false,
-    demoImgtoolZh: false,
+    demoList: false,
+    demo: null,
     allowUrl: false,
     buildExe: false,
     buildFor: "",
@@ -968,6 +993,7 @@ function parseArgs(argv) {
     plugin: "",
     cdpPort: 0,
     cdpAddress: "",
+    kittyMode: "off",
     settings: new Map(),
   };
   const files = [];
@@ -1000,11 +1026,25 @@ function parseArgs(argv) {
     else if (arg === "--export-readme") flags.exportReadme = true;
     else if (arg === "--changelog") flags.changelog = true;
     else if (arg === "--testapp.md") flags.testapp = true;
-    else if (arg === "--demo") flags.demo = true;
-    else if (arg === "--demo-select") flags.demoSelect = true;
-    else if (arg === "--demo-imgtool") flags.demoImgtool = true;
-    else if (arg === "--demo-imgtool-zh") flags.demoImgtoolZh = true;
+    else if (arg === "--demo-list") flags.demoList = true;
+    else if (arg === "--demo") {
+      flags.demo = { option: arg, filename: "testapp.md", asset: "testapp.md" };
+    }
+    else if (arg === "--demo-imgtool") {
+      flags.demo = { option: arg, filename: "image-processor.md", asset: "demos/image-processor.md" };
+    }
+    else if (arg === "--demo-imgtool-zh") {
+      flags.demo = { option: arg, filename: "image-processor.zh-TW.md", asset: "demos/image-processor.zh-TW.md" };
+    }
+    else if (arg.startsWith("--demo-")) {
+      const name = arg.slice("--demo-".length);
+      flags.demo = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)
+        ? { option: arg, filename: `${name}.md`, asset: `demos/${name}.md` }
+        : { option: arg, error: "demo filename must contain only letters, numbers, dots, underscores, and hyphens" };
+    }
     else if (arg === "--allow-url") flags.allowUrl = true;
+    else if (arg === "--kitty") flags.kittyMode = "extended";
+    else if (arg === "--kitty-compat") flags.kittyMode = "compat";
     else if (arg === "--build-exe") flags.buildExe = true;
     else if (arg === "--build-for") flags.buildFor = argv[++i] ?? "";
     else if (arg === "-debug") flags.debug = true;
@@ -1056,6 +1096,10 @@ Modes:
   -encoding mdcui
       Render Markdown through runmd.mjs#createTui; .md files use this automatically
       Writes .front.js, .back.js, .html, -rpc.js, and -server.js beside the .md file
+  --kitty
+      Display Markdown images with Kitty graphics and the jsgotty MIME extension
+  --kitty-compat
+      Display Markdown images with Kitty graphics without the non-standard MIME U field
 
 Settings:
   -SETTING VALUE
@@ -1086,22 +1130,23 @@ Information:
 Demo:
   --testapp.md
       Write the bundled testapp.md to stdout & exit
+  --demo-list
+      List the bundled demos and their command-line options, then exit
   --demo
       Use the existing ./testapp.md without overwriting it, or write the bundled demo if missing
       Open it in the TUI and write 5 generated files beside it
-  --demo-select
-      Use the existing ./select.md without overwriting it, or write the bundled demo if missing
+  --demo-<filename>
+      Load demos/<filename>.md, preserving an existing ./<filename>.md or writing the bundled copy
       Open it in the TUI and write 5 generated files beside it
+      For example: --demo-select, --demo-todo, or --demo-todo-zh
   --demo-imgtool
-      Use the existing ./image-processor.md without overwriting it, or write the bundled demo if missing
-      Open the Bun.Image processor in the TUI and write 5 generated files beside it
+      Alias for --demo-image-processor
   --demo-imgtool-zh
-      Use the existing ./image-processor.zh-TW.md without overwriting it, or write the bundled demo if missing
-      Open the Traditional Chinese Bun.Image processor in the TUI and write 5 generated files beside it
+      Alias for --demo-image-processor.zh-TW
 
 Remote Markdown:
   --allow-url
-      Download HTTP(S) Markdown to cwd, write 5 generated files, and allow its code to run
+      Download HTTP(S) Markdown and, with Kitty mode, its HTTP(S) images; allow its code to run
 
 Experimental:
   --build-exe                   Build a Bun single-file executable and exit
@@ -1149,7 +1194,7 @@ class BufferModel {
   get searchPattern() { return this._searchPattern ?? ""; }
   set searchPattern(v) { this._searchPattern = v ?? ""; this.searchMatches?.clear(); }
 
-  constructor({ path = "", text = "", command = {}, type = "default", readonly = false, modTimeMs = null, encoding = DEFAULT_SETTINGS.encoding, ansiStyleLines = null, ansiText = null, sourceText = null, tuiSourceText = null, mdcuiRenderWidth = 0 } = {}) {
+  constructor({ path = "", text = "", command = {}, type = "default", readonly = false, modTimeMs = null, encoding = DEFAULT_SETTINGS.encoding, ansiStyleLines = null, ansiText = null, sourceText = null, tuiSourceText = null, mdcuiImages = null, mdcuiRenderWidth = 0 } = {}) {
     this.path = path;
     this.type = type;
     this.name = path ? basename(path) : "No name";
@@ -1162,6 +1207,7 @@ class BufferModel {
     this._mdcuiAnsiText = isMdcuiEncoding(this.encoding) ? String(ansiText ?? "") : null;
     this._mdcuiSourceText = isMdcuiEncoding(this.encoding) ? String(sourceText ?? text) : null;
     this._mdcuiTuiSourceText = isMdcuiEncoding(this.encoding) ? String(tuiSourceText ?? sourceText ?? text) : null;
+    this._mdcuiImages = isMdcuiEncoding(this.encoding) ? (mdcuiImages ?? []) : [];
     this._mdcuiRenderWidth = Math.trunc(Number(mdcuiRenderWidth) || 0);
     this.cursor = { x: 0, y: 0 };
     this.scroll = { x: 0, y: 0, row: 0 };
@@ -1262,6 +1308,7 @@ class BufferModel {
     let sourceText = null;
     let tuiSourceText = null;
     let mdcuiRenderWidth = 0;
+    let mdcuiImages = null;
     if (existsSync(path)) {
       const info = statSync(path);
       if (info.isDirectory()) throw new Error(`${path} is a directory`);
@@ -1275,9 +1322,10 @@ class BufferModel {
       sourceText = decoded.sourceText ?? null;
       tuiSourceText = decoded.tuiSourceText ?? null;
       mdcuiRenderWidth = decoded.mdcuiRenderWidth ?? 0;
+      mdcuiImages = decoded.mdcuiImages ?? null;
       if (isMdcuiEncoding(encoding)) readonly = true;
     }
-    const buffer = new BufferModel({ path, text, command, readonly, modTimeMs, encoding, ansiStyleLines, ansiText, sourceText, tuiSourceText, mdcuiRenderWidth });
+    const buffer = new BufferModel({ path, text, command, readonly, modTimeMs, encoding, ansiStyleLines, ansiText, sourceText, tuiSourceText, mdcuiImages, mdcuiRenderWidth });
     buffer._configDir = context?.config?.configDir ?? null;
     attachSyntax(buffer, context, path, text);
     return buffer;
@@ -1678,6 +1726,7 @@ class BufferModel {
       this._mdcuiSourceText = isMdcuiEncoding(this.encoding) ? String(decoded.sourceText ?? text) : null;
       this._mdcuiTuiSourceText = isMdcuiEncoding(this.encoding) ? String(decoded.tuiSourceText ?? decoded.sourceText ?? text) : null;
       this._mdcuiRenderWidth = decoded.mdcuiRenderWidth ?? 0;
+      this._mdcuiImages = decoded.mdcuiImages ?? [];
       const readonly = isMdcuiEncoding(this.encoding);
       this.fileformat = detectFileFormat(text, this.Settings.fileformat ?? DEFAULT_SETTINGS.fileformat);
       this.Settings.fileformat = this.fileformat;
@@ -1710,6 +1759,7 @@ class BufferModel {
     this._mdcuiSourceText = isMdcuiEncoding(this.encoding) ? String(decoded.sourceText ?? text) : null;
     this._mdcuiTuiSourceText = isMdcuiEncoding(this.encoding) ? String(decoded.tuiSourceText ?? decoded.sourceText ?? text) : null;
     this._mdcuiRenderWidth = decoded.mdcuiRenderWidth ?? 0;
+    this._mdcuiImages = decoded.mdcuiImages ?? [];
     this.fileformat = detectFileFormat(text, this.Settings.fileformat ?? DEFAULT_SETTINGS.fileformat);
     this.Settings.fileformat = this.fileformat;
     this.lines = normalizeBufferText(text).split("\n");
@@ -1733,12 +1783,13 @@ class BufferModel {
     if (!isMdcuiEncoding(this.encoding) || this._mdcuiTuiSourceText == null) return false;
     const renderWidth = Math.max(1, Math.trunc(Number(width) || 80));
     if (renderWidth === this._mdcuiRenderWidth) return false;
-    const { rendered } = await renderMdcui(this._mdcuiTuiSourceText, renderWidth);
+    const { rendered, images } = await renderMdcui(this._mdcuiTuiSourceText, renderWidth, null, this.path);
     const styled = parseAnsiStyledText(rendered);
     this.lines = normalizeBufferText(styled.text).split("\n");
     if (this.lines.length === 0) this.lines = [""];
     this._ansiStyleLines = styled.styleLines;
     this._mdcuiAnsiText = rendered;
+    this._mdcuiImages = images;
     this._mdcuiRenderWidth = renderWidth;
     this.fileformat = detectFileFormat(styled.text, this.Settings.fileformat ?? DEFAULT_SETTINGS.fileformat);
     this.Settings.fileformat = this.fileformat;
@@ -2404,7 +2455,10 @@ class App {
     this.clipboard = new ClipboardManager();
     this.context = context;
     this.shellRunning = false;
-    this.screen = new Screen({ mouse: DEFAULT_SETTINGS.mouse !== false });
+    this.screen = new Screen({
+      mouse: DEFAULT_SETTINGS.mouse !== false,
+      kittyMode: context.kittyMode ?? "off",
+    });
     this.tabRects = [];
     this._escBuf = null;   // pending lone ESC bytes waiting for alt-key combo
     this._escTimer = null;
@@ -2638,6 +2692,7 @@ class App {
 
     const defaultStyle = this.context.colorscheme?.defaultStyle ?? {};
     this.screen.fill(" ", defaultStyle);
+    this._kittyFrameImages = [];
 
     this.tabRects = [];
     if (tabBarHeight) this.renderTabbar(defaultStyle);
@@ -2813,6 +2868,7 @@ class App {
       this.screen.setCursor(0, 0, false);
     }
 
+    this.screen.setKittyImages(this._kittyFrameImages);
     this.screen.show();
   }
 
@@ -2995,6 +3051,59 @@ class App {
       ? (this.context.colorscheme.get("cursor-line")?.fg ?? null)
       : null;
 
+    const addKittyImage = (lineNo, screenRow, subRow = 0) => {
+      if (subRow !== 0 || !Array.isArray(buf._mdcuiImages)) return;
+      for (const image of buf._mdcuiImages) {
+        if (image.line !== lineNo) continue;
+        const { cols, rows } = fitKittyImageToWidth(image, maxW);
+        const visibleTop = Math.max(pane.y, screenRow);
+        const visibleBottom = Math.min(pane.y + pane.h, screenRow + rows);
+        const visibleRows = visibleBottom - visibleTop;
+        if (visibleRows < 1 || cols < 1) continue;
+        const clippedTopRows = visibleTop - screenRow;
+        const pixelHeight = Math.max(1, Math.trunc(Number(image.pixelHeight) || 1));
+        const sourceY = Math.min(pixelHeight - 1, Math.round(pixelHeight * clippedTopRows / rows));
+        const sourceBottom = Math.min(pixelHeight, Math.round(pixelHeight * (clippedTopRows + visibleRows) / rows));
+        const sourceHeight = Math.max(1, sourceBottom - sourceY);
+        const sourceWidth = Math.max(1, Math.trunc(Number(image.pixelWidth) || 1));
+        const x = pane.x + gutterW;
+        const placementId = ((image.id ^ Math.imul(x + 1, 73856093) ^ Math.imul(visibleTop + 1, 19349663) ^ Math.imul(sourceY + 1, 83492791)) >>> 0) % 2147483646 + 1;
+        logKittyPlacement("app-placement", {
+          buffer: buf.path,
+          imagePath: image.path,
+          imageId: image.id,
+          placementId,
+          imageLogicalLine: image.line,
+          renderedLine: lineNo,
+          subRow,
+          pane: { x: pane.x, y: pane.y, width: pane.w, height: pane.h },
+          scroll: { ...buf.scroll },
+          gutterWidth: gutterW,
+          maxWidth: maxW,
+          screenX: x,
+          nominalScreenY: screenRow,
+          screenY: visibleTop,
+          cols,
+          rows: visibleRows,
+          originalCols: image.cols,
+          originalRows: image.rows,
+          sourceRect: { x: 0, y: sourceY, width: sourceWidth, height: sourceHeight },
+        });
+        this._kittyFrameImages.push({
+          ...image,
+          x,
+          y: visibleTop,
+          cols,
+          rows: visibleRows,
+          sourceX: 0,
+          sourceY,
+          sourceWidth,
+          sourceHeight,
+          placementId,
+        });
+      }
+    };
+
     const hasDiff   = (buf.Settings?.diffgutter ?? false) && !!buf.diffBase;
     if (hasDiff && !buf._diffOnUpdate) buf._diffOnUpdate = () => this.render();
     const diffMarks = hasDiff ? getDiffMarkers(buf) : null;
@@ -3009,6 +3118,18 @@ class App {
     const msgWarnStyle = cs?.styles?.has("gutter-warning") ? cs.get("gutter-warning") : defaultStyle;
     const msgErrStyle = cs?.styles?.has("gutter-error") ? cs.get("gutter-error") : defaultStyle;
 
+    // When the image anchor has scrolled above the pane, its lower portion can
+    // still intersect the viewport. It will not be encountered by the normal
+    // visible-line loop, so add that clipped placement explicitly.
+    for (const image of buf._mdcuiImages ?? []) {
+      if (image.line >= buf.scroll.y) continue;
+      const nominalScreenRow = pane.y + image.line - buf.scroll.y;
+      const { rows } = fitKittyImageToWidth(image, maxW);
+      if (nominalScreenRow < pane.y && nominalScreenRow + rows > pane.y) {
+        addKittyImage(image.line, nominalScreenRow);
+      }
+    }
+
     const renderGutter = (lineNo, row, screenRow, subRow = 0) => {
       // Message indicator: 2 cols, '> ' with kind-based style (Go: drawGutter)
       if (msgW > 0) {
@@ -3052,6 +3173,7 @@ class App {
         if (lineNo < buf.lines.length) {
           const cells = renderHighlightedCells(buf, lineNo, buf.scroll.x, maxW, this.context.colorscheme, pane.selection, getLineSearchRanges(buf, lineNo), braceMatches, isCL ? clBg : null);
           putCells(this.screen, pane.x + gutterW, screenRow, cells, maxW);
+          addKittyImage(lineNo, screenRow);
         }
       }
     } else {
@@ -3075,6 +3197,7 @@ class App {
 
         const cells = renderHighlightedCells(buf, lineNo, segStart, maxW, this.context.colorscheme, pane.selection, _swSearchRanges, braceMatches, isCL ? clBg : null);
         putCells(this.screen, pane.x + gutterW, screenRow, cells, maxW);
+        addKittyImage(lineNo, screenRow, subRow);
 
         if (subRow + 1 < breaks.length) {
           sloc = { line: lineNo, row: subRow + 1 };
@@ -4094,6 +4217,22 @@ class App {
       const checkboxResult = toggleTaskCheckboxBeforeColumn(payload.line, x);
       if (checkboxResult.toggled) {
         buf.lines[y] = checkboxResult.line;
+        const checkboxStyle = checkboxResult.checked ? { fg: "green" } : null;
+        const styleLine = buf._ansiStyleLines?.[y];
+        if (Array.isArray(styleLine)) {
+          styleLine[checkboxResult.checkboxAt] = checkboxStyle;
+          if (checkboxResult.line[checkboxResult.checkboxAt + 1] === " ")
+            styleLine[checkboxResult.checkboxAt + 1] = checkboxStyle;
+        }
+        if (typeof buf._mdcuiAnsiText === "string") {
+          const ansiLines = buf._mdcuiAnsiText.split("\n");
+          ansiLines[y] = updateAnsiTaskCheckbox(
+            ansiLines[y],
+            checkboxResult.checkboxAt,
+            checkboxResult.checked,
+          );
+          buf._mdcuiAnsiText = ansiLines.join("\n");
+        }
         buf.modified = true;
       }
     
@@ -6788,6 +6927,7 @@ async function loadBufferForPath(pathOrUrl, context, command = {}, { interactive
     if (!name.toLowerCase().endsWith(".md")) name += ".md";
     const localPath = resolve(name);
     await Bun.write(localPath, await fetchHttpBytes(pathOrUrl));
+    remoteMarkdownSources.set(localPath, new URL(pathOrUrl).href);
     return await loadBufferForPath(localPath, loadContext, command, { interactive });
   }
   let buffer;
@@ -6807,6 +6947,7 @@ async function loadBufferForPath(pathOrUrl, context, command = {}, { interactive
       sourceText: decoded.sourceText ?? null,
       tuiSourceText: decoded.tuiSourceText ?? null,
       mdcuiRenderWidth: decoded.mdcuiRenderWidth ?? 0,
+      mdcuiImages: decoded.mdcuiImages ?? null,
     });
     buffer._configDir = context?.config?.configDir ?? null;
     attachSyntax(buffer, loadContext, urlPath, text);
@@ -7517,6 +7658,7 @@ async function loadBuffers(files, command) {
       sourceText: decoded.sourceText ?? null,
       tuiSourceText: decoded.tuiSourceText ?? null,
       mdcuiRenderWidth: decoded.mdcuiRenderWidth ?? 0,
+      mdcuiImages: decoded.mdcuiImages ?? null,
     });
     if (loadBuffers.context) attachSyntax(stdinBuf, loadBuffers.context, "", stdinText);
     buffers.push(stdinBuf);
@@ -7558,6 +7700,42 @@ async function bundledMarkdownSource(filename) {
   return readInternalAssetText(filename) ?? await Bun.file(join(REPO_ROOT, filename)).text();
 }
 
+function availableDemoAssets() {
+  let paths;
+  if (hasInternalAssets()) {
+    paths = listInternalAssetPaths("demos");
+  } else {
+    try {
+      paths = readdirSync(join(REPO_ROOT, "demos"), { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => assetPath("demos", entry.name));
+    } catch {
+      paths = [];
+    }
+  }
+
+  return [...new Set(paths)]
+    .filter((path) => /^demos\/[^/]+\.md$/i.test(path))
+    .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+}
+
+function printDemoList() {
+  const demos = availableDemoAssets().map((asset) => ({
+    option: `--demo-${asset.slice("demos/".length, -".md".length)}`,
+    asset,
+  }));
+  const entries = [{ option: "--demo", asset: "testapp.md" }, ...demos];
+  const optionWidth = Math.max(...entries.map(({ option }) => option.length));
+
+  console.log("Available demos:\n");
+  for (const { option, asset } of entries) {
+    console.log(`  ${option.padEnd(optionWidth)}  ${asset}`);
+  }
+  console.log("\nCompatibility aliases:\n");
+  console.log("  --demo-imgtool     --demo-image-processor");
+  console.log("  --demo-imgtool-zh  --demo-image-processor.zh-TW");
+}
+
 async function main() {
   if (process.argv[2] === "--wui") {
     process.argv.splice(2, 1);
@@ -7571,6 +7749,8 @@ async function main() {
   await buildEarlyExit(null,DEFAULT_BUILD_OUTFILE)
   
   const { flags, files: rawFiles } = parseArgs(process.argv.slice(2));
+  kittyImageMode = flags.kittyMode;
+  allowRemoteKittyImages = flags.allowUrl;
 
   if (flags.help) {
     console.log(usage());
@@ -7636,19 +7816,27 @@ async function main() {
     await printTestappSource();
     return;
   }
-  const demoFilename = flags.demo
-    ? "testapp.md"
-    : flags.demoSelect
-      ? "select.md"
-      : flags.demoImgtool
-        ? "image-processor.md"
-        : flags.demoImgtoolZh
-          ? "image-processor.zh-TW.md"
-          : "";
-  if (demoFilename) {
-    const demoPath = resolve(demoFilename);
+  if (flags.demoList) {
+    printDemoList();
+    return;
+  }
+  if (flags.demo) {
+    if (flags.demo.error) {
+      console.error(`Invalid demo option ${flags.demo.option}: ${flags.demo.error}`);
+      process.exitCode = 2;
+      return;
+    }
+    let demoSource;
+    try {
+      demoSource = await bundledMarkdownSource(flags.demo.asset);
+    } catch {
+      console.error(`Unknown demo ${flags.demo.option}: ${flags.demo.asset} was not found`);
+      process.exitCode = 2;
+      return;
+    }
+    const demoPath = resolve(flags.demo.filename);
     if (!(await Bun.file(demoPath).exists())) {
-      await Bun.write(demoPath, await bundledMarkdownSource(demoFilename));
+      await Bun.write(demoPath, demoSource);
     }
     rawFiles.splice(0, rawFiles.length, demoPath);
   }
@@ -7732,7 +7920,16 @@ async function main() {
 
   const { files, command } = parseInput(rawFiles);
   const jsPlugins = new JsPluginManager();
-  const context = { colorscheme, syntaxDefinitions, config, runtime, jsPlugins, encodingExplicit, allowUrl: flags.allowUrl };
+  const context = {
+    colorscheme,
+    syntaxDefinitions,
+    config,
+    runtime,
+    jsPlugins,
+    encodingExplicit,
+    allowUrl: flags.allowUrl,
+    kittyMode: flags.kittyMode,
+  };
   jsPlugins.setContext(context);
   buildMicroGlobal(jsPlugins);   // sets globalThis.micro