ansiq-surface

ansiq-surface 负责把 runtime 的结果落到真实终端里。它主要拥有：

terminal session lifecycle
viewport policy
resize / reanchor planning
scrollback history commit

什么时候会用到它

大多数 app 只需要：


use ansiq_runtime::run_app;

只有当你需要明确控制 viewport 语义时，才会直接碰到 ansiq-surface 的概念，例如：

inline 工作区应该保留多少行
内容增长时要不要继续扩展 viewport
什么时候把内容提交进 scrollback

`ViewportPolicy`

Ansiq 当前有三种策略：


pub enum ViewportPolicy {
    PreserveVisible,
    ReservePreferred(u16),
    ReserveFitContent { min: u16, max: u16 },
}

`PreserveVisible`

语义：

不主动为 app 预留固定工作区
保持当前光标以下仍然可见的终端区域

适合：

很小的 inline 工具
不需要稳定 app shell 的短生命周期 UI

`ReservePreferred(height)`

语义：

尝试保留一个稳定的 live viewport
内容临时变高时可以扩展
history commit / reanchor 后会回到 preferred 高度

适合：

agent 类终端应用
需要稳定 header / body / footer 的 app shell

`ReserveFitContent { min, max }`

语义：

在 min..=max 范围内按内容高度调整
比固定壳层更弹性
比完全自由增长更稳定

适合：

example
小型工具
不想把 viewport 固定成某个高度，但也不希望它无限长大的场景

运行入口


use ansiq_runtime::run_app_with_policy;
use ansiq_surface::ViewportPolicy;
 
#[tokio::main]
async fn main() -> std::io::Result<()> {
    run_app_with_policy(
        MyApp::default(),
        ViewportPolicy::ReservePreferred(12),
    )
    .await
}

history commit 的语义

当 app 调用：


handle.commit_history("completed turn".to_string())?;
handle.commit_history_block(block)?;

surface 会把这些内容提交到 scrollback，而不是继续膨胀 live viewport。

这里有一个重要取舍：

history 文本按提交时的 viewport 宽度 wrap
后续 terminal resize 不会重新 reflow 已提交的历史

这是 inline viewport 模式的固有取舍，应该被当作产品语义，而不是渲染 bug。

ansiq-surface

什么时候会用到它

ViewportPolicy

PreserveVisible

ReservePreferred(height)

ReserveFitContent { min, max }