Concepts

Twelve pages. Each one exists because a decision was made, and the reasoning is recorded — usually in an ADR, always linked. If you only read three, read Renderer and diff, Widgets and focus and Responsiveness: those three explain most of the API surface you will meet.

The rendering path

How a cell gets from your Draw to the screen, and why each hop exists.

1. Renderer and diff — hybrid mode, dirty rectangles, the two-tier diff, frame pacing. ADR 0003
2. Buffers and cells — the 16-byte Cell, Buffer, SubBuffer, Row(y) and why Cells() was removed. ADR 0002, ADR 0006
3. Layout and constraints — Length, Min, Max, Percentage, Ratio, Fill, Solve, and why Fill is order-insensitive. ADR 0004

Input and output

4. Input — Decode, Parser, Source, the event model, why paste is one event, and what is deliberately out of scope. ADR 0005
5. Styling and spans — Style, Span, the wide-glyph rule, and the Draw-must-not-allocate constraint. ADR 0008
6. No theme, and why — the decision that shaped the whole styling surface. ADR 0008
7. Degradation and NO_COLOR — truecolor → 256 → 16, the Lab/CIEDE2000 quantiser decided on measurement, and NO_COLOR as an encode-time concern.

Composition and responsiveness

8. Responsiveness — ClampCount, Budget, Priority, MinSize(), the degenerate-size contract, and why there are no breakpoints. ADR 0007
9. Virtualization — the virtual/ engine behind List, Table and Tree, and what “flat cost” actually means.
10. Widgets and focus — the four-method Widget contract, Focusable, Minimizable, and what Draw may not do. ADR 0003

Quality

11. Accessibility — colour is never the only signal, what the catalog provides, and what it cannot provide.
12. Headless testing — MemorySink, widgettest, golden files, and why a screen reconstructed from an incomplete model makes every assertion against it unsound. ADR 0001

Two things worth knowing before you read any of them

A widget’s space is Bounds(), never buf.Size(). The buffer is the screen; the rect is the widget’s space. This is rule 1 of ADR 0007 §1 and every widget in the catalog obeys it.

Nothing size-derived is built inside Draw. Draw must be allocation-free; buffer.Wrap and buffer.Truncate allocate and are banned from it, so results are cached against the rect and rebuilt on change. And Invalidate() means both “mark dirty” and “drop everything you have cached” — see Responsiveness for why that amendment exists.

Pages in this section

• Renderer and diff Hybrid renderer mode, dirty rectangles, the two-tier diff, and frame pacing.
• Buffers and cells The 16-byte Cell, Buffer, SubBuffer, Row(y) and why Cells() was removed.
• Layout and constraints Length, Min, Max, Percentage, Ratio, Fill, Solve — and why Fill is order-insensitive.
• Input Decode, Parser, Source, the event model, one-event paste, and what is deliberately out of scope.
• Styling and spans One Style value, one Span type, the wide-glyph rule, and why Wrap and Truncate are banned from Draw.
• No theme, and why There is no theme system in v1, on purpose. Here is the trigger that would reverse the decision.
• Responsiveness ClampCount, Budget, Priority, MinSize — the shared arithmetic, the degenerate-size contract, and why there are no breakpoints.
• Virtualization The virtual/ engine behind List, Table and Tree, and what the flat-cost claim actually means.
• Widgets and focus The four-method Widget contract, what Draw may and may not do, Focusable, and Minimizable.
• Accessibility Colour is never the only signal — what the catalog provides, and what it structurally cannot.
• Headless testing MemorySink, widgettest, golden files — and why a screen reconstructed from an incomplete model makes every assertion unsound.
• Degradation and NO_COLOR Truecolor to 256 to 16, the Lab/CIEDE2000 quantiser decided on measurement, NO_COLOR as an encode-time concern, and the ASCII fallback.