@fx-/chat-ink 0.0.0-stage → 0.1.0

package/dist/kitty.js

@@ -0,0 +1,704 @@
+import { Buffer } from "node:buffer";
+
+//#region src/kitty/diacritics.ts
+/**
+* Row/column combining diacritics for kitty Unicode placeholders, in order:
+* the n-th code point encodes the number n. From the kitty graphics
+* protocol's published list (`gen/rowcolumn-diacritics.txt`, 297 entries).
+*/
+const DIACRITICS = [
+	773,
+	781,
+	782,
+	784,
+	786,
+	829,
+	830,
+	831,
+	838,
+	842,
+	843,
+	844,
+	848,
+	849,
+	850,
+	855,
+	859,
+	867,
+	868,
+	869,
+	870,
+	871,
+	872,
+	873,
+	874,
+	875,
+	876,
+	877,
+	878,
+	879,
+	1155,
+	1156,
+	1157,
+	1158,
+	1159,
+	1426,
+	1427,
+	1428,
+	1429,
+	1431,
+	1432,
+	1433,
+	1436,
+	1437,
+	1438,
+	1439,
+	1440,
+	1441,
+	1448,
+	1449,
+	1451,
+	1452,
+	1455,
+	1476,
+	1552,
+	1553,
+	1554,
+	1555,
+	1556,
+	1557,
+	1558,
+	1559,
+	1623,
+	1624,
+	1625,
+	1626,
+	1627,
+	1629,
+	1630,
+	1750,
+	1751,
+	1752,
+	1753,
+	1754,
+	1755,
+	1756,
+	1759,
+	1760,
+	1761,
+	1762,
+	1764,
+	1767,
+	1768,
+	1771,
+	1772,
+	1840,
+	1842,
+	1843,
+	1845,
+	1846,
+	1850,
+	1853,
+	1855,
+	1856,
+	1857,
+	1859,
+	1861,
+	1863,
+	1865,
+	1866,
+	2027,
+	2028,
+	2029,
+	2030,
+	2031,
+	2032,
+	2033,
+	2035,
+	2070,
+	2071,
+	2072,
+	2073,
+	2075,
+	2076,
+	2077,
+	2078,
+	2079,
+	2080,
+	2081,
+	2082,
+	2083,
+	2085,
+	2086,
+	2087,
+	2089,
+	2090,
+	2091,
+	2092,
+	2093,
+	2385,
+	2387,
+	2388,
+	3970,
+	3971,
+	3974,
+	3975,
+	4957,
+	4958,
+	4959,
+	6109,
+	6458,
+	6679,
+	6773,
+	6774,
+	6775,
+	6776,
+	6777,
+	6778,
+	6779,
+	6780,
+	7019,
+	7021,
+	7022,
+	7023,
+	7024,
+	7025,
+	7026,
+	7027,
+	7376,
+	7377,
+	7378,
+	7386,
+	7387,
+	7392,
+	7616,
+	7617,
+	7619,
+	7620,
+	7621,
+	7622,
+	7623,
+	7624,
+	7625,
+	7627,
+	7628,
+	7633,
+	7634,
+	7635,
+	7636,
+	7637,
+	7638,
+	7639,
+	7640,
+	7641,
+	7642,
+	7643,
+	7644,
+	7645,
+	7646,
+	7647,
+	7648,
+	7649,
+	7650,
+	7651,
+	7652,
+	7653,
+	7654,
+	7678,
+	8400,
+	8401,
+	8404,
+	8405,
+	8406,
+	8407,
+	8411,
+	8412,
+	8417,
+	8423,
+	8425,
+	8432,
+	11503,
+	11504,
+	11505,
+	11744,
+	11745,
+	11746,
+	11747,
+	11748,
+	11749,
+	11750,
+	11751,
+	11752,
+	11753,
+	11754,
+	11755,
+	11756,
+	11757,
+	11758,
+	11759,
+	11760,
+	11761,
+	11762,
+	11763,
+	11764,
+	11765,
+	11766,
+	11767,
+	11768,
+	11769,
+	11770,
+	11771,
+	11772,
+	11773,
+	11774,
+	11775,
+	42607,
+	42620,
+	42621,
+	42736,
+	42737,
+	43232,
+	43233,
+	43234,
+	43235,
+	43236,
+	43237,
+	43238,
+	43239,
+	43240,
+	43241,
+	43242,
+	43243,
+	43244,
+	43245,
+	43246,
+	43247,
+	43248,
+	43249,
+	43696,
+	43698,
+	43699,
+	43703,
+	43704,
+	43710,
+	43711,
+	43713,
+	65056,
+	65057,
+	65058,
+	65059,
+	65060,
+	65061,
+	65062,
+	68111,
+	68152,
+	119173,
+	119174,
+	119175,
+	119176,
+	119177,
+	119210,
+	119211,
+	119212,
+	119213,
+	119362,
+	119363,
+	119364
+];
+
+//#endregion
+//#region src/kitty/provider.ts
+const ESC = String.fromCharCode(27);
+const PLACEHOLDER = String.fromCodePoint(1109742);
+const PNG_SIGNATURE = [
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+];
+/** Ids available to images (the 256-colour foreground carries the id). */
+const MAX_IMAGES = 255;
+/** The largest width or height in pixels a terminal accepts (kitty's and ghostty's limit). */
+const MAX_IMAGE_SIDE = 1e4;
+/** The largest grid in cells: one combining diacritic per row and per column number. */
+const MAX_CELLS = DIACRITICS.length;
+/** The longest timer `setTimeout` keeps; longer ones fire at once. */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+/** Whether the terminal speaks the kitty graphics protocol (and is not behind a multiplexer). */
+function detectKitty(env = process.env) {
+	if (env.TMUX || env.STY || /^(screen|tmux)/.test(env.TERM ?? "")) return false;
+	return env.TERM_PROGRAM === "ghostty" || env.TERM_PROGRAM === "kitty" || Boolean(env.GHOSTTY_RESOURCES_DIR) || Boolean(env.KITTY_WINDOW_ID) || env.TERM === "xterm-ghostty" || env.TERM === "xterm-kitty";
+}
+function isPng(bytes) {
+	return PNG_SIGNATURE.every((b, i) => bytes[i] === b);
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+	let c = n;
+	for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+	return c >>> 0;
+});
+function crc32(bytes) {
+	let c = 4294967295;
+	for (const b of bytes) c = CRC_TABLE[(c ^ b) & 255] ^ c >>> 8;
+	return (c ^ 4294967295) >>> 0;
+}
+/** Legal PNG bit depths per colour type. */
+const BIT_DEPTHS = {
+	0: [
+		1,
+		2,
+		4,
+		8,
+		16
+	],
+	2: [8, 16],
+	3: [
+		1,
+		2,
+		4,
+		8
+	],
+	4: [8, 16],
+	6: [8, 16]
+};
+/**
+* A PNG's pixel size from its header: undefined unless the signature is
+* followed by a complete IHDR chunk (length, type, data, CRC) whose CRC
+* matches and whose fields are legal. The image data is not decoded here.
+*/
+function pngSize(bytes) {
+	if (!isPng(bytes) || bytes.length < 33) return void 0;
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (view.getUint32(8) !== 13 || view.getUint32(12) !== 1229472850) return void 0;
+	if (crc32(bytes.subarray(12, 29)) !== view.getUint32(29)) return void 0;
+	const width = view.getUint32(16);
+	const height = view.getUint32(20);
+	if (width === 0 || height === 0 || width > 2 ** 31 - 1 || height > 2 ** 31 - 1) return void 0;
+	if (!BIT_DEPTHS[bytes[25]]?.includes(bytes[24])) return void 0;
+	if (bytes[26] !== 0 || bytes[27] !== 0 || bytes[28] > 1) return void 0;
+	return {
+		width,
+		height
+	};
+}
+/**
+* The cells an image of `px` pixels takes in `box`, keeping its aspect and
+* never upscaling. The box is first capped to `MAX_CELLS` each way, the most
+* rows and columns placeholders can number.
+*/
+function fitCells(px, within, cell) {
+	const box = {
+		columns: Math.min(within.columns, MAX_CELLS),
+		rows: Math.min(within.rows, MAX_CELLS)
+	};
+	const scale = Math.min(box.columns * cell.width / px.width, box.rows * cell.height / px.height, 1);
+	return {
+		columns: Math.max(1, Math.min(box.columns, Math.ceil(px.width * scale / cell.width))),
+		rows: Math.max(1, Math.min(box.rows, Math.ceil(px.height * scale / cell.height)))
+	};
+}
+/** Placeholder text for an image: one string per cell row, at most `MAX_CELLS` each way. */
+function placeholderRows(columns, rows) {
+	const mark = (n) => String.fromCodePoint(DIACRITICS[n]);
+	return Array.from({ length: Math.min(rows, MAX_CELLS) }, (_, r) => Array.from({ length: Math.min(columns, MAX_CELLS) }, (_$1, c) => `${PLACEHOLDER}${mark(r)}${mark(c)}`).join(""));
+}
+const apc = (control, payload = "") => `${ESC}_G${control}${payload ? `;${payload}` : ""}${ESC}\\`;
+/** Transmit PNG bytes quietly under `id`, in protocol-sized chunks. */
+function transmit(id, png) {
+	const data = Buffer.from(png).toString("base64");
+	const chunks = data.match(/.{1,4096}/g) ?? [""];
+	return chunks.map((chunk, i) => {
+		const more = i < chunks.length - 1 ? 1 : 0;
+		return i === 0 ? apc(`a=t,f=100,t=d,i=${id},q=2,m=${more}`, chunk) : apc(`m=${more}`, chunk);
+	}).join("");
+}
+/** One virtual placement for `id`, sized to a cell box (replacing the previous one). */
+function place(id, box) {
+	return apc(`a=p,U=1,i=${id},p=1,c=${box.columns},r=${box.rows},q=2`);
+}
+/** Forget an image and its placements. */
+function forget(id) {
+	return apc(`a=d,d=I,i=${id},q=2`);
+}
+/** Ask the terminal for its cell size in pixels. */
+const CELL_SIZE_QUERY = `${ESC}[16t`;
+const CELL_SIZE_REPLY = new RegExp(`^(?:${ESC})?\\[6;(\\d+);(\\d+)t`);
+/** The byte a valid `%XX` escape at `i` stands for, else undefined. */
+function escapeAt(body, i) {
+	if (body.charCodeAt(i) !== 37) return void 0;
+	const hex = body.slice(i + 1, i + 3);
+	return /^[0-9a-f]{2}$/i.test(hex) ? Number.parseInt(hex, 16) : void 0;
+}
+/**
+* The exact bytes a percent-encoded body decodes to, counted without decoding
+* it: a valid `%XX` is one byte, anything else its UTF-8 length (a stray `%`
+* stays literal, a lone surrogate becomes U+FFFD).
+*/
+function percentLength(body) {
+	let n = 0;
+	for (let i = 0; i < body.length; i++) {
+		const code = body.charCodeAt(i);
+		if (escapeAt(body, i) !== void 0) {
+			n++;
+			i += 2;
+		} else if (code < 128) n++;
+		else if (code < 2048) n += 2;
+		else if (code >= 55296 && code < 56320 && (body.charCodeAt(i + 1) & 64512) === 56320) {
+			n += 4;
+			i++;
+		} else n += 3;
+	}
+	return n;
+}
+/** Percent-decode a body into the `length` raw bytes `percentLength` counted. */
+function percentDecode(body, length) {
+	const out = new Uint8Array(length);
+	const encoder = new TextEncoder();
+	let at = 0;
+	let i = 0;
+	while (i < body.length) {
+		const escaped = escapeAt(body, i);
+		if (escaped !== void 0) {
+			out[at++] = escaped;
+			i += 3;
+			continue;
+		}
+		let end = i + 1;
+		while (end < body.length && escapeAt(body, end) === void 0) end++;
+		at += encoder.encodeInto(body.slice(i, end), out.subarray(at)).written;
+		i = end;
+	}
+	return out;
+}
+/**
+* The most bytes a base64 body decodes to: exact for clean base64, more when
+* it holds whitespace or other skipped characters, so it never undercounts.
+*/
+function base64Ceiling(body) {
+	const padding = body.endsWith("==") ? 2 : body.endsWith("=") ? 1 : 0;
+	return Math.floor(body.length * 3 / 4) - padding;
+}
+/**
+* Decode a data URL, refusing one whose body decodes to more than `maxBytes`
+* before allocating the decoded bytes.
+*/
+function decodeDataUrl(src, maxBytes) {
+	const comma = src.indexOf(",");
+	if (comma < 0) throw new Error("malformed data URL");
+	const header = src.slice(5, comma);
+	const body = src.slice(comma + 1);
+	const mediaType = header.split(";")[0] || "text/plain";
+	if (header.endsWith(";base64")) {
+		if (base64Ceiling(body) > maxBytes) throw new Error("too large");
+		return {
+			bytes: new Uint8Array(Buffer.from(body, "base64")),
+			mediaType
+		};
+	}
+	const length = percentLength(body);
+	if (length > maxBytes) throw new Error("too large");
+	return {
+		bytes: percentDecode(body, length),
+		mediaType
+	};
+}
+/** Read a response body in chunks, cancelling it once it passes `maxBytes`. */
+async function readCapped(response, maxBytes) {
+	if (!response.body) return new Uint8Array();
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			await reader.cancel();
+			throw new Error("too large");
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let at = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, at);
+		at += chunk.byteLength;
+	}
+	return bytes;
+}
+/** Refuse an option that is not a finite number in (0, `max`]. */
+function positive(name, value, max = Number.MAX_VALUE) {
+	if (!(value > 0 && value <= max)) throw new RangeError(`${name} must be a positive number up to ${max}, got ${value}`);
+}
+function createKittyProvider(options) {
+	const { write, decode, autoFetch = (src) => src.startsWith("data:"), timeoutMs = 15e3, maxBytes = 20 * 1024 * 1024, maxMegapixels = 50 } = options;
+	positive("timeoutMs", timeoutMs, MAX_TIMEOUT_MS);
+	positive("maxBytes", maxBytes);
+	positive("maxMegapixels", maxMegapixels);
+	const fetcher = options.fetch ?? globalThis.fetch;
+	const entries = new Map();
+	const allowed = new Set();
+	const listeners = new Set();
+	const ids = [];
+	let version = 0;
+	let cell = {
+		width: 9,
+		height: 18
+	};
+	const changed = () => {
+		version++;
+		for (const listener of listeners) listener();
+	};
+	const fail = (entry, error) => {
+		entry.state = "failed";
+		entry.error = error;
+	};
+	async function bytesOf(src, clicked) {
+		if (src.startsWith("data:")) return decodeDataUrl(src, maxBytes);
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const response = await fetcher(src, {
+				redirect: clicked ? "follow" : "error",
+				signal: controller.signal
+			});
+			const refuse = (message) => {
+				response.body?.cancel().catch(() => {});
+				return new Error(message);
+			};
+			if (!response.ok) throw refuse(`HTTP ${response.status}`);
+			if (Number(response.headers.get("content-length") ?? 0) > maxBytes) throw refuse("too large");
+			const bytes = await readCapped(response, maxBytes);
+			clearTimeout(timer);
+			return {
+				bytes,
+				mediaType: response.headers.get("content-type") ?? ""
+			};
+		} catch (error) {
+			clearTimeout(timer);
+			throw controller.signal.aborted ? new Error("timed out") : error;
+		}
+	}
+	async function load(src, entry, clicked) {
+		entry.state = "loading";
+		try {
+			const { bytes, mediaType } = await bytesOf(src, clicked);
+			const png = isPng(bytes) ? bytes : await decode?.(bytes, mediaType);
+			if (png && png.byteLength > maxBytes) throw new Error("too large");
+			if (!png) entry.state = "declined";
+			else {
+				const px = pngSize(png);
+				if (!px) throw new Error("malformed image");
+				if (px.width > MAX_IMAGE_SIDE || px.height > MAX_IMAGE_SIDE || px.width * px.height > maxMegapixels * 1e6) throw new Error("too large");
+				Object.assign(entry, {
+					state: "ready",
+					png,
+					px
+				});
+			}
+		} catch (error) {
+			fail(entry, error instanceof Error ? error.message : String(error));
+		}
+		changed();
+	}
+	const entryFor = (src) => {
+		let entry = entries.get(src);
+		if (!entry) {
+			entry = { state: "ask" };
+			entries.set(src, entry);
+			if (allowed.has(src) || autoFetch(src)) load(src, entry, allowed.has(src));
+		}
+		return entry;
+	};
+	const assignId = (src, entry) => {
+		if (entry.id !== void 0) return entry.id;
+		const used = new Set(ids.map((i) => i.id));
+		let id = 1;
+		while (used.has(id) && id <= MAX_IMAGES) id++;
+		if (id > MAX_IMAGES) {
+			const oldest = ids.shift();
+			write(forget(oldest.id));
+			entries.delete(oldest.src);
+			id = oldest.id;
+			queueMicrotask(changed);
+		}
+		ids.push({
+			id,
+			src
+		});
+		entry.id = id;
+		return id;
+	};
+	return {
+		get(src, box) {
+			const entry = entryFor(src);
+			switch (entry.state) {
+				case "ask": return { kind: "ask" };
+				case "loading": return { kind: "loading" };
+				case "failed": return {
+					kind: "failed",
+					error: entry.error
+				};
+				case "declined": return void 0;
+			}
+			const id = assignId(src, entry);
+			if (!entry.sent) {
+				write(transmit(id, entry.png));
+				entry.sent = true;
+				entry.png = void 0;
+			}
+			const cells = fitCells(entry.px, box, cell);
+			const key = `${cells.columns}x${cells.rows}`;
+			if (entry.placed !== key) {
+				write(place(id, cells));
+				entry.placed = key;
+			}
+			return {
+				kind: "ready",
+				rows: placeholderRows(cells.columns, cells.rows),
+				color: `ansi256(${id})`
+			};
+		},
+		allow(src) {
+			allowed.add(src);
+			const entry = entries.get(src);
+			if (!entry) entryFor(src);
+			else if (entry.state === "ask") load(src, entry, true);
+			changed();
+		},
+		get version() {
+			return version;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		query: CELL_SIZE_QUERY,
+		get cellSize() {
+			return cell;
+		},
+		takeReply(input) {
+			const match = CELL_SIZE_REPLY.exec(input);
+			if (!match) return false;
+			const next = {
+				width: Number(match[2]),
+				height: Number(match[1])
+			};
+			if (next.width > 0 && next.height > 0 && (next.width !== cell.width || next.height !== cell.height)) {
+				cell = next;
+				for (const entry of entries.values()) entry.placed = void 0;
+				changed();
+			}
+			return true;
+		}
+	};
+}
+
+//#endregion
+export { CELL_SIZE_QUERY, DIACRITICS, MAX_CELLS, MAX_IMAGES, MAX_IMAGE_SIDE, createKittyProvider, detectKitty, fitCells, forget, isPng, place, placeholderRows, pngSize, transmit };