silvery 0.19.2 → 0.21.1

package/dist/index-Dg1YaeJb.d.mts

@@ -0,0 +1,336 @@
+import { P as TerminalCaps } from "./index-2E1jYgak.mjs";
+import { JSX } from "react";
+
+//#region packages/ag-react/src/ui/image/kitty-graphics.d.ts
+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;
+  /**
+   * Transmit only — store the image but do NOT place it.
+   *
+   * Default `false`: action is `a=T` (transmit and display at cursor).
+   * Set to `true` for `a=t` (transmit only) — store the image bytes for
+   * later placement via {@link placeKittyImage}, without consuming a cell.
+   * The two-step flow lets a moving consumer (e.g. an `<Image>` that
+   * re-positions on scroll) transmit the PNG bytes once and re-place
+   * with a tiny APC packet on every subsequent move — eliminating the
+   * "delete-and-retransmit" flicker that re-encoding the full base64
+   * blob on every position change otherwise produces.
+   */
+  transmitOnly?: boolean;
+  /** Z-index stacking order. Defaults to 1 so images remain above reserved cells. */
+  zIndex?: number;
+  /** Pixel offset inside the first cell. Kitty keys: X/Y. */
+  pixelOffset?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  /** Source rectangle in image pixels. Kitty keys: x/y/w/h. */
+  sourceRect?: {
+    readonly x?: number;
+    readonly y?: number;
+    readonly width?: number;
+    readonly height?: number;
+  };
+  /** Create a virtual placement for a Unicode placeholder. Kitty key: U=1. */
+  virtualPlacement?: boolean;
+}
+/** Options for {@link placeKittyImage}. */
+interface KittyPlaceOptions {
+  /** Image ID previously transmitted via `a=t` (or `a=T`). */
+  id: number;
+  /** Display width in terminal columns. */
+  width?: number;
+  /** Display height in terminal rows. */
+  height?: number;
+  /**
+   * Placement ID for this displayed instance. Defaults to 1.
+   *
+   * Multiple placements of the same `id` can coexist if you give them
+   * different `placementId`s — each is independently delete-able via
+   * {@link deleteKittyPlacement}.
+   */
+  placementId?: number;
+  /** Z-index stacking order. Defaults to 1 so images remain above reserved cells. */
+  zIndex?: number;
+  /** Pixel offset inside the first cell. Kitty keys: X/Y. */
+  pixelOffset?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  /** Source rectangle in image pixels. Kitty keys: x/y/w/h. */
+  sourceRect?: {
+    readonly x?: number;
+    readonly y?: number;
+    readonly width?: number;
+    readonly height?: number;
+  };
+  /** Create a virtual placement for a Unicode placeholder. Kitty key: U=1. */
+  virtualPlacement?: boolean;
+}
+/**
+ * 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). 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))
+ * ```
+ */
+declare function deleteKittyImage(id: number): string;
+/**
+ * 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)
+ */
+declare function deleteKittyPlacement(id: number, placementId?: number): string;
+/**
+ * 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 }))
+ * ```
+ */
+declare function placeKittyImage(opts: KittyPlaceOptions): string;
+/**
+ * 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
+ */
+declare function isKittyGraphicsSupported(profile?: {
+  readonly caps?: Pick<TerminalCaps, "kittyGraphics">;
+  readonly emulator?: {
+    program: string;
+    TERM: string;
+  };
+} | {
+  program: string;
+  TERM: string;
+}): 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;
+}
+/**
+ * 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))
+ * }
+ * ```
+ */
+declare function decodePngToRgba(pngData: Buffer | Uint8Array): SixelImageData | 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)
+ * ```
+ */
+declare function encodeSixel(imageData: SixelImageData): string;
+/**
+ * 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
+ */
+declare function isSixelSupported(emulator?: {
+  program: string;
+  TERM: string;
+}): 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;
+  /** Kitty placement id. Defaults to 1. */
+  placementId?: number;
+  /** Kitty z-index. Defaults to 1 so images render above reserved cells. */
+  zIndex?: number;
+  /** Kitty sub-cell pixel offset inside the first cell. */
+  pixelOffset?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  /** Kitty source crop rectangle in image pixels. */
+  sourceRect?: {
+    readonly x?: number;
+    readonly y?: number;
+    readonly width?: number;
+    readonly height?: number;
+  };
+  /** Kitty virtual placement flag for Unicode placeholder rendering. */
+  virtualPlacement?: boolean;
+}
+/**
+ * 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.
+ */
+declare function Image({
+  src,
+  width: requestedWidth,
+  height: requestedHeight,
+  fallback,
+  protocol: preferredProtocol,
+  placementId,
+  zIndex,
+  pixelOffset,
+  sourceRect,
+  virtualPlacement
+}: ImageProps): JSX.Element;
+//#endregion
+export { encodeSixel as a, KittyPlaceOptions as c, encodeKittyImage as d, isKittyGraphicsSupported as f, decodePngToRgba as i, deleteKittyImage as l, ImageProps as n, isSixelSupported as o, placeKittyImage as p, SixelImageData as r, KittyImageOptions as s, Image as t, deleteKittyPlacement as u };
+//# sourceMappingURL=index-Dg1YaeJb.d.mts.map

package/dist/index-Dg1YaeJb.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-Dg1YaeJb.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":";;;;UAyBiB,iBAAA;EA2BJ;EAzBX,KAAA;EA2BW;EAzBX,MAAA;EA4BgB;EA1BhB,EAAA;EA8Be;;;;;;;;;;;;EAjBf,YAAA;EAsCW;EApCX,MAAA;EAsCW;EApCX,WAAA;IAAA,SAAyB,CAAA;IAAA,SAAqB,CAAA;EAAA;EAiEhC;EA/Dd,UAAA;IAAA,SACW,CAAA;IAAA,SACA,CAAA;IAAA,SACA,KAAA;IAAA,SACA,MAAA;EAAA;EA2DqC;EAxDhD,gBAAA;AAAA;AAuGF;AAAA,UAnGiB,iBAAA;;EAEf,EAAA;EAiGyC;EA/FzC,KAAA;EAgHkC;EA9GlC,MAAA;EA8GmC;;AA6BrC;;;;;EAnIE,WAAA;EAmKsC;EAjKtC,MAAA;EAoK0B;EAlK1B,WAAA;IAAA,SAAyB,CAAA;IAAA,SAAqB,CAAA;EAAA;EAmKlB;EAjK5B,UAAA;IAAA,SACW,CAAA;IAAA,SACA,CAAA;IAAA,SACA,KAAA;IAAA,SACA,MAAA;EAAA;;EAGX,gBAAA;AAAA;ACxDF;;;;;;;;;;AAyCA;;;;;;;;;;;;AAzCA,iBDiFgB,gBAAA,CAAiB,OAAA,EAAS,MAAA,EAAQ,IAAA,GAAO,iBAAA;;ACEzD;;;;;AA2HA;;;;;;;;;;iBD9EgB,gBAAA,CAAiB,EAAA;;AE3GjC;;;;;AAEA;;;;iBF0HgB,oBAAA,CAAqB,EAAA,UAAY,WAAA;;;;;;;;;;;;;;;;;;;;AECjD;;;;;;iBF4BgB,eAAA,CAAgB,IAAA,EAAM,iBAAA;;;;;;;;;;;;;;;;;iBAgCtB,wBAAA,CACd,OAAA;EAAA,SAEe,IAAA,GAAO,IAAA,CAAK,YAAA;EAAA,SACZ,QAAA;IAAa,OAAA;IAAiB,IAAA;EAAA;AAAA;EAEvC,OAAA;EAAiB,IAAA;AAAA;;;;;;;AA3NzB;;;;;;;;;;;;;;;UCOiB,cAAA;EDsBJ;ECpBX,KAAA;EDuBgB;ECrBhB,MAAA;EDyBe;ECvBf,IAAA,EAAM,UAAA;AAAA;;;;;;;;;;;;;;;;;;AD2ER;;;;;;;;;;iBCxCgB,eAAA,CAAgB,OAAA,EAAS,MAAA,GAAS,UAAA,GAAa,cAAA;;;;;ADwG/D;;;;;AA6BA;;;;;AAgCA;;;;;;iBC3HgB,WAAA,CAAY,SAAA,EAAW,cAAA;;;;;;;;;;;;AAnFvC;;;;;;;iBA8MgB,gBAAA,CAAiB,QAAA;EAAa,OAAA;EAAiB,IAAA;AAAA;;;KCzLnD,aAAA;AAAA,UAEK,UAAA;EFUf;EERA,GAAA,EAAK,MAAA;EFkBL;EEhBA,KAAA;EFoBA;EElBA,MAAA;EFkB8C;EEhB9C,QAAA;EFmBW;EEjBX,QAAA,GAAW,aAAA;EFmBA;EEjBX,WAAA;EFqBA;EEnBA,MAAA;EFmBgB;EEjBhB,WAAA;IAAA,SAAyB,CAAA;IAAA,SAAqB,CAAA;EAAA;EF0CN;EExCxC,UAAA;IAAA,SACW,CAAA;IAAA,SACA,CAAA;IAAA,SACA,KAAA;IAAA,SACA,MAAA;EAAA;EFmFmB;EEhF9B,gBAAA;AAAA;;;;;;;;ADhDF;;;;iBCkJgB,KAAA,CAAA;EACd,GAAA;EACA,KAAA,EAAO,cAAA;EACP,MAAA,EAAQ,eAAA;EACR,QAAA;EACA,QAAA,EAAU,iBAAA;EACV,WAAA;EACA,MAAA;EACA,WAAA;EACA,UAAA;EACA;AAAA,GACC,UAAA,GAAa,GAAA,CAAI,OAAA"}