preview

Documentation

Overview

Package preview classifies and renders bounded object content for the preview pane: scrollable text, visual images, and a safe summary for binary. It has NO S3 dependency — callers fetch the bounded bytes and hand them in (FR-014/015/016).

Index

• Constants
• func HexDump(data []byte) string
• func Pretty(p Payload) (string, bool)
• func RenderHalfBlock(data []byte, cols, rows int) (string, error)
• func RenderImage(data []byte, proto Protocol, cols, rows int) (string, error)
• func Summary(p Payload) string
• type Compressed
• type Kind
  • func Classify(contentType string, data []byte) Kind
  • func (k Kind) String() string
• type Payload
  • func Build(key, contentType string, data []byte, truncated bool) Payload
• type Protocol
  • func DetectProtocol(env func(string) string) Protocol
  • func (p Protocol) String() string

Constants

const Limit int64 = 5 * 1024 * 1024

Limit is the maximum number of bytes fetched for a preview (FR-014/016).

Functions

func HexDump

func HexDump(data []byte) string

HexDump renders the classic offset + hex + printable-column dump, 16 bytes per row (017 US5/FR-027). Rows are ~76 chars — within the ≥80-column minimum, no wrapping.

func Pretty

func Pretty(p Payload) (string, bool)

Pretty renders a JSON/NDJSON payload indented (2 spaces); ok=false for any other kind or a parse failure — the caller falls back to the raw bytes with no error banner (017 US5/FR-025). Payload.Data is never modified (the raw-toggle source).

func RenderHalfBlock

func RenderHalfBlock(data []byte, cols, rows int) (string, error)

RenderHalfBlock renders image bytes to a truecolor ANSI half-block string sized to fit within cols×rows character cells. Works in any 24-bit terminal — the safe default (research §3). Returns an error if the bytes are not a decodable image, so callers can fall back to a summary (FR-015).

func RenderImage

func RenderImage(data []byte, proto Protocol, cols, rows int) (string, error)

RenderImage renders image bytes for the given terminal protocol. A real graphics protocol (kitty / iTerm2) produces a crisp, full-resolution image; ProtoNone/ProtoSixel (or any failure) fall back to ANSI half-block, which is low-resolution by nature (two pixels per character cell) but works everywhere. cols/rows are the target size in character cells. The protocol encoders are hand-rolled (no terminal queries) so they never block or panic inside the TUI.

func Summary

func Summary(p Payload) string

Summary returns a safe one-line description for binary (or any) content — never dumps raw bytes to the terminal (FR-015).

Types

type Compressed

type Compressed struct {
	From      int64 // compressed bytes the preview fetched
	Truncated bool  // decompressed output capped at Limit
}

Compressed carries the gzip-decode metadata of a transparently decompressed payload (017 US5/FR-026): the compressed input size and whether the OUTPUT hit the Limit cap.

type Kind

type Kind int

Kind classifies preview content for the renderer.

const (
	// KindBinary is non-text, non-image content — shown as a hex dump.
	KindBinary Kind = iota
	// KindText is renderable as scrollable text.
	KindText
	// KindImage is renderable visually (half-block or graphics protocol).
	KindImage
	// KindJSON is ONE parseable JSON value — pretty-printable (017 US5).
	KindJSON
	// KindNDJSON is ≥2 newline-delimited parseable JSON values (017 US5).
	KindNDJSON
)

func Classify

func Classify(contentType string, data []byte) Kind

Classify decides the Kind from the content type and (when ambiguous) the bytes. An empty content type is sniffed via http.DetectContentType. A NUL byte forces binary. octet-stream falls back to a UTF-8/printability check.

func (Kind) String

func (k Kind) String() string

type Payload

type Payload struct {
	Key         string
	ContentType string
	Data        []byte
	Truncated   bool // true if the object exceeds Limit (or a capped decompression)
	Kind        Kind
	// Compressed is set when Data was transparently gunzipped (017 US5/FR-026).
	Compressed *Compressed
}

Payload is bounded content ready for the preview pane (data-model PreviewPayload).

func Build

func Build(key, contentType string, data []byte, truncated bool) Payload

Build assembles a Payload, classifying the content. A gzip payload (magic bytes — the primary signal; the .gz name and Content-Encoding merely corroborate) is transparently decompressed with the output capped at Limit, and the decompressed bytes re-enter classification so a gzipped JSON pretty-prints (017 US5/FR-026). A failed decode falls back to the raw bytes silently.

type Protocol

type Protocol int

Protocol identifies a terminal graphics capability (research §3).

const (
	// ProtoNone means no graphics protocol — use ANSI half-block (works everywhere).
	ProtoNone Protocol = iota
	// ProtoKitty is the kitty graphics protocol (also Ghostty / WezTerm).
	ProtoKitty
	// ProtoITerm2 is the iTerm2 inline-images protocol.
	ProtoITerm2
	// ProtoSixel is the sixel graphics protocol.
	ProtoSixel
)

func DetectProtocol

func DetectProtocol(env func(string) string) Protocol

DetectProtocol resolves the best available graphics protocol from environment variables (research §3). env is an os.Getenv-like lookup (injectable for tests). Falls back to ProtoNone (→ half-block) when nothing is detected.

func (Protocol) String

func (p Protocol) String() string