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

package/dist/kitty-jpeg.d.ts

@@ -0,0 +1,26 @@
+//#region src/kitty/jpeg.d.ts
+interface JpegDecoderOptions {
+    /** Largest width and height in pixels after downscaling (default 1600 × 1600). */
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Refuse images above this many megapixels before decoding (default 50). */
+    maxMegapixels?: number;
+}
+/** Whether bytes start with the JPEG signature. */
+declare function isJpeg(bytes: Uint8Array): boolean;
+/** The size that fits `width` × `height` into the bounds, keeping aspect, never upscaling. */
+declare function fitSize(width: number, height: number, maxWidth: number, maxHeight: number): {
+    width: number;
+    height: number;
+};
+/** Downscale RGBA pixels by averaging the source area under each target pixel. */
+declare function downscale(data: Uint8Array, width: number, height: number, toWidth: number, toHeight: number): Uint8Array;
+/**
+* A decoder for `createKittyProvider({ decode })`: JPEG bytes become a
+* downscaled PNG; anything else is declined (`undefined`), as is a JPEG that
+* fails to decode or is too large.
+*/
+declare function createJpegDecoder(options?: JpegDecoderOptions): (bytes: Uint8Array, _mediaType: string) => Promise<Uint8Array | undefined>;
+
+//#endregion
+export { JpegDecoderOptions, createJpegDecoder, downscale, fitSize, isJpeg };

package/dist/kitty-jpeg.js

@@ -0,0 +1,84 @@
+import { encode } from "fast-png";
+import { decode } from "jpeg-js";
+
+//#region src/kitty/jpeg.ts
+/** Whether bytes start with the JPEG signature. */
+function isJpeg(bytes) {
+	return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+}
+/** The size that fits `width` × `height` into the bounds, keeping aspect, never upscaling. */
+function fitSize(width, height, maxWidth, maxHeight) {
+	const scale = Math.min(1, maxWidth / width, maxHeight / height);
+	return {
+		width: Math.max(1, Math.round(width * scale)),
+		height: Math.max(1, Math.round(height * scale))
+	};
+}
+/** Downscale RGBA pixels by averaging the source area under each target pixel. */
+function downscale(data, width, height, toWidth, toHeight) {
+	if (toWidth === width && toHeight === height) return data;
+	const out = new Uint8Array(toWidth * toHeight * 4);
+	const sx = width / toWidth;
+	const sy = height / toHeight;
+	for (let y = 0; y < toHeight; y++) {
+		const y0 = Math.floor(y * sy);
+		const y1 = Math.max(y0 + 1, Math.floor((y + 1) * sy));
+		for (let x = 0; x < toWidth; x++) {
+			const x0 = Math.floor(x * sx);
+			const x1 = Math.max(x0 + 1, Math.floor((x + 1) * sx));
+			const sum = [
+				0,
+				0,
+				0,
+				0
+			];
+			for (let yy = y0; yy < y1; yy++) for (let xx = x0; xx < x1; xx++) {
+				const i = (yy * width + xx) * 4;
+				for (let c = 0; c < 4; c++) sum[c] = sum[c] + data[i + c];
+			}
+			const n = (y1 - y0) * (x1 - x0);
+			const o = (y * toWidth + x) * 4;
+			for (let c = 0; c < 4; c++) out[o + c] = Math.round(sum[c] / n);
+		}
+	}
+	return out;
+}
+/**
+* A decoder for `createKittyProvider({ decode })`: JPEG bytes become a
+* downscaled PNG; anything else is declined (`undefined`), as is a JPEG that
+* fails to decode or is too large.
+*/
+function createJpegDecoder(options = {}) {
+	const { maxWidth = 1600, maxHeight = 1600, maxMegapixels = 50 } = options;
+	for (const [name, value] of Object.entries({
+		maxWidth,
+		maxHeight,
+		maxMegapixels
+	})) if (!(value > 0 && Number.isFinite(value))) throw new RangeError(`${name} must be a positive finite number, got ${value}`);
+	return async (bytes, _mediaType) => {
+		if (!isJpeg(bytes)) return void 0;
+		let image;
+		try {
+			image = decode(bytes, {
+				useTArray: true,
+				formatAsRGBA: true,
+				maxResolutionInMP: maxMegapixels,
+				maxMemoryUsageInMB: 1024
+			});
+		} catch {
+			return void 0;
+		}
+		const size = fitSize(image.width, image.height, maxWidth, maxHeight);
+		const data = downscale(image.data, image.width, image.height, size.width, size.height);
+		return encode({
+			width: size.width,
+			height: size.height,
+			data,
+			channels: 4,
+			depth: 8
+		});
+	};
+}
+
+//#endregion
+export { createJpegDecoder, downscale, fitSize, isJpeg };

package/dist/kitty.d.ts

@@ -0,0 +1,86 @@
+import { CellBox, ImageProvider } from "./images.d-KUBzdbd9.js";
+
+//#region src/kitty/diacritics.d.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).
+*/
+declare const DIACRITICS: readonly number[];
+
+//#endregion
+//#region src/kitty/provider.d.ts
+/** Ids available to images (the 256-colour foreground carries the id). */
+declare const MAX_IMAGES = 255;
+/** The largest width or height in pixels a terminal accepts (kitty's and ghostty's limit). */
+declare const MAX_IMAGE_SIDE = 10000;
+/** The largest grid in cells: one combining diacritic per row and per column number. */
+declare const MAX_CELLS: number;
+/** Whether the terminal speaks the kitty graphics protocol (and is not behind a multiplexer). */
+declare function detectKitty(env?: Record<string, string | undefined>): boolean;
+declare function isPng(bytes: Uint8Array): boolean;
+/**
+* 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.
+*/
+declare function pngSize(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+* 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.
+*/
+declare function fitCells(px: {
+    width: number;
+    height: number;
+}, within: CellBox, cell: {
+    width: number;
+    height: number;
+}): CellBox;
+/** Placeholder text for an image: one string per cell row, at most `MAX_CELLS` each way. */
+declare function placeholderRows(columns: number, rows: number): string[];
+/** Transmit PNG bytes quietly under `id`, in protocol-sized chunks. */
+declare function transmit(id: number, png: Uint8Array): string;
+/** One virtual placement for `id`, sized to a cell box (replacing the previous one). */
+declare function place(id: number, box: CellBox): string;
+/** Forget an image and its placements. */
+declare function forget(id: number): string;
+/** Ask the terminal for its cell size in pixels. */
+declare const CELL_SIZE_QUERY: string;
+interface KittyOptions {
+    /** Writes escapes to the terminal (before the frame showing the placeholders). */
+    write: (data: string) => void;
+    fetch?: typeof fetch;
+    /** Turns other formats into PNG bytes; without it they stay captions. */
+    decode?: (bytes: Uint8Array, mediaType: string) => Promise<Uint8Array | undefined>;
+    /** Sources loaded without a click (default: `data:` URLs only). */
+    autoFetch?: (src: string) => boolean;
+    /** Per fetch, in ms (default 15 s). */
+    timeoutMs?: number;
+    /** Largest image in bytes, fetched or decoded (default 20 MB). */
+    maxBytes?: number;
+    /**
+     * Largest image in megapixels, PNG or decoded (default 50); each side is
+     * also held to `MAX_IMAGE_SIDE`. The terminal inflates what it is sent, so
+     * a small, highly compressed PNG is bounded by its pixels, not its bytes.
+     */
+    maxMegapixels?: number;
+}
+interface KittyProvider extends ImageProvider {
+    /** The cell-size query (the viewport writes it once). */
+    readonly query: string;
+    /** The current cell size in pixels (9×18 until the terminal answers). */
+    readonly cellSize: {
+        width: number;
+        height: number;
+    };
+    /** Recognise a cell-size reply; returns whether `input` was one. */
+    takeReply(input: string): boolean;
+}
+declare function createKittyProvider(options: KittyOptions): KittyProvider;
+
+//#endregion
+export { CELL_SIZE_QUERY, DIACRITICS, KittyOptions, KittyProvider, MAX_CELLS, MAX_IMAGES, MAX_IMAGE_SIDE, createKittyProvider, detectKitty, fitCells, forget, isPng, place, placeholderRows, pngSize, transmit };