anitty 0.1.0

Anime character animation rendering for terminals
Documentation
# 终端 backend 与宿主接入

所有 backend 接收相同的 `RgbaFrame`,无需知道动画来源。

| Backend | 构造 | 像素输出 | 资源清理 |
| --- | --- | --- | --- |
| `Iterm2` | `Iterm2` | PNG,保留 RGBA alpha | `finish` 无操作 |
| `Kitty` | `Kitty::new([id_a, id_b])?` | 原始 RGBA,保留 alpha | `finish` 删除两个独占图像 ID |
| `Sixel` | `Sixel::new([r, g, b])` | 合成实色背景,最多 256 色,无抖动 | `finish` 无操作 |

编码成功只表示协议数据已写入,不保证终端支持或已经显示。
backend 不自动探测;应用可显式调用 [TerminalProbe](terminal.md),也可让用户选择。

## 统一调用与生命周期

```rust,no_run
use std::io;
use anitty::{Backend, Kitty, RgbaFrame};

let frame = RgbaFrame::new(1, 1, vec![255, 128, 0, 128])?;
// 两个 ID 必须由宿主预留,在同一终端屏幕中独占。
let mut backend: Box<dyn Backend> = Box::new(Kitty::new([100, 200])?);
let mut output = io::stdout().lock();
let result = backend.draw(&frame, &mut output);
// 有输出错误时也尝试清理;优先返回原来的绘制错误。
let cleanup = backend.finish(&mut output);
result?;
cleanup?;
# Ok::<(), anitty::Error>(())
```

`draw` 从当前光标位置绘制完整一帧并 flush,保持光标位置。
应用负责移动光标、串行化文字与图像输出、设置和恢复终端模式,以及安排绘制时间。
画面必须放入剩余视口,恢复光标不能撤销已经发生的滚屏。

`finish` 应在同一个输出、同一个终端屏幕上调用,且在离开备用屏幕之前调用。
它只清理该 backend 自身可寻址的图像资源,不恢复文字、不清空屏幕、不退出终端模式。
丢弃 backend 不会自动向终端写入;`finish` 后仍可继续绘制。

固定位置和尺寸有助于稳定播放。改变尺寸、位置或隐藏角色时,应用负责布局和旧区域恢复;
backend 仅提供协议支持的图像替换与删除。将 RGBA 设为全透明不等于所有终端都会擦除旧图。

## iTerm2 PNG

`Iterm2` 通过 inline-image 协议传输 PNG,保留完整 alpha,包括半透明边缘。
在已验证的 Konsole 23.08.5 中,同位置、同尺寸的新图片接收完成后会替换旧图片,透明区域也随之更新。
这属于终端的实现行为,不能推广到所有支持该协议的终端。

不要为每帧主动清屏:图像可能分多次传输,清屏先显示会导致闪烁。
`BufWriter` 本身也不能保证终端把一次更新原子呈现。若出现残影,检查终端的图片替换行为、画布大小和绘制位置。

## Kitty Graphics

`Kitty::new([100, 200])` 使用且只使用传入的两个 ID;ID 不需要连续,但必须非零、互不相同,
并且不能与同一屏幕上的其他实例或程序冲突。因此不提供自动分配 ID 的 `Default`。

同一实例交替上传两张图片,上传完新帧后删除旧图并显示新图,避免传输期间先清空画面。
保持实例与输出连接对应,不要逐帧创建新的 backend。退出时调用 `finish` 删除两个 ID。

使用直接 RGBA 传输,不量化颜色、不预先合成背景。原始数据可能大于 PNG,
尤其在远程连接上,传输带宽也是帧预算的一部分。
当前不提供终端驱动动画、Unicode placeholders 或终端复用器透传封装。

## SIXEL 与背景

当前 `Sixel` backend 将每帧合成到指定 RGB 背景,再量化并输出完整矩形。
`Sixel::default()` 为黑底,`Sixel::new([36, 40, 40])` 指定其他背景。
这是 backend 的输出策略;SIXEL 的跳过背景像素能力不能表达 RGBA 的连续 alpha,
也不能保证动画的上一帧会被擦除。

完整绘制背景可覆盖同一区域中的上一帧,半透明边缘按选定背景合成。
匹配终端默认背景能减少矩形边界,但默认背景不一定等于面板背景、背景图片或半透明窗口背后的颜色。
量化还可能产生轻微色差,不能承诺与终端背景逐像素相同。

SIXEL 按 6 像素高的条带编码,输出高度会向上补齐到 6 的倍数。
例如输入 256 行,输出占用 258 行;最后两行使用背景色,原图不缩放。
应用需为补齐后的高度预留空间。

库不读取终端背景;应用可以将 `TerminalCapabilities::background` 传给 `Sixel::new`,
未知时自行选择背景或提示用户。CLI 的背景策略见 [示例指南](examples.md)。

## 使用范围

目前实际验证环境是 Linux/Konsole。需要完整 alpha 时,可在支持的终端选择 iTerm2 PNG 或 Kitty;
SIXEL 可用于支持它的终端,但 Windows Terminal 的实际显示与刷新尚未验证。
tmux/screen 等复用器的透传、宿主界面重绘和输入管理属于调用方。