silvery 0.17.0 → 0.17.2

package/dist/index-p-wBs_wH.d.mts

@@ -0,0 +1,175 @@
+import { JSX } from "react";
+
+//#region packages/ag-react/src/ui/image/kitty-graphics.d.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
+ */
+interface KittyImageOptions {
+  /** Image width in terminal columns */
+  width?: number;
+  /** Image height in terminal rows */
+  height?: number;
+  /** Image ID for later reference/deletion (positive integer) */
+  id?: number;
+}
+/**
+ * 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)
+ * ```
+ */
+declare function encodeKittyImage(pngData: Buffer, opts?: KittyImageOptions): string;
+/**
+ * Generate an escape sequence to delete a Kitty image by ID.
+ *
+ * Uses `a=d` (delete) with `d=i` (delete by image ID).
+ *
+ * @param id - The image ID to delete
+ * @returns The delete escape sequence
+ *
+ * @example
+ * ```ts
+ * process.stdout.write(deleteKittyImage(42))
+ * ```
+ */
+declare function deleteKittyImage(id: number): string;
+/**
+ * Check if the current terminal likely supports the Kitty graphics protocol.
+ *
+ * This is a heuristic based on `TERM` and `TERM_PROGRAM` environment variables.
+ * 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
+ */
+declare function isKittyGraphicsSupported(): boolean;
+//#endregion
+//#region packages/ag-react/src/ui/image/sixel-encoder.d.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.
+ */
+interface SixelImageData {
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** RGBA pixel data (4 bytes per pixel: R, G, B, A), row-major order */
+  data: Uint8Array;
+}
+/**
+ * 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)
+ * ```
+ */
+declare function encodeSixel(imageData: SixelImageData): string;
+/**
+ * Check if the current terminal likely supports the Sixel protocol.
+ *
+ * This is a heuristic based on environment variables. 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
+ */
+declare function isSixelSupported(): boolean;
+//#endregion
+//#region packages/ag-react/src/ui/image/Image.d.ts
+type ImageProtocol = "kitty" | "sixel" | "auto";
+interface ImageProps {
+  /** PNG image data (Buffer) or file path (string) to a PNG file */
+  src: Buffer | string;
+  /** Width in terminal columns. If omitted, uses available width from layout. */
+  width?: number;
+  /** Height in terminal rows. If omitted, defaults to half the width (rough aspect ratio). */
+  height?: number;
+  /** Text to display when image rendering is not supported. Default: "[image]" */
+  fallback?: string;
+  /** Which protocol to use. Default: "auto" (tries Kitty, then Sixel, then fallback) */
+  protocol?: ImageProtocol;
+}
+/**
+ * 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. **Effect phase**: After render, writes the image escape sequence
+ *    directly to stdout, positioned over the reserved space.
+ *
+ * When image protocols are not available, the fallback text is shown instead.
+ */
+declare function Image({
+  src,
+  width: requestedWidth,
+  height: requestedHeight,
+  fallback,
+  protocol: preferredProtocol
+}: ImageProps): JSX.Element;
+//#endregion
+export { isSixelSupported as a, encodeKittyImage as c, encodeSixel as i, isKittyGraphicsSupported as l, ImageProps as n, KittyImageOptions as o, SixelImageData as r, deleteKittyImage as s, Image as t };
+//# sourceMappingURL=index-p-wBs_wH.d.mts.map

package/dist/index-p-wBs_wH.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-p-wBs_wH.d.mts","names":[],"sources":["../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"],"mappings":";;;;;;AAuBA;;;;;;;;;AA+BA;;;;UA/BiB,iBAAA;EA+BgB;EA7B/B,KAAA;EA6BgD;EA3BhD,MAAA;EA2BwE;EAzBxE,EAAA;AAAA;;;;AAoFF;;;;;;;;ACvFA;;;;;;;;;;AA6BA;iBDDgB,gBAAA,CAAiB,OAAA,EAAS,MAAA,EAAQ,IAAA,GAAO,iBAAA;;;;ACsHzD;;;;;;;;ACrIA;;iBF2DgB,gBAAA,CAAiB,EAAA;;;AEzDjC;;;;;;;;;iBFwEgB,wBAAA,CAAA;;;;;;AA1FhB;;;;;;;;;AA+BA;;;;;;;UC5BiB,cAAA;ED4ByD;EC1BxE,KAAA;EDsEc;ECpEd,MAAA;;EAEA,IAAA,EAAM,UAAA;AAAA;ADiFR;;;;;;;;ACvFA;;;;;;;;;;AA6BA;;AD0DA,iBC1DgB,WAAA,CAAY,SAAA,EAAW,cAAA;;;AAqHvC;;;;;;;;ACrIA;;iBDqIgB,gBAAA,CAAA;;;KCrIJ,aAAA;AAAA,UAEK,UAAA;EFwEuB;EEtEtC,GAAA,EAAK,MAAA;;EAEL,KAAA;;EAEA,MAAA;EDrB6B;ECuB7B,QAAA;EDjBgB;ECmBhB,QAAA,GAAW,aAAA;AAAA;;;;;ADIb;;;;;AAqHA;;iBC9EgB,KAAA,CAAA;EACd,GAAA;EACA,KAAA,EAAO,cAAA;EACP,MAAA,EAAQ,eAAA;EACR,QAAA;EACA,QAAA,EAAU;AAAA,GACT,UAAA,GAAa,GAAA,CAAI,OAAA"}