silvery 0.21.0 → 0.23.0

package/dist/{UPNG-DosRPdF4.mjs → image-CIF75xMr.mjs}

@@ -1,4 +1,302 @@
-import { i as __require, t as __commonJSMin } from "./chunk-BSw8zbkd.mjs";
+import { i as __toESM, r as __require, t as __commonJSMin } from "./chunk-BEJ448es.mjs";
+import { r as effect } from "./src-BqeBFB3X.mjs";
+import { j as createTerminalProfile } from "./src-B8lf1kiR.mjs";
+import { c as StdoutContext, l as TermContext } from "./context-CEhuD1R_.mjs";
+import { c as useScreenRect, i as useBoxSize } from "./useLayout-D5cE8OCI.mjs";
+import { n as Box, t as Text } from "./Text-Ci6UCSTL.mjs";
+import { readFileSync } from "node:fs";
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region packages/ag-react/src/hooks/useTerm.ts
+/**
+* Shallow equality comparison for object selectors.
+*
+* @example
+* ```tsx
+* const { cols, rows } = useTerm(t => ({ cols: t.cols, rows: t.rows }), shallow)
+* ```
+*/
+function shallow(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) if (!Object.is(a[key], b[key])) return false;
+	return true;
+}
+function useTerm(selector, equalityFn) {
+	const term = useContext(TermContext);
+	if (!term) throw new Error("useTerm must be used within a render(element, term) context");
+	if (!selector) return term;
+	return useTermSelector(term, selector, equalityFn);
+}
+function useTermSelector(term, selector, equalityFn) {
+	const prevRef = useRef(void 0);
+	const isEqual = equalityFn ?? Object.is;
+	const subscribe = useCallback((listener) => {
+		return effect(() => {
+			term.size.snapshot();
+			listener();
+		});
+	}, [term]);
+	const getSnapshot = useCallback(() => {
+		const next = selector(term);
+		if (prevRef.current !== void 0 && isEqual(prevRef.current, next)) return prevRef.current;
+		prevRef.current = next;
+		return next;
+	}, [
+		term,
+		selector,
+		isEqual
+	]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+//#endregion
+//#region packages/ag-react/src/hooks/useWindowSize.ts
+/**
+* Hook to get the current terminal window size.
+* Re-renders when the terminal is resized.
+*
+* Reads from `term.size` (the Size sub-owner) — always returns defined values
+* via the Size owner's default (80x24 for non-TTY streams).
+*
+* @example
+* ```tsx
+* import { useWindowSize, Box, Text } from '@silvery/ag-react'
+*
+* function StatusBar() {
+*   const { columns, rows } = useWindowSize()
+*   return <Text>{`${columns}x${rows}`}</Text>
+* }
+* ```
+*/
+function useWindowSize() {
+	return useTerm((t) => ({
+		columns: t.size.cols(),
+		rows: t.size.rows()
+	}), shallow);
+}
+//#endregion
+//#region packages/ag-react/src/ui/image/kitty-graphics.ts
+/**
+* Kitty Graphics Protocol
+*
+* Encodes and manages images using the Kitty terminal graphics protocol.
+* Images are transmitted as base64-encoded PNG data via APC (Application
+* Program Command) escape sequences.
+*
+* Protocol reference: https://sw.kovidgoyal.net/kitty/graphics-protocol/
+*
+* Key concepts:
+* - `a=T` — transmit and display the image
+* - `f=100` — format is PNG (raw PNG data, terminal decodes it)
+* - `m=0|1` — 0 = last/only chunk, 1 = more chunks follow
+* - Chunks should be <= 4096 bytes of base64 to avoid overwhelming the terminal
+* - Images can be assigned an `i=<id>` for later deletion
+*/
+const APC_START = "\x1B_G";
+const ST$1 = "\x1B\\";
+/** Maximum base64 bytes per chunk (Kitty recommendation) */
+const MAX_CHUNK_SIZE = 4096;
+/**
+* Encode a PNG image into Kitty graphics protocol escape sequences.
+*
+* The image data is base64-encoded and split into chunks of <= 4096 bytes.
+* Each chunk is wrapped in an APC escape sequence. The first chunk carries
+* the image metadata (action, format, dimensions, ID). Subsequent chunks
+* only carry `m=1` or `m=0` to indicate continuation.
+*
+* @param pngData - Raw PNG image data
+* @param opts - Optional dimensions and ID
+* @returns A string containing the complete escape sequence(s)
+*
+* @example
+* ```ts
+* import { readFileSync } from "fs"
+* import { encodeKittyImage } from "@silvery/ag-react"
+*
+* const png = readFileSync("photo.png")
+* const seq = encodeKittyImage(png, { width: 40, height: 20 })
+* process.stdout.write(seq)
+* ```
+*/
+function encodeKittyImage(pngData, opts) {
+	const chunks = splitIntoChunks(pngData.toString("base64"), MAX_CHUNK_SIZE);
+	if (chunks.length === 0) return `${APC_START}${buildParams(opts, 0)};${ST$1}`;
+	if (chunks.length === 1) return `${APC_START}${buildParams(opts, 0)};${chunks[0]}${ST$1}`;
+	const parts = [];
+	parts.push(`${APC_START}${buildParams(opts, 1)};${chunks[0]}${ST$1}`);
+	for (let i = 1; i < chunks.length - 1; i++) parts.push(`${APC_START}m=1;${chunks[i]}${ST$1}`);
+	parts.push(`${APC_START}m=0;${chunks[chunks.length - 1]}${ST$1}`);
+	return parts.join("");
+}
+/**
+* Generate an escape sequence to delete a Kitty image by ID.
+*
+* Uses `a=d` (delete) with `d=i` (delete by image ID). Removes both the
+* stored image bytes AND every placement of it. Use
+* {@link deleteKittyPlacement} to remove a single placement while keeping
+* the image stored for later re-placement.
+*
+* @param id - The image ID to delete
+* @returns The delete escape sequence
+*
+* @example
+* ```ts
+* process.stdout.write(deleteKittyImage(42))
+* ```
+*/
+function deleteKittyImage(id) {
+	return `${APC_START}a=d,d=i,i=${id},q=2${ST$1}`;
+}
+/**
+* Delete a single placement of a stored image, keeping the image bytes.
+*
+* Uses `a=d` with `d=i` (image id) and `p=` (placement id). The image
+* remains stored on the terminal — re-place via {@link placeKittyImage}
+* without re-transmitting the PNG.
+*
+* @param id - Image ID
+* @param placementId - Placement ID (defaults to 1)
+*/
+function deleteKittyPlacement(id, placementId = 1) {
+	return `${APC_START}a=d,d=i,i=${id},p=${placementId},q=2${ST$1}`;
+}
+/**
+* Place an already-transmitted image at the current cursor position.
+*
+* Uses `a=p` (place existing image). The image must have been previously
+* transmitted with `transmitOnly: true` (or `a=T` — which transmits AND
+* places, but you can still re-place separately afterwards). This is the
+* fast path for a moving image: transmit the PNG once, then emit a tiny
+* APC packet for each position update — no re-encoding of base64 bytes.
+*
+* Pair with {@link deleteKittyPlacement} to clear the prior placement
+* before placing at a new cursor position. Skipping the delete leaves a
+* stacked copy at the old position.
+*
+* @example
+* ```ts
+* // Transmit once
+* write(encodeKittyImage(png, { id: 42, transmitOnly: true }))
+* // Place at cursor (which the caller positions via CSI ;H)
+* write(placeKittyImage({ id: 42, width: 40, height: 20 }))
+* // Move: clear old placement, position cursor, place again
+* write(deleteKittyPlacement(42))
+* write(`\x1b[10;5H`) // move cursor
+* write(placeKittyImage({ id: 42, width: 40, height: 20 }))
+* ```
+*/
+function placeKittyImage(opts) {
+	const placementId = opts.placementId ?? 1;
+	const parts = [
+		`a=p`,
+		`i=${opts.id}`,
+		`p=${placementId}`,
+		`z=${formatIntParam("zIndex", opts.zIndex ?? 1)}`,
+		`C=1`,
+		`q=2`
+	];
+	if (opts.width != null) parts.push(`c=${opts.width}`);
+	if (opts.height != null) parts.push(`r=${opts.height}`);
+	appendPlacementParams(parts, opts);
+	return `${APC_START}${parts.join(",")};${ST$1}`;
+}
+/**
+* Check if the current terminal likely supports the Kitty graphics protocol.
+*
+* Pass a profile or caps fixture when available. Without one, this falls
+* back to {@link createTerminalProfile} — the canonical single-source-of-
+* truth entry point in `@silvery/ansi/profile`. Direct reads of terminal-
+* signal env vars (TERM / TERM_PROGRAM / …) are banned outside that module
+* — see `scripts/lint-env-reads.ts`.
+*
+* For definitive detection, use a terminal query (send the graphics protocol
+* query and check for a response), but that requires async I/O.
+*
+* Known supporting terminals: Kitty, WezTerm, Ghostty (partial), Konsole (partial).
+*
+* @returns `true` if the terminal likely supports Kitty graphics
+*/
+function isKittyGraphicsSupported(profile) {
+	if (profile === void 0) return createTerminalProfile().caps.kittyGraphics;
+	if ("caps" in profile && profile.caps) return profile.caps.kittyGraphics;
+	const resolved = isEmulator(profile) ? profile : profile.emulator;
+	if (!resolved) return false;
+	const term = resolved.TERM;
+	const termProgram = resolved.program;
+	if (term === "dumb") return false;
+	if (term === "xterm-kitty" || termProgram === "kitty") return true;
+	if (termProgram === "WezTerm") return true;
+	if (termProgram === "ghostty" || termProgram === "Ghostty") return true;
+	if (termProgram === "konsole") return true;
+	return false;
+}
+function isEmulator(value) {
+	if (value === null || typeof value !== "object") return false;
+	const maybe = value;
+	return typeof maybe.program === "string" && typeof maybe.TERM === "string";
+}
+/**
+* Build the Kitty graphics protocol parameter string for the first chunk.
+*
+* Important: `KittyImageOptions.width` / `.height` are documented as
+* "terminal columns" / "terminal rows" — i.e. CELL counts. The Kitty
+* protocol uses `c=N` / `r=M` for cell-based display sizing, NOT `s=` /
+* `v=` (those are SOURCE PIXEL dimensions, used only for raw RGB
+* uploads with f=24/32). Sending `s=`/`v=` with f=100 (PNG) leaves
+* display sizing to the PNG's native pixel dimensions, which on a
+* 1536×1024 asset blows up to ~192×64 cells and effectively disappears
+* off-screen. Use `c=`/`r=` so the terminal scales the PNG into the
+* reserved cell viewport.
+*/
+function buildParams(opts, more) {
+	const parts = [
+		opts?.transmitOnly ? `a=t` : `a=T`,
+		`f=100`,
+		`m=${more}`,
+		`z=${formatIntParam("zIndex", opts?.zIndex ?? 1)}`,
+		`C=1`,
+		`q=2`
+	];
+	if (opts?.width != null) parts.push(`c=${opts.width}`);
+	if (opts?.height != null) parts.push(`r=${opts.height}`);
+	if (opts?.id != null) parts.push(`i=${opts.id}`);
+	if (opts) appendPlacementParams(parts, opts);
+	return parts.join(",");
+}
+function appendPlacementParams(parts, opts) {
+	if (opts.pixelOffset?.x != null) parts.push(`X=${formatNonNegativeIntParam("pixelOffset.x", opts.pixelOffset.x)}`);
+	if (opts.pixelOffset?.y != null) parts.push(`Y=${formatNonNegativeIntParam("pixelOffset.y", opts.pixelOffset.y)}`);
+	if (opts.sourceRect?.x != null) parts.push(`x=${formatNonNegativeIntParam("sourceRect.x", opts.sourceRect.x)}`);
+	if (opts.sourceRect?.y != null) parts.push(`y=${formatNonNegativeIntParam("sourceRect.y", opts.sourceRect.y)}`);
+	if (opts.sourceRect?.width != null) parts.push(`w=${formatPositiveIntParam("sourceRect.width", opts.sourceRect.width)}`);
+	if (opts.sourceRect?.height != null) parts.push(`h=${formatPositiveIntParam("sourceRect.height", opts.sourceRect.height)}`);
+	if (opts.virtualPlacement) parts.push("U=1");
+}
+function formatIntParam(name, value) {
+	if (!Number.isInteger(value)) throw new Error(`kitty graphics ${name} must be an integer`);
+	return value;
+}
+function formatNonNegativeIntParam(name, value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`kitty graphics ${name} must be a non-negative integer`);
+	return value;
+}
+function formatPositiveIntParam(name, value) {
+	if (!Number.isInteger(value) || value <= 0) throw new Error(`kitty graphics ${name} must be a positive integer`);
+	return value;
+}
+/**
+* Split a string into chunks of at most `size` characters.
+*/
+function splitIntoChunks(str, size) {
+	if (str.length === 0) return [];
+	const chunks = [];
+	for (let i = 0; i < str.length; i += size) chunks.push(str.slice(i, i + size));
+	return chunks;
+}
+//#endregion
 //#region ../../node_modules/.bun/pako@1.0.11/node_modules/pako/lib/utils/common.js
 var require_common = /* @__PURE__ */ __commonJSMin(((exports) => {
 	var TYPED_OK = typeof Uint8Array !== "undefined" && typeof Uint16Array !== "undefined" && typeof Int32Array !== "undefined";
@@ -3913,8 +4211,27 @@ var require_pako = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = pako;
 }));
 //#endregion
-//#region ../../node_modules/.bun/upng-js@2.1.0/node_modules/upng-js/UPNG.js
-var require_UPNG = /* @__PURE__ */ __commonJSMin(((exports, module) => {
+//#region packages/ag-react/src/ui/image/sixel-encoder.ts
+/**
+* Sixel Encoder (Minimal Implementation)
+*
+* Sixel is an older image protocol supported by terminals like xterm, mlterm,
+* foot, and some others. Images are encoded as DCS (Device Control String)
+* sequences where each character encodes 6 vertical pixels.
+*
+* DCS format: `ESC P <params> q <sixel-data> ESC \`
+*
+* This is a minimal implementation that produces valid Sixel output for
+* simple images. For production use with complex images, consider using
+* a dedicated Sixel library that handles color quantization and dithering.
+*
+* Protocol reference: https://en.wikipedia.org/wiki/Sixel
+*
+* TODO: Full Sixel encoding with proper color quantization, dithering,
+* and compression. The current implementation handles basic RGBA image data
+* with a simple nearest-color palette approach.
+*/
+var import_UPNG = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function() {
 		var UPNG = {};
 		var pako;
@@ -5068,8 +5385,576 @@ var require_UPNG = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 			};
 		})(UPNG, pako);
 	})();
-}));
+})))(), 1);
+const DCS_START = "\x1BP";
+const ST = "\x1B\\";
+/** Sixel introduces a color with `#<index>;2;<r>;<g>;<b>` (RGB percentages 0-100) */
+const SIXEL_NEWLINE = "-";
+/**
+* Decode a PNG buffer into RGBA pixel data suitable for {@link encodeSixel}.
+*
+* The Sixel protocol cannot transmit PNG directly (unlike Kitty's `f=100`),
+* so terminals that fall back to Sixel need raw RGBA pixels. This helper
+* uses upng-js — a small (~30 KB) pure-JS PNG decoder with one tiny
+* dependency (pako) — to bridge PNG → RGBA.
+*
+* Returns `null` if the buffer is not a valid PNG. Callers should fall back
+* to a text placeholder in that case.
+*
+* Supports all PNG flavors UPNG handles: 8/16-bit depth, RGB/RGBA/grayscale/
+* palette, interlaced. Animated PNGs (APNG) collapse to the first frame —
+* Sixel itself is single-frame.
+*
+* @example
+* ```ts
+* import { readFileSync } from "fs"
+* import { decodePngToRgba, encodeSixel } from "./sixel-encoder"
+*
+* const png = readFileSync("photo.png")
+* const rgba = decodePngToRgba(png)
+* if (rgba) {
+*   process.stdout.write(encodeSixel(rgba))
+* }
+* ```
+*/
+function decodePngToRgba(pngData) {
+	try {
+		const view = pngData instanceof Uint8Array ? pngData : new Uint8Array(pngData);
+		const ab = view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+		const decoded = import_UPNG.default.decode(ab);
+		const frames = import_UPNG.default.toRGBA8(decoded);
+		if (frames.length === 0) return null;
+		return {
+			width: decoded.width,
+			height: decoded.height,
+			data: new Uint8Array(frames[0])
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Encode RGBA image data as a Sixel escape sequence.
+*
+* This is a basic implementation that:
+* 1. Quantizes colors to a small palette (up to 256 colors)
+* 2. Encodes 6-row bands as Sixel characters
+* 3. Wraps in a DCS escape sequence
+*
+* For transparent pixels (alpha < 128), the background shows through.
+*
+* @param imageData - Image dimensions and RGBA pixel data
+* @returns A DCS escape sequence containing the Sixel-encoded image
+*
+* @example
+* ```ts
+* const img = { width: 10, height: 12, data: new Uint8Array(10 * 12 * 4) }
+* const seq = encodeSixel(img)
+* process.stdout.write(seq)
+* ```
+*/
+function encodeSixel(imageData) {
+	const { width, height, data } = imageData;
+	if (width === 0 || height === 0 || data.length === 0) return `${DCS_START}q${ST}`;
+	const palette = /* @__PURE__ */ new Map();
+	const pixelColors = new Uint16Array(width * height);
+	let nextColorIndex = 1;
+	for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+		const offset = (y * width + x) * 4;
+		const r = data[offset];
+		const g = data[offset + 1];
+		const b = data[offset + 2];
+		if (data[offset + 3] < 128) continue;
+		const key = `${r >> 2 & 63},${g >> 2 & 63},${b >> 2 & 63}`;
+		let idx = palette.get(key);
+		if (idx == null) if (nextColorIndex >= 256) idx = 1;
+		else {
+			idx = nextColorIndex++;
+			palette.set(key, idx);
+		}
+		pixelColors[y * width + x] = idx;
+	}
+	const parts = [];
+	parts.push(`"1;1;${width};${height}`);
+	for (const [key, idx] of palette) {
+		const [qr, qg, qb] = key.split(",").map(Number);
+		const rPct = Math.round(qr / 63 * 100);
+		const gPct = Math.round(qg / 63 * 100);
+		const bPct = Math.round(qb / 63 * 100);
+		parts.push(`#${idx};2;${rPct};${gPct};${bPct}`);
+	}
+	for (let bandY = 0; bandY < height; bandY += 6) {
+		if (bandY > 0) parts.push(SIXEL_NEWLINE);
+		const bandColors = /* @__PURE__ */ new Set();
+		for (let dy = 0; dy < 6 && bandY + dy < height; dy++) for (let x = 0; x < width; x++) {
+			const ci = pixelColors[(bandY + dy) * width + x];
+			if (ci > 0) bandColors.add(ci);
+		}
+		let first = true;
+		for (const colorIdx of bandColors) {
+			if (!first) parts.push("$");
+			first = false;
+			parts.push(`#${colorIdx}`);
+			for (let x = 0; x < width; x++) {
+				let sixelBits = 0;
+				for (let dy = 0; dy < 6; dy++) {
+					const y = bandY + dy;
+					if (y < height && pixelColors[y * width + x] === colorIdx) sixelBits |= 1 << dy;
+				}
+				parts.push(String.fromCharCode(sixelBits + 63));
+			}
+		}
+	}
+	return `${DCS_START}q${parts.join("")}${ST}`;
+}
+/**
+* Check if the current terminal likely supports the Sixel protocol.
+*
+* Pass `caps` (from `term.caps` or a {@link TerminalCaps} fixture) when
+* available. Without caps, this falls back to {@link createTerminalProfile}
+* — the canonical single-source-of-truth entry point in
+* `@silvery/ansi/profile`. Direct reads of terminal-signal env vars
+* (TERM / TERM_PROGRAM / …) are banned outside that module — see
+* `scripts/lint-env-reads.ts`.
+*
+* For definitive detection, send a DA1 (Device Attributes) query and check
+* for "4" in the response, but that requires async I/O.
+*
+* Known supporting terminals: xterm (with +sixel), mlterm, foot, mintty,
+* WezTerm, Contour, Sixel-enabled builds of various terminals.
+*
+* @returns `true` if the terminal likely supports Sixel
+*/
+function isSixelSupported(emulator) {
+	const resolved = emulator ?? createTerminalProfile().emulator;
+	const term = resolved.TERM;
+	const termProgram = resolved.program;
+	if (termProgram === "mlterm" || term.startsWith("mlterm")) return true;
+	if (termProgram === "foot" || term === "foot" || term === "foot-extra") return true;
+	if (termProgram === "WezTerm") return true;
+	if (termProgram === "mintty") return true;
+	return false;
+}
+//#endregion
+//#region packages/ag-react/src/ui/image/image-placement.ts
+const CURSOR_HIDE = "\x1B[?25l";
+const CURSOR_SHOW = "\x1B[?25h";
+const CURSOR_SAVE = "\x1B7";
+const CURSOR_RESTORE = "\x1B8";
+function withCursorPreserved(seq) {
+	return `${CURSOR_HIDE}${CURSOR_SAVE}${seq}${CURSOR_RESTORE}${CURSOR_SHOW}`;
+}
+function computeVisibleImagePlacement({ rect, imagePixels, sourceRect, pixelOffset, viewport }) {
+	if (rect.width <= 0 || rect.height <= 0) return null;
+	if (rect.x + rect.width <= 0 || rect.y + rect.height <= 0) return null;
+	if (viewport && (rect.x >= viewport.width || rect.y >= viewport.height)) return null;
+	const leftClip = Math.max(0, -rect.x);
+	const topClip = Math.max(0, -rect.y);
+	const rightClip = viewport ? Math.max(0, rect.x + rect.width - viewport.width) : 0;
+	const bottomClip = viewport ? Math.max(0, rect.y + rect.height - viewport.height) : 0;
+	const visibleWidth = rect.width - leftClip - rightClip;
+	const visibleHeight = rect.height - topClip - bottomClip;
+	if (visibleWidth <= 0 || visibleHeight <= 0) return null;
+	const placement = {
+		x: Math.max(0, rect.x),
+		y: Math.max(0, rect.y),
+		width: visibleWidth,
+		height: visibleHeight,
+		...pixelOffset ? { pixelOffset } : {}
+	};
+	if (!imagePixels || topClip === 0 && leftClip === 0 && rightClip === 0 && bottomClip === 0) return sourceRect ? {
+		...placement,
+		sourceRect
+	} : placement;
+	const srcX = sourceRect?.x ?? 0;
+	const srcY = sourceRect?.y ?? 0;
+	const srcWidth = sourceRect?.width ?? imagePixels.width;
+	const srcHeight = sourceRect?.height ?? imagePixels.height;
+	const pixelsPerCol = srcWidth / Math.max(1, rect.width);
+	const pixelsPerRow = srcHeight / Math.max(1, rect.height);
+	return {
+		...placement,
+		sourceRect: {
+			x: Math.round(srcX + leftClip * pixelsPerCol),
+			y: Math.round(srcY + topClip * pixelsPerRow),
+			width: Math.max(1, Math.round(visibleWidth * pixelsPerCol)),
+			height: Math.max(1, Math.round(visibleHeight * pixelsPerRow))
+		}
+	};
+}
+function imagePlacementKey({ placementId, zIndex, pixelOffset, sourceRect, virtualPlacement }) {
+	return JSON.stringify({
+		placementId,
+		zIndex,
+		pixelOffset,
+		sourceRect,
+		virtualPlacement
+	});
+}
+function planKittyImagePlacement({ rect, imagePixels, sourceRect, pixelOffset, viewport, placementId, zIndex, virtualPlacement, previousPlacement, srcChanged }) {
+	const placement = computeVisibleImagePlacement({
+		rect,
+		imagePixels,
+		sourceRect,
+		pixelOffset,
+		viewport
+	});
+	if (!placement) return previousPlacement ? { kind: "delete-placement" } : { kind: "noop" };
+	const placementKey = imagePlacementKey({
+		placementId,
+		zIndex,
+		pixelOffset: placement.pixelOffset,
+		sourceRect: placement.sourceRect,
+		virtualPlacement
+	});
+	if (previousPlacement !== null && previousPlacement.x === placement.x && previousPlacement.y === placement.y && previousPlacement.width === placement.width && previousPlacement.height === placement.height && previousPlacement.placementKey === placementKey && !srcChanged) return { kind: "noop" };
+	return {
+		kind: "place",
+		placement,
+		placementKey,
+		transmit: srcChanged,
+		deleteImageBeforeTransmit: srcChanged && previousPlacement !== null
+	};
+}
+//#endregion
+//#region packages/ag-react/src/ui/image/Image.tsx
+/**
+* Image Component
+*
+* Renders bitmap images in supported terminals using the Kitty graphics
+* protocol (primary) or Sixel (fallback). When neither is supported,
+* displays a text placeholder.
+*
+* Since terminal images are escape-sequence-based and don't fit the cell
+* buffer model, the component reserves visual space with a Box of the
+* requested dimensions and queues typed terminal artifacts after layout.
+*
+* @example
+* ```tsx
+* import { readFileSync } from "fs"
+* import { Image } from "@silvery/ag-react"
+*
+* const png = readFileSync("photo.png")
+* <Image src={png} width={40} height={20} />
+*
+* // With file path
+* <Image src="/path/to/image.png" width={40} height={20} />
+*
+* // Auto-detect protocol, fall back to text
+* <Image src={png} width={40} height={20} fallback="[photo]" />
+* ```
+*/
+/**
+* Determine the best available image protocol.
+*
+* When `caps` is supplied (the caps of the Term we are actually rendering INTO,
+* read from {@link TermContext}), the decision is gated on THOSE — a terminal
+* whose own caps report no Kitty/Sixel support must never receive graphics
+* escape bytes, even if the ambient `process.stdout`/`TERM_PROGRAM` claims
+* support (a piped sink, a non-Kitty emulator, a proxied/cmux PTY). km bead
+* 19668: the welcome-bitmap escape-flood came from consulting ambient stdout
+* instead of the render term.
+*
+* When `caps` is absent (no TermContext — a standalone/unit render), it falls
+* back to the ambient profile, preserving the historical behavior.
+*
+* Returns null if no image protocol is available.
+*/
+function detectProtocol(preferred, caps) {
+	const kitty = caps ? caps.kittyGraphics : isKittyGraphicsSupported();
+	const sixel = caps ? caps.sixel : isSixelSupported();
+	if (preferred === "kitty") return kitty ? "kitty" : null;
+	if (preferred === "sixel") return sixel ? "sixel" : null;
+	if (kitty) return "kitty";
+	if (sixel) return "sixel";
+	return null;
+}
+/** Incrementing image ID counter for Kitty protocol */
+let nextImageId = 1;
+const KITTY_PLACEHOLDER = String.fromCodePoint(1109742);
+const KITTY_PLACEHOLDER_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
+].map((codepoint) => String.fromCodePoint(codepoint));
+function canRenderKittyPlaceholder({ id, width, height }) {
+	return id !== null && id > 0 && id <= 255 && width > 0 && height > 0 && width <= KITTY_PLACEHOLDER_DIACRITICS.length && height <= KITTY_PLACEHOLDER_DIACRITICS.length;
+}
+function kittyPlaceholderText(width, height) {
+	return Array.from({ length: height }, (_, row) => Array.from({ length: width }, (_, col) => KITTY_PLACEHOLDER + KITTY_PLACEHOLDER_DIACRITICS[row] + KITTY_PLACEHOLDER_DIACRITICS[col]).join("")).join("\n");
+}
+/**
+* Renders a bitmap image in the terminal.
+*
+* The component operates in two phases:
+* 1. **Layout phase**: Renders a Box that reserves the visual space
+*    (filled with spaces so the cell buffer has the right dimensions).
+* 2. **Commit phase**: Queues terminal image artifacts positioned over the
+*    reserved space.
+*
+* When image protocols are not available, the fallback text is shown instead.
+*/
+function Image({ src, width: requestedWidth, height: requestedHeight, fallback = "[image]", protocol: preferredProtocol = "auto", placementId, zIndex, pixelOffset, sourceRect, virtualPlacement }) {
+	const parentSize = useBoxSize();
+	const effectiveWidth = requestedWidth ?? parentSize.width;
+	const effectiveHeight = requestedHeight ?? Math.max(1, Math.floor(effectiveWidth / 2));
+	return /* @__PURE__ */ jsx(Box, {
+		width: effectiveWidth,
+		height: effectiveHeight,
+		children: /* @__PURE__ */ jsx(ImagePlacement, {
+			src,
+			width: effectiveWidth,
+			height: effectiveHeight,
+			fallback,
+			protocol: preferredProtocol,
+			placementId,
+			zIndex,
+			pixelOffset,
+			sourceRect,
+			virtualPlacement
+		})
+	});
+}
+function ImagePlacement({ src, width: effectiveWidth, height: effectiveHeight, fallback, protocol: preferredProtocol, placementId, zIndex, pixelOffset, sourceRect, virtualPlacement }) {
+	const boxRect = useScreenRect();
+	const stdoutCtx = useContext(StdoutContext);
+	const term = useContext(TermContext);
+	const termKittyGraphics = term?.caps.kittyGraphics;
+	const termSixel = term?.caps.sixel;
+	const { columns: viewportWidth, rows: viewportHeight } = useWindowSize();
+	const viewport = {
+		width: viewportWidth,
+		height: viewportHeight
+	};
+	const imageIdRef = useRef(null);
+	const transmittedSrcRef = useRef(null);
+	const lastEmittedRef = useRef(null);
+	const pngData = useMemo(() => {
+		if (Buffer.isBuffer(src)) return src;
+		try {
+			return readFileSync(src);
+		} catch {
+			return null;
+		}
+	}, [src]);
+	const decodedImage = useMemo(() => pngData ? decodePngToRgba(pngData) : null, [pngData]);
+	const activeProtocol = useMemo(() => detectProtocol(preferredProtocol, term ? {
+		kittyGraphics: term.caps.kittyGraphics,
+		sixel: term.caps.sixel
+	} : void 0), [
+		preferredProtocol,
+		term,
+		termKittyGraphics,
+		termSixel
+	]);
+	if (activeProtocol === "kitty" && imageIdRef.current == null) imageIdRef.current = nextImageId++;
+	useLayoutEffect(() => {
+		if (!pngData || !stdoutCtx || !activeProtocol) return;
+		if (effectiveWidth <= 0 || effectiveHeight <= 0) return;
+		if (boxRect.width <= 0) return;
+		const write = (data, artifact) => {
+			if (stdoutCtx.queueFrameArtifact && artifact) {
+				stdoutCtx.queueFrameArtifact({
+					kind: "terminal-sequence",
+					owner: artifact.owner,
+					zIndex: artifact.zIndex,
+					sequence: data
+				});
+				return;
+			}
+			(stdoutCtx.writeAfterFrame ?? stdoutCtx.write)(data);
+		};
+		if (activeProtocol === "kitty") {
+			const id = imageIdRef.current;
+			if (id == null) return;
+			const srcChanged = transmittedSrcRef.current !== pngData;
+			const plan = planKittyImagePlacement({
+				rect: {
+					x: boxRect.x,
+					y: boxRect.y,
+					width: effectiveWidth,
+					height: effectiveHeight
+				},
+				imagePixels: decodedImage,
+				sourceRect,
+				pixelOffset,
+				viewport,
+				placementId,
+				zIndex,
+				virtualPlacement,
+				previousPlacement: lastEmittedRef.current,
+				srcChanged
+			});
+			const placeVisible = (visible, placementKey) => {
+				write(withCursorPreserved(`\x1b[${visible.y + 1};${visible.x + 1}H` + placeKittyImage({
+					id,
+					width: visible.width,
+					height: visible.height,
+					placementId,
+					zIndex,
+					pixelOffset: visible.pixelOffset,
+					sourceRect: visible.sourceRect,
+					virtualPlacement
+				})), {
+					owner: "image:kitty:place",
+					zIndex
+				});
+				lastEmittedRef.current = {
+					x: visible.x,
+					y: visible.y,
+					width: visible.width,
+					height: visible.height,
+					placementKey
+				};
+			};
+			if (plan.kind === "noop") return;
+			if (plan.kind === "delete-placement") {
+				const id = imageIdRef.current;
+				if (id != null) write(withCursorPreserved(deleteKittyPlacement(id, placementId)), {
+					owner: "image:kitty:delete-placement",
+					zIndex
+				});
+				lastEmittedRef.current = null;
+				return;
+			}
+			if (plan.transmit) {
+				if (plan.deleteImageBeforeTransmit) write(deleteKittyImage(id), {
+					owner: "image:kitty:delete-image",
+					zIndex
+				});
+				write(encodeKittyImage(pngData, {
+					id,
+					transmitOnly: true
+				}), {
+					owner: "image:kitty:transmit",
+					zIndex
+				});
+				transmittedSrcRef.current = pngData;
+			}
+			const visible = plan.placement;
+			placeVisible(visible, plan.placementKey);
+		} else if (activeProtocol === "sixel") {
+			const visible = computeVisibleImagePlacement({
+				rect: {
+					x: boxRect.x,
+					y: boxRect.y,
+					width: effectiveWidth,
+					height: effectiveHeight
+				},
+				imagePixels: decodedImage,
+				sourceRect,
+				pixelOffset,
+				viewport
+			});
+			if (!visible) return;
+			const moveCursor = `\x1b[${visible.y + 1};${visible.x + 1}H`;
+			const rgba = decodePngToRgba(pngData);
+			if (rgba) write(withCursorPreserved(moveCursor + encodeSixel(rgba)), {
+				owner: "image:sixel:place",
+				zIndex
+			});
+		}
+	}, [
+		pngData,
+		stdoutCtx,
+		activeProtocol,
+		effectiveWidth,
+		effectiveHeight,
+		placementId,
+		zIndex,
+		pixelOffset,
+		sourceRect,
+		virtualPlacement,
+		boxRect.x,
+		boxRect.y,
+		boxRect.width,
+		boxRect.height,
+		viewportWidth,
+		viewportHeight,
+		decodedImage
+	]);
+	useEffect(() => {
+		const id = imageIdRef.current;
+		if (activeProtocol !== "kitty" || id == null || !stdoutCtx) return;
+		return () => {
+			stdoutCtx.write(withCursorPreserved(deleteKittyImage(id)));
+		};
+	}, [activeProtocol, stdoutCtx]);
+	if (!activeProtocol || !pngData) return /* @__PURE__ */ jsx(Text, { children: fallback });
+	const placeholderImageId = imageIdRef.current;
+	if (activeProtocol === "kitty" && virtualPlacement && placeholderImageId !== null && canRenderKittyPlaceholder({
+		id: placeholderImageId,
+		width: effectiveWidth,
+		height: effectiveHeight
+	})) return /* @__PURE__ */ jsx(Text, {
+		color: `ansi256(${placeholderImageId})`,
+		children: kittyPlaceholderText(effectiveWidth, effectiveHeight)
+	});
+	const spaceLine = " ".repeat(Math.max(0, effectiveWidth));
+	return /* @__PURE__ */ jsx(Text, { children: Array.from({ length: Math.max(0, effectiveHeight) }, () => spaceLine).join("\n") });
+}
 //#endregion
-export { require_UPNG as t };
+export { deleteKittyImage as a, isKittyGraphicsSupported as c, shallow as d, useTerm as f, isSixelSupported as i, placeKittyImage as l, decodePngToRgba as n, deleteKittyPlacement as o, encodeSixel as r, encodeKittyImage as s, Image as t, useWindowSize as u };
 
-//# sourceMappingURL=UPNG-DosRPdF4.mjs.map
+//# sourceMappingURL=image-CIF75xMr.mjs.map