jsmdcui 0.6.3 → 0.8.0

package/src/platform/terminal.js

@@ -0,0 +1,5 @@
+import process from "node:process";
+
+export function controllingTerminalInputPath(platform = process.platform) {
+  return platform === "win32" ? "CONIN$" : "/dev/tty";
+}

package/src/plugins/js-bridge.js

@@ -752,6 +752,56 @@ function _findBlock(lines, selector) {
   return null;
 }
 
+export function findTuiBlockAtLine(lines, lineIndex) {
+  return findTuiBlockInIndex(buildTuiBlockIndex(lines), lineIndex);
+}
+
+export function buildTuiBlockIndex(lines, declarations = null) {
+  const blocks = [];
+  for (let start = 0; start < lines.length; start++) {
+    const header = _blockHeader(lines[start]);
+    if (!header) continue;
+    let end = lines.length;
+    for (let y = start + 1; y < lines.length; y++) {
+      const line = String(lines[y] ?? "");
+      const rest = line.startsWith(header.indent)
+        ? line.slice(header.indent.length)
+        : line;
+      if (header.kind === "fenced") {
+        const closing = rest.match(/^(`{3,})\s*$/);
+        if (!closing || closing[1].length < header.fenceLength) continue;
+      } else if (!/^(?:└─|╰─|\+-)\s*$/.test(rest)) {
+        continue;
+      }
+      end = y;
+      break;
+    }
+    const declaration = header.id ? declarations?.get(header.id) : null;
+    if (
+      declarations == null
+      || (
+        declaration?.tag === header.tag
+        && declaration.events?.size > 0
+      )
+    ) blocks.push({ start, end, header });
+    start = Math.max(start, end);
+  }
+  return blocks;
+}
+
+export function findTuiBlockInIndex(blocks, lineIndex) {
+  let low = 0;
+  let high = blocks.length - 1;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const block = blocks[middle];
+    if (lineIndex <= block.start) high = middle - 1;
+    else if (lineIndex >= block.end) low = middle + 1;
+    else return block;
+  }
+  return null;
+}
+
 function _blockValue(lines, selector) {
   const block = _findBlock(lines, selector);
   if (!block) return undefined;
@@ -840,32 +890,188 @@ 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 _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 });
+    }
+    spliceTuiBufferLines(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,
+      });
+    }
+    spliceTuiBufferLines(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;
+  spliceTuiBufferLines(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) {
+export function spliceTuiBufferLines(buffer, start, deleteCount, replacement, replacementMeta = {}) {
   const oldCursor = buffer.cursor ? { ...buffer.cursor } : null;
+  buffer._mdcuiFenceBlockIndex = null;
+  buffer._mdcuiControlBlockIndex = null;
   buffer.lines.splice(start, deleteCount, ...replacement);
 
   if (Array.isArray(buffer._ansiStyleLines)) {
@@ -873,15 +1079,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) {
@@ -897,24 +1117,70 @@ function _spliceBufferLines(buffer, start, deleteCount, replacement) {
   buffer.ensureCursor?.();
 }
 
+export function insertTuiTextareaNewline(buffer, block) {
+  if (!buffer || block?.header?.tag !== "textarea") return false;
+  const prefix = block.header.indent + block.header.bodyMarker + " ";
+  const line = String(buffer.lines?.[buffer.cursor.y] ?? "");
+  const left = line.slice(0, buffer.cursor.x);
+  const right = line.slice(buffer.cursor.x);
+  buffer.lines[buffer.cursor.y] = left;
+  spliceTuiBufferLines(buffer, buffer.cursor.y + 1, 0, [prefix + right]);
+  buffer.cursor.y++;
+  buffer.cursor.x = prefix.length;
+  buffer.ensureCursor?.();
+  return true;
+}
+
+export function mergeTuiTextareaBackward(buffer, block) {
+  if (!buffer || block?.header?.tag !== "textarea") return false;
+  const prefix = block.header.indent + block.header.bodyMarker + " ";
+  if (buffer.cursor.x > prefix.length || buffer.cursor.y <= block.start + 1) return false;
+  const previousY = buffer.cursor.y - 1;
+  const previousLength = String(buffer.lines?.[previousY] ?? "").length;
+  const line = String(buffer.lines?.[buffer.cursor.y] ?? "");
+  const body = line.startsWith(prefix) ? line.slice(prefix.length) : line;
+  buffer.lines[previousY] += body;
+  spliceTuiBufferLines(buffer, buffer.cursor.y, 1, []);
+  buffer.cursor.y = previousY;
+  buffer.cursor.x = previousLength;
+  buffer.ensureCursor?.();
+  return true;
+}
+
+export function mergeTuiTextareaForward(buffer, block) {
+  if (!buffer || block?.header?.tag !== "textarea") return false;
+  const line = String(buffer.lines?.[buffer.cursor.y] ?? "");
+  if (buffer.cursor.x < line.length || buffer.cursor.y >= block.end - 1) return false;
+  const prefix = block.header.indent + block.header.bodyMarker + " ";
+  const nextLine = String(buffer.lines?.[buffer.cursor.y + 1] ?? "");
+  const body = nextLine.startsWith(prefix) ? nextLine.slice(prefix.length) : nextLine;
+  buffer.lines[buffer.cursor.y] += body;
+  spliceTuiBufferLines(buffer, buffer.cursor.y + 1, 1, []);
+  buffer.ensureCursor?.();
+  return true;
+}
+
 function _setBlockValue(buffer, selector, value) {
   const lines = buffer.lines;
   const block = _findBlock(lines, selector);
   if (!block) return false;
 
-  const values = String(value ?? "").replace(/\r\n?/g, "\n").split("\n");
+  const normalizedValue = String(value ?? "").replace(/\r\n?/g, "\n");
+  if ((_blockValue(lines, selector) ?? "") === normalizedValue) return true;
+  buffer.pushUndo?.(true);
+  const values = normalizedValue.split("\n");
   const contentStart = block.start + 1;
   const capacity = Math.max(0, block.end - contentStart);
 
   if (block.header.kind === "fenced") {
     const replacement = values.map((line) => block.header.indent + line);
-    _spliceBufferLines(buffer, contentStart, capacity, replacement);
+    spliceTuiBufferLines(buffer, contentStart, capacity, replacement);
     return true;
   }
 
   const rowPrefix = block.header.indent + block.header.bodyMarker + " ";
   const replacement = values.map((line) => rowPrefix + line);
-  _spliceBufferLines(buffer, contentStart, capacity, replacement);
+  spliceTuiBufferLines(buffer, contentStart, capacity, replacement);
   return true;
 }
 
@@ -961,6 +1227,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;
   };
@@ -1002,7 +1327,12 @@ export function buildMicroGlobal(jsManager) {
     // ── Messaging ─────────────────────────────────────────────────
     Log:         (...args) => console.log(...args),
     TermMessage: (msg) => { const app = getApp(); if (app) { app.message = String(msg); if (app._started) app.render?.(); } },
-    alert: async (msg) => { const app = getApp(); if (app) await app.runAlert(msg); else console.log(String(msg)); },
+    alert: (msg) => { const app = getApp(); return app ? app.protectedAlert(msg) : console.log(String(msg)); },
+    confirm: (msg) => { const app = getApp(); return app ? app.protectedConfirm(msg) : false; },
+    prompt: (msg, defaultValue = "") => {
+      const app = getApp();
+      return app ? app.protectedPrompt(msg, defaultValue) : defaultValue;
+    },
 
     // ── Buffer line access (1-based line numbers; omit → cursor line) ─
 
@@ -1023,6 +1353,7 @@ export function buildMicroGlobal(jsManager) {
       const y = lineNumber != null ? Number(lineNumber) - 1 : buf.cursor.y;
       if (y < 0 || y >= buf.lines.length) return;
       buf.pushUndo?.();
+      buf._mdcuiFenceBlockIndex = null;
       const parts = String(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
       buf.lines.splice(y, 1, ...parts);
       buf.invalidateHighlightFrom?.(y, { force: parts.length > 1 });
@@ -1039,6 +1370,7 @@ export function buildMicroGlobal(jsManager) {
       const y = lineNumber != null ? Number(lineNumber) - 1 : buf.cursor.y;
       if (y < 0 || y >= buf.lines.length) return;
       buf.pushUndo?.();
+      buf._mdcuiFenceBlockIndex = null;
       if (buf.lines.length === 1) {
         buf.lines[0] = "";
       } else {
@@ -1079,6 +1411,7 @@ export function buildMicroGlobal(jsManager) {
       if (!app?.buffer) return;
       const buf = app.buffer;
       buf.pushUndo?.();
+      buf._mdcuiFenceBlockIndex = null;
       buf.lines = String(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
       if (buf.lines.length === 0) buf.lines = [""];
       buf.invalidateHighlightFrom?.(0, { force: true });

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",