Add preferNativeRender option (#47)

Co-authored-by: Sindre Sorhus <[email protected]>

Author: umikoio

index.d.ts

@@ -33,6 +33,7 @@ declare const terminalImage: {
 	@param options.width - Optional: Custom image width. Can be set as percentage or number of columns of the terminal. It is recommended to use the percentage options.
 	@param options.height - Optional: Custom image height. Can be set as percentage or number of rows of the terminal. It is recommended to use the percentage options.
 	@param options.preserveAspectRatio - Optional: Whether to maintain image aspect ratio or not. Default: true.
+	@param options.preferNativeRender - Prefer native terminal image protocols when available; set to false to force ANSI rendering. Default: true.
 	@returns The ansi escape codes to display the image.
 
 	@example
@@ -51,6 +52,7 @@ declare const terminalImage: {
 		width?: string | number;
 		height?: string | number;
 		preserveAspectRatio?: boolean;
+		preferNativeRender?: boolean;
 	}>) => Promise<string>;
 
 	/**
@@ -69,6 +71,7 @@ declare const terminalImage: {
 	@param options.width - Optional: Custom image width. Can be set as percentage or number of columns of the terminal. It is recommended to use the percentage options.
 	@param options.height - Optional: Custom image height. Can be set as percentage or number of rows of the terminal. It is recommended to use the percentage options.
 	@param options.preserveAspectRatio - Optional: Whether to maintain image aspect ratio or not. Default: true.
+	@param options.preferNativeRender - Prefer native terminal image protocols when available; set to false to force ANSI rendering. Default: true.
 	@returns The ANSI escape codes to display the image.
 
 	@example
@@ -87,6 +90,7 @@ declare const terminalImage: {
 			width?: string | number;
 			height?: string | number;
 			preserveAspectRatio?: boolean;
+			preferNativeRender?: boolean;
 		}>
 	) => Promise<string>;
 

index.js

@@ -210,7 +210,12 @@ async function renderKitty(buffer, {width: inputWidth, height: inputHeight, pres
 
 const terminalImage = {};
 
-terminalImage.buffer = async (buffer, {width = '100%', height = '100%', preserveAspectRatio = true, isGifFrame = false} = {}) => {
+terminalImage.buffer = async (buffer, {width = '100%', height = '100%', preserveAspectRatio = true, isGifFrame = false, preferNativeRender = true} = {}) => {
+	// If not using native terminal rendering, fallback to ANSI
+	if (!preferNativeRender) {
+		return render(buffer, {height, width, preserveAspectRatio});
+	}
+
 	// Check for Kitty protocol support only if we're in an interactive terminal
 	// and not in iTerm2 (which has its own protocol)
 	// Note: We disable Kitty protocol for GIF frames as it doesn't work well with log-update

readme.md

@@ -89,6 +89,13 @@ Default: `true`
 
 Whether to maintain image aspect ratio or not.
 
+##### preferNativeRender
+
+Type: `boolean`\
+Default: `true`
+
+Prefer native terminal image protocols when available; set to false to force ANSI rendering.
+
 ##### maximumFrameRate
 
 **Only works for `terminalImage.gifBuffer` or `terminalImage.gifFile`**