jsmdcui 0.6.3 → 0.7.0

package/runtime/help/help.md

@@ -47,9 +47,10 @@ On other platforms, follow the [official Bun installation guide](https://bun.com
 Choose either of these two ways to run jsmdcui.
 
 > **Important:** Opening or rendering a local `.md` file writes or overwrites
-> 5 generated files beside it. Starting `--wui` without a file writes the
-> 5 files generated from `testapp.md` in the current directory. The source
-> Markdown is not changed, but you should run the demo in a directory where
+> 5 generated files beside it. 
+> Starting `--wui` without a file or starting all the `--demo`s writes the
+> 5 files generated from `testapp.md` in the current directory. 
+> The source Markdown is not changed, but you should run the demo in a directory where
 > overwriting generated files is safe.
 
 ### Route 1: Run with npx
@@ -72,9 +73,10 @@ npx jsmdcui
 npx jsmdcui --demo
 ```
 
+List every bundled demo and its command-line option:
+
 ```sh
-# Heading and task-list selector demo
-npx jsmdcui --demo-select
+npx jsmdcui --demo-list
 ```
 
 ```sh
@@ -121,22 +123,31 @@ bun src/index.js --wui testapp.md
 
 ### Usage table
 
-- The command table below uses the cloned-source form. 
+- The command table below assumes you're running from a cloned repository 
 - If you use npx, replace `bun src/index.js` with `npx jsmdcui`
 
+- I've also provided short aliases
+  * bun ./tui = bun src/index.js
+  * bun ./wui = bun src/index.js --wui
+
 | Command | Result |
 | --- | --- |
 | `bun src/index.js app.md` | Render `app.md` as a read-only terminal UI and write five generated files beside it. |
+| `bun src/index.js --kitty app.md` | Display Markdown images with Kitty graphics and the jsgotty MIME extension. |
+| `bun src/index.js --kitty-compat app.md` | Display Markdown images with Kitty graphics without the non-standard MIME `U` field. |
+| `bun src/index.js --kitty --allow-url URL.md` | Download trusted HTTP(S) Markdown and its HTTP(S) images, then display supported images with Kitty graphics. |
+| `JSMDCUI_KITTY_DEBUG=1 bun src/index.js --kitty app.md` | Enable Kitty image placement logging to `kitty-placement.log`. |
 | `bun src/index.js --check app.md` | Check heading and fenced-block IDs for collisions, print line-by-line details, and exit. |
 | `bun src/index.js --edit app.md` | Open `app.md` as editable UTF-8 source, overriding automatic Markdown UI detection. |
 | `bun src/index.js --cat app.md` | Render the terminal version to stdout, write five generated files beside it, and exit. |
 | `bun src/index.js --testapp.md` | Write the bundled `testapp.md` source to stdout and exit. |
 | `bun src/index.js --export-readme` | Write or overwrite `./README.md` with the bundled README source and exit. |
+| `bun src/index.js --demo-list` | List `testapp.md` and every bundled `demos/*.md` example with its command-line option, then exit. |
 | `bun src/index.js --demo` | Use local `testapp.md` when present, otherwise write the bundled demo; open it in the terminal UI and write five generated files beside it. |
-| `bun src/index.js --demo-select` | Use local `select.md` when present, otherwise write the bundled selector demo; open it in the terminal UI and write five generated files beside it. |
-| `bun src/index.js --demo-imgtool` | Use local `image-processor.md` when present, otherwise write the bundled Bun.Image processor; open it in the terminal UI and write five generated files beside it. |
-| `bun src/index.js --demo-imgtool-zh` | Use local `image-processor.zh-TW.md` when present, otherwise write the bundled Traditional Chinese Bun.Image processor; open it in the terminal UI and write five generated files beside it. |
-| `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory, write 5 generated files, and allow its embedded code to run. Only use trusted URLs. |
+| `bun src/index.js --demo-<filename>` | Load `demos/<filename>.md`; preserve an existing local copy or write the bundled copy, then open it and generate its five companion files. New files added under `demos/` work automatically. |
+| `bun src/index.js --demo-imgtool` | Compatibility alias for `--demo-image-processor`. |
+| `bun src/index.js --demo-imgtool-zh` | Compatibility alias for `--demo-image-processor.zh-TW`. |
+| `bun src/index.js --allow-url URL.md` | Download HTTP(S) Markdown to the current directory and, with Kitty mode enabled, download its HTTP(S) images; write 5 generated files and allow embedded code to run. Only use trusted URLs. |
 | `bun src/index.js --wui` | Use local `testapp.md` when present, otherwise write the bundled demo; write five generated files in the current directory, then print and serve a random URL. |
 | `bun src/index.js --wui app.md` | Write five generated files beside `app.md`, then print and serve a random URL. |
 | `PORT=8080 bun src/index.js --wui app.md` | Start the browser UI on another port. |
@@ -239,9 +250,10 @@ non-empty content is never removed.
 
 Headings can act as form-group selectors. jsmdcui uses the IDs generated by
 `Bun.markdown.html(..., { headings: { ids: true } })`; for example,
-`## Select Color` becomes `#select-color`. A heading selection reads the first
-task list directly following that heading and stops at the next heading. Nested
-task items are not included in the outer list's value.
+`## Select Color` becomes `#select-color`. A heading selection reads direct
+task items from the first list following that heading and stops at the next
+heading. In the TUI, the first rendered `☐` or `☒` establishes that list and
+its indentation. Nested task items are not included in the outer list's value.
 
 Heading IDs share the same selector namespace as all explicitly named fenced
 blocks, not only `text` and `textarea`, so avoid name collisions between them.
@@ -306,14 +318,65 @@ $('#select-color').val() // "Green"
 $('#features').val()     // ["Search", "Offline mode"]
 ```
 
-The bundled `select.md` is a multilevel runnable example. Use `--demo-select`
+The first direct task list belonging to a heading can also be changed with
+Array-style methods. String arguments create unchecked items. Pass an object
+to choose the initial checked state:
+
+```js
+$('#features').push('Export')
+$('#features').unshift({ value: 'Import', checked: true })
+$('#features').splice(1, 2, 'Replacement')
+$('#features').slice(0, 2)
+$('#features').pop()
+$('#features').shift()
+```
+
+Like the corresponding `Array.prototype` methods, `.push(...items)` and
+`.unshift(...items)` accept multiple items and return the new number of direct
+items. `.pop()` and `.shift()` return the removed item's visible label, or
+`undefined` when the list is empty. Nested task items are part of their parent
+item: they are not counted separately, and are removed together with that
+parent. These methods change the rendered TUI/WUI state; they do not rewrite
+the source Markdown file. A heading must already have a task list before items
+can be added.
+
+`.splice(start, deleteCount, ...items)` follows `Array.prototype.splice()`:
+negative indexes count from the end, omitting `deleteCount` removes through the
+end, and the return value is an array containing the removed visible labels.
+
+`.slice(start, end)` is read-only and follows `Array.prototype.slice()`. It
+returns fresh item snapshots, including unchecked items, so changing the
+returned array or its objects does not change the rendered list:
+
+```js
+$('#features').slice()
+// [
+//   { value: 'Search', checked: true },
+//   { value: 'Notifications', checked: false },
+// ]
+```
+
+`demos/todo.md` and `demos/todo-zh.md` are runnable Todo examples that
+demonstrate `.push()`,
+`.splice()`, `.slice()`, and `{ value, checked }` snapshots using editable text
+controls instead of `prompt()` dialogs. Materialize one in the current
+directory with its demo flag, or open the source-tree copy directly:
+
+```sh
+bun src/index.js --demo-todo
+bun src/index.js --demo-todo-zh
+bun src/index.js demos/todo.md
+bun src/index.js --wui demos/todo-zh.md
+```
+
+The bundled `demos/select.md` is a multilevel runnable example. Use `--demo-select`
 to write it into the current directory when missing and open it in the TUI, or
 open it explicitly in either interface:
 
 ```sh
 bun src/index.js --demo-select
-bun src/index.js select.md
-bun src/index.js --wui select.md
+bun src/index.js demos/select.md
+bun src/index.js --wui demos/select.md
 ```
 
 The available selector methods are:
@@ -324,6 +387,12 @@ The available selector methods are:
 | `.val(value)` | Replace text-block contents and resize multiline values. | Set textarea/control values and resize textareas. |
 | `.html()` | Return a selected heading's inner HTML. | Return any successfully selected DOM element's `innerHTML`. |
 | `.line()` | Return a heading's current 1-based TUI row, or `0` if missing. | Not available. |
+| `.push(...items)` | Append unchecked strings or `{ value, checked }` task items; return the new direct-item count. | Same. |
+| `.pop()` | Remove and return the last direct task item's label, or `undefined`. | Same. |
+| `.shift()` | Remove and return the first direct task item's label, or `undefined`. | Same. |
+| `.unshift(...items)` | Prepend unchecked strings or `{ value, checked }` task items; return the new direct-item count. | Same. |
+| `.splice(start, deleteCount, ...items)` | Remove and insert direct task items; return the removed labels as an array. | Same. |
+| `.slice(start, end)` | Return `{ value, checked }` snapshots without changing the direct task items. | Same. |
 
 TUI heading rows are recalculated after text-block rows are added, removed, or
 replaced with multiline `.val(value)` content.
@@ -398,6 +467,19 @@ The terminal automatically reflows the Markdown when its width changes.
 Only `javascript:` links execute in the TUI; ordinary web links behave as
 normal links in the browser.
 
+Local Markdown images are displayed automatically in terminals that support
+the Kitty graphics protocol. Relative image paths are resolved from the
+Markdown file's directory. jsmdcui reads the image dimensions, reserves the
+corresponding terminal rows, and updates the placement when the document is
+scrolled, resized, or shown in a split pane. Unsupported or missing images, as
+well as remote images not authorized with `--allow-url`, retain Bun's normal
+linked `📷` fallback. To download trusted remote Markdown and display its
+supported HTTP(S) images with Kitty graphics, combine the options:
+
+```sh
+bun src/index.js --kitty --allow-url https://example.com/app.md
+```
+
 ## Browser interaction
 
 The WUI uses normal browser mouse and keyboard behavior. Clicking a
@@ -431,6 +513,13 @@ app.md-server.js
 They are regenerated from `app.md`, so edit the Markdown source rather than the
 generated files. The source directory must be writable.
 
+From the project directory, remove generated `*.md.*` and `*.md-*` companion
+files while keeping the Markdown source files:
+
+```sh
+bun ./clean.sh
+```
+
 ### Generated heading sections
 
 WUI output wraps each h1-h6 and its content in a hierarchical `<section>`.

package/single-exe/packAssets.sh

@@ -4,4 +4,4 @@ sd=$(dirname "$0")
 
 cd "$sd"/..
 
-tar -cvf single-exe/assets.tar runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md select.md image-processor.md image-processor.zh-TW.md
+tar -cvf single-exe/assets.tar demos runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md

package/src/cui/kitty-debug.mjs

@@ -0,0 +1,25 @@
+import { appendFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const KITTY_DEBUG_LOG = resolve(import.meta.dir, "../..", "kitty-placement.log");
+export const KITTY_DEBUG_ENABLED = /^(1|true|yes|on)$/i.test(
+  String(process.env.JSMDCUI_KITTY_DEBUG ?? ""),
+);
+
+if (KITTY_DEBUG_ENABLED) {
+  try {
+    writeFileSync(KITTY_DEBUG_LOG, "");
+  } catch {}
+}
+
+export function logKittyPlacement(stage, details = {}) {
+  if (!KITTY_DEBUG_ENABLED) return;
+  try {
+    appendFileSync(KITTY_DEBUG_LOG, JSON.stringify({
+      time: new Date().toISOString(),
+      pid: process.pid,
+      stage,
+      ...details,
+    }) + "\n");
+  } catch {}
+}

package/src/cui/kitty-images.mjs

@@ -0,0 +1,190 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logKittyPlacement } from "./kitty-debug.mjs";
+import { fetchHttpBytes as defaultFetchHttpBytes } from "../platform/commands.js";
+
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function imageSize(buffer) {
+  if (buffer.length >= 24 && buffer.subarray(0, 8).equals(PNG)) {
+    return { mime: "image/png", width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+  }
+  const gif = buffer.toString("ascii", 0, 6);
+  if (buffer.length >= 10 && (gif === "GIF87a" || gif === "GIF89a")) {
+    return { mime: "image/gif", width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) };
+  }
+  if (buffer.length >= 26 && buffer.toString("ascii", 0, 2) === "BM") {
+    return { mime: "image/bmp", width: Math.abs(buffer.readInt32LE(18)), height: Math.abs(buffer.readInt32LE(22)) };
+  }
+  if (buffer.length >= 16 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WEBP") {
+    const kind = buffer.toString("ascii", 12, 16);
+    if (kind === "VP8 " && buffer.length >= 30) {
+      return {
+        mime: "image/webp",
+        width: buffer.readUInt16LE(26) & 0x3fff,
+        height: buffer.readUInt16LE(28) & 0x3fff,
+      };
+    }
+    if (kind === "VP8L" && buffer.length >= 25) {
+      const bits = buffer[21] | (buffer[22] << 8) | (buffer[23] << 16) | (buffer[24] << 24);
+      return {
+        mime: "image/webp",
+        width: (bits & 0x3fff) + 1,
+        height: ((bits >> 14) & 0x3fff) + 1,
+      };
+    }
+    if (kind === "VP8X" && buffer.length >= 30) {
+      return {
+        mime: "image/webp",
+        width: 1 + buffer.readUIntLE(24, 3),
+        height: 1 + buffer.readUIntLE(27, 3),
+      };
+    }
+  }
+  if (buffer.length >= 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 8 < buffer.length) {
+      if (buffer[offset] !== 0xff) { offset++; continue; }
+      const marker = buffer[offset + 1];
+      offset += 2;
+      if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+      if (offset + 2 > buffer.length) break;
+      const length = buffer.readUInt16BE(offset);
+      if (length < 2 || offset + length > buffer.length) break;
+      const sof = (marker >= 0xc0 && marker <= 0xc3) ||
+        (marker >= 0xc5 && marker <= 0xc7) ||
+        (marker >= 0xc9 && marker <= 0xcb) ||
+        (marker >= 0xcd && marker <= 0xcf);
+      if (sof && length >= 7) {
+        return { mime: "image/jpeg", width: buffer.readUInt16BE(offset + 5), height: buffer.readUInt16BE(offset + 3) };
+      }
+      offset += length;
+    }
+  }
+  const svg = buffer.subarray(0, Math.min(buffer.length, 8192)).toString("utf8");
+  if (svg.includes("<svg")) {
+    const width = svg.match(/\bwidth=["']([0-9.]+)(?:px)?["']/i);
+    const height = svg.match(/\bheight=["']([0-9.]+)(?:px)?["']/i);
+    if (width && height) {
+      return { mime: "image/svg+xml", width: Math.round(Number(width[1])), height: Math.round(Number(height[1])) };
+    }
+    const viewBox = svg.match(/\bviewBox=["'][^"']*?([0-9.]+)[ ,]+([0-9.]+)\s*["']/i);
+    if (viewBox) {
+      return { mime: "image/svg+xml", width: Math.round(Number(viewBox[1])), height: Math.round(Number(viewBox[2])) };
+    }
+  }
+  return null;
+}
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value ?? ""));
+}
+
+function imageSource(href, markdownPath, allowUrl) {
+  try {
+    if (href.startsWith("file:")) return { kind: "local", value: fileURLToPath(href) };
+    if (process.platform === "win32" && /^[A-Za-z]:[\\/]/.test(href)) {
+      return { kind: "local", value: resolve(href) };
+    }
+    if (isHttpUrl(href)) {
+      return allowUrl ? { kind: "remote", value: new URL(href).href } : null;
+    }
+    if (href.startsWith("//")) {
+      if (!allowUrl) return null;
+      const protocol = isHttpUrl(markdownPath) ? new URL(markdownPath).protocol : "https:";
+      return { kind: "remote", value: new URL(`${protocol}${href}`).href };
+    }
+    if (/^[A-Za-z][A-Za-z\d+.-]*:/.test(href)) return null;
+    if (isHttpUrl(markdownPath)) {
+      return allowUrl ? { kind: "remote", value: new URL(href, markdownPath).href } : null;
+    }
+    const decoded = decodeURIComponent(href.replace(/[?#].*$/, ""));
+    return {
+      kind: "local",
+      value: resolve(markdownPath ? dirname(markdownPath) : process.cwd(), decoded),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function stableImageId(pathname, line, data) {
+  let hash = 2166136261;
+  for (const byte of Buffer.concat([Buffer.from(`${pathname}\0${line}\0`), data])) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) % 2147483646 + 1;
+}
+
+export function fitKittyImageToWidth(image, maxCols) {
+  const originalCols = Math.max(1, Math.trunc(Number(image?.cols) || 1));
+  const originalRows = Math.max(1, Math.trunc(Number(image?.rows) || 1));
+  const availableCols = Math.max(1, Math.trunc(Number(maxCols) || 1));
+  const cols = Math.min(originalCols, availableCols);
+  const rows = Math.max(1, Math.round(originalRows * cols / originalCols));
+  return { cols, rows };
+}
+
+export async function prepareKittyImages(ansiText, markdownPath, terminalCols = 80, options = {}) {
+  const inputLines = String(ansiText).split("\n");
+  const outputLines = [];
+  const images = [];
+  const maxCols = Math.max(1, Math.trunc(Number(terminalCols) || 80));
+  const oscImage = /\x1b\]8;;([^\x1b]*)\x1b\\(?=[^\n]*📷)/;
+
+  for (let sourceLine = 0; sourceLine < inputLines.length; sourceLine++) {
+    const line = inputLines[sourceLine];
+    const match = line.match(oscImage);
+    const source = match ? imageSource(match[1], markdownPath, options.allowUrl === true) : null;
+    if (!source) {
+      outputLines.push(line);
+      continue;
+    }
+    try {
+      let data;
+      if (source.kind === "remote") {
+        const fetchBytes = options.fetchHttpBytes ?? defaultFetchHttpBytes;
+        data = Buffer.from(await fetchBytes(source.value));
+      } else {
+        const file = Bun.file(source.value);
+        if (!(await file.exists())) throw new Error("missing image");
+        data = Buffer.from(await file.arrayBuffer());
+      }
+      const size = imageSize(data);
+      if (!size?.width || !size?.height) throw new Error("unsupported image");
+      const estimatedCols = Math.max(1, Math.round(size.width / 8));
+      const cols = Math.min(maxCols, estimatedCols);
+      const rows = Math.max(1, Math.round((cols * size.height) / size.width / 2));
+      const lineIndex = outputLines.length;
+      outputLines.push(line, ...Array(Math.max(0, rows - 1)).fill(""));
+      images.push({
+        id: stableImageId(source.value, sourceLine, data),
+        line: lineIndex,
+        cols,
+        rows,
+        pixelWidth: size.width,
+        pixelHeight: size.height,
+        mime: size.mime,
+        data,
+        path: source.value,
+      });
+      logKittyPlacement("image-prepared", {
+        path: source.value,
+        sourceKind: source.kind,
+        sourceLine,
+        renderedLine: lineIndex,
+        imageId: images.at(-1).id,
+        intrinsicWidth: size.width,
+        intrinsicHeight: size.height,
+        cols,
+        rows,
+        terminalCols: maxCols + 1,
+      });
+    } catch {
+      // An unavailable or unsupported image remains the normal Markdown link.
+      outputLines.push(line);
+    }
+  }
+  return { rendered: outputLines.join("\n"), images };
+}

package/src/cui/rpc.mjs

@@ -71,16 +71,13 @@ function isWebHeading(element)
   return /^h[1-6]$/i.test(String(element?.tagName ?? ""));
 }
 
-function firstHeadingTaskList(heading)
+function firstHeadingList(heading)
 {
   for (let sibling = heading?.nextElementSibling; sibling; sibling = sibling.nextElementSibling) {
     if (isWebHeading(sibling) || String(sibling.tagName ?? "").toLowerCase() === "section")
       break;
-    const task = sibling.matches?.("li.task-list-item")
-      ? sibling
-      : sibling.querySelector?.("li.task-list-item");
-    if (!task) continue;
-    const list = task.closest?.("ul, ol");
+    if (sibling.matches?.("ul, ol")) return sibling;
+    const list = sibling.querySelector?.("ul, ol");
     if (list) return list;
   }
   return null;
@@ -109,7 +106,7 @@ function webTaskItemValue(item, checkbox)
 function webHeadingValue(heading)
 {
   const single = String(heading?.id ?? "").startsWith("select");
-  const list = firstHeadingTaskList(heading);
+  const list = firstHeadingList(heading);
   if (!list) return single ? null : [];
 
   const selected = [];
@@ -124,6 +121,114 @@ function webHeadingValue(heading)
   return single ? null : selected;
 }
 
+function directWebTaskItems(list)
+{
+  const items = [];
+  for (const item of list?.children ?? []) {
+    if (!item.matches?.("li.task-list-item")) continue;
+    if (directTaskCheckbox(item)) items.push(item);
+  }
+  return items;
+}
+
+function webTaskItemSnapshot(item)
+{
+  const checkbox = directTaskCheckbox(item);
+  return {
+    value: webTaskItemValue(item, checkbox),
+    checked: Boolean(checkbox?.checked),
+  };
+}
+
+function normalizedTaskItem(input)
+{
+  if (input && typeof input === "object") {
+    return {
+      value: String(input.value ?? input.label ?? "").replace(/\r?\n/g, " "),
+      checked: Boolean(input.checked),
+    };
+  }
+  return {
+    value: String(input ?? "").replace(/\r?\n/g, " "),
+    checked: false,
+  };
+}
+
+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 appendWebTaskItem(list, input, before = null)
+{
+  const documentObject = list?.ownerDocument;
+  if (!documentObject?.createElement || !documentObject?.createTextNode) return false;
+
+  const itemValue = normalizedTaskItem(input);
+  const item = documentObject.createElement("li");
+  item.classList?.add("task-list-item");
+  const label = documentObject.createElement("label");
+  const checkbox = documentObject.createElement("input");
+  checkbox.type = "checkbox";
+  checkbox.classList?.add("task-list-item-checkbox");
+  checkbox.checked = itemValue.checked;
+  label.append(checkbox, documentObject.createTextNode(itemValue.value));
+  item.append(label);
+  list.insertBefore(item, before);
+  return true;
+}
+
+function mutateWebHeadingList(heading, method, args)
+{
+  const list = firstHeadingList(heading);
+  if (!list) {
+    if (method === "push" || method === "unshift") return 0;
+    if (method === "splice") return [];
+    return undefined;
+  }
+
+  const items = directWebTaskItems(list);
+  if (method === "splice") {
+    const range = normalizedSpliceRange(items.length, args.length, args[0], args[1]);
+    const removed = items
+      .slice(range.start, range.start + range.deleteCount)
+      .map((item) => webTaskItemValue(item, directTaskCheckbox(item)));
+    const before = items[range.start] ?? null;
+    for (const input of args.slice(2)) appendWebTaskItem(list, input, before);
+    for (const item of items.slice(range.start, range.start + range.deleteCount)) item.remove?.();
+    return removed;
+  }
+  if (method === "pop" || method === "shift") {
+    const item = method === "pop" ? items.at(-1) : items[0];
+    if (!item) return undefined;
+    const value = webTaskItemValue(item, directTaskCheckbox(item));
+    item.remove?.();
+    return value;
+  }
+
+  if (method === "push") {
+    for (const input of args) appendWebTaskItem(list, input);
+  } else {
+    const before = items[0] ?? list.firstChild ?? null;
+    for (const input of args) appendWebTaskItem(list, input, before);
+  }
+  return directWebTaskItems(list).length;
+}
+
 function resizeWebTextarea(element)
 {
   if (!element || String(element.tagName ?? "").toLowerCase() !== "textarea") return;
@@ -194,6 +299,57 @@ export function createWebDollar(documentObject = globalThis.document)
           return args.length > 0 ? selection : "";
         }
       },
+      push(...items) {
+        try {
+          const element = findWebDollarElement(documentObject, selectorText, selector);
+          return isWebHeading(element) ? mutateWebHeadingList(element, "push", items) : 0;
+        } catch {
+          return 0;
+        }
+      },
+      pop() {
+        try {
+          const element = findWebDollarElement(documentObject, selectorText, selector);
+          return isWebHeading(element) ? mutateWebHeadingList(element, "pop", []) : undefined;
+        } catch {
+          return undefined;
+        }
+      },
+      shift() {
+        try {
+          const element = findWebDollarElement(documentObject, selectorText, selector);
+          return isWebHeading(element) ? mutateWebHeadingList(element, "shift", []) : undefined;
+        } catch {
+          return undefined;
+        }
+      },
+      unshift(...items) {
+        try {
+          const element = findWebDollarElement(documentObject, selectorText, selector);
+          return isWebHeading(element) ? mutateWebHeadingList(element, "unshift", items) : 0;
+        } catch {
+          return 0;
+        }
+      },
+      splice(...args) {
+        try {
+          const element = findWebDollarElement(documentObject, selectorText, selector);
+          return isWebHeading(element) ? mutateWebHeadingList(element, "splice", args) : [];
+        } catch {
+          return [];
+        }
+      },
+      slice(...args) {
+        try {
+          const element = findWebDollarElement(documentObject, selectorText, selector);
+          if (!isWebHeading(element)) return [];
+          const list = firstHeadingList(element);
+          if (!list) return [];
+          return directWebTaskItems(list).map(webTaskItemSnapshot).slice(...args);
+        } catch {
+          return [];
+        }
+      },
     };
     return selection;
   };

package/src/cui/server.mjs

@@ -103,7 +103,7 @@ const server = Bun.serve({
   },
 });
 
-console.log(mda("- Bun RPC server listening on"));
+console.error(mda("- Bun RPC server listening on"));
 console.log(`http://localhost:${server.port}${pathname}`);
 
 

package/src/cui/task-checkbox.mjs

@@ -12,5 +12,49 @@ export function toggleTaskCheckboxBeforeColumn(line, column) {
   return {
     line: text.slice(0, checkboxAt) + replacement + text.slice(checkboxAt + 1),
     toggled: true,
+    checkboxAt,
+    checked: replacement === "☒",
   };
 }
+
+export function updateAnsiTaskCheckbox(ansiLine, checkboxAt, checked) {
+  const input = String(ansiLine ?? "");
+  const target = checked ? "☒" : "☐";
+  const sgr = `\x1b[${checked ? "32" : "2"}m`;
+  let plainIndex = 0;
+
+  for (let i = 0; i < input.length;) {
+    if (input[i] === "\x1b" && input[i + 1] === "[") {
+      let end = i + 2;
+      while (end < input.length) {
+        const code = input.charCodeAt(end);
+        if (code >= 0x40 && code <= 0x7e) { end++; break; }
+        end++;
+      }
+      i = end;
+      continue;
+    }
+    if (input[i] === "\x1b" && input[i + 1] === "]") {
+      const bel = input.indexOf("\x07", i + 2);
+      const st = input.indexOf("\x1b\\", i + 2);
+      if (bel < 0 && st < 0) break;
+      i = bel >= 0 && (st < 0 || bel < st) ? bel + 1 : st + 2;
+      continue;
+    }
+
+    const codePoint = input.codePointAt(i);
+    const charLength = codePoint > 0xffff ? 2 : 1;
+    if (plainIndex === checkboxAt && (input[i] === "☐" || input[i] === "☒")) {
+      const prefix = input.slice(0, i);
+      const immediateSgr = prefix.match(/\x1b\[[0-9;]*m$/);
+      const beforeStyle = immediateSgr
+        ? prefix.slice(0, prefix.length - immediateSgr[0].length) + sgr
+        : prefix;
+      return beforeStyle + target + input.slice(i + charLength);
+    }
+    plainIndex += charLength;
+    i += charLength;
+  }
+
+  return input;
+}