jsmdcui 0.6.3 → 0.7.0

package/src/plugins/js-bridge.js

@@ -840,31 +840,185 @@ function _tuiHeadingLines(buffer) {
 }
 
 function _headingCheckboxValue(buffer, heading, id) {
+  const list = _tuiHeadingTaskList(buffer, heading);
+  if (!list) return id.startsWith("select") ? null : [];
+  const selected = [];
+  for (const item of list.items) {
+    const checkbox = String(buffer.lines[item.start] ?? "").match(/^(\s*)([☐☒])(?:\s+|$)(.*)$/);
+    if (checkbox?.[2] !== "☒") continue;
+    if (id.startsWith("select")) return item.value;
+    selected.push(item.value);
+  }
+  return id.startsWith("select") ? null : selected;
+}
+
+function _tuiHeadingTaskList(buffer, heading) {
+  const savedAnchor = buffer?._mdcuiHeadingTaskListAnchors?.get(heading.ordinal);
+  if (savedAnchor) {
+    return {
+      first: savedAnchor.index,
+      end: savedAnchor.index,
+      indent: savedAnchor.indent,
+      items: [],
+    };
+  }
   const headingLine = _headingTuiLine(buffer, heading);
-  if (!headingLine || !Array.isArray(buffer?.lines))
-    return id.startsWith("select") ? null : [];
+  if (!headingLine || !Array.isArray(buffer?.lines)) return null;
 
   const tuiHeadings = _tuiHeadingLines(buffer);
   const nextHeading = tuiHeadings[heading.ordinal + 1];
   const endLine = nextHeading?.line ?? buffer.lines.length + 1;
+  let first = -1;
+  let indent = "";
 
-  let optionIndent = null;
-  const selected = [];
-  for (let lineNumber = headingLine + 1; lineNumber < endLine; lineNumber++) {
-    const line = String(buffer.lines[lineNumber - 1] ?? "");
-    const checkbox = line.match(/^(\s*)([☐☒])(?:\s+|$)(.*)$/);
+  for (let y = headingLine; y < endLine - 1; y++) {
+    const checkbox = String(buffer.lines[y] ?? "").match(/^(\s*)[☐☒](?:\s+|$)/);
     if (!checkbox) continue;
-    const indent = checkbox[1].length;
-    if (optionIndent == null) optionIndent = indent;
-    if (indent !== optionIndent || checkbox[2] !== "☒") continue;
-    const value = checkbox[3].trim();
-    if (id.startsWith("select")) return value;
-    selected.push(value);
+    first = y;
+    indent = checkbox[1];
+    break;
   }
-  return id.startsWith("select") ? null : selected;
+  if (first < 0) return null;
+
+  let end = endLine - 1;
+  let pendingBlank = -1;
+  for (let y = first + 1; y < endLine - 1; y++) {
+    const line = String(buffer.lines[y] ?? "");
+    if (line.trim() === "") {
+      if (pendingBlank < 0) pendingBlank = y;
+      continue;
+    }
+    const leading = line.match(/^\s*/)?.[0].length ?? 0;
+    const checkbox = line.match(/^(\s*)[☐☒](?:\s+|$)/);
+    if (checkbox || leading > indent.length) {
+      pendingBlank = -1;
+      continue;
+    }
+    end = pendingBlank >= 0 ? pendingBlank : y;
+    break;
+  }
+  if (end === endLine - 1 && pendingBlank >= 0) end = pendingBlank;
+
+  const items = [];
+  for (let y = first; y < end; y++) {
+    const checkbox = String(buffer.lines[y] ?? "").match(/^(\s*)([☐☒])(?:\s+|$)(.*)$/);
+    if (checkbox && checkbox[1] === indent) {
+      items.push({
+        start: y,
+        end,
+        value: checkbox[3].trim(),
+      });
+    }
+  }
+  for (let index = 0; index < items.length - 1; index++)
+    items[index].end = items[index + 1].start;
+
+  return { first, end, indent, items };
+}
+
+function _normalizedSpliceRange(length, argumentCount, start, deleteCount) {
+  if (argumentCount === 0) return { start: 0, deleteCount: 0 };
+  let relativeStart = Number(start);
+  if (Number.isNaN(relativeStart)) relativeStart = 0;
+  relativeStart = Math.trunc(relativeStart);
+  const actualStart = relativeStart < 0
+    ? Math.max(length + relativeStart, 0)
+    : Math.min(relativeStart, length);
+  if (argumentCount === 1) return { start: actualStart, deleteCount: length - actualStart };
+  let requestedDelete = Number(deleteCount);
+  if (Number.isNaN(requestedDelete)) requestedDelete = 0;
+  requestedDelete = Math.max(0, Math.trunc(requestedDelete));
+  return {
+    start: actualStart,
+    deleteCount: Math.min(requestedDelete, length - actualStart),
+  };
 }
 
-function _spliceBufferLines(buffer, start, deleteCount, replacement) {
+function _tuiTaskItemReplacement(indent, inputs) {
+  const normalized = inputs.map((input) => {
+    const item = input && typeof input === "object"
+      ? { value: input.value ?? input.label ?? "", checked: Boolean(input.checked) }
+      : { value: input ?? "", checked: false };
+    return {
+      value: String(item.value).replace(/\r?\n/g, " "),
+      checked: item.checked,
+    };
+  });
+  return {
+    lines: normalized.map((item) =>
+      `${indent}${item.checked ? "☒" : "☐"} ${item.value}`,
+    ),
+    styles: normalized.map((item) => {
+      const styles = [];
+      if (item.checked) {
+        styles[indent.length] = { fg: "green" };
+        styles[indent.length + 1] = { fg: "green" };
+      }
+      return styles;
+    }),
+    ansi: normalized.map((item) =>
+      `${indent}\x1b[${item.checked ? "32" : "2"}m${item.checked ? "☒" : "☐"} \x1b[0m${item.value}`,
+    ),
+  };
+}
+
+function _mutateTuiHeadingList(buffer, heading, method, args) {
+  const list = _tuiHeadingTaskList(buffer, heading);
+  if (!list) {
+    if (method === "push" || method === "unshift") return 0;
+    if (method === "splice") return [];
+    return undefined;
+  }
+
+  if (method === "splice") {
+    const range = _normalizedSpliceRange(list.items.length, args.length, args[0], args[1]);
+    const removedItems = list.items.slice(range.start, range.start + range.deleteCount);
+    const removed = removedItems.map((item) => item.value);
+    const replacement = _tuiTaskItemReplacement(list.indent, args.slice(2));
+    if (range.deleteCount === 0 && replacement.lines.length === 0) return [];
+    const start = list.items[range.start]?.start ?? list.end;
+    const end = removedItems.at(-1)?.end ?? start;
+    if (range.deleteCount === list.items.length && replacement.lines.length === 0 && list.items.length > 0) {
+      if (!(buffer._mdcuiHeadingTaskListAnchors instanceof Map))
+        buffer._mdcuiHeadingTaskListAnchors = new Map();
+      buffer._mdcuiHeadingTaskListAnchors.set(heading.ordinal, { index: start, indent: list.indent });
+    }
+    _spliceBufferLines(buffer, start, end - start, replacement.lines, {
+      styles: replacement.styles,
+      ansi: replacement.ansi,
+    });
+    if (replacement.lines.length > 0)
+      buffer._mdcuiHeadingTaskListAnchors?.delete(heading.ordinal);
+    return removed;
+  }
+
+  if (method === "pop" || method === "shift") {
+    const item = method === "pop" ? list.items.at(-1) : list.items[0];
+    if (!item) return undefined;
+    if (list.items.length === 1) {
+      if (!(buffer._mdcuiHeadingTaskListAnchors instanceof Map))
+        buffer._mdcuiHeadingTaskListAnchors = new Map();
+      buffer._mdcuiHeadingTaskListAnchors.set(heading.ordinal, {
+        index: item.start,
+        indent: list.indent,
+      });
+    }
+    _spliceBufferLines(buffer, item.start, item.end - item.start, []);
+    return item.value;
+  }
+
+  const replacement = _tuiTaskItemReplacement(list.indent, args);
+  if (replacement.lines.length === 0) return list.items.length;
+  const start = method === "push" ? list.end : list.first;
+  _spliceBufferLines(buffer, start, 0, replacement.lines, {
+    styles: replacement.styles,
+    ansi: replacement.ansi,
+  });
+  if (replacement.lines.length > 0) buffer._mdcuiHeadingTaskListAnchors?.delete(heading.ordinal);
+  return list.items.length + replacement.lines.length;
+}
+
+function _spliceBufferLines(buffer, start, deleteCount, replacement, replacementMeta = {}) {
   const oldCursor = buffer.cursor ? { ...buffer.cursor } : null;
   buffer.lines.splice(start, deleteCount, ...replacement);
 
@@ -873,15 +1027,29 @@ function _spliceBufferLines(buffer, start, deleteCount, replacement) {
     buffer._ansiStyleLines.splice(
       start,
       deleteCount,
-      ...replacement.map(() => template),
+      ...(replacementMeta.styles ?? replacement.map(() => template)),
     );
   }
 
   if (typeof buffer._mdcuiAnsiText === "string") {
     const ansiLines = buffer._mdcuiAnsiText.split("\n");
-    ansiLines.splice(start, deleteCount, ...replacement);
+    ansiLines.splice(start, deleteCount, ...(replacementMeta.ansi ?? replacement));
     buffer._mdcuiAnsiText = ansiLines.join("\n");
   }
+  if (Array.isArray(buffer._mdcuiImages)) {
+    const delta = replacement.length - deleteCount;
+    buffer._mdcuiImages = buffer._mdcuiImages
+      .filter((image) => image.line < start || image.line >= start + deleteCount)
+      .map((image) => image.line >= start + deleteCount ? { ...image, line: image.line + delta } : image);
+  }
+  if (buffer._mdcuiHeadingTaskListAnchors instanceof Map) {
+    const oldEnd = start + deleteCount;
+    const delta = replacement.length - deleteCount;
+    for (const anchor of buffer._mdcuiHeadingTaskListAnchors.values()) {
+      if (anchor.index >= oldEnd) anchor.index += delta;
+      else if (anchor.index >= start) anchor.index = start;
+    }
+  }
 
   buffer.invalidateHighlightFrom?.(start, { force: replacement.length !== deleteCount });
   if (oldCursor) {
@@ -961,6 +1129,65 @@ export function createTuiSelector(getBuffer) {
           return args.length > 0 ? selection : "";
         }
       },
+      push(...items) {
+        try {
+          const buffer = getBuffer?.();
+          const heading = _findHeading(buffer, selector);
+          return heading ? _mutateTuiHeadingList(buffer, heading, "push", items) : 0;
+        } catch {
+          return 0;
+        }
+      },
+      pop() {
+        try {
+          const buffer = getBuffer?.();
+          const heading = _findHeading(buffer, selector);
+          return heading ? _mutateTuiHeadingList(buffer, heading, "pop", []) : undefined;
+        } catch {
+          return undefined;
+        }
+      },
+      shift() {
+        try {
+          const buffer = getBuffer?.();
+          const heading = _findHeading(buffer, selector);
+          return heading ? _mutateTuiHeadingList(buffer, heading, "shift", []) : undefined;
+        } catch {
+          return undefined;
+        }
+      },
+      unshift(...items) {
+        try {
+          const buffer = getBuffer?.();
+          const heading = _findHeading(buffer, selector);
+          return heading ? _mutateTuiHeadingList(buffer, heading, "unshift", items) : 0;
+        } catch {
+          return 0;
+        }
+      },
+      splice(...args) {
+        try {
+          const buffer = getBuffer?.();
+          const heading = _findHeading(buffer, selector);
+          return heading ? _mutateTuiHeadingList(buffer, heading, "splice", args) : [];
+        } catch {
+          return [];
+        }
+      },
+      slice(...args) {
+        try {
+          const buffer = getBuffer?.();
+          const heading = _findHeading(buffer, selector);
+          const list = heading ? _tuiHeadingTaskList(buffer, heading) : null;
+          if (!list) return [];
+          return list.items.map((item) => ({
+            value: item.value,
+            checked: String(buffer.lines[item.start] ?? "").match(/^(\s*)([☐☒])(?:\s+|$)/)?.[2] === "☒",
+          })).slice(...args);
+        } catch {
+          return [];
+        }
+      },
     };
     return selection;
   };

package/src/screen/screen.js

@@ -2,6 +2,7 @@ import process from "node:process";
 import { styleToAnsi } from "../display/ansi-style.js";
 import { CellBuffer } from "./cell-buffer.js";
 import { DISABLE_MOUSE, DISABLE_PASTE, ENABLE_MOUSE, ENABLE_PASTE, ResizeEvent } from "./events.js";
+import { logKittyPlacement } from "../cui/kitty-debug.mjs";
 
 const CURSOR_SHAPE_SEQUENCE = {
   default: "\x1b[0 q",
@@ -13,28 +14,45 @@ const CURSOR_SHAPE_SEQUENCE = {
   bar: "\x1b[6 q",
 };
 
+const KITTY_APC = "\x1b_G";
+const KITTY_ST = "\x1b\\";
+const KITTY_CHUNK_SIZE = 4096;
+
 export function cursorShapeSequence(shape) {
   return CURSOR_SHAPE_SEQUENCE[shape] ?? CURSOR_SHAPE_SEQUENCE.block;
 }
 
 export class Screen {
-  constructor({ mouse = true } = {}) {
+  constructor({ mouse = true, kittyMode = "off" } = {}) {
     this.mouse = mouse;
+    this.kittyMode = kittyMode;
     this.cols = process.stdout.columns || 80;
     this.rows = process.stdout.rows || 24;
     this.cells = new CellBuffer(this.cols, this.rows);
     this.previous = null;
     this.cursor = null;
     this.cursorVisible = false;
+    this.kittyImages = [];
+    this._shownKittySignature = "";
+    this._shownKittyIds = [];
+    this._transmittedKittyIds = new Set();
   }
 
   init() {
+    this._shownKittySignature = "";
+    this._shownKittyIds = [];
+    this._transmittedKittyIds.clear();
     this.write("\x1b[?1049h\x1b[?25l");
     if (this.mouse) this.write(ENABLE_MOUSE);
     this.write(ENABLE_PASTE);
   }
 
   fini() {
+    for (const id of this._transmittedKittyIds)
+      this.write(`${KITTY_APC}a=d,d=I,i=${id},q=2;${KITTY_ST}`);
+    this._shownKittySignature = "";
+    this._shownKittyIds = [];
+    this._transmittedKittyIds.clear();
     if (this.mouse) this.write(DISABLE_MOUSE);
     this.write(DISABLE_PASTE);
     this.write("\x1b[0 q\x1b[?25h\x1b[?1049l\x1b[0m");
@@ -97,6 +115,74 @@ export class Screen {
     if (this.cursor && this.cursorVisible) {
       out += cursorShapeSequence(this.cursor.shape) + this.move(this.cursor.y + 1, this.cursor.x + 1) + "\x1b[?25h";
     } else out += "\x1b[?25l";
+    const kittySignature = this.kittyImages.map((image) =>
+      `${image.id}:${image.placementId ?? image.id}:${image.x}:${image.y}:${image.cols}:${image.rows}:${image.sourceX ?? 0}:${image.sourceY ?? 0}:${image.sourceWidth ?? 0}:${image.sourceHeight ?? 0}`
+    ).join("|");
+    if (kittySignature !== this._shownKittySignature) {
+      logKittyPlacement("screen-overlay-change", {
+        previousSignature: this._shownKittySignature,
+        nextSignature: kittySignature,
+        deletingImageIds: this._shownKittyIds,
+        terminalCols: this.cols,
+        terminalRows: this.rows,
+        textCursor: this.cursor,
+        textCursorVisible: this.cursorVisible,
+      });
+      for (const id of this._shownKittyIds)
+        out += `${KITTY_APC}a=d,d=i,i=${id},q=2;${KITTY_ST}`;
+      for (const image of this.kittyImages) {
+        const transmitted = this._transmittedKittyIds.has(image.id);
+        logKittyPlacement("screen-placement-packet", {
+          imageId: image.id,
+          placementId: image.placementId ?? image.id,
+          zeroBasedX: image.x,
+          zeroBasedY: image.y,
+          csiCol: image.x + 1,
+          csiRow: image.y + 1,
+          cols: image.cols,
+          rows: image.rows,
+          sourceRect: image.sourceWidth && image.sourceHeight ? {
+            x: image.sourceX ?? 0,
+            y: image.sourceY ?? 0,
+            width: image.sourceWidth,
+            height: image.sourceHeight,
+          } : null,
+          C: 1,
+          mime: image.mime,
+          bytes: image.data?.length ?? 0,
+          action: transmitted ? "p" : "T",
+        });
+        out += this.move(image.y + 1, image.x + 1);
+        const placementFields = [
+          `i=${image.id}`, `p=${image.placementId ?? image.id}`, "q=2",
+          ...(image.sourceWidth && image.sourceHeight ? [
+            `x=${image.sourceX ?? 0}`,
+            `y=${image.sourceY ?? 0}`,
+            `w=${image.sourceWidth}`,
+            `h=${image.sourceHeight}`,
+          ] : []),
+          `c=${image.cols}`, `r=${image.rows}`, "C=1",
+          ...(this.kittyMode === "extended" && image.mime ? [`U=${image.mime}`] : []),
+        ];
+        if (transmitted) {
+          out += `${KITTY_APC}a=p,${placementFields.join(",")};${KITTY_ST}`;
+          continue;
+        }
+        const base64 = Buffer.from(image.data).toString("base64");
+        for (let offset = 0; offset < base64.length; offset += KITTY_CHUNK_SIZE) {
+          const payload = base64.slice(offset, offset + KITTY_CHUNK_SIZE);
+          const more = offset + KITTY_CHUNK_SIZE < base64.length;
+          const fields = [
+            "a=T", "f=100", "t=d", ...placementFields, `m=${more ? 1 : 0}`,
+          ];
+          out += `${KITTY_APC}${fields.join(",")};${payload}${KITTY_ST}`;
+        }
+        this._transmittedKittyIds.add(image.id);
+      }
+      if (this.cursor && this.cursorVisible) out += this.move(this.cursor.y + 1, this.cursor.x + 1);
+      this._shownKittySignature = kittySignature;
+      this._shownKittyIds = [...new Set(this.kittyImages.map((image) => image.id))];
+    }
     this.write(out);
     this.previous = this.cells.clone();
   }
@@ -110,6 +196,26 @@ export class Screen {
     this.cursorVisible = visible;
   }
 
+  setKittyImages(images = []) {
+    this.kittyImages = this.kittyMode === "off" ? [] : images;
+    logKittyPlacement("screen-frame-images", {
+      count: this.kittyImages.length,
+      kittyMode: this.kittyMode,
+      images: this.kittyImages.map((image) => ({
+        imageId: image.id,
+        placementId: image.placementId ?? image.id,
+        x: image.x,
+        y: image.y,
+        cols: image.cols,
+        rows: image.rows,
+        sourceX: image.sourceX ?? null,
+        sourceY: image.sourceY ?? null,
+        sourceWidth: image.sourceWidth ?? null,
+        sourceHeight: image.sourceHeight ?? null,
+      })),
+    });
+  }
+
   hideCursor() {
     this.cursorVisible = false;
     this.write("\x1b[?25l");
@@ -133,6 +239,7 @@ export class Screen {
     this.rows = process.stdout.rows || this.rows;
     this.cells.resize(this.cols, this.rows);
     this.previous = null;
+    this._shownKittySignature = "";
     return new ResizeEvent(this.cols, this.rows);
   }
 

package/tests/cat-markdown.test.js

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const tui = join(import.meta.dir, "..", "tui");
+const bunBin = Bun.which("bun") || process.argv0;
 
 test("cat renders .md files once with the implicit mdcui encoding", async () => {
   const dir = await mkdtemp(join(tmpdir(), "jsmdcui-cat-"));
@@ -12,12 +13,12 @@ test("cat renders .md files once with the implicit mdcui encoding", async () =>
   await writeFile(markdownPath, "# Heading\n\n- one\n- two\n");
 
   try {
-    const implicit = Bun.spawnSync([tui, "-cat", markdownPath], {
+    const implicit = Bun.spawnSync([bunBin, tui, "-cat", markdownPath], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
     });
-    const explicit = Bun.spawnSync([tui, "-cat", "-encoding", "mdcui", markdownPath], {
+    const explicit = Bun.spawnSync([bunBin, tui, "-cat", "-encoding", "mdcui", markdownPath], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -37,7 +38,7 @@ test("an explicit utf8 encoding overrides the .md mdcui default", async () => {
   await writeFile(markdownPath, "# Heading\n\n```js front\nalert('kept')\n```\n");
 
   try {
-    const result = Bun.spawnSync([tui, "-cat", "-encoding", "utf8", markdownPath], {
+    const result = Bun.spawnSync([bunBin, tui, "-cat", "-encoding", "utf8", markdownPath], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -58,12 +59,12 @@ test("--edit overrides the .md mdcui default with utf8", async () => {
   await writeFile(markdownPath, "# Heading\n\n```js front\nalert('editable')\n```\n");
 
   try {
-    const edit = Bun.spawnSync([tui, "-cat", "--edit", markdownPath], {
+    const edit = Bun.spawnSync([bunBin, tui, "-cat", "--edit", markdownPath], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
     });
-    const utf8 = Bun.spawnSync([tui, "-cat", "-encoding", "utf8", markdownPath], {
+    const utf8 = Bun.spawnSync([bunBin, tui, "-cat", "-encoding", "utf8", markdownPath], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",

package/tests/demo.test.js

@@ -4,9 +4,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const tui = join(import.meta.dir, "..", "tui");
+const bunBin = Bun.which("bun") || process.argv0;
 
 test("--help describes the non-overwriting demo behavior", () => {
-  const result = Bun.spawnSync([tui, "--help"], {
+  const result = Bun.spawnSync([bunBin, tui, "--help"], {
     stdout: "pipe",
     stderr: "pipe",
   });
@@ -15,14 +16,32 @@ test("--help describes the non-overwriting demo behavior", () => {
   const output = result.stdout.toString();
   expect(output).toContain("use the existing ./testapp.md without overwriting it");
   expect(output).toContain("If ./testapp.md is missing, write the bundled demo there first");
+  expect(output).toContain("--demo-<filename>");
+  expect(output).toContain("demos/<filename>.md");
+  expect(output.match(/Open it in the TUI and write 5 generated files beside it/g)?.length).toBe(2);
   expect(output).toContain("--demo-imgtool");
   expect(output).toContain("--demo-imgtool-zh");
 });
 
+test("--demo-list lists root and automatically discovered demos", () => {
+  const result = Bun.spawnSync([bunBin, tui, "--demo-list"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  expect(result.exitCode).toBe(0);
+  const output = result.stdout.toString();
+  expect(output).toMatch(/--demo\s+testapp\.md/);
+  expect(output).toMatch(/--demo-image-processor\s+demos\/image-processor\.md/);
+  expect(output).toMatch(/--demo-select\s+demos\/select\.md/);
+  expect(output).toMatch(/--demo-todo-zh\s+demos\/todo-zh\.md/);
+  expect(output).toContain("--demo-imgtool     --demo-image-processor");
+});
+
 test("--demo writes bundled testapp.md to cwd before opening it", async () => {
   const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-"));
   try {
-    const result = Bun.spawnSync([tui, "--demo", "-cat", "-encoding", "utf8"], {
+    const result = Bun.spawnSync([bunBin, tui, "--demo", "-cat", "-encoding", "utf8"], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -30,8 +49,8 @@ test("--demo writes bundled testapp.md to cwd before opening it", async () => {
 
     expect(result.exitCode).toBe(0);
     const written = await readFile(join(dir, "testapp.md"), "utf8");
-    expect(written).toContain("# jsmdcui");
-    expect(Bun.stripANSI(result.stdout.toString())).toContain("jsmdcui");
+    expect(written).toContain("計算機");
+    expect(Bun.stripANSI(result.stdout.toString())).toContain("計算機");
   } finally {
     await rm(dir, { recursive: true, force: true });
   }
@@ -42,7 +61,7 @@ test("--demo preserves an existing testapp.md", async () => {
   const existing = "# Keep my demo\n";
   try {
     await writeFile(join(dir, "testapp.md"), existing);
-    const result = Bun.spawnSync([tui, "--demo", "-cat", "-encoding", "utf8"], {
+    const result = Bun.spawnSync([bunBin, tui, "--demo", "-cat", "-encoding", "utf8"], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -56,10 +75,81 @@ test("--demo preserves an existing testapp.md", async () => {
   }
 });
 
+test("--demo-<filename> automatically loads a matching demos file", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-generic-"));
+  try {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-todo", "-cat", "-encoding", "utf8"], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(result.exitCode).toBe(0);
+    const written = await readFile(join(dir, "todo.md"), "utf8");
+    expect(written).toContain("# Todo List");
+    expect(written).toContain("javascript:addTodo()");
+    expect(Bun.stripANSI(result.stdout.toString())).toContain("Show Completed");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("--demo-<filename> preserves an existing local copy", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-generic-existing-"));
+  const existing = "# Keep my selector demo\n";
+  try {
+    await writeFile(join(dir, "select.md"), existing);
+    const result = Bun.spawnSync([bunBin, tui, "--demo-select", "-cat", "-encoding", "utf8"], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(await readFile(join(dir, "select.md"), "utf8")).toBe(existing);
+    expect(Bun.stripANSI(result.stdout.toString())).toContain("Keep my selector demo");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an unknown --demo-<filename> reports an error without creating a file", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-demo-unknown-"));
+  try {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-does-not-exist", "-cat", "-encoding", "utf8"], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr.toString()).toContain("Unknown demo --demo-does-not-exist");
+    expect(await Bun.file(join(dir, "does-not-exist.md")).exists()).toBe(false);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("--demo-image-processor works through generic demo discovery", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jsmdcui-imgtool-generic-"));
+  try {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-image-processor", "-cat", "-encoding", "utf8"], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(await readFile(join(dir, "image-processor.md"), "utf8")).toContain("# Bun.Image Processor");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("--demo-imgtool writes the bundled image processor to cwd", async () => {
   const dir = await mkdtemp(join(tmpdir(), "jsmdcui-imgtool-"));
   try {
-    const result = Bun.spawnSync([tui, "--demo-imgtool", "-cat", "-encoding", "utf8"], {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-imgtool", "-cat", "-encoding", "utf8"], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -80,7 +170,7 @@ test("--demo-imgtool preserves an existing image-processor.md", async () => {
   const existing = "# Keep my image tool\n";
   try {
     await writeFile(join(dir, "image-processor.md"), existing);
-    const result = Bun.spawnSync([tui, "--demo-imgtool", "-cat", "-encoding", "utf8"], {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-imgtool", "-cat", "-encoding", "utf8"], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -97,7 +187,7 @@ test("--demo-imgtool preserves an existing image-processor.md", async () => {
 test("--demo-imgtool-zh writes the bundled Traditional Chinese image processor to cwd", async () => {
   const dir = await mkdtemp(join(tmpdir(), "jsmdcui-imgtool-zh-"));
   try {
-    const result = Bun.spawnSync([tui, "--demo-imgtool-zh", "-cat", "-encoding", "utf8"], {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-imgtool-zh", "-cat", "-encoding", "utf8"], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",
@@ -118,7 +208,7 @@ test("--demo-imgtool-zh preserves an existing image-processor.zh-TW.md", async (
   const existing = "# 保留我的圖片工具\n";
   try {
     await writeFile(join(dir, "image-processor.zh-TW.md"), existing);
-    const result = Bun.spawnSync([tui, "--demo-imgtool-zh", "-cat", "-encoding", "utf8"], {
+    const result = Bun.spawnSync([bunBin, tui, "--demo-imgtool-zh", "-cat", "-encoding", "utf8"], {
       cwd: dir,
       stdout: "pipe",
       stderr: "pipe",