Internals Overview

Guide teaches you how to use Ansiq, but it deliberately avoids going too deep into a different question:

Why are the boundaries inside Ansiq drawn this way?

That is what the Internals section is for.

Who this section is for

This section is worth reading if:

• you have already written a Ansiq app and want to understand the system below the API
• you want to contribute to runtime, layout, surface, or widgets
• you hit a bug that is not really explained by API docs alone
• you want to judge whether Ansiq is appropriate for a long-running terminal application

If you have not written any Ansiq code yet, the Guide is still the better starting point.

What this section is not

It is not:

• an API reference
• a replacement for rustdoc
• a line-by-line source walkthrough

It is a design explanation.

That means the central questions here are things like:

• why a boundary belongs to runtime rather than widgets
• why the reactive graph and the UI tree must remain separate
• why subtree replacement is not the same thing as a general virtual DOM diff
• why viewport and history are surface semantics rather than app-local tricks

What topics are covered here

Runtime Boundary

Explains:

• what runtime owns
• what runtime intentionally does not own

This is the most important architectural boundary in Ansiq.

If the main question in your head is “how does an app actually start, loop, and exit inside the runtime?”, the next page to read is Runtime Loop.

Reactive Graph vs UI Tree

Explains:

• why reactivity should only decide “what became dirty”
• why runtime should decide “how the screen updates”

If you want to understand why Ansiq is not just “React for terminals”, this page matters.

If your question is more specific — “how does the reactive system itself work, and how does dirty information reach the runtime?” — go directly to Reactive Graph vs UI Tree.

Subtree Replacement

Explains:

• why Ansiq does not currently rely on a full virtual DOM reconciliation model
• why dirty scopes plus subtree replacement were chosen

Continuity Contract

Explains:

• how interaction state survives subtree replacement
• why continuity keys exist

Partial Relayout and Damage Model

Explains:

• why Ansiq avoids full relayout when it can
• why invalidated regions are not just an optimization detail

Terminal Session, Viewport, History, and Scrollback

Explains:

• how Ansiq manages live viewport space inside a real terminal session
• how history is committed into scrollback
• which behaviors are explicit tradeoffs rather than accidents

Suggested reading order

If this is your first pass through Internals, read in this order:

1. Runtime Boundary
2. Reactive Graph vs UI Tree
3. Subtree Replacement
4. Continuity Contract
5. Partial Relayout and Damage Model
6. Terminal Session and Viewport
7. History and Scrollback

If this is your first jump from the Guide into Internals, a better bridge is:

1. Lifecycle and Runtime Loop
2. Reactive System in Depth
3. then come back to the Internals reading order above

How this section relates to the Guide

Guide tells you:

• which API to use
• which example to begin with
• how to write components and signals

Internals tells you:

• what system boundary sits behind those APIs
• why certain behavior belongs in runtime instead of app code
• which parts of the current implementation are already stable and which are still explicit tradeoffs

The two sections are not redundant. They are complementary.