silvery 0.18.2 → 0.19.1

package/dist/{flexily-zero-adapter-V8R3HQtK.mjs → flexily-zero-adapter-CMxXhdOL.mjs}

@@ -1,2 +1,2 @@
-import { n as createFlexilyZeroEngine } from "./flexily-zero-adapter-BOM0cl8R.mjs";
+import { n as createFlexilyZeroEngine } from "./flexily-zero-adapter-BlQa46nr.mjs";
 export { createFlexilyZeroEngine };

package/dist/{image-B0zMbVUr.mjs → image-CTII5QWI.mjs}

@@ -1,5 +1,5 @@
-import { n as getLayoutSignals, s as effect, t as rectEqual } from "./types-e4dpfbSa.mjs";
-import { i as NodeContext, s as StdoutContext } from "./context-BjWgrikx.mjs";
+import { n as getLayoutSignals, s as effect, t as rectEqual } from "./types-Bk2yw9Qj.mjs";
+import { a as NodeContext, c as StdoutContext } from "./context-BU5LkkIy.mjs";
 import { useContext, useEffect, useLayoutEffect, useMemo, useReducer, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 import { readFileSync } from "node:fs";
@@ -474,4 +474,4 @@ function Image({ src, width: requestedWidth, height: requestedHeight, fallback =
 //#endregion
 export { encodeKittyImage as a, useScreenRect as c, deleteKittyImage as i, useScrollRect as l, encodeSixel as n, isKittyGraphicsSupported as o, isSixelSupported as r, useBoxRect as s, Image as t };
 
-//# sourceMappingURL=image-B0zMbVUr.mjs.map
+//# sourceMappingURL=image-CTII5QWI.mjs.map

package/dist/image-CTII5QWI.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-CTII5QWI.mjs","names":["ST"],"sources":["../packages/ag-react/src/hooks/useLayout.ts","../packages/ag-react/src/ui/image/kitty-graphics.ts","../packages/ag-react/src/ui/image/sixel-encoder.ts","../packages/ag-react/src/ui/image/Image.tsx"],"sourcesContent":["/**\n * Layout Hooks — three coordinate systems for positioning in silvery.\n *\n * Every silvery node has three rects that differ only by how scroll and\n * sticky offsets are applied. Pick the one that matches your use case:\n *\n * - `useBoxRect()`    — layout position (border-box sized). Use for responsive\n *                       sizing inside a component. Matches CSS offset-like\n *                       semantics for the content area.\n * - `useScrollRect()` — scroll-adjusted position, **pre** sticky clamping.\n *                       Use when you need the \"natural\" position of a node\n *                       in scrolled coordinates (can go off-screen).\n * - `useScreenRect()` — actual paint position on the terminal screen.\n *                       Use for hit testing, cursor positioning, and\n *                       cross-component visual navigation. The CSS\n *                       `getBoundingClientRect()` analogue.\n *\n * Each hook has two call signatures:\n *\n *   const rect = useBoxRect()                 // reactive — re-renders on change\n *   useBoxRect((rect) => register(id, rect))  // callback — zero re-renders\n *\n * The callback form is the right choice for hot paths like large lists where\n * re-rendering on every layout change is prohibitive.\n */\n\nimport { useContext, useLayoutEffect, useReducer, useRef } from \"react\"\nimport { effect } from \"@silvery/signals\"\nimport { NodeContext } from \"../context\"\nimport { type AgNode, type BoxProps, type Rect, rectEqual } from \"@silvery/ag/types\"\nimport { getLayoutSignals } from \"@silvery/ag/layout-signals\"\n\nexport type { Rect }\n\nconst EMPTY_RECT: Rect = { x: 0, y: 0, width: 0, height: 0 }\n\n/**\n * Get the inner content dimensions of a node (border-box minus padding and border).\n * This is the space available for the node's children.\n */\nfunction getInnerRect(node: AgNode): Rect {\n  const rect = node.boxRect\n  if (!rect) return EMPTY_RECT\n\n  const props = node.props as BoxProps\n  if (!props || node.type === \"silvery-text\") return rect\n\n  // Compute padding\n  const pTop = props.paddingTop ?? props.paddingY ?? props.padding ?? 0\n  const pBottom = props.paddingBottom ?? props.paddingY ?? props.padding ?? 0\n  const pLeft = props.paddingLeft ?? props.paddingX ?? props.padding ?? 0\n  const pRight = props.paddingRight ?? props.paddingX ?? props.padding ?? 0\n\n  // Compute border (1px per side if borderStyle is set)\n  let bTop = 0\n  let bBottom = 0\n  let bLeft = 0\n  let bRight = 0\n  if (props.borderStyle) {\n    bTop = props.borderTop !== false ? 1 : 0\n    bBottom = props.borderBottom !== false ? 1 : 0\n    bLeft = props.borderLeft !== false ? 1 : 0\n    bRight = props.borderRight !== false ? 1 : 0\n  }\n\n  return {\n    x: rect.x + pLeft + bLeft,\n    y: rect.y + pTop + bTop,\n    width: Math.max(0, rect.width - pLeft - pRight - bLeft - bRight),\n    height: Math.max(0, rect.height - pTop - pBottom - bTop - bBottom),\n  }\n}\n\ntype RectCallback = (rect: Rect) => void\n\n/** Selector that picks which rect signal to subscribe to. */\ntype RectSignalKey = \"boxRect\" | \"scrollRect\" | \"screenRect\"\n\n/**\n * Reactive rect hook: subscribes to a rect signal via alien-signals effect()\n * and forces a React re-render whenever the derived rect changes.\n *\n * `signalKey` identifies which rect signal to track (boxRect, scrollRect, or\n * screenRect). `getRect` derives the final value from the node (e.g.,\n * computing inner rect from boxRect by subtracting padding/border).\n *\n * The effect() creates a reactive dependency on the signal — when\n * syncRectSignals writes a new value, the effect re-runs, compares via\n * rectEqual, and triggers forceUpdate only when the derived rect changed.\n */\nfunction useReactiveRect(\n  getRect: (node: AgNode) => Rect | null | undefined,\n  signalKey: RectSignalKey,\n): Rect {\n  const node = useContext(NodeContext)\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)\n  const prevRef = useRef<Rect | null>(null)\n\n  useLayoutEffect(() => {\n    if (!node) return\n\n    const signals = getLayoutSignals(node)\n    const rectSignal = signals[signalKey]\n\n    // effect() subscribes to the signal — re-runs when the signal value changes.\n    // Reading rectSignal() inside effect creates the reactive dependency.\n    const dispose = effect(() => {\n      // Read the signal to establish the dependency\n      rectSignal()\n\n      // Derive the final rect from the node (may compute inner rect, etc.)\n      const next = getRect(node) ?? null\n      if (!rectEqual(prevRef.current, next)) {\n        prevRef.current = next\n        forceUpdate()\n      }\n    })\n\n    return dispose\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [node])\n\n  if (!node) return EMPTY_RECT\n  return getRect(node) ?? EMPTY_RECT\n}\n\n/**\n * Callback rect hook: subscribes via alien-signals effect() without\n * triggering React re-renders. The callback is invoked after layout\n * completes whenever the selected rect is available.\n *\n * Uses refs to keep the subscription stable across renders — the `getRect`\n * and `callback` functions are typically created inline and would otherwise\n * invalidate the effect on every render.\n */\nfunction useCallbackRect(\n  getRect: (node: AgNode) => Rect | null | undefined,\n  callback: RectCallback,\n  signalKey: RectSignalKey,\n): void {\n  const node = useContext(NodeContext)\n\n  const callbackRef = useRef(callback)\n  callbackRef.current = callback\n  const getRectRef = useRef(getRect)\n  getRectRef.current = getRect\n\n  useLayoutEffect(() => {\n    if (!node) return\n\n    const signals = getLayoutSignals(node)\n    const rectSignal = signals[signalKey]\n\n    // effect() subscribes to the signal — re-runs when the signal value changes.\n    const dispose = effect(() => {\n      // Read the signal to establish the dependency\n      rectSignal()\n\n      const rect = getRectRef.current(node)\n      if (rect) callbackRef.current(rect)\n    })\n\n    return dispose\n  }, [node])\n}\n\n// ============================================================================\n// boxRect — layout position (border-box)\n// ============================================================================\n\n/**\n * Returns the inner content dimensions for the current component's nearest Box.\n * Width and height reflect the space available for children (border-box minus\n * padding and border), like CSS `clientWidth`/`clientHeight`.\n *\n * Two signatures:\n *\n * ```tsx\n * // Reactive — re-renders when the rect changes\n * function Header() {\n *   const { width } = useBoxRect()\n *   return <Text>{'='.repeat(width)}</Text>\n * }\n *\n * // Callback — zero re-renders, use for hot paths like large lists\n * function Card({ id, onLayout }) {\n *   useBoxRect((rect) => onLayout(id, rect))\n *   return <Box>...</Box>\n * }\n * ```\n *\n * On first render (reactive form), returns `{ x: 0, y: 0, width: 0, height: 0 }`.\n * After layout completes, automatically re-renders with actual dimensions.\n */\nexport function useBoxRect(): Rect\nexport function useBoxRect(callback: RectCallback): void\nexport function useBoxRect(callback?: RectCallback): Rect | void {\n  if (callback) {\n    return useCallbackRect((node) => getInnerRect(node), callback, \"boxRect\")\n  }\n  return useReactiveRect((node) => getInnerRect(node), \"boxRect\")\n}\n\n// ============================================================================\n// scrollRect — scroll-adjusted position (pre-sticky clamping)\n// ============================================================================\n\n/**\n * Returns the scroll-adjusted position for the current component.\n *\n * This is the node's position in scroll coordinates, *before* sticky clamping.\n * For non-sticky nodes it equals `useScreenRect()`. For sticky nodes, the\n * scrollRect reflects where the node would be without sticky adjustment —\n * so it can go off-screen (negative y, etc.) when scrolled past.\n *\n * Use this when you need to reason about the node's \"natural\" position in the\n * scrolled document. For hit testing or cursor positioning, use\n * `useScreenRect()` instead.\n *\n * Two signatures:\n *\n * ```tsx\n * // Reactive — re-renders when scroll changes\n * function Card({ id }) {\n *   const { y } = useScrollRect()\n *   return <Box>Scroll y: {y}</Box>\n * }\n *\n * // Callback — zero re-renders\n * function Card({ id, onLayout }) {\n *   useScrollRect((rect) => onLayout(id, rect.y))\n *   return <Box>...</Box>\n * }\n * ```\n */\nexport function useScrollRect(): Rect\nexport function useScrollRect(callback: RectCallback): void\nexport function useScrollRect(callback?: RectCallback): Rect | void {\n  if (callback) {\n    return useCallbackRect((node) => node.scrollRect, callback, \"scrollRect\")\n  }\n  return useReactiveRect((node) => node.scrollRect, \"scrollRect\")\n}\n\n// ============================================================================\n// screenRect — actual paint position on the terminal screen\n// ============================================================================\n\n/**\n * Returns the actual paint position on the terminal screen — the silvery\n * analogue of `getBoundingClientRect()`.\n *\n * For non-sticky nodes this equals `useScrollRect()`. For sticky nodes\n * (`position=\"sticky\"`), it reflects the clamped position where pixels\n * actually land on screen.\n *\n * Use this for hit testing, cursor positioning, and any feature that needs\n * to know where a node visually appears on the terminal.\n *\n * Two signatures:\n *\n * ```tsx\n * // Reactive — re-renders when the screen position changes\n * function StickyHeader() {\n *   const { y } = useScreenRect()\n *   return <Box position=\"sticky\" stickyTop={0}>Header at row {y}</Box>\n * }\n *\n * // Callback — zero re-renders, recommended for cross-component visual\n * // navigation (e.g. registering card positions for arrow-key navigation\n * // across columns with independent scroll state).\n * function Card({ id, onLayout }) {\n *   useScreenRect((rect) => onLayout(id, rect.y))\n *   return <Box>...</Box>\n * }\n * ```\n */\nexport function useScreenRect(): Rect\nexport function useScreenRect(callback: RectCallback): void\nexport function useScreenRect(callback?: RectCallback): Rect | void {\n  if (callback) {\n    return useCallbackRect((node) => node.screenRect, callback, \"screenRect\")\n  }\n  return useReactiveRect((node) => node.screenRect, \"screenRect\")\n}\n","/**\n * Kitty Graphics Protocol\n *\n * Encodes and manages images using the Kitty terminal graphics protocol.\n * Images are transmitted as base64-encoded PNG data via APC (Application\n * Program Command) escape sequences.\n *\n * Protocol reference: https://sw.kovidgoyal.net/kitty/graphics-protocol/\n *\n * Key concepts:\n * - `a=T` — transmit and display the image\n * - `f=100` — format is PNG (raw PNG data, terminal decodes it)\n * - `m=0|1` — 0 = last/only chunk, 1 = more chunks follow\n * - Chunks should be <= 4096 bytes of base64 to avoid overwhelming the terminal\n * - Images can be assigned an `i=<id>` for later deletion\n */\n\nconst APC_START = \"\\x1b_G\"\nconst ST = \"\\x1b\\\\\"\n\n/** Maximum base64 bytes per chunk (Kitty recommendation) */\nconst MAX_CHUNK_SIZE = 4096\n\nexport interface KittyImageOptions {\n  /** Image width in terminal columns */\n  width?: number\n  /** Image height in terminal rows */\n  height?: number\n  /** Image ID for later reference/deletion (positive integer) */\n  id?: number\n}\n\n/**\n * Encode a PNG image into Kitty graphics protocol escape sequences.\n *\n * The image data is base64-encoded and split into chunks of <= 4096 bytes.\n * Each chunk is wrapped in an APC escape sequence. The first chunk carries\n * the image metadata (action, format, dimensions, ID). Subsequent chunks\n * only carry `m=1` or `m=0` to indicate continuation.\n *\n * @param pngData - Raw PNG image data\n * @param opts - Optional dimensions and ID\n * @returns A string containing the complete escape sequence(s)\n *\n * @example\n * ```ts\n * import { readFileSync } from \"fs\"\n * import { encodeKittyImage } from \"@silvery/ag-react\"\n *\n * const png = readFileSync(\"photo.png\")\n * const seq = encodeKittyImage(png, { width: 40, height: 20 })\n * process.stdout.write(seq)\n * ```\n */\nexport function encodeKittyImage(pngData: Buffer, opts?: KittyImageOptions): string {\n  const b64 = pngData.toString(\"base64\")\n  const chunks = splitIntoChunks(b64, MAX_CHUNK_SIZE)\n\n  if (chunks.length === 0) {\n    // Empty image — send a single empty payload\n    return `${APC_START}${buildParams(opts, 0)};${ST}`\n  }\n\n  if (chunks.length === 1) {\n    // Single chunk — m=0 (last/only)\n    return `${APC_START}${buildParams(opts, 0)};${chunks[0]}${ST}`\n  }\n\n  // Multiple chunks\n  const parts: string[] = []\n\n  // First chunk carries full metadata, m=1 (more follows)\n  parts.push(`${APC_START}${buildParams(opts, 1)};${chunks[0]}${ST}`)\n\n  // Middle chunks — only m=1\n  for (let i = 1; i < chunks.length - 1; i++) {\n    parts.push(`${APC_START}m=1;${chunks[i]}${ST}`)\n  }\n\n  // Last chunk — m=0\n  parts.push(`${APC_START}m=0;${chunks[chunks.length - 1]}${ST}`)\n\n  return parts.join(\"\")\n}\n\n/**\n * Generate an escape sequence to delete a Kitty image by ID.\n *\n * Uses `a=d` (delete) with `d=i` (delete by image ID).\n *\n * @param id - The image ID to delete\n * @returns The delete escape sequence\n *\n * @example\n * ```ts\n * process.stdout.write(deleteKittyImage(42))\n * ```\n */\nexport function deleteKittyImage(id: number): string {\n  return `${APC_START}a=d,d=i,i=${id}${ST}`\n}\n\n/**\n * Check if the current terminal likely supports the Kitty graphics protocol.\n *\n * This is a heuristic based on `TERM` and `TERM_PROGRAM` environment variables.\n * For definitive detection, use a terminal query (send the graphics protocol\n * query and check for a response), but that requires async I/O.\n *\n * Known supporting terminals: Kitty, WezTerm, Ghostty (partial), Konsole (partial).\n *\n * @returns `true` if the terminal likely supports Kitty graphics\n */\nexport function isKittyGraphicsSupported(): boolean {\n  const term = process.env.TERM ?? \"\"\n  const termProgram = process.env.TERM_PROGRAM ?? \"\"\n\n  // Kitty terminal\n  if (term === \"xterm-kitty\" || termProgram === \"kitty\") return true\n\n  // WezTerm supports Kitty graphics protocol\n  if (termProgram === \"WezTerm\") return true\n\n  // Ghostty supports Kitty graphics\n  if (termProgram === \"ghostty\") return true\n\n  // Konsole 22.04+ supports Kitty graphics\n  if (termProgram === \"konsole\") return true\n\n  return false\n}\n\n// ============================================================================\n// Internal helpers\n// ============================================================================\n\n/**\n * Build the Kitty graphics protocol parameter string for the first chunk.\n */\nfunction buildParams(opts: KittyImageOptions | undefined, more: 0 | 1): string {\n  const parts = [`a=T`, `f=100`, `m=${more}`]\n\n  if (opts?.width != null) parts.push(`s=${opts.width}`)\n  if (opts?.height != null) parts.push(`v=${opts.height}`)\n  if (opts?.id != null) parts.push(`i=${opts.id}`)\n\n  return parts.join(\",\")\n}\n\n/**\n * Split a string into chunks of at most `size` characters.\n */\nfunction splitIntoChunks(str: string, size: number): string[] {\n  if (str.length === 0) return []\n\n  const chunks: string[] = []\n  for (let i = 0; i < str.length; i += size) {\n    chunks.push(str.slice(i, i + size))\n  }\n  return chunks\n}\n","/**\n * Sixel Encoder (Minimal Implementation)\n *\n * Sixel is an older image protocol supported by terminals like xterm, mlterm,\n * foot, and some others. Images are encoded as DCS (Device Control String)\n * sequences where each character encodes 6 vertical pixels.\n *\n * DCS format: `ESC P <params> q <sixel-data> ESC \\`\n *\n * This is a minimal implementation that produces valid Sixel output for\n * simple images. For production use with complex images, consider using\n * a dedicated Sixel library that handles color quantization and dithering.\n *\n * Protocol reference: https://en.wikipedia.org/wiki/Sixel\n *\n * TODO: Full Sixel encoding with proper color quantization, dithering,\n * and compression. The current implementation handles basic RGBA image data\n * with a simple nearest-color palette approach.\n */\n\nconst DCS_START = \"\\x1bP\"\nconst ST = \"\\x1b\\\\\"\n\n/** Sixel introduces a color with `#<index>;2;<r>;<g>;<b>` (RGB percentages 0-100) */\nconst SIXEL_NEWLINE = \"-\"\n\nexport interface SixelImageData {\n  /** Image width in pixels */\n  width: number\n  /** Image height in pixels */\n  height: number\n  /** RGBA pixel data (4 bytes per pixel: R, G, B, A), row-major order */\n  data: Uint8Array\n}\n\n/**\n * Encode RGBA image data as a Sixel escape sequence.\n *\n * This is a basic implementation that:\n * 1. Quantizes colors to a small palette (up to 256 colors)\n * 2. Encodes 6-row bands as Sixel characters\n * 3. Wraps in a DCS escape sequence\n *\n * For transparent pixels (alpha < 128), the background shows through.\n *\n * @param imageData - Image dimensions and RGBA pixel data\n * @returns A DCS escape sequence containing the Sixel-encoded image\n *\n * @example\n * ```ts\n * const img = { width: 10, height: 12, data: new Uint8Array(10 * 12 * 4) }\n * const seq = encodeSixel(img)\n * process.stdout.write(seq)\n * ```\n */\nexport function encodeSixel(imageData: SixelImageData): string {\n  const { width, height, data } = imageData\n\n  if (width === 0 || height === 0 || data.length === 0) {\n    return `${DCS_START}q${ST}`\n  }\n\n  // Build a simple palette by collecting unique (quantized) colors\n  const palette = new Map<string, number>()\n  const pixelColors = new Uint16Array(width * height) // palette index per pixel (0 = transparent)\n  let nextColorIndex = 1 // 0 reserved for transparent/background\n\n  for (let y = 0; y < height; y++) {\n    for (let x = 0; x < width; x++) {\n      const offset = (y * width + x) * 4\n      const r = data[offset]!\n      const g = data[offset + 1]!\n      const b = data[offset + 2]!\n      const a = data[offset + 3]!\n\n      if (a < 128) {\n        // Transparent — leave as 0\n        continue\n      }\n\n      // Quantize to 6-bit per channel (64 levels) to keep palette small\n      const qr = (r >> 2) & 0x3f\n      const qg = (g >> 2) & 0x3f\n      const qb = (b >> 2) & 0x3f\n      const key = `${qr},${qg},${qb}`\n\n      let idx = palette.get(key)\n      if (idx == null) {\n        if (nextColorIndex >= 256) {\n          // Palette full — find closest existing color (simple fallback)\n          idx = 1\n        } else {\n          idx = nextColorIndex++\n          palette.set(key, idx)\n        }\n      }\n\n      pixelColors[y * width + x] = idx\n    }\n  }\n\n  // Build Sixel data\n  const parts: string[] = []\n\n  // Raster attributes: Pan;Pad;Ph;Pv (aspect ratio 1:1, width, height)\n  parts.push(`\"1;1;${width};${height}`)\n\n  // Define palette colors\n  for (const [key, idx] of palette) {\n    const [qr, qg, qb] = key.split(\",\").map(Number)\n    // Convert from 6-bit (0-63) to percentage (0-100)\n    const rPct = Math.round((qr! / 63) * 100)\n    const gPct = Math.round((qg! / 63) * 100)\n    const bPct = Math.round((qb! / 63) * 100)\n    parts.push(`#${idx};2;${rPct};${gPct};${bPct}`)\n  }\n\n  // Encode pixel data in 6-row bands\n  for (let bandY = 0; bandY < height; bandY += 6) {\n    if (bandY > 0) {\n      parts.push(SIXEL_NEWLINE) // Move to next sixel row\n    }\n\n    // For each color in the palette, emit the sixel row\n    // (Only emit colors that appear in this band)\n    const bandColors = new Set<number>()\n    for (let dy = 0; dy < 6 && bandY + dy < height; dy++) {\n      for (let x = 0; x < width; x++) {\n        const ci = pixelColors[(bandY + dy) * width + x]!\n        if (ci > 0) bandColors.add(ci)\n      }\n    }\n\n    let first = true\n    for (const colorIdx of bandColors) {\n      if (!first) {\n        parts.push(\"$\") // Carriage return within sixel line (reposition to start)\n      }\n      first = false\n\n      parts.push(`#${colorIdx}`)\n\n      // Build the sixel characters for this color in this band\n      for (let x = 0; x < width; x++) {\n        let sixelBits = 0\n        for (let dy = 0; dy < 6; dy++) {\n          const y = bandY + dy\n          if (y < height && pixelColors[y * width + x] === colorIdx) {\n            sixelBits |= 1 << dy\n          }\n        }\n        // Sixel character = bits + 63 (0x3F)\n        parts.push(String.fromCharCode(sixelBits + 63))\n      }\n    }\n  }\n\n  return `${DCS_START}q${parts.join(\"\")}${ST}`\n}\n\n/**\n * Check if the current terminal likely supports the Sixel protocol.\n *\n * This is a heuristic based on environment variables. For definitive\n * detection, send a DA1 (Device Attributes) query and check for \"4\"\n * in the response, but that requires async I/O.\n *\n * Known supporting terminals: xterm (with +sixel), mlterm, foot, mintty,\n * WezTerm, Contour, Sixel-enabled builds of various terminals.\n *\n * @returns `true` if the terminal likely supports Sixel\n */\nexport function isSixelSupported(): boolean {\n  const term = process.env.TERM ?? \"\"\n  const termProgram = process.env.TERM_PROGRAM ?? \"\"\n\n  // mlterm supports Sixel natively\n  if (termProgram === \"mlterm\" || term.startsWith(\"mlterm\")) return true\n\n  // foot supports Sixel\n  if (termProgram === \"foot\" || term === \"foot\" || term === \"foot-extra\") return true\n\n  // WezTerm supports Sixel\n  if (termProgram === \"WezTerm\") return true\n\n  // mintty supports Sixel\n  if (termProgram === \"mintty\") return true\n\n  // xterm might support Sixel if compiled with +sixel\n  // We can't know for sure from env alone, so we don't claim support\n  // (the user can set protocol='sixel' explicitly)\n\n  return false\n}\n","/**\n * Image Component\n *\n * Renders bitmap images in supported terminals using the Kitty graphics\n * protocol (primary) or Sixel (fallback). When neither is supported,\n * displays a text placeholder.\n *\n * Since terminal images are escape-sequence-based and don't fit the cell\n * buffer model, the component reserves visual space with a Box of the\n * requested dimensions and uses `useEffect` to write image data directly\n * to stdout after render.\n *\n * @example\n * ```tsx\n * import { readFileSync } from \"fs\"\n * import { Image } from \"@silvery/ag-react\"\n *\n * const png = readFileSync(\"photo.png\")\n * <Image src={png} width={40} height={20} />\n *\n * // With file path\n * <Image src=\"/path/to/image.png\" width={40} height={20} />\n *\n * // Auto-detect protocol, fall back to text\n * <Image src={png} width={40} height={20} fallback=\"[photo]\" />\n * ```\n */\n\nimport { readFileSync } from \"node:fs\"\nimport { type JSX, useContext, useEffect, useMemo, useRef } from \"react\"\nimport { StdoutContext } from \"../../context\"\nimport { useBoxRect } from \"../../hooks/useLayout\"\nimport { encodeKittyImage, isKittyGraphicsSupported, deleteKittyImage } from \"./kitty-graphics\"\nimport { isSixelSupported } from \"./sixel-encoder\"\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport type ImageProtocol = \"kitty\" | \"sixel\" | \"auto\"\n\nexport interface ImageProps {\n  /** PNG image data (Buffer) or file path (string) to a PNG file */\n  src: Buffer | string\n  /** Width in terminal columns. If omitted, uses available width from layout. */\n  width?: number\n  /** Height in terminal rows. If omitted, defaults to half the width (rough aspect ratio). */\n  height?: number\n  /** Text to display when image rendering is not supported. Default: \"[image]\" */\n  fallback?: string\n  /** Which protocol to use. Default: \"auto\" (tries Kitty, then Sixel, then fallback) */\n  protocol?: ImageProtocol\n}\n\n// ============================================================================\n// Protocol Detection\n// ============================================================================\n\n/**\n * Determine the best available image protocol.\n * Returns null if no image protocol is available.\n */\nfunction detectProtocol(preferred: ImageProtocol): \"kitty\" | \"sixel\" | null {\n  if (preferred === \"kitty\") {\n    return isKittyGraphicsSupported() ? \"kitty\" : null\n  }\n  if (preferred === \"sixel\") {\n    return isSixelSupported() ? \"sixel\" : null\n  }\n\n  // Auto-detect: prefer Kitty, fall back to Sixel\n  if (isKittyGraphicsSupported()) return \"kitty\"\n  if (isSixelSupported()) return \"sixel\"\n  return null\n}\n\n// ============================================================================\n// Component\n// ============================================================================\n\n/** Incrementing image ID counter for Kitty protocol */\nlet nextImageId = 1\n\n/**\n * Renders a bitmap image in the terminal.\n *\n * The component operates in two phases:\n * 1. **Layout phase**: Renders a Box that reserves the visual space\n *    (filled with spaces so the cell buffer has the right dimensions).\n * 2. **Effect phase**: After render, writes the image escape sequence\n *    directly to stdout, positioned over the reserved space.\n *\n * When image protocols are not available, the fallback text is shown instead.\n */\nexport function Image({\n  src,\n  width: requestedWidth,\n  height: requestedHeight,\n  fallback = \"[image]\",\n  protocol: preferredProtocol = \"auto\",\n}: ImageProps): JSX.Element {\n  const boxRect = useBoxRect()\n  const stdoutCtx = useContext(StdoutContext)\n  const imageIdRef = useRef<number | null>(null)\n\n  // Resolve image data\n  const pngData = useMemo(() => {\n    if (Buffer.isBuffer(src)) return src\n    // String path — read file synchronously (during render is fine for a path)\n    try {\n      return readFileSync(src)\n    } catch {\n      return null\n    }\n  }, [src])\n\n  // Determine effective dimensions\n  const effectiveWidth = requestedWidth ?? boxRect.width\n  const effectiveHeight = requestedHeight ?? Math.max(1, Math.floor(effectiveWidth / 2))\n\n  // Detect protocol support\n  const activeProtocol = useMemo(() => detectProtocol(preferredProtocol), [preferredProtocol])\n\n  // Assign a stable image ID for Kitty (for cleanup on unmount)\n  if (activeProtocol === \"kitty\" && imageIdRef.current == null) {\n    imageIdRef.current = nextImageId++\n  }\n\n  // Write image escape sequences after render\n  useEffect(() => {\n    if (!pngData || !stdoutCtx || !activeProtocol) return\n    if (effectiveWidth <= 0 || effectiveHeight <= 0) return\n\n    const { write } = stdoutCtx\n\n    if (activeProtocol === \"kitty\") {\n      const seq = encodeKittyImage(pngData, {\n        width: effectiveWidth,\n        height: effectiveHeight,\n        id: imageIdRef.current ?? undefined,\n      })\n      write(seq)\n    } else if (activeProtocol === \"sixel\") {\n      // For Sixel, we would need the decoded pixel data.\n      // Since we receive PNG, and decoding PNG requires a library,\n      // Sixel rendering from raw PNG is deferred. The Kitty protocol\n      // can transmit PNG directly (f=100), but Sixel cannot.\n      // For now, Sixel only works if src is already decoded pixel data.\n      // This is a known limitation noted in the module docs.\n      //\n      // If someone passes a Buffer that's already RGBA pixel data\n      // (not PNG), this would need a flag. For now, Sixel falls through\n      // to fallback when src is PNG.\n    }\n  }, [pngData, stdoutCtx, activeProtocol, effectiveWidth, effectiveHeight])\n\n  // Cleanup: delete Kitty image on unmount\n  useEffect(() => {\n    const id = imageIdRef.current\n    if (activeProtocol !== \"kitty\" || id == null || !stdoutCtx) return\n\n    return () => {\n      stdoutCtx.write(deleteKittyImage(id))\n    }\n  }, [activeProtocol, stdoutCtx])\n\n  // If no protocol or no image data, render fallback text\n  if (!activeProtocol || !pngData) {\n    return (\n      <silvery-box width={effectiveWidth} height={effectiveHeight}>\n        <silvery-text>{fallback}</silvery-text>\n      </silvery-box>\n    )\n  }\n\n  // Reserve visual space with an empty box.\n  // The image is drawn over this space via stdout escape sequences.\n  // Fill with spaces so the cell buffer allocates the right area.\n  const spaceLine = \" \".repeat(Math.max(0, effectiveWidth))\n  const spaceContent = Array.from({ length: Math.max(0, effectiveHeight) }, () => spaceLine).join(\n    \"\\n\",\n  )\n\n  return (\n    <silvery-box width={effectiveWidth} height={effectiveHeight}>\n      <silvery-text>{spaceContent}</silvery-text>\n    </silvery-box>\n  )\n}\n"],"mappings":"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"}