[feature] Public preview surface API for line/item previews

[kzhrv]

Hi, I’m integrating reeflective/readline into a shell that has two preview concepts:

• preview for the current command line
• preview for the currently selected completion/item

At the moment I can only degrade those previews into helper text because I can’t find a public preview surface API that matches those use cases.

Current issue

The library exposes strong completion and helper behavior, but I could not find a public way to plug in:

• line preview callbacks
• item preview callbacks
• preview sizing
• preview refresh behavior separate from the normal hint/helper row

This makes it hard to preserve preview-heavy workflows when swapping from another readline implementation.

Requested API

Something in this direction would help a lot:

type PreviewSize struct {
    Width  int
    Height int
}

type PreviewCallback func(lines []string, pos int, err error)

type PreviewFunc func(ctx context.Context, line []rune, item string, size PreviewSize, cb PreviewCallback)

func (rl *Shell) SetPreviewLine(fn PreviewFunc)
func (rl *Shell) SetPreviewItem(fn PreviewFunc)
func (rl *Shell) EnablePreview(enabled bool)

This is only a sketch, not a strict requirement.

Why this matters

Without a public preview API:

• command/item previews get collapsed into generic hint text
• preview and hint concepts cannot be separated cleanly
• integrations lose UX parity even if the rest of the shell behavior is close

Desired behavior

It would be enough if:

• preview rendering had a distinct public hook
• the preview area had known size constraints
• integrations could refresh/update preview content cleanly

Even a minimal preview lane would be a big improvement over having to overload the helper row.