termgrid-core 1.5.5

Deterministic terminal grid state engine with invariant enforcement and backend decoupling.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# Architecture

## Core Components

The system has three primary components:

1. **`Grid`** — canonical state representation.
2. **`Renderer`** — mutation layer that applies `RenderOp` / `Frame`.
3. **`GlyphRegistry` / `RenderProfile`** — authoritative glyph-width policy.

The `Grid` is the source of truth. Backends render from `Grid` state (optionally using `Damage` for incremental redraw).

## Grid

A `Grid` is a 2D matrix of `Cell` values:

- `Cell::Empty`
- `Cell::Glyph { .. }` (a visible cell)
- `Cell::Continuation` (a trailing cell of a wide glyph)

The `Grid` stores resolved layout state. It does not perform terminal emulation semantics.

## Renderer

The `Renderer` applies operations sequentially and deterministically:

- `Renderer::apply_op(&mut Grid, &GlyphRegistry, RenderOp)`
- `Renderer::apply(&mut Grid, &GlyphRegistry, &Frame)`
- `Renderer::apply_with_damage(..)` (returns `Damage`)

The renderer is responsible for:

- Bounds clipping
- Wide-glyph expansion into `Continuation` cells
- Maintaining invariants
- Producing damage regions

## Glyph Width Policy

Glyph width is resolved through `GlyphRegistry` / `RenderProfile`.

Width behavior MUST be deterministic for a given registry/profile configuration.

## Damage Model

Mutations produce `Damage` (a bounded set of rectangles, `Rect`), enabling backends to redraw only affected regions.

Damage is derived from actual state changes, not inferred from backend behavior.

## Backend Decoupling

Backends consume:

- Immutable `Grid` reference
- `Damage` (optional)

Backends MUST NOT reinterpret the grid model (e.g., MUST treat `Continuation` as non-rendering).

### High-Level Interaction Flow

```mermaid
flowchart LR
  U["Application / Producer"] --> R["Renderer"]
  R --> G["Grid State"]
  R --> D["Damage"]

  G --> B["Backend"]
  D --> B

  B --> O["Output Surface<br>(terminal, xterm.js, buffer)"]
```

### Backend Update Sequence

```mermaid
sequenceDiagram
  participant App as Application
  participant Ren as Renderer
  participant Grid as Grid
  participant Reg as GlyphRegistry
  participant Back as Backend

  App->>Ren: apply(op or frame)
  Ren->>Grid: clip + mutate cells
  Ren->>Reg: resolve glyph widths
  Ren->>Ren: compute damage
  Ren-->>App: Damage
  App->>Back: render(Grid, Damage)
  Back->>Back: emit backend-specific updates
```