Skip to Content
APIansiq-surface

ansiq-surface

ansiq-surface is the layer that turns runtime output into real terminal behavior. It owns:

  • terminal session lifecycle
  • viewport policy
  • resize and reanchor planning
  • scrollback history commit

When you need it

Most apps only need:

use ansiq_runtime::run_app;

You need the ansiq-surface concepts when you want explicit control over viewport behavior, for example:

  • how much inline space should the app reserve?
  • when content grows, should the viewport expand?
  • when should completed content move into scrollback?

ViewportPolicy

Ansiq currently exposes three policies:

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

PreserveVisible

Semantics:

  • do not reserve a stable working area
  • use the terminal area that is already visible below the cursor

Good for:

  • tiny inline tools
  • short-lived UI where a stable app shell is unnecessary

ReservePreferred(height)

Semantics:

  • try to keep a stable live viewport
  • allow temporary growth when content becomes taller
  • reset back to the preferred height after history commit or reanchor

Good for:

  • agent-style terminal apps
  • shells that want a stable header / body / footer structure

ReserveFitContent { min, max }

Semantics:

  • fit the viewport height to content within min..=max
  • more elastic than a fixed shell
  • more stable than fully unbounded growth

Good for:

  • examples
  • small utilities
  • UIs that should adapt a little without growing forever

Running with a policy

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 semantics

When an app calls:

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

the surface layer moves that content into terminal scrollback instead of letting the live viewport grow indefinitely.

One important tradeoff:

  • committed history is wrapped at the viewport width at commit time
  • later terminal resizes do not reflow already committed history

That is a real inline-viewport tradeoff, not a rendering bug.

If you want the conceptual explanation first, continue with:

Last updated on
ansiq-runtimeansiq-widgets