@narumitw/pi-jupyter 0.1.4 → 0.33.0

package/src/notebook-panel.ts

@@ -0,0 +1,204 @@
+import { basename, relative } from "node:path";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	Key,
+	matchesKey,
+	type OverlayOptions,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import {
+	type LoadedNotebook,
+	type Notebook,
+	renderNotebookBody,
+	sanitizeTerminalText,
+	wrapBoxLines,
+} from "./notebook.js";
+
+export const DEFAULT_PANEL_WIDTH_PERCENT = 42;
+export const MIN_PANEL_WIDTH = 42;
+export const MIN_EDITOR_WIDTH = 24;
+export const RIGHT_MARGIN = 1;
+
+export type PreviewState = {
+	path?: string;
+	cwd: string;
+	visible: boolean;
+	focused: boolean;
+	scroll: number;
+	lastLoadedAt?: Date;
+	lastMtime?: Date;
+	lastError?: string;
+	model?: Notebook;
+	panelWidth?: number;
+	resizing?: boolean;
+};
+
+export function applyLoadedNotebook(state: PreviewState, loaded: LoadedNotebook): void {
+	state.model = loaded.model;
+	state.lastMtime = loaded.lastMtime;
+	state.lastLoadedAt = loaded.lastLoadedAt;
+	state.lastError = undefined;
+}
+
+export class NotebookPreviewPanel implements Component {
+	private readonly tui: TUI;
+	private readonly theme: Theme;
+	private readonly state: PreviewState;
+	private readonly releaseFocus: () => void;
+
+	constructor(tui: TUI, theme: Theme, state: PreviewState, releaseFocus: () => void) {
+		this.tui = tui;
+		this.theme = theme;
+		this.state = state;
+		this.releaseFocus = releaseFocus;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape) || matchesKey(data, "f8")) {
+			this.releaseFocus();
+			return;
+		}
+		const page = 10;
+		if (matchesKey(data, Key.up) || data === "k")
+			this.state.scroll = Math.max(0, this.state.scroll - 1);
+		else if (matchesKey(data, Key.down) || data === "j") this.state.scroll += 1;
+		else if (matchesKey(data, Key.home) || data === "g") this.state.scroll = 0;
+		else if (matchesKey(data, Key.pageUp) || data === "u") {
+			this.state.scroll = Math.max(0, this.state.scroll - page);
+		} else if (matchesKey(data, Key.pageDown) || data === "d") this.state.scroll += page;
+		else return;
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		const inner = Math.max(1, width - 2);
+		const border = (text: string) => this.theme.fg("border", text);
+		const accent = (text: string) => this.theme.fg("accent", text);
+		const dim = (text: string) => this.theme.fg("dim", text);
+		const error = (text: string) => this.theme.fg("error", text);
+		const pad = (text = "") => {
+			const truncated = truncateToWidth(text, inner, "…", true);
+			return `${border("│")}${truncated}${" ".repeat(Math.max(0, inner - visibleWidth(truncated)))}${border("│")}`;
+		};
+		const pathLabel = this.state.path
+			? sanitizeTerminalText(relative(this.state.cwd, this.state.path) || basename(this.state.path))
+			: "no notebook";
+		const title = `${this.state.resizing ? "↔ " : this.state.focused ? "● " : ""}Jupyter Preview`;
+		const lines = [border(`╭${"─".repeat(inner)}╮`), pad(` ${accent(title)} ${dim(pathLabel)}`)];
+		lines.push(`${border("├")}${border("─".repeat(inner))}${border("┤")}`);
+
+		if (!this.state.path) {
+			lines.push(pad(" No notebook selected."), pad(dim(" Run /jupyter to choose one.")));
+		} else if (this.state.lastError && !this.state.model) {
+			lines.push(
+				...wrapBoxLines(error(sanitizeTerminalText(this.state.lastError)), inner).map(pad),
+			);
+		} else if (!this.state.model) lines.push(pad(dim(" Loading…")));
+		else {
+			if (this.state.lastError) {
+				lines.push(
+					...wrapBoxLines(
+						error(
+							` Refresh failed; showing last valid version: ${sanitizeTerminalText(this.state.lastError)}`,
+						),
+						inner,
+					).map(pad),
+					pad(),
+				);
+			}
+			const body = renderNotebookBody(this.state, inner, this.theme);
+			const maximumScroll = Math.max(0, body.length - 3);
+			this.state.scroll = Math.min(this.state.scroll, maximumScroll);
+			lines.push(...body.slice(this.state.scroll).map(pad));
+		}
+
+		lines.push(`${border("├")}${border("─".repeat(inner))}${border("┤")}`);
+		lines.push(pad(dim(previewFooter(this.state, inner))), border(`╰${"─".repeat(inner)}╯`));
+		return lines;
+	}
+
+	invalidate(): void {}
+}
+
+type MouseEvent = { button: number; x: number; y: number; released: boolean };
+
+export function installMouseResize(
+	tui: TUI,
+	state: PreviewState,
+	overlayOptions: OverlayOptions,
+	requestRender: () => void,
+): () => void {
+	const terminal = tui.terminal;
+	terminal.write("\x1b[?1000h\x1b[?1002h\x1b[?1006h");
+	const removeListener = tui.addInputListener((data) => {
+		const event = parseSgrMouseEvent(data);
+		if (!event) return undefined;
+		const isPrimaryButton = (event.button & 3) === 0;
+		const isMotion = (event.button & 32) !== 0;
+		const handleX = getPanelLeftBorderX(terminal.columns, state);
+		if (event.released && state.resizing) {
+			state.resizing = false;
+			requestRender();
+			return { consume: true };
+		}
+		if (!state.resizing && isPrimaryButton && Math.abs(event.x - handleX) <= 1)
+			state.resizing = true;
+		if (!state.resizing || !isPrimaryButton) return undefined;
+		if (isMotion || event.x !== handleX) {
+			const width = clampPanelWidth(
+				terminal.columns - RIGHT_MARGIN - (event.x - 1),
+				terminal.columns,
+			);
+			state.panelWidth = width;
+			overlayOptions.width = width;
+			requestRender();
+		}
+		return { consume: true };
+	});
+	return () => {
+		state.resizing = false;
+		removeListener();
+		terminal.write("\x1b[?1006l\x1b[?1002l\x1b[?1000l");
+	};
+}
+
+export function previewFooter(state: PreviewState, width: number): string {
+	if (state.resizing) return " Drag to resize width";
+	if (state.focused) {
+		return width >= 58
+			? " ↑↓ PgUp/PgDn or j/k/u/d scroll • Esc/F8 return"
+			: " ↑↓ scroll • Esc/F8 return";
+	}
+	return width >= 58
+		? " Drag left border resize • Ctrl+Alt+j/k scroll • Shift+F8 focus"
+		: " Shift+F8 focus • F8 close";
+}
+
+export function parseSgrMouseEvent(data: string): MouseEvent | undefined {
+	const prefix = "\x1b[<";
+	if (!data.startsWith(prefix)) return undefined;
+	const suffix = data.at(-1);
+	if (suffix !== "M" && suffix !== "m") return undefined;
+	const parts = data.slice(prefix.length, -1).split(";");
+	if (parts.length !== 3) return undefined;
+	const [button, x, y] = parts.map((part) => Number.parseInt(part, 10));
+	if (button === undefined || x === undefined || y === undefined) return undefined;
+	if (![button, x, y].every(Number.isFinite)) return undefined;
+	return { button, x, y, released: suffix === "m" };
+}
+
+function getPanelLeftBorderX(termWidth: number, state: PreviewState): number {
+	const width = clampPanelWidth(
+		state.panelWidth ?? Math.floor((termWidth * DEFAULT_PANEL_WIDTH_PERCENT) / 100),
+		termWidth,
+	);
+	return termWidth - RIGHT_MARGIN - width + 1;
+}
+
+export function clampPanelWidth(width: number, termWidth: number): number {
+	const maxWidth = Math.max(MIN_PANEL_WIDTH, termWidth - RIGHT_MARGIN - MIN_EDITOR_WIDTH);
+	return Math.max(MIN_PANEL_WIDTH, Math.min(maxWidth, Math.round(width)));
+}

package/src/notebook.ts

@@ -0,0 +1,237 @@
+import { constants } from "node:fs";
+import { type FileHandle, open } from "node:fs/promises";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Image, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { decodePng, renderPngThumbnail } from "./png-thumbnail.js";
+
+export const MAX_NOTEBOOK_BYTES = 10 * 1024 * 1024;
+
+export type NotebookCell = {
+	cell_type?: string;
+	execution_count?: number | null;
+	source?: string | string[];
+	outputs?: Array<Record<string, unknown>>;
+};
+
+export type Notebook = {
+	cells?: NotebookCell[];
+	metadata?: Record<string, unknown>;
+	nbformat?: number;
+	nbformat_minor?: number;
+};
+
+export type LoadedNotebook = {
+	model: Notebook;
+	lastMtime: Date;
+	lastLoadedAt: Date;
+};
+
+export type NotebookRenderState = Partial<LoadedNotebook> & {
+	model?: Notebook;
+};
+
+export async function loadNotebook(path: string, signal?: AbortSignal): Promise<LoadedNotebook> {
+	signal?.throwIfAborted();
+	const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		signal?.throwIfAborted();
+		const info = await file.stat();
+		if (!info.isFile()) throw new Error("notebook path is not a regular file");
+		if (info.size > MAX_NOTEBOOK_BYTES) {
+			throw new Error(`notebook exceeds the ${MAX_NOTEBOOK_BYTES / 1024 / 1024} MB preview limit`);
+		}
+		const model = JSON.parse(await readBoundedUtf8(file, signal)) as Notebook;
+		validateNotebook(model);
+		return { model, lastMtime: info.mtime, lastLoadedAt: new Date() };
+	} finally {
+		await file.close();
+	}
+}
+
+async function readBoundedUtf8(file: FileHandle, signal?: AbortSignal): Promise<string> {
+	const chunks: Buffer[] = [];
+	let total = 0;
+	while (total <= MAX_NOTEBOOK_BYTES) {
+		signal?.throwIfAborted();
+		const buffer = Buffer.alloc(Math.min(64 * 1024, MAX_NOTEBOOK_BYTES + 1 - total));
+		const { bytesRead } = await file.read(buffer, 0, buffer.length, null);
+		if (bytesRead === 0) break;
+		chunks.push(buffer.subarray(0, bytesRead));
+		total += bytesRead;
+	}
+	if (total > MAX_NOTEBOOK_BYTES) {
+		throw new Error(`notebook exceeds the ${MAX_NOTEBOOK_BYTES / 1024 / 1024} MB preview limit`);
+	}
+	return Buffer.concat(chunks, total).toString("utf8");
+}
+
+function validateNotebook(value: unknown): asserts value is Notebook {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("notebook root must be an object");
+	}
+	const notebook = value as Notebook;
+	if (notebook.cells !== undefined && !Array.isArray(notebook.cells)) {
+		throw new Error("notebook cells must be an array");
+	}
+}
+
+export function renderNotebookBody(
+	state: NotebookRenderState,
+	width: number,
+	theme: Theme,
+): string[] {
+	const notebook = state.model;
+	if (!notebook) return [];
+	const cells = Array.isArray(notebook.cells) ? notebook.cells : [];
+	const dim = (text: string) => theme.fg("dim", text);
+	const accent = (text: string) => theme.fg("accent", text);
+	const success = (text: string) => theme.fg("success", text);
+	const warning = (text: string) => theme.fg("warning", text);
+	const error = (text: string) => theme.fg("error", text);
+	const loaded = state.lastLoadedAt?.toLocaleTimeString() ?? "unknown";
+	const mtime = state.lastMtime?.toLocaleTimeString() ?? "unknown";
+	const lines = [
+		` ${success("✓")} ${cells.length} cells ${dim(`loaded ${loaded}, mtime ${mtime}`)}`,
+		"",
+	];
+
+	cells.forEach((cell, index) => {
+		const type = sanitizeTerminalText(cell.cell_type ?? "unknown");
+		const execution = cell.execution_count == null ? "" : ` In [${cell.execution_count}]`;
+		const color = type === "markdown" ? accent : type === "code" ? success : warning;
+		lines.push(color(` ${index + 1}. ${type}${execution}`));
+
+		const source = sanitizeTerminalText(normalizeSource(cell.source)).trimEnd();
+		const sourceLines = source.length > 0 ? source.split("\n") : [dim("(empty)")];
+		for (const line of sourceLines.slice(0, 12)) lines.push(...wrapBoxLines(`   ${line}`, width));
+		if (sourceLines.length > 12)
+			lines.push(dim(`   … ${sourceLines.length - 12} more source lines`));
+
+		if (type === "code" && Array.isArray(cell.outputs) && cell.outputs.length > 0) {
+			const outputLines = renderOutputs(cell.outputs, width, theme);
+			if (outputLines.length > 0) {
+				lines.push(dim("   output:"));
+				for (const outputLine of outputLines.slice(0, 24)) {
+					const styled = outputLine.startsWith("Error:") ? error(outputLine) : outputLine;
+					lines.push(...wrapBoxLines(`     ${styled}`, width));
+				}
+				if (outputLines.length > 24) {
+					lines.push(dim(`     … ${outputLines.length - 24} more output lines`));
+				}
+			}
+		}
+		lines.push("");
+	});
+	return lines;
+}
+
+function renderOutputs(
+	outputs: Array<Record<string, unknown>>,
+	width: number,
+	theme: Theme,
+): string[] {
+	const lines: string[] = [];
+	const dim = (text: string) => theme.fg("dim", text);
+	for (const output of outputs) {
+		const outputType = sanitizeTerminalText(String(output.output_type ?? "output"));
+		if (outputType === "stream") {
+			lines.push(
+				...sanitizeTerminalText(normalizeSource(output.text as string | string[] | undefined))
+					.split("\n")
+					.filter(Boolean)
+					.map(dim),
+			);
+			continue;
+		}
+		if (outputType === "error") {
+			const name = sanitizeTerminalText(String(output.ename ?? "Error"));
+			const value = sanitizeTerminalText(String(output.evalue ?? ""));
+			lines.push(`Error: ${name}${value ? `: ${value}` : ""}`);
+			continue;
+		}
+
+		const data = output.data as Record<string, unknown> | undefined;
+		if (data) {
+			const imageMime = Object.keys(data).find((key) => key.startsWith("image/"));
+			if (imageMime) {
+				lines.push(dim(`${sanitizeTerminalText(imageMime)}:`));
+				lines.push(
+					...renderInlineImage(
+						normalizeSource(data[imageMime] as string | string[]),
+						imageMime,
+						width,
+						theme,
+					),
+				);
+			}
+			const text = data["text/plain"] ?? data["text/markdown"];
+			if (typeof text === "string" || Array.isArray(text)) {
+				lines.push(
+					...sanitizeTerminalText(normalizeSource(text as string | string[]))
+						.split("\n")
+						.filter(Boolean)
+						.map(dim),
+				);
+			}
+			if (imageMime || typeof text === "string" || Array.isArray(text)) continue;
+		}
+		lines.push(dim(`[${outputType}]`));
+	}
+	return lines;
+}
+
+function renderInlineImage(
+	base64Data: string,
+	mimeType: string,
+	width: number,
+	theme: Theme,
+): string[] {
+	const cleanBase64 = base64Data.replace(/\s+/g, "");
+	if (!cleanBase64) return [theme.fg("warning", `[empty ${mimeType} output]`)];
+	if (mimeType === "image/png") {
+		try {
+			return renderPngThumbnail(decodePng(cleanBase64), Math.max(8, Math.min(60, width - 8)), 16);
+		} catch (cause) {
+			return [theme.fg("warning", `[${mimeType} thumbnail failed: ${errorMessage(cause)}]`)];
+		}
+	}
+	try {
+		const image = new Image(
+			cleanBase64,
+			mimeType,
+			{ fallbackColor: (text: string) => theme.fg("muted", text) },
+			{ maxWidthCells: Math.max(8, Math.min(60, width - 8)), maxHeightCells: 16 },
+		);
+		return image.render(Math.max(10, width - 8));
+	} catch (cause) {
+		return [theme.fg("warning", `[${mimeType} output: ${errorMessage(cause)}]`)];
+	}
+}
+
+export function sanitizeTerminalText(text: string): string {
+	let sanitized = "";
+	for (const character of text) {
+		const code = character.codePointAt(0) ?? 0;
+		const isUnsafe =
+			(code < 0x20 && code !== 0x09 && code !== 0x0a) || (code >= 0x7f && code <= 0x9f);
+		sanitized += isUnsafe ? `\\x${code.toString(16).padStart(2, "0")}` : character;
+	}
+	return sanitized;
+}
+
+function errorMessage(cause: unknown): string {
+	return sanitizeTerminalText(cause instanceof Error ? cause.message : String(cause));
+}
+
+function normalizeSource(source: string | string[] | undefined): string {
+	if (Array.isArray(source)) return source.join("");
+	return typeof source === "string" ? source : "";
+}
+
+export function wrapBoxLines(text: string, width: number): string[] {
+	const max = Math.max(1, width - 1);
+	return wrapTextWithAnsi(text, max).map((line) => {
+		if (visibleWidth(line) <= max) return line;
+		return truncateToWidth(line, max, "…", true);
+	});
+}

package/src/png-thumbnail.ts

@@ -0,0 +1,237 @@
+import { inflateSync } from "node:zlib";
+
+export type DecodedPng = {
+	width: number;
+	height: number;
+	pixels: Uint8ClampedArray;
+};
+
+const MAX_PNG_PIXELS = 16_000_000;
+const MAX_INFLATED_BYTES = MAX_PNG_PIXELS * 4 + 4096;
+
+export function decodePng(base64Data: string): DecodedPng {
+	const bytes = Buffer.from(base64Data, "base64");
+	const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+	if (bytes.length < signature.length || !bytes.subarray(0, signature.length).equals(signature)) {
+		throw new Error("not a PNG");
+	}
+
+	let offset = 8;
+	let width = 0;
+	let height = 0;
+	let bitDepth = 0;
+	let colorType = 0;
+	let palette: Buffer | undefined;
+	let transparency: Buffer | undefined;
+	const idat: Buffer[] = [];
+
+	while (offset + 12 <= bytes.length) {
+		const length = bytes.readUInt32BE(offset);
+		const chunkEnd = offset + 12 + length;
+		if (chunkEnd > bytes.length) throw new Error("truncated PNG chunk");
+		const type = bytes.subarray(offset + 4, offset + 8).toString("ascii");
+		const data = bytes.subarray(offset + 8, offset + 8 + length);
+		offset = chunkEnd;
+
+		if (type === "IHDR") {
+			if (data.length !== 13) throw new Error("invalid PNG header");
+			width = data.readUInt32BE(0);
+			height = data.readUInt32BE(4);
+			bitDepth = data[8] ?? 0;
+			colorType = data[9] ?? 0;
+			if (data[10] !== 0 || data[11] !== 0 || data[12] !== 0) {
+				throw new Error("unsupported PNG format");
+			}
+		} else if (type === "PLTE") palette = Buffer.from(data);
+		else if (type === "tRNS") transparency = Buffer.from(data);
+		else if (type === "IDAT") idat.push(Buffer.from(data));
+		else if (type === "IEND") break;
+	}
+
+	if (!width || !height || idat.length === 0) throw new Error("missing PNG data");
+	if (width * height > MAX_PNG_PIXELS) throw new Error("PNG dimensions are too large");
+	if (bitDepth !== 8) throw new Error(`unsupported PNG bit depth ${bitDepth}`);
+
+	const channels = pngChannels(colorType);
+	const stride = width * channels;
+	const expectedBytes = height * (stride + 1);
+	if (expectedBytes > MAX_INFLATED_BYTES) throw new Error("PNG output is too large");
+	const inflated = inflateSync(Buffer.concat(idat), { maxOutputLength: expectedBytes });
+	if (inflated.length !== expectedBytes) throw new Error("invalid PNG scanline data");
+
+	const raw = Buffer.alloc(height * stride);
+	let inOffset = 0;
+	let outOffset = 0;
+	let previous = Buffer.alloc(stride);
+	for (let y = 0; y < height; y++) {
+		const filter = inflated[inOffset++];
+		const scanline = inflated.subarray(inOffset, inOffset + stride);
+		inOffset += stride;
+		const recon = Buffer.alloc(stride);
+		for (let x = 0; x < stride; x++) {
+			const left = x >= channels ? (recon[x - channels] ?? 0) : 0;
+			const up = previous[x] ?? 0;
+			const upLeft = x >= channels ? (previous[x - channels] ?? 0) : 0;
+			const value = scanline[x] ?? 0;
+			switch (filter) {
+				case 0:
+					recon[x] = value;
+					break;
+				case 1:
+					recon[x] = (value + left) & 0xff;
+					break;
+				case 2:
+					recon[x] = (value + up) & 0xff;
+					break;
+				case 3:
+					recon[x] = (value + Math.floor((left + up) / 2)) & 0xff;
+					break;
+				case 4:
+					recon[x] = (value + paeth(left, up, upLeft)) & 0xff;
+					break;
+				default:
+					throw new Error(`unsupported PNG filter ${filter}`);
+			}
+		}
+		recon.copy(raw, outOffset);
+		outOffset += stride;
+		previous = recon;
+	}
+
+	return {
+		width,
+		height,
+		pixels: convertToRgba(raw, width, height, colorType, palette, transparency),
+	};
+}
+
+function convertToRgba(
+	raw: Buffer,
+	width: number,
+	height: number,
+	colorType: number,
+	palette?: Buffer,
+	transparency?: Buffer,
+): Uint8ClampedArray {
+	const pixels = new Uint8ClampedArray(width * height * 4);
+	for (let i = 0, p = 0; i < raw.length; p++) {
+		let r = 0;
+		let g = 0;
+		let b = 0;
+		let a = 255;
+		if (colorType === 0) {
+			r = g = b = raw[i++] ?? 0;
+			if (transparency?.length === 2 && r === transparency.readUInt16BE(0)) a = 0;
+		} else if (colorType === 2) {
+			r = raw[i++] ?? 0;
+			g = raw[i++] ?? 0;
+			b = raw[i++] ?? 0;
+			if (
+				transparency?.length === 6 &&
+				r === transparency.readUInt16BE(0) &&
+				g === transparency.readUInt16BE(2) &&
+				b === transparency.readUInt16BE(4)
+			)
+				a = 0;
+		} else if (colorType === 3) {
+			const index = raw[i++] ?? 0;
+			if (!palette || index * 3 + 2 >= palette.length) throw new Error("invalid PNG palette");
+			r = palette[index * 3] ?? 0;
+			g = palette[index * 3 + 1] ?? 0;
+			b = palette[index * 3 + 2] ?? 0;
+			a = transparency?.[index] ?? 255;
+		} else if (colorType === 4) {
+			r = g = b = raw[i++] ?? 0;
+			a = raw[i++] ?? 0;
+		} else {
+			r = raw[i++] ?? 0;
+			g = raw[i++] ?? 0;
+			b = raw[i++] ?? 0;
+			a = raw[i++] ?? 0;
+		}
+		const output = p * 4;
+		pixels[output] = r;
+		pixels[output + 1] = g;
+		pixels[output + 2] = b;
+		pixels[output + 3] = a;
+	}
+	return pixels;
+}
+
+function pngChannels(colorType: number): number {
+	switch (colorType) {
+		case 0:
+		case 3:
+			return 1;
+		case 2:
+			return 3;
+		case 4:
+			return 2;
+		case 6:
+			return 4;
+		default:
+			throw new Error(`unsupported PNG color type ${colorType}`);
+	}
+}
+
+function paeth(a: number, b: number, c: number): number {
+	const p = a + b - c;
+	const pa = Math.abs(p - a);
+	const pb = Math.abs(p - b);
+	const pc = Math.abs(p - c);
+	if (pa <= pb && pa <= pc) return a;
+	return pb <= pc ? b : c;
+}
+
+export function renderPngThumbnail(
+	png: DecodedPng,
+	maxWidthCells: number,
+	maxHeightCells: number,
+): string[] {
+	let targetWidth = Math.max(1, Math.min(maxWidthCells, png.width));
+	let targetPixelHeight = Math.max(1, Math.round((png.height / png.width) * targetWidth));
+	if (Math.ceil(targetPixelHeight / 2) > maxHeightCells) {
+		targetPixelHeight = maxHeightCells * 2;
+		targetWidth = Math.max(
+			1,
+			Math.min(maxWidthCells, Math.round((png.width / png.height) * targetPixelHeight)),
+		);
+	}
+
+	const lines: string[] = [];
+	for (let row = 0; row < Math.ceil(targetPixelHeight / 2); row++) {
+		let line = "";
+		for (let x = 0; x < targetWidth; x++) {
+			const upper = samplePngPixel(png, x, row * 2, targetWidth, targetPixelHeight);
+			const lower =
+				row * 2 + 1 < targetPixelHeight
+					? samplePngPixel(png, x, row * 2 + 1, targetWidth, targetPixelHeight)
+					: ([255, 255, 255] as const);
+			line += `\x1b[38;2;${upper[0]};${upper[1]};${upper[2]}m\x1b[48;2;${lower[0]};${lower[1]};${lower[2]}m▀`;
+		}
+		lines.push(`${line}\x1b[0m`);
+	}
+	return lines;
+}
+
+function samplePngPixel(
+	png: DecodedPng,
+	x: number,
+	y: number,
+	targetWidth: number,
+	targetHeight: number,
+): readonly [number, number, number] {
+	const sx = Math.min(
+		png.width - 1,
+		Math.max(0, Math.floor(((x + 0.5) / targetWidth) * png.width)),
+	);
+	const sy = Math.min(
+		png.height - 1,
+		Math.max(0, Math.floor(((y + 0.5) / targetHeight) * png.height)),
+	);
+	const offset = (sy * png.width + sx) * 4;
+	const alpha = (png.pixels[offset + 3] ?? 0) / 255;
+	const blend = (channel: number) =>
+		Math.round((png.pixels[offset + channel] ?? 0) * alpha + 255 * (1 - alpha));
+	return [blend(0), blend(1), blend(2)];
+}