jsmdcui 0.5.0 → 0.7.0

package/src/index.js

@@ -98,11 +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, 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";
@@ -117,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";
 
@@ -311,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") {
@@ -335,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,
   };
 }
@@ -588,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++;
@@ -947,11 +976,14 @@ function parseArgs(argv) {
     options: false,
     help: false,
     clean: false,
+    check: false,
     cat: false,
     docs: false,
+    exportReadme: false,
     changelog: false,
     testapp: false,
-    demo: false,
+    demoList: false,
+    demo: null,
     allowUrl: false,
     buildExe: false,
     buildFor: "",
@@ -961,6 +993,7 @@ function parseArgs(argv) {
     plugin: "",
     cdpPort: 0,
     cdpAddress: "",
+    kittyMode: "off",
     settings: new Map(),
   };
   const files = [];
@@ -971,6 +1004,7 @@ function parseArgs(argv) {
     else if (arg === "-options") flags.options = true;
     else if (arg === "-help" || arg === "--help" || arg === "-h") flags.help = true;
     else if (arg === "-clean") flags.clean = true;
+    else if (arg === "--check") flags.check = true;
     else if (arg === "--cat" || arg === "-cat" || arg === "--ccat" || arg === "-ccat" || arg === "--bat" || arg === "-bat" || arg === "--glow" || arg === "-glow") flags.cat = true;
     else if (arg === "--xxd" || arg === "--hexdump") {
       flags.cat = true;
@@ -989,10 +1023,28 @@ function parseArgs(argv) {
       flags.settings.set("encoding", "utf-8");
     }
     else if (arg === "--docs" || arg === "--readme") flags.docs = true;
+    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-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;
@@ -1024,9 +1076,13 @@ function usage() {
   ${pkg.name} --wui [FILE.md]
 
 Modes:
+  --check FILE.md
+      Check heading and fenced-block IDs for collisions, print details, and exit
+      Exits 0 when IDs are unique, 1 on collisions, and 2 on usage/read errors
   --wui [FILE.md]
       Generate or overwrite Markdown UI files beside FILE.md and start the server
-      Without FILE.md, use testapp.md and write generated files in the current directory
+      Without FILE.md, use the existing ./testapp.md without overwriting it
+      If ./testapp.md is missing, write the bundled demo there first
   --cat, --ccat, --bat, --glow
       Render file(s) and write to stdout, then exit (.md uses mdcui/createTui)
       A local .md file also writes or overwrites five generated files beside it
@@ -1040,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
@@ -1060,6 +1120,8 @@ Information:
       Show version+backend info & exit
   --docs, --readme
       Show ${pkg.name}'s README.md & exit
+  --export-readme
+      Write or overwrite ./README.md with the bundled README.md & exit
   --changelog
       Show CHANGELOG.md & exit
   -profile, --profile
@@ -1068,12 +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
-      Outputs & overwrites ./testapp.md, opens it in the TUI, and writes 5 generated files
+      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-<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
+      Alias for --demo-image-processor
+  --demo-imgtool-zh
+      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
@@ -1121,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";
@@ -1134,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 };
@@ -1234,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`);
@@ -1247,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;
@@ -1650,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;
@@ -1682,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");
@@ -1705,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;
@@ -2376,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;
@@ -2610,6 +2692,7 @@ class App {
 
     const defaultStyle = this.context.colorscheme?.defaultStyle ?? {};
     this.screen.fill(" ", defaultStyle);
+    this._kittyFrameImages = [];
 
     this.tabRects = [];
     if (tabBarHeight) this.renderTabbar(defaultStyle);
@@ -2785,6 +2868,7 @@ class App {
       this.screen.setCursor(0, 0, false);
     }
 
+    this.screen.setKittyImages(this._kittyFrameImages);
     this.screen.show();
   }
 
@@ -2967,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;
@@ -2981,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) {
@@ -3024,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 {
@@ -3047,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 };
@@ -4062,6 +4213,28 @@ class App {
           return true;
         }
       }
+
+      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;
+      }
     
       this.message = `event ${payload.trigger}:`+
       `(${payload.row},${payload.col})`+
@@ -6754,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;
@@ -6773,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);
@@ -7483,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);
@@ -7498,8 +7674,17 @@ async function loadBuffers(files, command) {
 }
 
 async function printReadmeDocs() {
-  const readme = readInternalAssetText("README.md") ?? await Bun.file(join(REPO_ROOT, "README.md")).text();
-  process.stdout.write(Bun.markdown.ansi(readme, { hyperlinks: true }));
+  process.stdout.write(Bun.markdown.ansi(await bundledReadmeSource(), { hyperlinks: true }));
+}
+
+async function bundledReadmeSource() {
+  return readInternalAssetText("README.md") ?? await Bun.file(join(REPO_ROOT, "README.md")).text();
+}
+
+async function exportReadme() {
+  const readmePath = resolve("README.md");
+  await Bun.write(readmePath, await bundledReadmeSource());
+  console.log(`Wrote ${readmePath}`);
 }
 
 async function printChangelogDocs() {
@@ -7508,11 +7693,47 @@ async function printChangelogDocs() {
 }
 
 async function printTestappSource() {
-  process.stdout.write(await bundledTestappSource());
+  process.stdout.write(await bundledMarkdownSource("testapp.md"));
+}
+
+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);
 }
 
-async function bundledTestappSource() {
-  return readInternalAssetText("testapp.md") ?? await Bun.file(join(REPO_ROOT, "testapp.md")).text();
+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() {
@@ -7528,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());
@@ -7558,10 +7781,33 @@ async function main() {
     console.log("Clipboard:", backends);
     return;
   }
+  if (flags.check) {
+    if (rawFiles.length !== 1) {
+      console.error("Usage: jsmdcui --check FILE.md");
+      process.exitCode = 2;
+      return;
+    }
+    const checkPath = resolve(rawFiles[0]);
+    try {
+      const file = Bun.file(checkPath);
+      if (!(await file.exists())) throw new Error("file not found");
+      const result = checkMarkdownIdCollisions(await file.text());
+      process.stdout.write(formatMarkdownIdCheckAnsi(checkPath, result));
+      if (result.collisions.length) process.exitCode = 1;
+    } catch (error) {
+      console.error(`Cannot check ${checkPath}: ${error?.message || error}`);
+      process.exitCode = 2;
+    }
+    return;
+  }
   if (flags.docs) {
     await printReadmeDocs();
     return;
   }
+  if (flags.exportReadme) {
+    await exportReadme();
+    return;
+  }
   if (flags.changelog) {
     await printChangelogDocs();
     return;
@@ -7570,9 +7816,28 @@ async function main() {
     await printTestappSource();
     return;
   }
+  if (flags.demoList) {
+    printDemoList();
+    return;
+  }
   if (flags.demo) {
-    const demoPath = resolve("testapp.md");
-    await Bun.write(demoPath, await bundledTestappSource());
+    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, demoSource);
+    }
     rawFiles.splice(0, rawFiles.length, demoPath);
   }
   if (flags.options) {
@@ -7655,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