silvery 0.19.2 → 0.21.0

package/dist/image-C2Birh2x.mjs

@@ -0,0 +1,1252 @@
+import { o as __toESM } from "./chunk-BSw8zbkd.mjs";
+import { r as effect } from "./src-DKp-_OFG.mjs";
+import { a as NodeContext, c as StdoutContext, l as TermContext } from "./context-BU5LkkIy.mjs";
+import { m as rectEqual, o as markObservedLayoutSignal, r as getLayoutSignals } from "./layout-signals-Cnw6xk8Q.mjs";
+import { a as Box, t as Text } from "./Text-Lq0dmj8-.mjs";
+import { M as createTerminalProfile, t as init_src } from "./src-BNTToU7l.mjs";
+import { t as require_UPNG } from "./UPNG-DosRPdF4.mjs";
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+import { readFileSync } from "node:fs";
+//#region packages/ag-react/src/hooks/useLayout.ts
+/**
+* Layout Hooks — three coordinate systems for positioning in silvery.
+*
+* Every silvery node has three rects that differ only by how scroll and
+* sticky offsets are applied. Pick the one that matches your use case:
+*
+* - `useBoxRect()`    — layout position (border-box sized, minus padding/border).
+*                       Use for responsive sizing inside a component. Matches
+*                       CSS `clientWidth`/`clientHeight` for the content area.
+* - `useScrollRect()` — scroll-adjusted position, **pre** sticky clamping.
+*                       Use when you need the "natural" position of a node
+*                       in scrolled coordinates (can go off-screen).
+* - `useScreenRect()` — actual paint position on the terminal screen.
+*                       Use for hit testing, cursor positioning, and
+*                       cross-component visual navigation. The CSS
+*                       `getBoundingClientRect()` analogue.
+*
+* ## Deferred semantics (the only contract)
+*
+* Each hook returns the rect as of the **most recent committed layout** —
+* the value as of the last event-batch commit boundary. Within a single
+* batch, the returned value is invariant across every convergence pass;
+* React renders see one value per batch. After the batch's commit boundary
+* fires, the next batch sees the new value.
+*
+* This is the structural fix for the "render reads useBoxRect AND writes
+* a layout-affecting prop based on it" feedback loop. Under the in-flight
+* model that preceded this hook (pre 2026-05-06), the read returned the
+* latest measurement during the same batch, which could differ between
+* the first and second convergence passes — causing the write to flip
+* between branches and the loop to ping-pong until `MAX_CONVERGENCE_PASSES`
+* capped it. Under deferred semantics the read is invariant for the
+* batch, so the loop completes in one pass.
+*
+* **One-frame-late by design.** A component that mounts shows the
+* empty-rect fallback (`{ x: 0, y: 0, width: 0, height: 0 }`) on its
+* first render and the real rect on the next commit boundary. Layout
+* effects that run on the second render see the real rect and can write
+* positioned terminal escapes (Image, decorations) into the next
+* paintFrame.
+*
+* Components that need same-frame measurements must read `node.boxRect`
+* etc. directly via `useAgNode()` and gate on `useLayoutEffect` —
+* recommended only for leaf primitives in the silvery framework itself.
+*
+* For breakpoint logic, prefer `useResponsiveValue()` or
+* `useResponsiveBoxProps()` — bucketing into stable zones gives more
+* predictable behavior than branching on raw widths.
+*
+* See bead `@km/silvery/use-deferred-box-rect-and-post-commit-observers`.
+*/
+const EMPTY_RECT = {
+	x: 0,
+	y: 0,
+	width: 0,
+	height: 0
+};
+const EMPTY_SIZE = {
+	width: 0,
+	height: 0
+};
+/**
+* Get the inner content dimensions of a node (border-box minus padding and border).
+* This is the space available for the node's children.
+*
+* `boxRect` is passed in explicitly so the helper derives the inner rect
+* from the committed signal value rather than re-reading `node.boxRect`
+* (which holds the in-flight value mid-batch).
+*/
+function deriveInnerRect(node, boxRect) {
+	if (!boxRect) return null;
+	const props = node.props;
+	if (!props || node.type === "silvery-text") return boxRect;
+	const pTop = props.paddingTop ?? props.paddingY ?? props.padding ?? 0;
+	const pBottom = props.paddingBottom ?? props.paddingY ?? props.padding ?? 0;
+	const pLeft = props.paddingLeft ?? props.paddingX ?? props.padding ?? 0;
+	const pRight = props.paddingRight ?? props.paddingX ?? props.padding ?? 0;
+	let bTop = 0;
+	let bBottom = 0;
+	let bLeft = 0;
+	let bRight = 0;
+	if (props.borderStyle) {
+		bTop = props.borderTop !== false ? 1 : 0;
+		bBottom = props.borderBottom !== false ? 1 : 0;
+		bLeft = props.borderLeft !== false ? 1 : 0;
+		bRight = props.borderRight !== false ? 1 : 0;
+	}
+	return {
+		x: boxRect.x + pLeft + bLeft,
+		y: boxRect.y + pTop + bTop,
+		width: Math.max(0, boxRect.width - pLeft - pRight - bLeft - bRight),
+		height: Math.max(0, boxRect.height - pTop - pBottom - bTop - bBottom)
+	};
+}
+const COMMITTED_RECT_OBSERVED_KEY = {
+	boxRectCommitted: "boxRect",
+	scrollRectCommitted: "scrollRect",
+	screenRectCommitted: "screenRect"
+};
+const IN_FLIGHT_RECT_OBSERVED_KEY = {
+	boxRect: "boxRect",
+	scrollRect: "scrollRect",
+	screenRect: "screenRect"
+};
+/**
+* Reactive rect hook (deferred): subscribes to a committed rect signal and
+* re-renders when the value advances at a commit boundary. Returns the
+* rect derived from the committed value via `getCommittedRect`.
+*
+* Within a single event batch the committed signal does not change — every
+* convergence pass sees the same value, so a render that reads useBoxRect
+* and writes a layout-affecting prop converges in one pass. After the
+* batch's commit boundary (handled by the runtime via
+* `commitLayoutSnapshot`), the next batch's first render sees the new
+* value.
+*/
+function useReactiveRect(getCommittedRect, committedSignalKey) {
+	const node = useContext(NodeContext);
+	const [, forceUpdate] = useReducer((x) => x + 1, 0);
+	const prevRef = useRef(null);
+	useLayoutEffect(() => {
+		if (!node) return;
+		markObservedLayoutSignal(node, COMMITTED_RECT_OBSERVED_KEY[committedSignalKey]);
+		const rectSignal = getLayoutSignals(node)[committedSignalKey];
+		return effect(() => {
+			const next = getCommittedRect(rectSignal(), node) ?? null;
+			if (!rectEqual(prevRef.current, next)) {
+				prevRef.current = next;
+				forceUpdate();
+			}
+		});
+	}, [node]);
+	if (!node) return EMPTY_RECT;
+	markObservedLayoutSignal(node, COMMITTED_RECT_OBSERVED_KEY[committedSignalKey]);
+	return getCommittedRect(getLayoutSignals(node)[committedSignalKey](), node) ?? EMPTY_RECT;
+}
+/**
+* **DANGEROUS — measurement read on the render path.** Prefer a declarative
+* primitive (`<Box fitWidth>`, `useResponsiveBoxProps`, `useResponsiveValue`,
+* `useOnBoxRectCommitted`) before reaching for this hook.
+*
+* Returns the inner content dimensions for the current component's nearest
+* Box, as of the most recent committed layout. Width and height reflect
+* the space available for children (border-box minus padding and border),
+* like CSS `clientWidth`/`clientHeight`.
+*
+* ```tsx
+* function Header() {
+*   const { width } = useBoxRectDangerously()
+*   return <Text>{'='.repeat(Math.max(0, width))}</Text>
+* }
+* ```
+*
+* On first render returns `{ x: 0, y: 0, width: 0, height: 0 }`. After the
+* first commit boundary, automatically re-renders with the measured
+* dimensions. This **first-paint zero-rect transition** is the social cost
+* the rename announces — components that branch layout on this hook see a
+* flush-left / collapsed first paint, then re-flow when the real rect
+* commits one event-loop tick later. Visible jank under streaming / dynamic
+* mount / SIGWINCH burst.
+*
+* Use only when:
+* - You need a measurement read in JS control flow (animation, autoscroll
+*   thresholds, hit-testing) that **doesn't drive layout-affecting props**.
+* - No declarative primitive covers the case.
+*
+* Deferred semantics — see this file's docstring for the contract and the
+* one-frame-late behavior.
+*
+* Bead: `@km/silvery/responsive-layout-architecture-reframe` (Phase A.1
+* lands this rename; the full Phase A migrates each consumer to a
+* declarative primitive or, where genuinely needed, to a Suspense-friendly
+* `Promise<Rect>` form coordinated via `RectReadBarrier`).
+*/
+function useBoxRectDangerously() {
+	return useReactiveRect((committed, node) => deriveInnerRect(node, committed), "boxRectCommitted");
+}
+/**
+* @deprecated Renamed to `useBoxRectDangerously`. The original name read as
+* "the normal hook for getting your rect" — exactly the framing the Phase
+* A.1 rename is intended to break. App authors should reach for declarative
+* primitives first; this alias remains for one release cycle and logs a
+* dev-time warning per call site. Will be removed in the next major.
+*
+* Bead: `@km/silvery/responsive-layout-architecture-reframe`.
+*/
+function useBoxRect() {
+	if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test") warnUseBoxRectDeprecation();
+	return useReactiveRect((committed, node) => deriveInnerRect(node, committed), "boxRectCommitted");
+}
+/**
+* Internal dimensions-only variant of the deferred box rect read.
+*
+* This is for framework primitives that build width/height-derived text
+* (Divider, ProgressBar, TextArea wrapping) but do not care where their
+* parent sits on screen. It subscribes to the same committed boxRect signal
+* as `useBoxRect()`, but only re-renders when the derived inner
+* `{width,height}` changes. Scrolling and virtual-window spacer movement
+* often change x/y without changing dimensions; full-rect subscriptions wake
+* these primitives on every such frame and steal scroll budget.
+*/
+function useBoxSize() {
+	const node = useContext(NodeContext);
+	const [, forceUpdate] = useReducer((x) => x + 1, 0);
+	const prevRef = useRef(null);
+	useLayoutEffect(() => {
+		if (!node) return;
+		markObservedLayoutSignal(node, "boxSize");
+		const signals = getLayoutSignals(node);
+		return effect(() => {
+			const rect = deriveInnerRect(node, signals.boxRectCommitted());
+			const next = rect ? {
+				width: rect.width,
+				height: rect.height
+			} : EMPTY_SIZE;
+			const prev = prevRef.current;
+			if (!prev || prev.width !== next.width || prev.height !== next.height) {
+				prevRef.current = next;
+				forceUpdate();
+			}
+		});
+	}, [node]);
+	if (!node) return EMPTY_SIZE;
+	markObservedLayoutSignal(node, "boxSize");
+	const rect = deriveInnerRect(node, getLayoutSignals(node).boxRectCommitted());
+	return rect ? {
+		width: rect.width,
+		height: rect.height
+	} : EMPTY_SIZE;
+}
+const useBoxRectWarnedCallSites = /* @__PURE__ */ new Set();
+function warnUseBoxRectDeprecation() {
+	const lines = ((/* @__PURE__ */ new Error()).stack ?? "").split("\n");
+	let consumerFrame = "";
+	for (let i = 1; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		if (!line.includes("useLayout.ts") && line.trim().startsWith("at ")) {
+			consumerFrame = line.trim();
+			break;
+		}
+	}
+	const key = consumerFrame || "<unknown>";
+	if (useBoxRectWarnedCallSites.has(key)) return;
+	useBoxRectWarnedCallSites.add(key);
+	console.warn(`[silvery] useBoxRect() is deprecated — rename to useBoxRectDangerously(), or migrate to a declarative primitive (<Box fitWidth>, useResponsiveBoxProps, useResponsiveValue, useOnBoxRectCommitted). See @km/silvery/responsive-layout-architecture-reframe. Call site: ${key}`);
+}
+/**
+* Returns the scroll-adjusted position for the current component, as of
+* the most recent committed layout.
+*
+* This is the node's position in scroll coordinates, *before* sticky
+* clamping. For non-sticky nodes it equals `useScreenRect()`. For sticky
+* nodes, the scrollRect reflects where the node would be without sticky
+* adjustment — so it can go off-screen (negative y, etc.) when scrolled
+* past.
+*
+* ```tsx
+* function Card({ id }) {
+*   const { y } = useScrollRect()
+*   return <Box>Scroll y: {y}</Box>
+* }
+* ```
+*
+* Deferred semantics — see this file's docstring.
+*/
+function useScrollRect() {
+	return useReactiveRect((committed) => committed, "scrollRectCommitted");
+}
+/**
+* Returns the actual paint position on the terminal screen as of the most
+* recent committed layout — the silvery analogue of
+* `getBoundingClientRect()`.
+*
+* For non-sticky nodes this equals `useScrollRect()`. For sticky nodes
+* (`position="sticky"`), it reflects the clamped position where pixels
+* actually land on screen.
+*
+* ```tsx
+* function StickyHeader() {
+*   const { y } = useScreenRect()
+*   return <Box position="sticky" stickyTop={0}>Header at row {y}</Box>
+* }
+* ```
+*
+* Deferred semantics — see this file's docstring.
+*/
+function useScreenRect() {
+	return useReactiveRect((committed) => committed, "screenRectCommitted");
+}
+/**
+* In-flight reactive rect hook (escape hatch): subscribes to the LIVE rect
+* signal — the value as written by the most recent layout pass within the
+* current convergence cycle. Re-renders when the in-flight value advances,
+* which can happen multiple times per event batch as the convergence loop
+* iterates.
+*
+* Use only inside silvery framework internals where first-paint measurement
+* is required and the consumer does not write layout-affecting props
+* derived from the read. App code must use the deferred form
+* (`useBoxRect()` / `useScrollRect()` / `useScreenRect()`) or
+* `useResponsiveBoxProps`/`useResponsiveValue` instead.
+*/
+function useReactiveRectInFlight(getDerivedRect, inFlightSignalKey) {
+	const node = useContext(NodeContext);
+	const [, forceUpdate] = useReducer((x) => x + 1, 0);
+	const prevRef = useRef(null);
+	useLayoutEffect(() => {
+		if (!node) return;
+		markObservedLayoutSignal(node, IN_FLIGHT_RECT_OBSERVED_KEY[inFlightSignalKey]);
+		const rectSignal = getLayoutSignals(node)[inFlightSignalKey];
+		return effect(() => {
+			const next = getDerivedRect(rectSignal(), node) ?? null;
+			if (!rectEqual(prevRef.current, next)) {
+				prevRef.current = next;
+				forceUpdate();
+			}
+		});
+	}, [node]);
+	if (!node) return EMPTY_RECT;
+	markObservedLayoutSignal(node, IN_FLIGHT_RECT_OBSERVED_KEY[inFlightSignalKey]);
+	return getDerivedRect(getLayoutSignals(node)[inFlightSignalKey](), node) ?? EMPTY_RECT;
+}
+/**
+* Returns the inner content dimensions of the current Box from the IN-FLIGHT
+* signal — the value as of the most recent layout pass, which may change
+* between convergence passes within an event batch.
+*
+* Silvery framework internals only — app code must use {@link useBoxRect}
+* (deferred) or `useResponsiveBoxProps`/`useResponsiveValue` instead.
+*
+* Unlike {@link useBoxRect} (the deferred form), this hook returns the
+* measured value on the first render after layout — there is no one-frame
+* fallback. The cost is that a render reading this hook AND writing a
+* layout-affecting prop can form a convergence-loop feedback edge; the
+* lint rule `silvery/no-in-flight-rect-in-app` enforces the call-site
+* scope.
+*/
+function useBoxRectInFlight() {
+	return useReactiveRectInFlight((raw, node) => deriveInnerRect(node, raw), "boxRect");
+}
+/**
+* Returns the scroll-adjusted position from the IN-FLIGHT signal — the
+* value as of the most recent layout pass, which may change between
+* convergence passes within an event batch.
+*
+* Silvery framework internals only — see {@link useBoxRectInFlight} for
+* the contract and the lint rule that gates app-code use.
+*/
+function useScrollRectInFlight() {
+	return useReactiveRectInFlight((raw) => raw, "scrollRect");
+}
+/**
+* Returns the actual paint position from the IN-FLIGHT signal — the value
+* as of the most recent layout pass, which may change between convergence
+* passes within an event batch.
+*
+* Silvery framework internals only — see {@link useBoxRectInFlight} for
+* the contract and the lint rule that gates app-code use.
+*/
+function useScreenRectInFlight() {
+	return useReactiveRectInFlight((raw) => raw, "screenRect");
+}
+/**
+* Subscribes to the committed rect signal and fires `cb(rect)` at each
+* commit boundary, **without** triggering a re-render of the consumer.
+*
+* Use for hot paths where a rect change drives an imperative side effect
+* (cursor store update, registry write, ANSI emission) and there is no
+* render path that needs to reflect the rect.
+*
+* The callback is invoked synchronously from a commit-boundary effect(),
+* with the derived rect (`getDerivedRect` applied to the committed signal
+* value). It is NOT invoked when the derived rect is null. The caller may
+* close over component state via refs; see `useCursor` / `useGridPosition`
+* for canonical patterns.
+*/
+function useOnRectCommitted(cb, getDerivedRect, committedSignalKey) {
+	const node = useContext(NodeContext);
+	const cbRef = useRef(cb);
+	cbRef.current = cb;
+	useLayoutEffect(() => {
+		if (!node) return;
+		const rectSignal = getLayoutSignals(node)[committedSignalKey];
+		let prev = null;
+		return effect(() => {
+			const next = getDerivedRect(rectSignal(), node) ?? null;
+			if (next == null) return;
+			if (rectEqual(prev, next)) return;
+			prev = next;
+			cbRef.current(next);
+		});
+	}, [node]);
+}
+/**
+* Subscribes to the committed boxRect (inner content) and fires `cb` at
+* each commit boundary without re-rendering. See {@link useBoxRect} for
+* the deferred-rect contract; this is the observer form.
+*/
+function useOnBoxRectCommitted(cb) {
+	useOnRectCommitted(cb, (committed, node) => deriveInnerRect(node, committed), "boxRectCommitted");
+}
+/**
+* Subscribes to the committed scrollRect and fires `cb` at each commit
+* boundary without re-rendering.
+*/
+function useOnScrollRectCommitted(cb) {
+	useOnRectCommitted(cb, (committed) => committed, "scrollRectCommitted");
+}
+/**
+* Subscribes to the committed screenRect and fires `cb` at each commit
+* boundary without re-rendering.
+*/
+function useOnScreenRectCommitted(cb) {
+	useOnRectCommitted(cb, (committed) => committed, "screenRectCommitted");
+}
+//#endregion
+//#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
+init_src();
+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 packages/ag-react/src/ui/image/sixel-encoder.ts
+init_src();
+var import_UPNG = /* @__PURE__ */ __toESM(require_UPNG(), 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.
+* Returns null if no image protocol is available.
+*/
+function detectProtocol(preferred) {
+	if (preferred === "kitty") return isKittyGraphicsSupported() ? "kitty" : null;
+	if (preferred === "sixel") return isSixelSupported() ? "sixel" : null;
+	if (isKittyGraphicsSupported()) return "kitty";
+	if (isSixelSupported()) 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 { 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), [preferredProtocol]);
+	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 { useScrollRectInFlight as C, useScrollRect as S, useOnBoxRectCommitted as _, deleteKittyImage as a, useScreenRect as b, isKittyGraphicsSupported as c, shallow as d, useTerm as f, useBoxSize as g, useBoxRectInFlight as h, isSixelSupported as i, placeKittyImage as l, useBoxRectDangerously as m, decodePngToRgba as n, deleteKittyPlacement as o, useBoxRect as p, encodeSixel as r, encodeKittyImage as s, Image as t, useWindowSize as u, useOnScreenRectCommitted as v, useScreenRectInFlight as x, useOnScrollRectCommitted as y };
+
+//# sourceMappingURL=image-C2Birh2x.mjs.map