buninu 0.1.1

package/apps/jsmdcui/src/cui/id-collision.mjs

@@ -0,0 +1,111 @@
+import { parseFenceDeclarations } from "./fence-events.mjs";
+import {
+  collectMarkdownHeadingDeclarations,
+  collectRawHtmlHeadingDeclarations,
+  renderMarkdownWithHeadingIds,
+} from "./heading-ids.mjs";
+
+function fencedBlockDeclarations(markdown) {
+  return parseFenceDeclarations(markdown)
+    .filter((declaration) => declaration.id)
+    .map((declaration) => ({
+      id: declaration.id,
+      kind: `${declaration.tag} fenced block`,
+      line: declaration.line,
+      source: declaration.source,
+    }));
+}
+
+export function checkMarkdownIdCollisions(markdown) {
+  const rendered = renderMarkdownWithHeadingIds(markdown);
+  if (!rendered.normalized)
+    throw new Error("Markdown headings could not be classified safely");
+  const declarations = [
+    ...collectMarkdownHeadingDeclarations(markdown, { includeLevel: true }),
+    ...collectRawHtmlHeadingDeclarations(markdown, {
+      strict: true,
+      includeLevel: true,
+    }),
+    ...fencedBlockDeclarations(markdown),
+  ].sort((a, b) => a.line - b.line);
+  const byId = new Map();
+  for (const declaration of declarations) {
+    if (!byId.has(declaration.id)) byId.set(declaration.id, []);
+    byId.get(declaration.id).push(declaration);
+  }
+  const collisions = [...byId.entries()]
+    .filter(([, items]) => items.length > 1)
+    .map(([id, items]) => ({ id, declarations: items }));
+  return { declarations, collisions };
+}
+
+export function formatMarkdownOutline(result) {
+  const lines = [];
+  for (const declaration of result?.declarations ?? []) {
+    if (
+      declaration.kind === "heading"
+      || declaration.kind === "raw HTML heading"
+    ) {
+      const level = Math.min(6, Math.max(1, Number(declaration.level) || 1));
+      lines.push(`${"  ".repeat(level - 1)}- ${declaration.id}`);
+    } else {
+      lines.push(`+ ${declaration.id}`);
+    }
+  }
+  return lines.length ? `${lines.join("\n")}\n` : "";
+}
+
+function inlineCode(value) {
+  const text = String(value);
+  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((match) => match[0].length));
+  const delimiter = "`".repeat(longest + 1);
+  const padding = text.startsWith("`") || text.endsWith("`") ? " " : "";
+  return `${delimiter}${padding}${text}${padding}${delimiter}`;
+}
+
+export function formatMarkdownIdCheck(path, result) {
+  const headings = result.declarations.filter(
+    item => item.kind === "heading" || item.kind === "raw HTML heading",
+  ).length;
+  const fencedBlocks = result.declarations.length - headings;
+  const lines = [
+    "# Markdown UI ID Check",
+    "",
+    `- File: ${inlineCode(path)}`,
+    `- Selectable IDs: **${result.declarations.length}**`,
+    `  * Headings: **${headings}**`,
+    `  * Fenced blocks: **${fencedBlocks}**`,
+  ];
+
+  if (!result.collisions.length) {
+    lines.push("", "## No ID collisions found");
+    return lines.join("\n");
+  }
+
+  lines.push("", `## FAIL — Found ${result.collisions.length} colliding ID(s)`);
+  for (const collision of result.collisions) {
+    lines.push("", `### ID ${inlineCode(`#${collision.id}`)}`);
+    lines.push("", `- Declarations: **${collision.declarations.length}**`);
+    for (const declaration of collision.declarations) {
+      lines.push(`  * Line **${declaration.line}**`);
+      lines.push(`    - Type: ${declaration.kind}`);
+      lines.push(`    - Source: ${inlineCode(declaration.source)}`);
+    }
+  }
+  lines.push("", "## Suggested fix", "", "- Rename the heading or fenced block so every selectable ID is unique.");
+  return lines.join("\n");
+}
+
+function statusBanner(label, color, fallbackColor) {
+  const foreground = Bun.color?.(color, "ansi-16m") || fallbackColor;
+  return `${foreground}\x1b[1m${label}\x1b[0m\n${foreground}\x1b[2m${"═".repeat(label.length)}\x1b[0m\n`;
+}
+
+export function formatMarkdownIdCheckAnsi(path, result) {
+  let output = String(Bun.markdown.ansi(formatMarkdownIdCheck(path, result)));
+  if (!output.endsWith("\n")) output += "\n";
+  output += "\n" + (result.collisions.length
+    ? statusBanner("FAILED", "#ff3030", "\x1b[31m")
+    : statusBanner("PASSED", "#00d75f", "\x1b[32m"));
+  return output;
+}

package/apps/jsmdcui/src/cui/identity.mjs

@@ -0,0 +1,26 @@
+const MDCUI_ID_SOURCE = String.raw`[_\p{L}\p{N}][_\p{L}\p{M}\p{N}:-]*`;
+const MDCUI_ID_RE = new RegExp(`^${MDCUI_ID_SOURCE}$`, "u");
+const MDCUI_ID_SELECTOR_RE = new RegExp(`^#(${MDCUI_ID_SOURCE})$`, "u");
+const MDCUI_IDENTITY_RE = new RegExp(
+  `^([A-Za-z_][\\w:-]*)?(?:#(${MDCUI_ID_SOURCE}))?((?:\\.[A-Za-z_][\\w:-]*)*)$`,
+  "u",
+);
+
+export function isMdcuiId(value) {
+  return MDCUI_ID_RE.test(String(value ?? ""));
+}
+
+export function parseMdcuiIdSelector(value) {
+  return String(value ?? "").trim().match(MDCUI_ID_SELECTOR_RE)?.[1] ?? null;
+}
+
+export function parseMdcuiIdentity(value, { selector = false } = {}) {
+  const match = String(value ?? "").trim().match(MDCUI_IDENTITY_RE);
+  if (!match || (!match[1] && !match[2] && !match[3])) return null;
+  if (!selector && !match[1]) return null;
+  return {
+    tag: match[1] || null,
+    id: match[2] || null,
+    classes: match[3] ? match[3].slice(1).split(".") : [],
+  };
+}

package/apps/jsmdcui/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.dirname, "../..", "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/apps/jsmdcui/src/cui/kitty-images.mjs

@@ -0,0 +1,280 @@
+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";
+import { canonicalHtmlBundleImageHref } from "../../single-exe/assetsHelper.js";
+
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const REMOTE_IMAGE_TIMEOUT_MS = 10_000;
+
+export function renderAnsiWithDataImages(markdown, options = {}) {
+  const dataUrls = [];
+  const protectedMarkdown = String(markdown ?? "").replace(
+    /(!\[[^\]]*\]\()(data:image\/[^)\s]+)(\))/giu,
+    (whole, opening, href, closing) => {
+      const index = dataUrls.push(href) - 1;
+      return `${opening}https://mdcui.invalid/data-image/${index}${closing}`;
+    },
+  );
+  let ansi = String(Bun.markdown.ansi(protectedMarkdown, options));
+  for (let index = 0; index < dataUrls.length; index++) {
+    ansi = ansi.replaceAll(
+      `https://mdcui.invalid/data-image/${index}`,
+      dataUrls[index],
+    );
+  }
+  return ansi;
+}
+
+async function withTimeout(promise, timeoutMs, onTimeout) {
+  let timeout;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timeout = setTimeout(
+          () => {
+            try { onTimeout?.(); } catch {}
+            reject(new Error("remote image timed out"));
+          },
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+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 imageDataUrlBytes(href) {
+  const match = /^data:(image\/[^;,]+)((?:;[^,]*)?),(.*)$/isu.exec(href);
+  if (!match) return null;
+  try {
+    return /;base64(?:;|$)/iu.test(match[2])
+      ? Buffer.from(match[3].replace(/\s+/gu, ""), "base64")
+      : Buffer.from(decodeURIComponent(match[3]), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function imageSource(href, markdownPath, allowUrl) {
+  try {
+    if (href.startsWith("data:image/")) {
+      const data = imageDataUrlBytes(href);
+      return data ? { kind: "data", value: data } : null;
+    }
+    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;
+}
+
+async function convertToKittyPng(data) {
+  return Buffer.from(await new Bun.Image(data).png().toBuffer());
+}
+
+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]*📷)/;
+  const bundledImages = await options.getBundledImageMap?.() ?? null;
+  const remoteBudgetMs = Number.isFinite(options.remoteTimeoutMs)
+    ? Math.max(1, Math.trunc(options.remoteTimeoutMs))
+    : REMOTE_IMAGE_TIMEOUT_MS;
+  const remoteDeadline = Date.now() + remoteBudgetMs;
+
+  for (let sourceLine = 0; sourceLine < inputLines.length; sourceLine++) {
+    const line = inputLines[sourceLine];
+    const match = line.match(oscImage);
+    const bundledPath = match
+      ? bundledImages?.get(canonicalHtmlBundleImageHref(match[1]))
+      : null;
+    const source = bundledPath
+      ? { kind: "bundled", value: bundledPath }
+      : match ? imageSource(match[1], markdownPath, options.allowUrl === true) : null;
+    if (!source) {
+      outputLines.push(line);
+      continue;
+    }
+    try {
+      let data;
+      if (source.kind === "data") {
+        data = source.value;
+      } else if (source.kind === "remote") {
+        const fetchBytes = options.fetchHttpBytes ?? defaultFetchHttpBytes;
+        const timeoutMs = remoteDeadline - Date.now();
+        if (timeoutMs <= 0) throw new Error("remote image budget exhausted");
+        const controller = new AbortController();
+        data = Buffer.from(await withTimeout(
+          fetchBytes(source.value, {
+            timeoutMs,
+            signal: controller.signal,
+          }),
+          timeoutMs,
+          () => controller.abort(),
+        ));
+      } else {
+        const file = Bun.file(source.value);
+        if (!(await file.exists())) throw new Error("missing image");
+        data = Buffer.from(await file.arrayBuffer());
+      }
+      let size = imageSize(data);
+      if (!size?.width || !size?.height) throw new Error("unsupported image");
+      if (options.kittyMode === "compat" && size.mime !== "image/png") {
+        data = await convertToKittyPng(data);
+        size = imageSize(data);
+        if (size?.mime !== "image/png" || !size.width || !size.height)
+          throw new Error("PNG conversion failed");
+      }
+      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(""));
+      const sourcePath = source.kind === "data" ? `data:${size.mime}` : source.value;
+      images.push({
+        id: stableImageId(sourcePath, sourceLine, data),
+        line: lineIndex,
+        cols,
+        rows,
+        pixelWidth: size.width,
+        pixelHeight: size.height,
+        mime: size.mime,
+        data,
+        path: sourcePath,
+      });
+      logKittyPlacement("image-prepared", {
+        path: sourcePath,
+        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/apps/jsmdcui/src/cui/kitty-mode.mjs

@@ -0,0 +1,6 @@
+const KITTY_MODES = new Set(["off", "compat", "extended"]);
+
+export function kittyModeFromEnvironment(input) {
+  const value = String(input ?? "").trim().toLowerCase();
+  return KITTY_MODES.has(value) ? value : "off";
+}

package/apps/jsmdcui/src/cui/rerender-queue.mjs

@@ -0,0 +1,66 @@
+const rerenderQueues = new WeakMap();
+
+function settleWaiters(waiters, method, value) {
+  for (const waiter of waiters) waiter[method](value);
+}
+
+async function drainRerenders(target, state, firstRequest) {
+  try {
+    let request = firstRequest;
+    while (request) {
+      try {
+        const value = await request.operation();
+        settleWaiters(request.waiters, "resolve", value);
+      } catch (error) {
+        settleWaiters(request.waiters, "reject", error);
+      }
+
+      request = state.pending;
+      state.pending = null;
+    }
+  } finally {
+    rerenderQueues.delete(target);
+    state.resolveIdle();
+  }
+}
+
+export function enqueueMdcuiRerender(target, operation) {
+  if ((typeof target !== "object" && typeof target !== "function") || target === null)
+    return Promise.reject(new TypeError("MDCUI rerender target must be an object"));
+  if (typeof operation !== "function")
+    return Promise.reject(new TypeError("MDCUI rerender operation must be a function"));
+
+  let resolve;
+  let reject;
+  const result = new Promise((done, fail) => {
+    resolve = done;
+    reject = fail;
+  });
+  const waiter = { resolve, reject };
+  const state = rerenderQueues.get(target);
+
+  if (!state) {
+    let resolveIdle;
+    const idle = new Promise((done) => {
+      resolveIdle = done;
+    });
+    const nextState = { idle, pending: null, resolveIdle };
+    rerenderQueues.set(target, nextState);
+    void Promise.resolve().then(() => drainRerenders(
+      target,
+      nextState,
+      { operation, waiters: [waiter] },
+    ));
+  } else if (state.pending) {
+    state.pending.operation = operation;
+    state.pending.waiters.push(waiter);
+  } else {
+    state.pending = { operation, waiters: [waiter] };
+  }
+
+  return result;
+}
+
+export function waitForMdcuiRerenders(target) {
+  return rerenderQueues.get(target)?.idle ?? Promise.resolve();
+}