# RTXUI > RTXUI is a C++23 library for terminal user interfaces. A component is a C++ > class whose HTML template and CSS live in a string member; bound members are > interpolated with `{name}`, and the interface updates when they change. Before writing RTXUI code, read "Common Mistakes": RTXUI templates are not Vue or React. `{}` holds a bound name, never an expression; conditions and loops use `if="{name}"` and ``; handlers are `onclick="Method"`; CSS lengths are terminal cells. Run an app with `RTXUI_STRICT=1` to fail on anything RTXUI would silently ignore, and with `RTXUI_HEADLESS=80x24` to print its screen as text. --- # Getting Started This page covers what you need to build RTXUI, how to add it to a CMake project, and how to build the repository itself. ## Requirements - **A C++23 compiler.** C++23 is required to build and use RTXUI. If available, C++26 enables reflection, which avoids having to bind C++ members manually. - **Linux or macOS.** The terminal backend requires POSIX termios and `SIGWINCH`. Windows is not supported (no ConPTY backend); CMake terminates configuration on Windows platforms with an explicit error. RTXUI also targets the browser through Emscripten / WebAssembly. - **CMake 3.24 or newer.** - **Ninja** (optional, faster builds than Make). On Debian or Ubuntu: ```bash sudo apt install cmake ninja-build g++-14 ``` Select the compiler per build rather than changing system defaults — pass it to CMake explicitly: ```bash CC=gcc-14 CXX=g++-14 cmake -B build -G Ninja ``` (For Clang, install it from your distribution or [apt.llvm.org](https://apt.llvm.org) and set `CC=clang CXX=clang++` the same way.) ## Adding RTXUI to your project ### With FetchContent The simplest integration downloads RTXUI at configure time: ```cmake cmake_minimum_required(VERSION 3.24) project(my_app LANGUAGES CXX) set(CMAKE_CXX_STANDARD 23) # Use 26 to enable automatic static reflection. set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) include(FetchContent) FetchContent_Declare( rtxui GIT_REPOSITORY https://github.com/ArthurSonzogni/RTXUI.git GIT_TAG main # Pin a tag or commit for reproducible builds. ) FetchContent_MakeAvailable(rtxui) add_executable(my_app main.cpp) target_link_libraries(my_app PRIVATE rtxui) ``` Link against the **`rtxui`** target, not `rtxui_lib`. Built-in elements register themselves through static initializers, and the `rtxui` target carries the linker flags that keep those initializers from being discarded. Linking `rtxui_lib` directly can produce binaries where tags like ` ``` ### `@` shorthand (`@click`, `@change`) The `@` prefix is equivalent: ```html ``` --- ## 3. Event Modifiers To intercept specific mouse behaviors (like context menu clicks), you can append a modifier suffix: ```html ``` * `@click` or `@click.left`: Main trigger callback. * `@click.right`: Secondary/context menu trigger. --- ## 4. Parameterized Callbacks Callbacks can accept arguments from templates. The arguments are received by the C++ lambda as `std::string` parameters. This is extremely useful for index tracking in loops: ```cpp // Registered in constructor Import("RemoveItem", [this](std::string index_str) { size_t index = std::stoull(index_str); items.erase(items.begin() + index); }); ``` To invoke a parameterized callback in a template, pass a value or an interpolated loop variable in parentheses. Inside a [`` loop](/guide/loops), `{$index}` interpolates to the current item's index: ```html

{todo}

``` --- ## 5. Two-Way Data Binding For interactive input widgets, RTXUI supports automatic two-way data bindings. When a user types text or checks a box, the bound C++ member variable is updated instantly, and programmatically changing the C++ value repaints the input field: * **`` / `

`**: Bind the `value` attribute to a reactive string.
*   **`<checkbox>`**: Bind the `checked` attribute to a reactive boolean.
*   **`<select>`**: Bind the `value` attribute to a reactive string matching the selected option.

```html
<input value="{search_query}" />
<checkbox checked="{is_enabled}">Toggle Features</checkbox>
```

---

## Interactive Demo

Below is the interactive tab view for two-way input field bindings:

Example source: [example/input.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/input.cpp)

---

# Conditional Rendering

Elements can be included or excluded from the interface based on component
state. A condition is a bound name — a `bool` member or a `const` method
returning `bool` — interpolated with `{...}`. An element renders when the
value is `true` (or `1`).

Templates do not evaluate expressions: comparisons such as
`{status == "loading"}` are not supported. Put the comparison in a computed
method and bind that instead:

```cpp
class Profile : public rtxui::Component<Profile> {
 public:
  std::string status = "loading";

bool is_loading() const { return status == "loading"; }
  bool is_error() const { return status == "error"; }

Profile() {
    Bind(status);
    Bind(is_loading);
    Bind(is_error);
  }
  // ...
};
```

## The `<if>` / `<elif>` / `<else>` chain

For block-level branching, wrap the alternatives in consecutive logic tags.
The chain renders the first branch whose condition holds; formatting
whitespace and comments between the tags do not break the chain.

```html
<if condition="{is_loading}">
  <progress value="50" />
</if>
<elif condition="{is_error}">
  <span class="text-error">Failed to fetch profile details.</span>
</elif>
<else>
  <span>Profile loaded.</span>
</else>
```

## The `if` attribute

To toggle a single element without a wrapper tag, put an `if` attribute on
the element itself. When the condition is false the element is not
constructed at all — it has no layout size and receives no events.

```html
<span if="{is_admin}">Delete profile</span>
```

## Choosing between them

- Use the `if` attribute for a single optional element.
- Use `<if>`/`<elif>`/`<else>` when branches are alternatives to each other,
  or when a branch contains several elements.
- To keep an element's space in the layout while hiding it, use CSS
  `visibility: hidden` instead; to remove its space without removing it from
  the DOM, toggle a class that sets `display: none`.

## Demo

Example source: [example/conditional.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/conditional.cpp)

---

# Loops & Lists

The `<for>` tag renders its children once per item of a bound C++ container,
such as a `std::vector`.

## The `<for>` tag

Name the bound collection with `each`, and choose the loop variable's name
with `as`:

```cpp
// Bound in the constructor:
std::vector<std::string> fruits = {"Apple", "Banana", "Cherry"};
Bind(fruits);
```

```html
<ul>
  <for each="{fruits}" as="fruit">
    <li>{fruit} (index: {$index})</li>
  </for>
</ul>
```

Inside the loop body:

- `{fruit}` interpolates the item, converted to a string.
- `{$index}` interpolates the zero-based index. It is most useful for
  passing to a parameterized callback, e.g.
  `<button onclick="RemoveItem({$index})">`
  (see [Event Handlers](/guide/bindings)).

When the collection changes — items added, removed, or mutated — the loop's
rendered children are reconciled on the next digest.

This demo loops over a `std::vector<std::string>`, appending with a bound
`<input>` and removing by `{$index}`:

Example source: [example/loop_simple.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/loop_simple.cpp)

## Keyed loops

By default, collection children reconcile by **position**: the DOM node at index `i` is reused for the `i`-th item. When items reorder or shift, element-local state (keyboard focus, scroll offsets, active CSS transitions) stays locked to the index rather than tracking the item.

Give the loop a `key` to identify items instead:

```html
<for each="{tasks}" as="task" key="{task.id}">
  <div tabindex="0">{task.name}</div>
</for>
```

The key is interpolated per item, exactly like the loop body, so it can be any
expression that names the item — an id field is the usual choice. On the next
digest each item's existing elements are moved to the item's new position and
reused there, carrying their state with them. Focus stays on the task the user
had focused, even if it shifts three rows down.

Keys must be unique within the loop, and stable across frames: keying by
`{$index}` is the same as not keying at all. A loop without `key` keeps the
position matching described above, which stays the cheaper option for a list
that never reorders.

## Collections of structs

A collection of plain values stringifies each item directly. For a collection
of structs, provide a mapper that exposes named fields to the template. The
mapper returns a `ManualStructVisitor` built from a field-name → value map:

```cpp
struct Task {
  std::string name;
  bool completed;
};

std::vector<Task> tasks;

// In the constructor:
Bind(tasks, [](const Task& t) {
  return std::make_shared<ManualStructVisitor>(
      std::map<std::string, std::string, std::less<>>{
          {"name", t.name},
          {"status", t.completed ? "Done" : "Pending"}});
});
```

The template reads the mapped fields with dot notation on the loop variable:

```html
<ul>
  <for each="{tasks}" as="task">
    <li>{task.name} — {task.status}</li>
  </for>
</ul>
```

`BindCollection("name", &collection, mapper)` is equivalent when you want the
template name to differ from the member name.

When compiled with C++26 static reflection (`RTXUI_HAS_REFLECTION`), struct fields are mapped automatically and explicit mappers are not required.

This demo loops over a `std::vector<Task>` through a mapper, toggling each
item's `completed` field from the template:

Example source: [example/loop_complex.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/loop_complex.cpp)

---

# Form Elements

RTXUI provides a set of interactive form elements for building terminal UIs
with user input. Each element supports two-way data binding through the `{}`
syntax — when the user interacts with a form control, the bound C++ variable
updates automatically, and vice versa.

---

## Input (`<input>`)

A single-line text entry field. Bind a `std::string` member to the `value`
attribute for two-way updates. Supports arrow-key navigation (Ctrl to move by
word), deletion (Ctrl to delete words), mouse click positioning, and horizontal
scrolling on overflow.

Text selection works via Shift+arrow keys, double-click (selects a word) and
click-drag, or Ctrl+A (select all). With an active selection, Ctrl+C copies
and Ctrl+X cuts to the system clipboard (via the terminal's OSC 52 escape
sequence, so it works over SSH without a host-side clipboard tool). Pasting
uses the terminal's own paste action: RTXUI enables bracketed paste mode, so
pasted text is inserted as a single update rather than one keystroke per
character.

Set `disabled="true"` (or bind it, e.g. `disabled="{is_disabled}"`) to remove
the field from keyboard/mouse interaction and tab order entirely; it matches
the `:disabled` CSS pseudo-class, which the default style uses to dim it.
Set `readonly="true"` to keep the field focusable, selectable, and copyable
while blocking anything that would change its value (typing, paste,
backspace/delete, cut); it matches `:read-only`.

`placeholder` shows hint text (styled dim by default, via a `.placeholder`
class) whenever `value` is empty, and never touches `value` itself.

Set `type="password"` to visually mask entered characters with asterisks (`*`) while preserving the actual plain-text secret in the bound `value` string.

Its selection/cursor/placeholder spans expose the same
[`::part()`](/guide/css/basics) names as `<textarea>` (see below):
`part="selection"` on the selected-text span, `part="cursor"` (also
`cursor-focused` while focused) on the cursor cell, and `part="placeholder"`
on the placeholder text.

`maxlength` caps how many graphemes `value` can grow to from user input
(typing, pasting, Enter, Tab-indent). A paste that would overflow it is
truncated to fit rather than rejected outright, matching a browser's
maxlength field. It only limits interactive edits — assigning a longer
string to the bound C++ variable directly is unaffected.

Ctrl+Z undoes; Ctrl+Y or Ctrl+Shift+Z redoes. Edits coalesce into a single
undo step while they're contiguous — typing "abc" without moving the
cursor undoes as one step, as do consecutive Backspace/Delete presses —
but moving the cursor, selecting text, pasting, cutting, Enter, or
Tab-indent each start a fresh step (so pasted text always undoes as a
whole, separately from typing before or after it). Undo/redo is blocked
while `readonly` or `disabled`.

```html
<input value="{text}" />
```

```cpp
class MyApp : public Component<MyApp> {
  std::string text = "Hello, RTXUI!";

std::string_view view = R"html(
    <input value="{text}" />
  )html";

MyApp() { Bind(text); }
};
```

Example source: [example/input.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/input.cpp)

---

## Textarea (`<textarea>`)

A multi-line scrollable text editor. Bind a `std::string` to `value`. Supports
arrow-key navigation, Enter for newlines, Home/End for line boundaries, and
Ctrl+Backspace/Delete for word deletion. Enter carries over the current
line's leading indentation onto the new line; Tab/Shift-Tab indent and
unindent the current line. A vertical scrollbar (`scrollbar-width: auto` by
default, same as any other scrollable element) shows the scroll position;
set `scrollbar-width: none` on it to hide it, as `<input>` does for its
own horizontal scrollbar.

Selection, copy/cut, paste, `disabled`, `readonly`, `placeholder`,
`maxlength`, and undo/redo all work the same way as `<input>` (see above;
a multi-line placeholder string renders across multiple lines, same as
`value`; `maxlength` also blocks Enter/Tab-indent once there's no room
left; Enter and Tab-indent each undo as their own step, never merged with
surrounding typing). A newline pasted into a
single-line `<input>` is dropped; pasting into a `<textarea>` inserts the
newlines as-is without
triggering the auto-indent that a manually-typed Enter gets. Under
`readonly`, Enter and Tab/Shift-Tab (which would otherwise insert a newline
or indent) are no-ops too.

Set `linenumbers` to `true` (or `absolute`) to show a line-number gutter, or
to `relative` for vim-style relative numbers (the active line shows its
absolute number; every other line shows its distance from it). `line_start`
offsets the displayed numbers (e.g. `41` to show the field as an excerpt
starting at line 41 of a larger file); `line_end` blanks the gutter past a
given displayed number (unbounded by default). `line_wrap="subline"` gives
word-wrapped continuation rows their own blank gutter entry instead of
letting the logical-line numbering drift out of alignment with them; this
is a wrap-count estimate, not an exact one.

Set `highlight_current_line="true"` for a full-width background band behind
the line the cursor is on, independently of `linenumbers` (works with or
without a gutter).

Several internal elements expose [`::part()`](/guide/css/basics) names so an
app can theme them: `part="gutter"` on the gutter container, `part="line-number"`
on every row (also `active` on the active line's row, and `wrapped` on a
subline continuation row), `part="line"` on every `highlight_current_line`
row (also `current-line` on the active one), and — regardless of
`linenumbers`/`highlight_current_line` — `part="selection"` on the
selected-text span, `part="cursor"` (also `cursor-focused` while focused) on
the cursor cell, and `part="placeholder"` on the placeholder text.

```html
<textarea value="{text}" />
<textarea value="{text}" linenumbers="true" />
<textarea value="{text}" linenumbers="true" highlight_current_line="true" />
```

```css
textarea::part(gutter)       { color: rgb(100, 116, 139); }
textarea::part(active)       { color: rgb(129, 140, 248); }
textarea::part(current-line) { background-color: rgb(49, 55, 79); }
textarea::part(selection)    { background-color: rgb(67, 56, 202); }
textarea::part(placeholder)  { color: rgb(100, 116, 139); }
```

```cpp
class MyApp : public Component<MyApp> {
  std::string text = "Line one\nLine two\n";

std::string_view view = R"html(
    <textarea value="{text}" />
  )html";

MyApp() { Bind(text); }
};
```

Example source: [example/textarea.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/textarea.cpp)

---

## Checkbox (`<checkbox>`)

A boolean toggle. Bind a `bool` member to the `checked` attribute. Click or
press Space when focused to toggle. The element's text content becomes the
label.

The checkmark glyph exposes [`part="checkmark"`](/guide/css/basics) so an
app can theme it: `checkbox::part(checkmark) { color: ...; }`.

```html
<checkbox checked="{enabled}">Enable Notifications</checkbox>
```

```cpp
class MyApp : public Component<MyApp> {
  bool enabled = false;

std::string_view view = R"html(
    <checkbox checked="{enabled}">Enable Notifications</checkbox>
  )html";

MyApp() { Bind(enabled); }
};
```

Example source: [example/checkbox.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/checkbox.cpp)

---

## Radio Button (`<radio>`)

A mutually exclusive selection toggle within a named group. Radio buttons sharing the same `name` attribute coordinate automatically — selecting one unchecks the others in the same group. Bind a `bool` member to `checked` to observe or control the state.

```html
<radio name="theme" checked="{dark_mode}">Dark Theme</radio>
<radio name="theme" checked="{light_mode}">Light Theme</radio>
```

```cpp
class MyApp : public Component<MyApp> {
  bool dark_mode = true;
  bool light_mode = false;

std::string_view view = R"html(
    <radio name="theme" checked="{dark_mode}">Dark Theme</radio>
    <radio name="theme" checked="{light_mode}">Light Theme</radio>
  )html";

MyApp() {
    Bind(dark_mode);
    Bind(light_mode);
  }
};
```

Exposes [`part="radio-circle"`](/guide/css/basics) on the radio indicator circle glyph for scoped CSS styling.

Example source: [example/radio.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/radio.cpp)

---

## Slider (`<slider>`)

A range slider control. Bind an `int` to `value` and configure the range with
`min`, `max`, `step`, and `width` attributes. Drag the thumb with the mouse
or use Arrow Keys when focused.

```html
<slider value="{volume}" min="0" max="100" step="5" width="30" />
```

```cpp
class MyApp : public Component<MyApp> {
  int volume = 50;

std::string_view view = R"html(
    <slider value="{volume}" min="0" max="100" step="5" width="30" />
    <span>{volume}%</span>
  )html";

MyApp() { Bind(volume); }
};
```

| Attribute | Type  | Description                          |
|-----------|-------|--------------------------------------|
| `value`   | `int` | Current value (two-way bound)        |
| `min`     | `int` | Minimum value (default `0`)          |
| `max`     | `int` | Maximum value (default `100`)        |
| `step`    | `int` | Increment per step (default `1`)     |
| `width`   | `int` | Display width in terminal columns    |

Exposes [`part="slider-container"`](/guide/css/basics) on the outer track
wrapper, and `part="track-left"`/`part="thumb"`/`part="track-right"` on the
three segments either side of and including the thumb.

Example source: [example/slider.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/slider.cpp)

---

## Progress Bar (`<progress>`)

A non-interactive progress indicator. Bind an `int` to `value` and set the
`max` attribute to define the range. Use `width` to control the bar length.

```html
<progress value="{progress_val}" max="100" width="30" />
```

```cpp
class MyApp : public Component<MyApp> {
  int progress_val = 45;

std::string_view view = R"html(
    <progress value="{progress_val}" max="100" width="30" />
    <span>{progress_val}%</span>
  )html";

MyApp() { Bind(progress_val); }
};
```

| Attribute | Type  | Description                          |
|-----------|-------|--------------------------------------|
| `value`   | `int` | Current progress value (bound)       |
| `max`     | `int` | Maximum value (default `100`)        |
| `width`   | `int` | Display width in terminal columns    |

Exposes [`part="filled"`](/guide/css/basics) and `part="empty"` on the two
track segments, e.g. `progress::part(filled) { color: ...; }`.

Example source: [example/progress.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/progress.cpp)

---

## Select / Dropdown (`<select>`)

A dropdown picker menu. Bind a `std::string` to `value`. Children are
`<option>` elements whose `value` attributes determine the bound string.
Click to open, or focus with Tab and use Enter/Space. Navigate options with
ArrowUp/ArrowDown and confirm with Enter.

```html
<select value="{my_theme}">
  <option value="dark">Dark Theme</option>
  <option value="light">Light Theme</option>
  <option value="solarized">Solarized</option>
</select>
```

```cpp
class MyApp : public Component<MyApp> {
  std::string my_theme = "light";

std::string_view view = R"html(
    <select value="{my_theme}">
      <option value="dark">Dark Theme</option>
      <option value="light">Light Theme</option>
      <option value="solarized">Solarized</option>
    </select>
  )html";

MyApp() { Bind(my_theme); }
};
```

Exposes [`part="select-btn"`](/guide/css/basics) on the closed button,
`part="select-label"`/`part="select-arrow"` on its two children, and
`part="dropdown-list"` on the open dropdown panel.

Example source: [example/select.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/select.cpp)

---

## Label (`<label>`)

A helper element that delegates mouse click events and focus to an associated interactive element (like a checkbox or text input).
It can associate either explicitly via the `for` attribute (matching the target element's `id`), or implicitly by nesting the target element inside the `<label>`.

### Explicit Association (via `for` attribute)
```html
<label for="my-checkbox">Notification Settings</label>
<checkbox id="my-checkbox" checked="{enabled}">Enable Alerts</checkbox>
```

### Implicit Association (via Nesting)
```html
<label>
  Accept Terms
  <checkbox checked="{accepted}">Accept</checkbox>
</label>
```

Example source: [example/label.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/label.cpp)

---

# Keyboard Focus & Navigation

RTXUI applications are fully keyboard-operable out of the box. This page
describes what users can do with the keyboard, and how to control which
elements participate.

## Built-in keys

Component `OnEvent` overrides see events before these built-in behaviors, so
custom key handling always wins.

## Focus Control

To make any layout container (like a custom card or wrapper `<div>`) interactive and focusable, use these properties:

### `tabindex`
Determines where the element fits in the sequential keyboard **Tab** navigation loop:
*   `tabindex="0"`: The element is sequentially focusable (standard behavior).
*   `tabindex="-1"`: The element is focusable programmatically or via mouse clicks, but skipped when hitting Tab/Shift-Tab.
*   `tabindex="1"` (or higher): Establishes custom sequential traversal order (lower positive values focus first).

```html

<div tabindex="1">First focusable zone</div>
<div tabindex="2">Second focusable zone</div>
```

### `focusable` Shorthand
Set `focusable="true"` as a clean shorthand for setting `tabindex="0"`:
```html
<div focusable="true" class="button">
  Interactive Box
</div>
```
Focusable items automatically capture keyboard events (`ArrowLeft`, `Enter`, etc.) and focus CSS pseudoclasses like `:focus`.

## Live Demo

Example source: [example/tabindex.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/tabindex.cpp)

## Spatial Navigation

In addition to sequential tab navigation (using Tab/Shift-Tab), RTXUI supports **Spatial Navigation**. By pressing the **Arrow keys** (or **hjkl** keys), RTXUI performs a geometric search in 2D screen space to find the closest focusable element in that direction and moves focus there. This provides a natural, game-like, or TV-like focus navigation experience for complex layouts.

### Live Demo - Spatial Navigation

Example source: [example/spatial_navigation.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/spatial_navigation.cpp)

---

# CSS Basics & Selectors

Each component carries its styles next to its markup, and those styles apply
only to that component's own template — class names cannot collide across
components. This page covers where styles live, which selectors match, and
how values work in a terminal.

## Declaring Styles

Styles are written using standard CSS rulesets inside a `<style>` block in your component's template string:

```html
<div>
  <span class="header">App Title</span>
</div>

A component may declare more than one `<style>` block. They are concatenated in
the order they appear, so a later block can override an earlier one exactly as
two rulesets in a single block would — when neither selector is more specific,
the one written later wins.

## Supported Selectors

The CSS parser supports a wide range of standard selectors and combinators:
*   **Tag Selectors**: Targets specific tags (e.g., `div { margin: 1; }`).
*   **Class Selectors**: Targets class names (e.g., `.card { padding: 1; }`).
*   **ID Selectors**: Targets unique identifiers (e.g., `#submit-btn { background-color: green; }`).
*   **Compound Selectors**: Combine tags, classes, and IDs simultaneously (e.g., `div.card#active { border-color: red; }`).
*   **Pseudo-classes**: Targets interactive states (`:hover`, `:focus`, `:active`,
    `:disabled`, `:checked`, `:read-only`) and scrollbars.
*   **Structural Pseudo-classes**:
    *   `:first-child`: Matches the first element among its siblings.
    *   `:last-child`: Matches the last element among its siblings.
    *   `:nth-child(even)`/`:nth-child(odd)`: Matches even or odd siblings.
    *   `:nth-child(N)`: Matches the 1-based N-th sibling (e.g., `:nth-child(3)`).
    *   `:nth-child(An+B)`: Matches sibling `A x k + B` for every whole `k >= 0`
        — `3n` is every third sibling, `2n+1` the odd ones, `n+3` everything
        from the third on, and `-n+2` the first two. Whitespace is allowed
        around the parts and the `n` is case-insensitive, so `2N + 1` parses.
    *   `:nth-last-child(...)`: The same arguments, counted from the last sibling backwards.
    *   `:only-child`: Matches an element that is its parent's only child.
    *   `:empty`: Matches an element with no content between its tags.
    *   `:first-of-type` / `:last-of-type` / `:only-of-type` / `:nth-of-type(...)` / `:nth-last-of-type(...)`: The same as the `-child` family, but counting only siblings with the same tag.
    *   `:not(<selector-list>)`: Matches an element that none of the listed selectors do, e.g. `:not(.a, .b)`. Each entry is one compound selector — a tag, `.class`, `#id`, `[attribute]`, a pseudo-class, or a combination such as `:not(div.card)` or `:not(.item:first-child)`. Every part of an entry must match for that entry to exclude an element, so `:not(.x:first-child)` still matches a `.x` that is not first. Combinators inside the negation (`:not(div span)`) are not supported and match nothing, as do an empty `:not()` and a list with a stray or trailing comma. `:not()` may nest, up to 32 levels; deeper than that matches nothing.

`<style>` blocks and text do not count as siblings, so they never displace a
    `:first-child` nor stop an element being an `:only-child`. An `An+B` offset must
    carry its own sign, so `2n3` is not `2n+3`; it matches nothing, as does
    any other argument that is not one of the forms above.

A pseudo-class outside the list above matches nothing, and one bad token
    disqualifies the whole selector: a misspelled `span:hovr` styles no span
    rather than every span. Rules that quietly stop applying are easier to
    spot than rules that quietly apply everywhere.

`:empty` departs from CSS in one way: CSS counts any text node as content,
    which would mean nothing is ever empty in a template where tags sit
    indented on their own lines. Whitespace-only text is ignored here, so
    `<div></div>` and a `<div>` spanning two lines with nothing between them
    both match.
*   **Combinators**:
    *   **Descendant combinator (space)**: Matches nested elements (e.g., `div span` targets any `span` inside a `div`).
    *   **Child combinator (`>`)**: Matches direct children (e.g., `div > span` targets `span` elements immediately nested under `div`).
    *   **Adjacent Sibling combinator (`+`)**: Matches immediate following sibling (e.g., `div + p` targets a `p` that is placed right after a `div`).
    *   **General Sibling combinator (`~`)**: Matches any following sibling (e.g., `div ~ p` targets any `p` that shares the same parent and follows a `div`).

### The Special `self` Selector
To target the component's root outer boundary tag itself (rather than one of its child elements), use the `self` selector keyword:

```css
self {
  display: block;
  border: round;
  border-color: yellow;
}
```
This is essential for wrapping custom components in custom borders or configuring their layout growth constraints in flex containers.

### Styling a Nested Component's Internals: `::part()`

The opening line of this page said styles apply "only to that component's
own template" — that's true even for a component you instantiate yourself.
`<textarea linenumbers="true">`'s line-number gutter is built out of `<div>`s
inside `textarea`'s own template; a `.gutter { color: ... }` rule in *your*
component's stylesheet simply never reaches them, no matter how directly you
wrote the `<textarea>` tag.

A component opts specific internal elements into being styled from outside
by marking them with a `part` attribute (space-separated for more than one,
like `class`):

```html

<div class="row" part="gutter active">...</div>
```

An outside component then targets that name with `::part(name)`, following
whatever selector matches the *instantiation site* (tag, class, id — not the
part element itself):

```css
textarea::part(gutter) { color: rgb(100, 116, 139); }
.editor::part(active)  { color: rgb(129, 140, 248); }
```

This reaches through as many layers of nesting as it takes to get there —
internal markup inside the component, and even further component
boundaries in between. If `<Foo>`'s own template instantiates `<Bar
part="baz">`, an app that only ever writes `<Foo class="thing">` can still
reach `baz` directly with `.thing::part(baz)`, with no need for `Foo` to
forward or re-expose it itself (there's no `exportparts`-style ceremony
here, unlike standard CSS shadow DOM).

Built-in components that expose parts document them alongside their other
attributes — see the [`<textarea>`](/guide/forms) guide for the
line-number gutter and current-line highlight parts.

## The Cascade

When more than one rule sets the same property on an element, the winner is the
one with the highest **specificity** — the same rule CSS uses. Specificity
counts three things across the whole selector, ancestors included:

A single id outranks any number of classes, and a single class outranks any
number of element names:

```css
#panel      { color: red; }   /* wins */
.a.b.c      { color: blue; }
section div { color: green; }
```

Because the count runs over the entire selector, rules that look similar still
rank correctly:

```css
.a.b        { color: red; }   /* wins over .a  — two classes beat one */
div.a       { color: red; }   /* wins over .a  — same classes, one more type */
.wrap .a    { color: red; }   /* wins over .a  — same classes, plus an ancestor */
```

`*` contributes nothing, and `self` selects the component's own root rather
than an element name, so neither adds weight.

Between two rules of **equal** specificity, the later one wins:

```css
.a { color: red; }
.b { color: blue; }   /* an element with class="a b" is blue */
```

The `style` attribute is applied after every selector, so it always wins, and
`!important` overrides even that — see [`!important`](#important) below.

## Inline Styles

The `style` attribute applies declarations to a single element, taking
precedence over rules from `<style>` blocks:

```html
<div style="padding: 1; color: red;">Highlighted</div>
```

## Values in a Terminal

Lengths are measured in **character cells** — `padding: 1` is one cell, and
because cells are roughly twice as tall as they are wide, one vertical cell
looks about as large as two horizontal ones. Percentages resolve against the
parent, and lengths accept arithmetic:

```css
.sidebar { width: 25%; }
.content { width: calc(100% - 20); }
.panel   { width: min(100%, 60); height: clamp(5, 50%, 20); }
```

## Custom Properties

Variables declared with `--name` inherit down the tree and are read with
`var(--name)` or `var(--name, fallback)` — the usual way to define a theme
in one place:

```css
self { --accent: rgb(59, 130, 246); }
.card { border-color: var(--accent); }
.card-title { color: var(--accent); }
```

## `!important`

Appending `!important` to a declaration makes it win over normal
declarations from later rules and over inline styles, as in standard CSS.
Reach for it rarely; more specific selectors usually express intent better.

::: warning Architectural detail
An `!important` declaration does not survive a matching pseudo-class rule on the same element: given

```css
.row       { color: green !important; }
.row:focus { color: blue; }
```

a focused `.row` renders blue, where CSS would keep it green. Interactive
state is resolved in a second pass layered on top of the resting style, and
that pass applies its normal declarations after the first pass has already
applied its important ones. Avoid combining `!important` with pseudo-class
rules for the same property.
:::

## `inherit`, `initial` and `unset`

Any property accepts the CSS-wide keywords `inherit`, `initial` and `unset`
(and `revert`, treated like `unset`). When one of them wins the cascade for a
property, every declaration of that property on the element is dropped, so
the property keeps the value it starts from: inherited from the parent for
inherited properties such as `color`, the initial value for the others such
as `width` or `padding-left`.

```css
.card       { color: #3b82f6; width: 30; }
.card.plain { color: inherit; width: initial; }  /* parent's color, auto width */
```

That is exactly `unset`. `inherit` and `initial` match it in the common
cases, with two differences from browser CSS: `initial` on an inherited
property still inherits, and `inherit` on a non-inherited property gives the
initial value rather than the parent's. A keyword on a longhand does not
undo a shorthand (`margin: 1; margin-top: initial` keeps the top margin).

The [CSS property reference](/css_reference) lists every supported property
with its accepted values.

---

# Box Model & Dimensions

RTXUI elements behave as standard CSS boxes, though spacing measurements represent terminal character cells instead of pixels.

## Margin & Padding

Spacing properties accept positive integer values representing the number of character columns (for horizontal spacing) or character rows (for vertical spacing):

*   **Shorthand Syntax**:
    *   `padding: 1`: Spacing of 1 cell on all sides (top, right, bottom, left).
    *   `padding: 1 2`: Spacing of 1 vertical cell (top/bottom) and 2 horizontal cells (left/right).
*   **Specific Properties**:
    *   `margin-top`, `margin-bottom`, `margin-left`, `margin-right`
    *   `padding-top`, `padding-bottom`, `padding-left`, `padding-right`

```css
.card {
  margin: 1 2; /* 1 row margin top/bottom, 2 columns left/right */
  padding: 1;   /* 1 cell padding internally on all sides */
}
```

---

## Differences from CSS

Two box-model behaviours differ from a browser and are worth knowing before
you port a stylesheet:

**Vertical margins do not collapse.** In CSS, a `margin-bottom: 1` above a
`margin-top: 1` collapse into a single cell of space. Here they add up to two.
Set the margin on one side only when you want a predictable gap, or use `gap`
on a flex container:

```css
.a { margin-bottom: 1; }
.b { margin-top: 1; }   /* two blank rows between them, not one */
```

**Auto margins centre inside a parent, not at the component root.**
`margin: 0 auto` (and the `margin-left`/`margin-right` longhands) centre a
fixed-width block within its containing block, and a single `auto` pushes the
block to the opposite edge. A block that is the component's own root element
has no containing block to centre within, so wrap it:

```html
<div><div class="card">centred</div></div>
```

```css
.card { width: 40; margin: 0 auto; }
```

For centring a whole screen, `display: flex` with `justify-content: center` on
the root is usually clearer than auto margins.

## Dimension Units

Sizing attributes `width` and `height` accept two types of length units:

1.  **Integer Cell Counts**: A raw number indicates character cell counts.
    ```css
    .sidebar { width: 20; } /* Exactly 20 columns wide */
    ```
2.  **Percentage Boundaries**: Appending a `%` dynamically resolves the dimension relative to the parent box.
    ```css
    .half-pane { width: 50%; } /* Fills half the parent width */
    ```

Both forms combine in `calc()` and are bounded by `min()`, `max()`, and
`clamp()` — see [values in a terminal](/guide/css/basics#values-in-a-terminal).
`min-width`/`max-width` and `min-height`/`max-height` constrain the resolved
size.

## box-sizing

`width` and `height` describe the border box (border + padding + content) by
default — unlike web CSS, whose initial value is `content-box`. A box styled
`width: 10; padding-left: 2; border: solid;` is exactly 10 cells wide; the
content area shrinks to fit inside the padding and border.

```css
.card { width: 10; padding: 1; border: solid; } /* 10 cells wide total */
```

Set `box-sizing: content-box` to make `width`/`height` (and their `min-`/`max-`
variants, and `flex-basis`) describe the content area instead, with padding
and border added on top — the familiar web-CSS behavior:

```css
.card {
  box-sizing: content-box;
  width: 10;    /* 10 cells of content ... */
  padding: 1;   /* ... plus 1 cell of padding each side ... */
  border: solid; /* ... plus a 1-cell border each side: 14 cells total. */
}
```

## Aspect Ratio

`aspect-ratio: <width> / <height>` derives a block element's automatic
height from its used width. Ratios are measured in cells; since terminal
cells are roughly twice as tall as they are wide, `2 / 1` produces a
visually square box:

```css
.tile { width: 30%; aspect-ratio: 2 / 1; }
```

An explicit `height`, or `min-`/`max-height`, takes precedence. Content
taller than the ratio overflows — combine with `overflow` when clipping is
wanted.

## Live Demo - Borders

Example source: [example/borders.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/borders.cpp)

## Live Demo - Borders & Scrollbars Interaction

To see how all the different border styles behave interactively and how they coordinate with scrollbars when content overflows, check out the following interactive demo.

Example source: [example/border_scroll_demo.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/border_scroll_demo.cpp)

---

# Flexbox Layouts

To design structured terminal views that adapt dynamically to varying viewport sizes, use the **Flexbox** positioning engine.

## Activating Flex Layout

To lay out children inside a container using flex rules, set the display property of the parent to `flex`:

```css
.row-container {
  display: flex;
  flex-direction: row; /* Layout items side-by-side */
}
```

## Alignment Properties

*   **`flex-direction`**: Defines the main axis formatting flow:
    *   `row` (default): Stacks child elements horizontally from left to right.
    *   `column`: Stacks child elements vertically from top to bottom.
*   **`flex-grow`**: Factors how much free space the element claims along the main axis:
    *   `flex-grow: 1`: Expands the element to fill all available leftover cells.
*   **`flex-shrink`**: Factors how much the element shrinks when space is constrained:
    *   `flex-shrink: 0`: Prevents the element from shrinking below its default content boundaries.

```css
.sidebar {
  width: 25;
  flex-shrink: 0; /* Keeps sidebar width exactly 25 cells */
}
.main-content {
  flex-grow: 1; /* Claims remaining terminal width */
}
```
## Live Demo

A row of boxes laid out with `justify-content` and `align-items`:

Example source: [example/layout.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/layout.cpp)

## Live Demo - Interactive Flex Playground

The same properties, driven from the UI. Change `flex-direction`,
`justify-content`, `align-items` and the per-item `flex-grow`/`flex-shrink`
/`flex-basis`, and watch the boxes redistribute:

Example source: [example/layout_flex.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/layout_flex.cpp)

---

# Grid

`display: grid` lays children out on a two-dimensional track grid — the
right tool when rows and columns must stay aligned with each other, which
flexbox cannot guarantee. Dashboards, key/value panes, and button pads are
typical uses.

## Defining tracks

Column and row tracks are lists of sizes:

```css
.board {
  display: grid;
  grid-template-columns: 10 1fr 2fr;
  grid-template-rows: repeat(3, 1fr);
  gap: 1;
}
```

Track sizes accept:

- **Cells** — `10` is ten characters wide.
- **Percentages** — resolved against the container.
- **Fractions** — `1fr`, `2fr`: after fixed tracks are placed, remaining
  space is divided proportionally.
- **`repeat(count, size)`** — shorthand for repeated tracks.
- **`calc()` expressions** — e.g. `calc(50% - 5)`.

`grid-template` combines both axes as `rows / columns`:

```css
grid-template: 1fr 1fr / 10 1fr 10;
```

`gap` (one value, or `row-gap column-gap` as two) inserts space between
tracks without adding outer margins.

## Placing and spanning items

Children fill the grid in source order, left to right, top to bottom. An
item can cover several tracks:

```css
.header  { grid-column: span 2; }
.sidebar { grid-row: span 3; }
```

## Aligning items in their cells

By default items stretch to fill their cell. `justify-items` (inline axis)
and `align-items` (block axis) on the container change that for all items;
`justify-self` / `align-self` override per item, and an explicit
width/height opts an item out of stretching:

```css
.board { justify-items: center; align-items: start; }
.badge { justify-self: end; }
```

`place-items` and `place-self` set both axes at once
(`place-items: center center`).

## Demo

Fraction tracks, spanning, and gaps together:

Example source: [example/grid.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/grid.cpp)

---

# Positioning & Layers

By default, RTXUI components arrange elements within the standard flexbox layout flow. For overlay blocks, modals, status bars, or layered widgets, you can use absolute coordinates and z-index ordering.

---

## 1. Positioning Modes (`position`)

RTXUI supports element positioning contexts:

1.  **`static`** (Default): The element renders in order within the normal flex layout flow.
2.  **`relative`**: The element remains in the normal flow but establishes a reference origin point for any descendant child elements set to `position: absolute`.
3.  **`absolute`**: The element is removed from the normal flow. It is positioned relative to its closest parent ancestor that has `position: relative` (or the root screen boundary if no ancestor is relative).
4.  **`fixed`**: The element is removed from the normal flow and positioned relative to the outermost terminal screen viewport.
5.  **`sticky`**: The element is positioned based on the user's scroll position. It behaves like `relative` until the viewport scrolls past a given offset (such as `top: 0`), at which point it "sticks" to that position, similar to `fixed`.

---

## 2. Offset Coordinates

For elements configured with `position: absolute`, `position: fixed`, or `position: sticky`, use these properties to set the spacing offsets from the container margins (measured in character cells):

*   `left`: Spacing from the container's left edge.
*   `right`: Spacing from the container's right edge.
*   `top`: Spacing from the container's top edge.
*   `bottom`: Spacing from the container's bottom edge.

A sticky element honours all four offsets. `top`/`left` pin it as it scrolls
up or left out of view; `bottom`/`right` pin it while it is still below or to
the right of the viewport, which is how a footer stays visible until the
content it belongs to scrolls past. When both edges of one axis are set, the
leading edge (`top`, `left`) wins.

```html
<div class="modal-box">Centered Overlay</div>

---

## 3. Layer Ordering (`z-index`)

To manage depth when multiple absolute or fixed elements overlap, assign the drawing layers using `z-index`:

*   Elements with a **higher `z-index`** are drawn on top of elements with lower values.
*   Default `z-index` value is `0` (where overlap order falls back to template declaration order).

```html
<div class="background-pane">Behind (z-index = 1)</div>
<div class="foreground-pane">In Front (z-index = 10)</div>

---

## Interactive Demo

Below is the interactive tab view for layout layering:

Example source: [example/positioning.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/positioning.cpp)

---

## Sticky Positioning Demo

The interactive demo below showcases `position: sticky` inside a scrollable container. Notice how category headers stay pinned at the top until they are pushed out of the way by the next category.

Example source: [example/sticky.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/sticky.cpp)

---

# Typography & Text Styling

RTXUI supports rich text styling including colors, alignment, decorations,
bold/strong emphasis, and opacity. These are applied via CSS properties in
`<style>` blocks, just like in the web.

---

## Colors

RTXUI supports multiple color formats for `color` and `background-color`
properties:

| Format | Example |
|---|---|
| Named keywords | `red`, `navy`, `silver`, `fuchsia`, … |
| Hex (short) | `#f0f`, `#0ff` |
| Hex (full) | `#ff3366`, `#151520` |
| Hex with alpha | `#00ffcc88`, `#ff000080` |
| `rgb()` | `rgb(255, 0, 128)` |
| `rgba()` | `rgba(255, 0, 0, 0.5)` |

The 16 standard CSS color keywords are supported (`black`, `white`, `red`,
`green`, `blue`, `yellow`, `aqua`, `fuchsia`, `gray`, `silver`, `maroon`,
`olive`, `navy`, `purple`, `teal`, `lime`).

Example source: [example/colors.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/colors.cpp)

---

## Weight and Style

Terminals render four text intensities and an italic face; RTXUI maps the
standard CSS properties onto them:

```css
font-weight: bold;      /* bold — also: bolder, or numbers >= 600 */
font-weight: lighter;   /* dim  — also: numbers <= 300 */
font-weight: normal;
font-style: italic;     /* also: oblique */
```

The semantic inline tags apply these for you: `<b>`/`<strong>` for bold,
`<i>`/`<em>` for italic, `<u>` for underline, `<s>`/`<del>` for
strikethrough.

---

## Case Transformation

`text-transform` changes the rendered case without touching the underlying
text. It is inherited.

```css
text-transform: uppercase;   /* MENU */
text-transform: lowercase;   /* menu */
text-transform: capitalize;  /* Menu Item */
```

ASCII letters are transformed; other characters pass through unchanged.

---

## Spacing

`letter-spacing` inserts blank cells between characters, and `line-height`
sets how many rows each line occupies. Both take whole numbers of cells and
are inherited:

```css
h1 { letter-spacing: 1; }   /* H E A D I N G */
p  { line-height: 2; }      /* one blank row between lines */
```

The cells added by `letter-spacing` are non-breaking: a spaced word never
wraps in the middle, while the gaps between words stay breakable.
`line-height` is a minimum — a taller inline element still grows its line.

---

## Text Alignment

Use `text-align` to control horizontal text placement within a block element:

```css
text-align: left;    /* Default */
text-align: center;
text-align: right;
text-align: justify;
```

`justify` widens the spaces of soft-wrapped lines so each fills the content
width; the last line, and lines ended by an explicit newline, keep their
natural width. The alignment is inherited by child elements.

Example source: [example/text_align.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/text_align.cpp)

---

## Text Decoration

Use `text-decoration` to add visual emphasis to text. Multiple decorations can
be combined by separating them with spaces.

| Value | Effect |
|---|---|
| `underline` | Single underline |
| `double-underline` | Double underline |
| `line-through` / `strikethrough` | Horizontal line through text |
| `blink` | Blinking text (terminal support varies) |
| `none` | Remove decorations |

Combine multiple decorations:

```css
text-decoration: double-underline strikethrough;
```

Example source: [example/text_decoration.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/text_decoration.cpp)

---

## Whitespace and Wrapping

`white-space` controls how newlines and wrapping behave inside an element:

| Value | Newlines | Wrapping |
|---|---|---|
| `normal` (default) | Rendered as spaces | Wraps at spaces |
| `nowrap` | Rendered as spaces | Never wraps |
| `pre` | Hard line breaks | Never wraps |
| `pre-wrap` | Hard line breaks | Wraps at spaces |
| `pre-line` | Hard line breaks; space runs collapse to one | Wraps at spaces |

The `<pre>` element sets `white-space: pre` for you; `<textarea>` uses
`pre-wrap`. For text that must not wrap, pair `nowrap` with
`text-overflow: ellipsis` to truncate with `...` instead of overflowing. Three
periods rather than `…`, because they are one cell each and every terminal has
them; in a container too narrow for the text plus the marker, as many periods
are shown as fit. Truncation lands on a character boundary, so a double-width
glyph is dropped whole rather than halved:

```css
.crumb {
  white-space: nowrap;
  text-overflow: ellipsis;
}
```

Words longer than the line break at the container edge by default
(`overflow-wrap: anywhere` — note this differs from CSS, whose default lets
long words overflow). Set `overflow-wrap: normal` to keep such words intact
and let them overflow instead:

```css
.url { overflow-wrap: normal; }
```

---

## Opacity

The `opacity` property controls the transparency of an element and all its
children. Values range from `0.0` (fully transparent) to `1.0` (fully opaque).

```css
opacity: 0.5;
```

Opacity is multiplicative: a child with `opacity: 0.5` inside a parent with
`opacity: 0.5` will render at 25% opacity. Opacity can also be animated using
CSS transitions.

Example source: [example/opacity.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/opacity.cpp)

---

# Scrolling Containers

When layouts contain lists or large blocks of content, they can overflow. RTXUI supports full horizontal and vertical scrolling with visual scrollbars.

### Enabling Scroll

By adding `overflow-y: scroll` (or `overflow-x: scroll`) and restricting the dimensions (`height` or `width`), RTXUI automatically crops overflowing elements and displays a modern, responsive scrollbar.

```cpp
class ScrollBox : public Component<ScrollBox> {
 public:
  std::string_view view = R"html(
      <div class="scroll-container">
        <div>Item 1</div>
        <div>Item 2</div>
        <div>Item 3</div>
        
      </div>
      <style>
        .scroll-container {
          display: block;
          height: 5;
          overflow-y: scroll;
          scrollbar-width: auto;
          border: wide;
          border-color: rgb(29, 78, 216);
        }
      </style>
    )html";
};
```

### Event Bubbling

Scroll events automatically bubble up to nested containers when boundaries are reached, allowing for natural feeling nested scroll areas.

Example source: [example/nested_scroll.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/nested_scroll.cpp)

### Scroll-Into-View on Keyboard Focus

RTXUI automatically scrolls containers to keep focused elements visible when users navigate using the keyboard (`Tab` and `Shift+Tab`).

Example source: [example/focus_scroll.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/focus_scroll.cpp)

### Horizontal Scrolling

Example source: [example/horizontal_scroll.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/horizontal_scroll.cpp)

### Scroll Behavior

Example source: [example/scroll_behavior.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/scroll_behavior.cpp)

### Anchor Navigation

RTXUI supports anchor navigation using `<a>` tags. When an `<a>` tag with a target hash (e.g. `href="#sec-intro"`) is clicked, RTXUI automatically scrolls the element with the corresponding `id` (e.g. `id="sec-intro"`) into view. Combined with `position: sticky` and `scroll-behavior: smooth`, this allows building robust sidebar navigation layouts.

Example source: [example/anchor.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/anchor.cpp)

## An application using all of it

A file browser: the listing scrolls, its rows are focusable, and moving the
focus walks them while keeping the focused row on screen.

Example source: [example/app_filebrowser.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/app_filebrowser.cpp)

---

# Transitions & Hover States

RTXUI supports CSS-style transitions and interactive pseudo-classes on DOM elements. This allows you to build terminal applications with smooth color shifts, expanding borders, and responsive mouse effects without writing manual frame updates.

---

## 1. Interactive Pseudo-Classes

You can define styles that apply only under specific user interaction states:

*   **`:hover`**: Active when the mouse cursor is hovering over the element or its children.
*   **`:active`**: Active while the element is being clicked/pressed.
*   **`:focus`**: Active when the element has captured keyboard focus.

### Example Rulesets
```css
.button {
  background-color: rgb(30, 58, 138); /* Slate Blue */
}
.button:hover {
  background-color: rgb(29, 78, 216); /* Bright Blue on hover */
}
.button:active {
  background-color: rgb(30, 64, 175); /* Dark Blue on click */
}
```

### Minimal Interactive Demo
Below is the interactive tab view for `:hover`, `:active`, and `:focus` pseudo-classes:

Example source: [example/pseudo_classes.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/pseudo_classes.cpp)

---

## 2. CSS Transitions

The `transition` property configures how style attributes interpolate smoothly over time instead of changing instantly.

### Shorthand Syntax
```css
transition: <property> <duration> [<timing-function>] [<delay>]
```
You can declare multiple property transitions by separating them with commas, or use the keyword `all` to animate all supported variables:
```css
transition: background-color 0.2s ease-in-out, width 0.3s ease-out;
```

### Animatable Properties
*   **Dimensions**: `width`, `height` (e.g. `20` to `40` cells).
*   **Borders**: `border-top-color`, `border-right-color`, `border-bottom-color`, `border-left-color` (or shorthand `border-color`).
*   **Colors & Opacities**: `color`, `background-color`, `opacity`.
*   **Flex Constraints**: `flex-grow`, `flex-shrink`.

### Easing Functions
*   `linear`
*   `ease` (Default curve)
*   `ease-in`
*   `ease-out`
*   `ease-in-out`
*   **Sine curves**: `ease-in-sine`, `ease-out-sine`, `ease-in-out-sine`
*   **Quad curves**: `ease-in-quad`, `ease-out-quad`, `ease-in-out-quad`
*   **Cubic curves**: `ease-in-cubic`, `ease-out-cubic`, `ease-in-out-cubic`
*   **Quart curves**: `ease-in-quart`, `ease-out-quart`, `ease-in-out-quart`
*   **Quint curves**: `ease-in-quint`, `ease-out-quint`, `ease-in-out-quint`
*   **Expo curves**: `ease-in-expo`, `ease-out-expo`, `ease-in-out-expo`
*   **Circ curves**: `ease-in-circ`, `ease-out-circ`, `ease-in-out-circ`
*   **Back curves**: `ease-in-back`, `ease-out-back`, `ease-in-out-back`
*   `cubic-bezier(x1, y1, x2, y2)` (Defines a custom cubic Bézier easing curve)

### Minimal Transition Demo
Below is the interactive tab view for background-color and border-color transitions:

Example source: [example/transitions.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/transitions.cpp)

---

## 3. Advanced Transition Examples

### Primary Animation & Flex Layout Demo
Hover over the **Hover Me** button and click **Grow Me** to observe interactive transitions reflow the flex container:

Example source: [example/animation.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/animation.cpp)

---

### Component-Level Transition Demos

*   **Slider Transition**: Smooth track and thumb focus highlighting. (See [Slider Demo](/guide/examples/slider))
*   **Checkbox Transition**: Background check state changes. (See [Checkbox Demo](/guide/examples/checkbox))
*   **Dropdown Select Menu**: Highlight shifts. (See [Select Demo](/guide/examples/select))

---

# Terminal Media Queries

RTXUI supports media queries to automatically adapt component styling when the terminal viewport is resized.

## Viewport Features

Media queries parse current terminal size columns and rows:
*   `width` / `min-width` / `max-width` (measured in character columns)
*   `height` / `min-height` / `max-height` (measured in character rows)

## Responsive Rulesets

Define conditional styles by enclosing rules within `@media` blocks. Multiple rules can be chained using the `and` operator:

```css
/* General mobile layout (terminal width < 60 columns) */
@media (max-width: 59) {
  .container {
    flex-direction: column;
  }
  .sidebar {
    width: 100%;
    border-right: none;
    border-bottom: solid;
  }
}

/* Landscape desktop constraints */
@media (min-width: 80) and (min-height: 24) {
  .container {
    flex-direction: row;
    padding: 1 2;
  }
}
```
Whenever the terminal interface detects a resize event, styles are automatically re-evaluated, and layout reflow runs instantly.

## Live Demo

Example source: [example/media.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/media.cpp)

---

# Creating Components

In RTXUI, components are the primary building blocks of the user interface. Every component encapsulates its markup template, reactive state, and scoped CSS styles.

---

## Component Definition (`Component<Derived>`)

Every custom component inherits from `rtxui::Component<Derived>` via the Curiously Recurring Template Pattern (CRTP). Declare the template using the `view` member string:

```cpp
#include <rtxui/rtxui.hpp>

class MyCard : public rtxui::Component<MyCard> {
 public:
  std::string_view view = R"html(
    <div class="card">
      <h2>Card Title</h2>
      <span>Card content goes here.</span>
    </div>

Components can instead compute their template in a public `std::string_view Setup()` method, for example to call `Import<T>()` first. It is found at compile time, like `view`, so it is not virtual and takes no `override`. Define one or the other: a class with both does not compile.

---

## Importing Child Components (`Import<T>`)

To instantiate a custom C++ component inside another component's template, import it in the parent constructor using `Import<T>()`:

```cpp
class Header : public rtxui::Component<Header> {
 public:
  std::string_view view = R"html(
    <header>
      <h1>Application Dashboard</h1>
    </header>
  )html";
};

class Dashboard : public rtxui::Component<Dashboard> {
 public:
  Dashboard() { Import<Header>(); }

std::string_view view = R"html(
    <div>
      <Header />
      <p>Content</p>
    </div>
  )html";
};
```

By default, the tag name matches the C++ class name (e.g. `<Header />`).

### Custom Tag Aliases

To use a different XML tag name in the template, pass an alias string to `Import<T>`:

```cpp
Dashboard() {
  Import<MyCard>("card");
}
```

The template can now use `<card />`:

```html
<div>
  <card />
</div>
```

---

## State & Data Binding in Components

Child components can declare internal reactive state. Bind members with `Bind(member)` to enable template interpolation and two-way synchronization:

```cpp
class Counter : public rtxui::Component<Counter> {
 public:
  int count = 0;

void Increment() {
    count++;
  }

Counter() {
    Bind(count);
    Bind(Increment);
  }

std::string_view view = R"html(
    <div>
      <span>Count: {count}</span>
      <button @click="Increment">+1</button>
    </div>
  )html";
};
```

When compiled with C++26 static reflection (`RTXUI_HAS_REFLECTION`), struct members and method callbacks are bound automatically without explicit `Bind()` calls.

---

## Content Projection with Slots

Custom components can accept projected child markup from caller templates using `<slot>` containers:

```cpp
class Panel : public rtxui::Component<Panel> {
 public:
  std::string_view view = R"html(
    <div class="panel">
      <div class="header">
        <slot.title select="h3">Default Title</slot.title>
      </div>
      <div class="body">
        <slot>Default body content.</slot>
      </div>
    </div>
  )html";
};
```

Callers project content into the default or named slots directly:

```html
<Panel>
  <h3>System Status</h3>
  <span>All services operational.</span>
</Panel>
```

For complete details on slot matching and named slots, see the [Slots Guide](/guide/cpp/slots).

---

## Next Steps

- **[State Bindings & Reflection](/guide/cpp/bindings)**: Two-way data binding, member types, and reflection.
- **[Component Lifecycle](/guide/cpp/lifecycle)**: Mounting, rendering passes, and event loops.
- **[Navigating the DOM](/guide/cpp/dom)**: Inspecting elements and querying components dynamically.

---

# Component Slots & Composition

To build modular, reusable UI layouts, RTXUI supports **Component Slots**. This allows you to write wrapper components (such as layout grids, panels, cards, or dialogs) that receive and arrange arbitrary child markup passed from their parents.

RTXUI supports both **default slots** (for simple child wrapping) and **named slots** (for multi-zone layouts).

---

## Default Slots (`<slot>`)

A default slot acts as a placeholder for any child element nested inside your custom component's tag.

To declare a slot in your component's template, use the `<slot></slot>` tag:

```cpp
class MyPanel : public Component<MyPanel> {
 public:
  std::string_view view = R"html(
    <div class="panel-border">
      <slot></slot>
    </div>
  )html";
};
```

When using `MyPanel` inside a parent component, any children you nest inside `<MyPanel>` will automatically project into the `<slot></slot>` placeholder:

```html
<MyPanel>
  <p>This paragraph is projected inside the panel border.</p>
</MyPanel>
```

### Fallback Content

Content placed inside a slot declaration acts as its fallback: it is rendered when the caller projects no elements into that slot, and is replaced whenever projecting content is provided. If the projected content is dynamically unmounted (e.g. by a reactive `<if>` condition evaluating to `false`), the slot reverts to displaying its fallback markup:

```html
<slot>
  <span>Default placeholder content when no children are provided.</span>
</slot>
```

---

## Named Slots (`<slot.name>`)

For complex components that have multiple customizable content zones (e.g. a Header, a Body, and a Footer), you can use named slots.

### Declaring Named Slots
Define slots with dot-separated names inside your component template (e.g. `<slot.header>` and `<slot.footer>`):

```cpp
class PageLayout : public Component<PageLayout> {
 public:
  std::string_view view = R"html(
    <div class="layout">
      <div class="header-zone">
        <slot.header>Default Header Content</slot.header>
      </div>
      <div class="body-zone">
        <slot></slot> 
      </div>
      <div class="footer-zone">
        <slot.footer></slot.footer>
      </div>
    </div>
  )html";
};
```

### Projecting to Named Slots
When consuming a component with named slots, wrap the projected elements inside `<template.name>` tags:

```html
<PageLayout>
  
  <template.header>
    <h1>Welcome to my App</h1>
  </template.header>

<p>Here is some page body content...</p>

<template.footer>
    <span>Status: Ready</span>
  </template.footer>
</PageLayout>
```

### Selecting Projected Content by Tag (`select`)

`<template.name>` asks the consumer to say where content goes. Sometimes the
component should decide instead, from the tag the consumer wrote. Give the slot
a `select` attribute and it claims projected children with that tag, wherever
they appear in the projected content:

```html

<div class="legend-line">
  <slot.legend select="legend"></slot.legend>
</div>
<div class="body">
  <slot></slot>
</div>
```

```html

<fieldset>
  <legend>Group title</legend>
  <div>body</div>
</fieldset>
```

The `<legend>` is routed into the legend slot; everything else falls through to
the default slot. This is how the built-in `<fieldset>` and `<details>` pick up
`<legend>` and `<summary>`.

Selection looks through `<if>`, `<elif>`, `<else>` and `<for>`, so a
conditionally rendered `<legend>` still reaches its slot, and the slot empties
again when the condition turns off. Only elements are matched — bare text has
no tag and always lands in the default slot.

---

## Interactive Demo

Below is the live demo showcasing a reusable Card component using both named slots (for header and footer) and a default slot (for the body content):

Example source: [example/slots.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/slots.cpp)

---

# State Bindings & Reflection

To make C++ member variables accessible inside your HTML templates, you must register them in the reflection system.

## Component Constructor & Binding

### Binding Primitive Values
Use `Bind()` to link scalar types (such as `std::string`, `int`, `double`, `bool`) to the template environment:

```cpp
struct Profile : public rtxui::Component<Profile> {
  std::string username = "Alice";
  int level = 5;

Profile() {
    Bind(username);
    Bind(level);
  }

std::string_view Setup() {
    return R"html(
      <div>
        <span>User: {username}</span>
        <span>Level: {level}</span>
      </div>
    )html";
  }
};
```

### Binding Standard Collections
For rendering lists dynamically (using the template `<for>` or `for` attribute), use `BindCollection()` or `Bind()`:

```cpp
struct TodoList : public rtxui::Component<TodoList> {
  std::vector<std::string> items = {"Task 1", "Task 2"};

TodoList() {
    BindCollection("items", &items);
  }

std::string_view Setup() {
    return R"html(
      <ul>
        <for each="{items}" as="todo">
          <li>{todo}</li>
        </for>
      </ul>
    )html";
  }
};
```
The first parameter of `BindCollection` is the name the template's
`each="{...}"` refers to. `Bind(items)` is equivalent when the template name
should match the member name. Collections of structs additionally take a
mapper — see [Loops & Lists](/guide/loops#collections-of-structs).

---

# Navigating the DOM

Once templates are parsed, components build a tree of elements. Applications
reach it through `rtxui::ElementHandle`, which `<rtxui/rtxui.hpp>` already
includes.

If all you want is the component rendered at a selector — rather than the
element itself — use `QueryComponent`:

```cpp
if (auto* preview = dynamic_cast<Preview*>(QueryComponent("#preview"))) {
  preview->Reload(text);
}
```

## Query Selector Queries

Elements are found with CSS-style selectors (`#id`, `.class`, or a tag
name). A component queries its own tree with `QueryElement`, and any handle
can query below itself with `QuerySelector`:

```cpp
void ResetScrollbar() {
  QueryElement("#my-list").SetScrollY(0);
}
```

A query that matches nothing returns a null handle. Every method on a null
handle is a no-op returning an empty value, so the line above is safe even when
`#my-list` is not rendered. Test a handle with `if (handle)` when you need to
know.

## Tree Traversal

`RootElement()` returns the root of a component's tree. From any handle:

*   `Parent()`: the parent element, or a null handle at the root.
*   `ChildCount()`: the number of child elements.
*   `ChildAt(index)`: the child element at `index`, or a null handle.
*   `tag()` and `GetAttribute(name)`: what the template declared.

```cpp
void InspectFirstChild(rtxui::ElementHandle parent) {
  if (parent.ChildCount() > 0) {
    rtxui::ElementHandle child = parent.ChildAt(0);
    // Perform operations on the child element...
  }
}
```

The tree follows the template as written: `<slot>` wrappers are transparent,
and text is not counted as a child.

## Lifetime

A handle does not keep its element alive. When a re-render removes the element
— an `<if>` turning false, say — the handle becomes null rather than dangling.
Removed elements are pooled for reuse until the next render, so for one frame
the handle may still point at the detached element (its `Parent()` is null).
Holding a handle across frames is safe, but query again rather than expecting
it to follow a re-created element.

## ABI note

The element itself stays internal: its layout, style and animation state change
between releases. `ElementHandle` is a single pointer and all of its methods
are out-of-line library functions, so a release can change the element freely
and add new handle methods without breaking programs built against an older
one.

---

# Screen & Lifecycle

`rtxui::Screen` connects a component tree to the terminal and owns the event
loop.

## Running an application

Create the root component through `Ref<T>::New()` and hand it to a `Screen`;
`Loop()` blocks until the user quits:

```cpp
#include <rtxui/rtxui.hpp>

int main() {
  auto root = rtxui::Ref<MyRootComponent>::New();
  rtxui::Screen screen(root);
  screen.Loop();
  return 0;
}
```

Constructing the screen mounts the component (parsing its template and
building the element tree), runs a first digest, and draws the initial
frame. Entering `Loop()` switches the terminal to raw mode and enables mouse
reporting; both are restored when the loop exits — on <kbd>Ctrl-C</kbd>, on
<kbd>Escape</kbd> when no dialog is open, or when input closes.

## What one loop iteration does

The loop is event-driven; it sleeps until something happens. Each iteration:

1. **Input.** Raw terminal bytes are parsed into `rtxui::Event` values
   (keys, mouse, resize) and dispatched: first to component `OnEvent`
   overrides, then to the built-in behaviors (focus traversal with
   <kbd>Tab</kbd>, spatial navigation with arrows, scrolling, click
   simulation with <kbd>Enter</kbd>/<kbd>Space</kbd>).
2. **Posted tasks.** Work queued with
   `rtxui::PostTask(...)` — typically results arriving
   from worker threads — runs on the loop thread. If any task ran, a digest
   follows automatically, so state mutated by tasks is repainted without
   waiting for further input.
3. **Digest and draw.** After events or tasks, bound state is compared to
   its snapshots; changed components re-render, layout runs, and only the
   cells that differ from the previous frame are written to the terminal.
4. **Animations.** While CSS transitions are active, the loop wakes at a
   steady cadence to advance them; otherwise it stays idle.

There is no manual invalidation API to call in normal use: mutate bound
state in an event handler or a posted task, and the frame follows.

## Finer control

For tests and embedding, `Screen` exposes the loop's pieces:

- `Step()` runs a single iteration (wait, dispatch, digest, draw).
- `Dispatch(event)` injects one event as if it came from the terminal.
- `Draw()` forces a render of the current state.
- `SetSmoothScrollEnabled(bool)` toggles scroll animation, useful for
  deterministic tests.

A second constructor argument accepts a custom `TerminalDevice`; the test
suite uses this with a mock device to run entire interfaces headlessly.

---

# HTML/CSS Hot-Reloading

RTXUI can re-read a component's HTML template and `<style>` block from its C++
source file while the application is running, updating the live interface
without recompiling.

## How It Works

`EnableHotReload()` records which source file defines the component, using
`std::source_location`, and which member variable holds its template. While
the application runs, the event loop polls the file's modification time; when
the file is saved, the
raw string literal is re-extracted from the C++ source, re-parsed, and the
component's DOM subtree is rebuilt and re-bound.

Only the template text is reloaded — the compiled C++ stays as it was. Changes
to methods, bindings, event handlers, or member variables still require a
rebuild.

## Usage

Call `EnableHotReload()` in the component's constructor:

```cpp
#include <rtxui/rtxui.hpp>

class MyPanel : public rtxui::Component<MyPanel> {
 public:
  std::string_view view = R"html(
    <div class="panel">
      <h1>Live Panel</h1>
      <p>Modify this text, save the file, and watch the terminal update.</p>
    </div>
    <style>
      .panel {
        border: heavy;
        border-color: rgb(59, 130, 246);
        padding: 1;
      }
      h1 { color: rgb(234, 179, 8); }
    </style>
  )html";

MyPanel() {
    EnableHotReload();
  }
};
```

By default the template is assumed to live in a member named `view`. If yours
is named differently, pass the name:

```cpp
EnableHotReload("my_custom_view");
```

An overload also accepts an explicit file path, for cases where
`std::source_location` does not point at the file you want watched:

```cpp
EnableHotReload("view", "src/panels/my_panel.cpp");
```

## Limitations

- Only HTML markup and `<style>` blocks inside the watched raw string literal
  are reloaded.
- The extractor locates the template by the member variable's name in the
  source text, so the declaration must keep the form
  `std::string_view view = R"html(...)html";`.
- If the edited template fails to parse, the error is printed to stderr and
  the previous template stays active.
- A `<style>` block failing to parse (including one whose text is built from
  reactive/interpolated state, not just file-watched hot reload) also prints
  to stderr by default. Since an RTXUI app typically owns the terminal in raw
  mode, that print lands mid-frame instead of a scrollback the user could
  read — call `rtxui::SetCssErrorHandler(handler)` once (e.g. in `main()`) to
  redirect these into your own UI (an app that renders arbitrary/live-edited
  CSS, like a playground, should do this). `handler` receives a
  `rtxui::CssError{message, line, column}`; pass `nullptr` to restore the
  default stderr behavior.

---

# Diagnostics

A template or stylesheet can be valid HTML and CSS and still do nothing in
RTXUI: a property the engine does not implement, a typo in a bound name, an
attribute borrowed from another framework. Rather than ignore these silently,
RTXUI reports each one as a diagnostic.

## What Is Reported

| Mistake | Example | Diagnostic |
|---|---|---|
| Unsupported CSS property or value | `font-size: small`, `flex-direction: diagonal` | `unsupported CSS declaration 'font-size: small'` |
| Interpolating a name that is not bound | `{titel}` | `'{titel}' in <App> is not a bound name` |
| An expression inside `{}` | `{count == 1}` | `templates do not evaluate expressions; bind a const method computing the value and use its name` |
| A handler that is not bound | `onclick="Sumbit"`, when clicked | `handler 'Sumbit' is not bound in any enclosing component` |
| A tag that is not a built-in or an imported component | `<View>`, `<Card/>` without `Import<Card>()` | `unknown tag <Card> in <App>: if it is your component, call Import<Card>() in <App>'s constructor` |
| A `<style>` nested inside an element | `<div><style>...</style></div>` | `<style> inside <div> in <App> is ignored: put <style> at the top level of the view` |
| Another framework's attribute syntax | `v-if`, `*ngFor`, `className`, `onClick`, `for="x in xs"` | `attribute 'v-if' on <div> in <App> is not RTXUI syntax: use if="{name}" or <if condition="{name}">` |

Each distinct message is reported once per run, even though styles are
re-applied on every frame.

## Where They Go

By default each diagnostic is printed to stderr, prefixed with `rtxui:`.

Set the environment variable `RTXUI_STRICT=1` to abort on the first one
instead. This is what RTXUI's own example test runs with, and it is a good
setting for your tests and CI:

```bash
RTXUI_STRICT=1 ./my_app
```

An application that owns the terminal can route diagnostics through its own
interface, since printing to stderr disturbs a running frame:

```cpp
#include <rtxui/rtxui.hpp>

rtxui::SetDiagnosticHandler([](const rtxui::Diagnostic& d) {
  log_file << d.message << '\n';
});
```

Pass `nullptr` to restore the default.

---

# Headless Rendering

An RTXUI application can run without a terminal: at a fixed size, fed input as
bytes, with the screen read back as plain text. Use it to test an interface,
or to check from a script what a change looks like.

## From the Command Line

Any RTXUI program runs headless when the environment variable
`RTXUI_HEADLESS` gives a size. `Screen::Loop()` then feeds whatever is piped
on stdin to the application as input, prints the final screen to stdout and
returns. No code change is needed.

```bash
RTXUI_HEADLESS=80x24 ./my_app < /dev/null    # The first screen.
printf '\t\t\r' | RTXUI_HEADLESS=80x24 ./my_app  # After Tab, Tab, Enter.
```

Input is raw terminal bytes, exactly as a terminal sends them:

| Input | Bytes |
|---|---|
| Typed text | the text itself |
| Tab, Shift+Tab | `\t`, `\x1b[Z` |
| Enter, Backspace | `\r`, `\x7f` |
| Arrows | `\x1b[A` up, `\x1b[B` down, `\x1b[C` right, `\x1b[D` left |
| Left click at column x, row y (1-based) | `\x1b[<0;x;yM\x1b[<0;x;ym` |

The output has one line per row, without colors or styles, with trailing
spaces removed. Combine it with `RTXUI_STRICT=1` (see
[Diagnostics](/guide/diagnostics)) to also fail on any construct RTXUI ignores.

## From C++

`HeadlessScreen` does the same inside a program, which suits unit tests:

```cpp
#include <rtxui/rtxui.hpp>

auto app = rtxui::Ref<Counter>::New();
rtxui::HeadlessScreen screen(app, 40, 10);

screen.Click(5, 3);       // 0-based column and row.
screen.Input("\t\r");     // Tab, then Enter.
screen.Resize(30, 8);

std::string text = screen.Text();
```

Each call returns once the input is handled and any transition it started has
finished, so `Text()` does not depend on timing.

For a single frame, `RenderToString(app, width, height)` returns the text
directly.

## Snapshot Tests

RTXUI checks every example this way: `scripts/snapshot_examples.py` runs each
one headless at 80x24 and compares the output with `example/snapshots/`. A
change that alters what an example shows fails the test with a diff of the
text. When the change is intended, accept it with:

```bash
python3 scripts/snapshot_examples.py build --update
```

---

# Coding Agents

RTXUI's templates resemble HTML, Vue and browser CSS closely enough that a
language model writes them from habit, borrowing syntax RTXUI does not have.
Three things keep an agent on track.

## Give It the Manual

- [`llms.txt`](https://arthursonzogni.github.io/RTXUI/llms.txt) indexes the
  documentation.
- [`llms-full.txt`](https://arthursonzogni.github.io/RTXUI/llms-full.txt) is
  the whole manual as one Markdown file, opening with the rules models most
  often get wrong.

## Install the Skill

The RTXUI skill holds the supported syntax and the steps to check a change.
In Claude Code:

```text
/plugin marketplace add ArthurSonzogni/RTXUI
/plugin install rtxui@rtxui
```

Other agents that read Agent Skills can use the file directly:
[`tools/claude-plugin/skills/rtxui/SKILL.md`](https://github.com/ArthurSonzogni/RTXUI/blob/main/tools/claude-plugin/skills/rtxui/SKILL.md).

## Let It Check Its Work

An agent should not trust an interface it has only read. Have it run the
application with [diagnostics](/guide/diagnostics) made fatal and the screen
printed as text ([headless rendering](/guide/headless)):

```bash
printf '\t\r' | RTXUI_STRICT=1 RTXUI_HEADLESS=80x24 ./my_app
```

`RTXUI_STRICT=1` stops on the first construct RTXUI would ignore and says
what to write instead. `RTXUI_HEADLESS` shows what the interface looks like
after the piped input, so the agent can compare it with what was asked.

---

# Editor Syntax Highlighting

Component templates live in C++ raw string literals. By default an editor
shows them as a plain string. With a little setup it can highlight the HTML
inside, and the CSS inside `<style>` blocks, as if they were separate files.

## Name the Language in the Delimiter

A raw string literal can carry a delimiter between the quote and the
parenthesis. Use it to name the embedded language:

```cpp
class Counter : public rtxui::Component<Counter> {
 public:
  std::string_view view = R"html(
    <div class="counter">Hello</div>
    <style>
      .counter { color: rgb(59, 130, 246); }
    </style>
  )html";
};
```

The delimiter has no effect on the compiled program, but editors that
understand language injection use it to pick a parser. Supported names are
the tree-sitter parser names: `html`, `css`, `xml`, `markdown`. A bare `R"(`
carries no language and stays a plain string.

## Neovim

[nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) already
ships a C++ injection rule that parses a raw string's content with the parser
named by its delimiter. Two things are needed:

1. **Enable tree-sitter highlighting.** In the nvim-treesitter setup:

```lua
   require("nvim-treesitter.configs").setup({
     highlight = { enable = true },
   })
   ```

2. **Install the parsers**: `:TSInstall cpp html css`. With `auto_install =
   true` they are installed the first time a matching file is opened.

The HTML parser injects CSS into `<style>` elements on its own, so styles
inside an `R"html(` template are highlighted too.

To check that it works, put the cursor on a tag inside a template and run
`:Inspect`. It should list captures such as `@tag.html`.

---

# Playground: A Live HTML/CSS Editor

> [!TIP] Live Interactive Environment
> Experiment with templates and styles directly in the browser using the [**Full-Screen Playground**](/playground).

`example/playground.cpp` splits the terminal in two: a `<textarea>` on the
left holds raw HTML + CSS template text, and the pane on the right renders
that exact text live, using RTXUI to render RTXUI. Every keystroke reparses
the template and repaints the preview — no recompilation, no restart.

```bash
./build/rtxui_example_playground
```

## How It Works

The app is two components:

*   `Playground` — the static shell. It owns a `std::string code` bound to
    the editor's `<textarea>`, and lays out the two panes with flexbox.
*   `LivePreview` — a child component mounted as `<LivePreview id="preview" />`
    inside the right-hand pane. Its initial template is just a sensible
    default; after that, its content is replaced entirely at runtime.

`Playground` overrides `Digest()` to notice when `code` has changed since the
last frame. When it has, it parses the new text with `xml::Parse()` to check
it's valid, then looks up the preview child through the DOM and reloads it:

```cpp
bool Digest() override {
  bool changed = Component<Playground>::Digest();
  if (code == last_code_) {
    return changed;
  }
  last_code_ = code;

if (!xml::Parse(code)) {
    status = "Parse error: ...";
    return true;  // Keep showing the last valid preview.
  }

auto* preview = dynamic_cast<LivePreview*>(QueryComponent("#preview"));
  preview->HotReload(code);
  return true;
}
```

Two mechanisms from elsewhere in RTXUI make this possible:

*   **[`HotReload()`](/guide/hot-reload)** normally re-reads a component's own
    source file when it changes on disk. Called directly with an in-memory
    string, it reparses and re-renders *any* mounted component — which is
    exactly what a live editor needs, minus the file-watching.
*   **[`QueryComponent()`](/guide/cpp/dom)** finds the preview component by
    its `id` so `Playground` can call `HotReload()` on it directly.

If the typed markup fails to parse, `LivePreview` simply keeps rendering
whatever it last rendered successfully, and the status line beneath the
editor reports the error with a line number — the same recovery behavior
`EnableHotReload()` uses for file-based reloading.

## Limitations

*   The preview is a *document*, not a program: `onclick` handlers and
    C++ member bindings only work for names already bound on `LivePreview`
    itself. Typed markup can restyle and rearrange freely, but it can't
    invent new application logic.

---

## See Also

*   [**Interactive Playground (Full Screen)**](/playground) — Browser WebAssembly playground.
*   [**HTML Elements Reference**](/html_reference) — All built-in tags and attributes.
*   [**CSS Reference**](/css_reference) — Layout and style properties.

---

# Unicode & CJK Support

RTXUI measures text in grapheme clusters and computes display widths per
cluster, so layout works with any script the terminal can render.

## Wide Characters

Wide characters (such as Chinese, Japanese, and Korean ideographs) occupy two
terminal cell columns. RTXUI accounts for this when measuring text, so wide
characters align correctly in flexbox and grid layouts.

## Control Characters

Text is displayed, never executed. An application shows text it did not write --
a filename, a log line, a response from the network -- and a byte like `ESC` in
there is a command to the terminal rather than a character: it would repaint,
move the cursor, or recolour the interface, and everything after it on the line
would end up somewhere other than where the layout put it.

Every control character except newline and tab is therefore replaced with `U+FFFD`
(the replacement character) before measurement, so it occupies exactly the one
cell it is counted as. Newline and tab survive because layout gives them a
meaning of its own -- a hard break and a [tab stop](/guide/typography). A
carriage return becomes a line break, as CSS treats it.

## Malformed Text

Byte sequences that are not valid UTF-8 are replaced the same way, one `U+FFFD`
per bad byte. This is not pedantry about encodings: the engine and the terminal
have to agree on how many cells a sequence occupies, and they can only agree
about sequences that can actually be decoded.

The sharpest case is a truncated one. A lead byte announces how many bytes
follow it, so `E4 BD` at the end of a string claims a third byte that is not
there and takes whatever comes next instead -- the character after it is
absorbed and simply disappears from the display. Replacing per byte rather than
per sequence is what keeps the following character intact.

Valid text is never touched, including the parts of Unicode that are easy to
mistake for damage: wide characters, combining marks, zero-width characters and
four-byte code points all pass through as written.

## Zero-Width Characters

Format characters occupy no cell, and are measured that way: the zero-width
space and non-joiner, the bidi marks, embeddings, overrides and isolates, the
word joiner and invisible operators, and the byte-order mark. These arrive in
ordinary text -- a zero-width space pasted from a web page, a bidi mark inside a
filename, a byte-order mark at the head of a file -- and counting one as a cell
would put everything after it on that line a column to the left of where the
layout expects it.

Nothing is required of you to get any of this: it applies to every string a
template interpolates, whatever its source.

## Layout Alignment

Because widths are computed from display columns rather than byte or code
point counts, centering and alignment stay correct when ASCII and wide
characters are mixed on the same line.

Example source: [example/cjk.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/cjk.cpp)

---

# Markdown Component

The built-in `<markdown>` component renders Markdown text as regular RTXUI
elements. The Markdown source is converted to HTML internally, so the result
participates in layout and styling like any other part of the tree.

## Basic Usage

Pass the Markdown source through the `content` attribute. For anything longer
than a single line, bind a C++ string — C++ string literals give you real
newlines, which attribute text does not:

```cpp
class MyDoc : public Component<MyDoc> {
  std::string my_content = R"md(
# Hello World

This is **bold** and *italic*.
)md";

std::string_view view = R"html(
    <markdown content="{my_content}" />
  )html";

MyDoc() { Bind(my_content); }
};
```

Because `content` is a reactive binding, updating `my_content` re-renders the
Markdown on the next frame. This is how a live preview or a document viewer
that reloads files works — see the [complete example](#complete-example)
below, which reads a `.md` file from disk.

## Styling

The `stylesheet` attribute takes CSS scoped to the component. Target the
generated tags — `h1`, `p`, `ul`, `code`, `blockquote`, and so on:

```cpp
std::string my_styles = R"css(
  h1 { color: #3b82f6; border-bottom: solid; }
  code { background-color: #1e293b; }
)css";
```

```html
<markdown content="{my_content}" stylesheet="{my_styles}" />
```

`stylesheet` is reactive too: changing the bound string restyles the rendered
document.

## Tables

Markdown pipe-tables are parsed into standard HTML table elements (`<table>`,
`<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`), which you can style through the
`stylesheet` attribute:

```markdown
| Name     | Role     |
|----------|----------|
| Ada      | Engineer |
| Grace    | Admiral  |
```

```css
table { border: solid; border-color: #334155; }
th { font-weight: bold; border-bottom: solid; border-color: #334155; padding-left: 1; }
td { padding-left: 1; }
```

Escaped pipes (`\|`) inside cells and inline formatting inside cells are
supported.

## Supported Syntax

The built-in parser supports:

- Headings: `#` through `######`, and Setext-style (`title` underlined with `===` for h1, `---` for h2)
- Paragraphs, separated by blank lines
- Blockquotes, starting with `>`
- Fenced code blocks, using ` ``` `
- Lists: ordered (`1. `) and unordered (`- `, `* `, `+ `)
- Inline formatting: `**bold**`, `*italic*`, `` `code` ``
- Links: `[text](url)`
- Tables: pipe-tables with inline formatting and escaped pipes (`\|`)

## Complete Example

`example/markdown.cpp` is a live playground: a `<textarea>` holds the
Markdown source and another holds its CSS stylesheet, both bound straight to
a `<markdown>` component's `content`/`stylesheet` props. Since those are
ordinary reactive bindings, no manual reparse step is needed — every
keystroke re-renders the preview on the right.

```bash
./build/rtxui_example_markdown
```

Example source: [example/markdown.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/markdown.cpp)

---

# Cookbook

Self-contained patterns for interface problems that come up in most terminal
applications. Each recipe is a complete program from the repository's
`example/` directory — it compiles as part of the project's example build, so
you can paste it into a project and adapt it.

The recipes rely on three RTXUI idioms worth internalizing:

- **State lives in C++ members; the template reads it.** Templates interpolate
  bound names — they do not evaluate expressions, contain statements, or
  perform assignments.
- **Logic is a computed method.** A `const` method returns a class string or a
  boolean; the template binds it with `class="{method_name}"` or
  `condition="{method_name}"`. Ternaries and comparisons live in C++.
- **Event handlers name a bound method**, optionally with one argument:
  `onclick="Select(home)"` invokes `void Select(std::string)` with `"home"`.

---

## Tabbed navigation

Track the active tab in a state variable. Buttons call a single parameterized
method; each button's class and each pane's visibility come from computed
methods. The `<if>`/`<elif>`/`<else>` chain shows one pane at a time.

Example source: [example/cookbook_tabs.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/cookbook_tabs.cpp)

For most tabbed interfaces the built-in
[`<tabs>`/`<tab-pane>` components](/html_reference) are enough; this recipe
is the underlying pattern for when you need full control over the header.

---

## Background work without freezing the UI

Callbacks run on the main thread, so blocking inside one (network requests,
large file reads) freezes rendering. Run the work on a `std::thread` and post
the result back to the main loop with `rtxui::PostTask(...)`, which may be
called from any thread. State mutations posted this way are picked up by the
normal digest cycle; a task posted after the application exited is dropped.

Example source: [example/cookbook_async.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/cookbook_async.cpp)

A detached thread must not outlive the component it captures. In real
applications, join or signal worker threads before the component is
destroyed, or route results through state that survives the component.

---

## Confirmation dialog

The built-in [`<dialog>`](/html_reference) element renders centered above the
rest of the interface with a dimmed backdrop, and closes on
<kbd>Escape</kbd>. Bind its `open` attribute to a boolean and flip that
boolean from methods.

Example source: [example/cookbook_dialog.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/cookbook_dialog.cpp)

To build an overlay by hand instead — a dropdown, a toast, a context menu —
use `position: absolute` (or `fixed`) with `z-index` inside a
`position: relative` ancestor, and gate it behind an `<if>`. The
[positioning guide](/guide/css/positioning) covers the mechanics.

---

# Examples Index

Every example in the repository's [example/](https://github.com/ArthurSonzogni/RTXUI/tree/main/example) directory, running live in WebAssembly and accompanied by its C++ source code.

## Applications

Complete applications, showing how individual features compose into full programs.

## Core Concepts

Components, reactivity, interpolation, conditional rendering, and slots.

| Example | Demonstrates | Guide |
| :--- | :--- | :--- |
| [conditional.cpp](/guide/examples/conditional) | Conditional rendering. | [Guide](/guide/conditionals) |
| [counter.cpp](/guide/examples/counter) | Reactive state and `{...}` interpolation. | [Guide](/guide/interpolation) |
| [helloworld.cpp](/guide/examples/helloworld) | The smallest possible RTXUI application. | [Guide](/guide/hello-world) |
| [loop_complex.cpp](/guide/examples/loop_complex) | Looping over a collection of structs. | [Guide](/guide/loops) |
| [loop_simple.cpp](/guide/examples/loop_simple) | Looping over a `std::vector<std::string>` with `<for>`. | [Guide](/guide/loops) |
| [slots.cpp](/guide/examples/slots) | Content projection with `<slot>`. | [Guide](/guide/cpp/slots) |

## Form Elements

User input through keyboard and mouse, bound to C++ variables.

## Layout & Box Model

Positioning terminal cells with flexbox, grid, borders, and margins.

## Scrolling & Overflow

Handling scrollable regions, focus tracking, and overflow behavior.

## Typography & Styling

Colors, text decorations, pseudo-classes, transitions, and keyframe animations.

## Components & Advanced Features

Built-in HTML elements, CJK text, Markdown rendering, spatial nav, and cookbook recipes.

---

# HTML Element & Component Reference

This specification defines the complete set of built-in XML/HTML tags and components supported by the RTXUI template parser, including their classification, attribute interfaces, slot projections, event contracts, and default user-agent stylesheets.

---

## 1. Architectural Model

### 1.1 Unified Component Architecture
Every built-in tag—from `<div>` to `<dialog>`—is a component registered via `RegisterGlobalComponent()` and built over `rtxui::Element`. Simpler tags like `<div>` or `<span>` use trivial templates (e.g. `<slot></slot>` with a default stylesheet), while richer widgets like `<input>` or `<select>` encapsulate internal HTML templates, reactive state bindings, slot projections, and scoped CSS rules. The difference is in complexity, not in kind.

### 1.2 Parser Contract
- **Well-Formed XML/HTML**: All tags must be balanced or explicitly self-closed (e.g. `<hr />`, `<br />`, `<input />`). Unclosed tags generate parser errors with line and column diagnostics.
- **Case Sensitivity**: Tag names and attribute names are parsed as lower-case identifiers.
- **Quoting**: Attribute values must be enclosed in double (`"..."`) or single (`'...'`) quotes.

### 1.3 Binding Syntax
| Syntax | Target | Example | Semantic Contract |
| :--- | :--- | :--- | :--- |
| `{member}` | Text / Attribute | `<span id="{node_id}">{title}</span>` | Interpolates C++ member snapshot; updates DOM on change. |
| `:attr="member"` | Attribute | `<input :value="username" />` | Equivalent to `attr="{member}"`. |
| `on<event>="Handler"` | Event Callback | `<button onclick="Submit">OK</button>` | Dispatches to registered C++ method or lambda. |
| `@<event>="Handler"` | Event Callback | `<button @click="Submit">OK</button>` | Shorthand for event dispatch. |
| `@<event>.<mod>="Handler"` | Event Modifier | `<button @click.right="OnMenu">OK</button>` | Restricts dispatch to specific event conditions (e.g. mouse right-click). |

---

## 2. Global Attributes & Directives

The following attributes apply to all elements and components:

---

## 3. Structural Containers & Layout

### `<div>`
- **Classification**: Block Component
- **Layout Model**: `display: block`
- **Semantics**: Standard block-level container for flow, flex, or grid layouts.

### `<span>`
- **Classification**: Inline Component
- **Layout Model**: `display: inline`
- **Semantics**: Inline-level formatting wrapper for styled text segments.

### Semantic Elements (`<header>`, `<footer>`, `<main>`, `<nav>`, `<aside>`, `<section>`, `<article>`)
- **Classification**: Block Components
- **Layout Model**: `display: block`
- **Semantics**: Structural containers functionally identical to `<div>`, providing semantic document organization.

### `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`
- **Classification**: Table Components
- **Layout Model**: Table formatting context with automatic column and row sizing.
- **Section Containers**: `<thead>`, `<tbody>`, and `<tfoot>` group rows logically. The layout engine traverses them transparently when assembling grid rows and computing cell geometry.

#### Table Sizing Algorithm:
- **Columns**: Evaluates the maximum preferred cell width across each column. Extra horizontal space from fixed container `width` or `min-width` is distributed proportionally.
- **Rows**: Row height conforms to the tallest cell in the row. Shorter cells stretch vertically to maintain unbroken borders and backgrounds.

```xml
<table>
  <thead>
    <tr>
      <th>Service</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Database</td>
      <td>Active</td>
    </tr>
  </tbody>
</table>

Example source: [example/table.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/table.cpp)

---

## 4. Form Controls & Interactive Widgets

### `<button>`
- **Classification**: Inline Component (`rtxui::button`)
- **Focusable**: Yes (`tabindex="0"`)

#### Default Stylesheet
```css
self {
  display: inline-block;
  padding-left: 1;
  padding-right: 1;
  cursor: pointer;
  background-color: lighten(10%);
  opacity: 0.85;
  transition: background-color 0.1s linear, opacity 0.1s linear, color 0.1s linear;
}
self:hover    { background-color: rgb(59, 130, 246); color: white; opacity: 0.95; }
self:focus    { background-color: rgb(37, 99, 235); color: white; opacity: 1.0; }
self:active   { background-color: rgb(29, 78, 216); color: white; opacity: 1.0; }
self:disabled { cursor: default; opacity: 0.4; }
```

---

### `<input>`
- **Classification**: Inline Component (`rtxui::input`)
- **Focusable**: Yes (`tabindex="0"`)

#### Styleable Parts (`::part()`)
- `placeholder`: The span element rendering placeholder text.
- `cursor`, `cursor-focused`: The active cursor indicator.
- `selection`: Highlighted text selection regions.

#### Default Stylesheet
```css
self {
  display: inline-flex;
  flex-direction: row;
  width: 20;
  padding-left: 1;
  padding-right: 1;
  overflow-x: scroll;
  scrollbar-width: none;
  white-space: nowrap;
  background-color: rgb(40, 40, 40);
  opacity: 0.8;
}
self:focus {
  opacity: 1.0;
}
self:disabled {
  opacity: 0.4;
  cursor: default;
}
```

---

### `<textarea>`
- **Classification**: Block Component (`rtxui::textarea`)
- **Focusable**: Yes (`tabindex="0"`)

---

### `<checkbox>`
- **Classification**: Inline-Flex Component (`rtxui::checkbox`)
- **Focusable**: Yes (`tabindex="0"`)

#### Styleable Parts (`::part()`)
- `checkmark`: Span element containing the checkmark glyph (`☑` or `☐`).

#### Default Stylesheet
```css
self {
  display: inline-flex;
  flex-direction: row;
  white-space: nowrap;
  cursor: pointer;
  padding-left: 1;
  padding-right: 1;
  transition: background-color 0.1s linear;
}
self:hover    { background-color: lighten(10%); }
self:focus    { background-color: lighten(25%); }
self:active   { background-color: lighten(35%); }
self:disabled { cursor: default; opacity: 0.4; }
.checkmark    { margin-right: 1; }
```

---

### `<radio>`
- **Classification**: Inline-Flex Component (`rtxui::radio`)
- **Focusable**: Yes (`tabindex="0"`)

#### Styleable Parts (`::part()`)
- `radio-mark`: Span element containing the radio glyph (`◉` or `○`).

```xml
<radio name="theme" checked="{dark_mode}">Dark</radio>
<radio name="theme" checked="{light_mode}">Light</radio>
```

Example source: [example/radio.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/radio.cpp)

---

### `<select>` and `<option>`
- **Classification**: Component (`rtxui::select`, `rtxui::option`)
- **Focusable**: Yes (`tabindex="0"`)

#### Styleable Parts (`::part()`)
- `select-btn`: Main clickable trigger container.
- `select-label`: Active selected text label.
- `select-arrow`: Dropdown expand/collapse arrow glyph.
- `dropdown-list`: Floating options list container.

---

### `<slider>`
- **Classification**: Inline Component (`rtxui::slider`)
- **Focusable**: Yes (`tabindex="0"`)

#### Styleable Parts (`::part()`)
- `slider-container`: Wrapper element.
- `track-left`: Filled track portion preceding the thumb.
- `thumb`: Visual thumb handle glyph (`●`).
- `track-right`: Unfilled track portion following the thumb.

---

### `<progress>`
- **Classification**: Inline Component (`rtxui::progress`)
- **Focusable**: No

#### Styleable Parts (`::part()`)
- `filled`: Active progress section (rendered using `█`).
- `empty`: Inactive remainder section.

---

### `<label>`
- **Classification**: Inline-Flex Component (`rtxui::label`)
- **Focusable**: No (`cursor: pointer`)

#### Attributes
| Attribute | Type | Default | Reactive | Description |
| :--- | :--- | :--- | :--- | :--- |
| `for` | `string` | `""` | One-way | ID of target interactive element. |

#### Event Delegation Semantics:
Clicking a `<label>` delegates focus and activation to the target:
1. **Explicit Target**: Element whose `id` matches the `for` attribute.
2. **Implicit Target**: The first focusable descendant nested within `<label></label>`.

Example source: [example/label.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/label.cpp)

---

## 5. Disclosure, Navigation & Overlays

### `<details>` and `<summary>`
- **Classification**: Block Component (`rtxui::details`, `rtxui::summary`)

Example source: [example/details.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/details.cpp)

---

### `<fieldset>` and `<legend>`
- **Classification**: Block Component (`rtxui::fieldset`, `rtxui::legend`)

Example source: [example/fieldset.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/fieldset.cpp)

---

### `<tabs>` and `<tab-pane>`
- **Classification**: Component (`rtxui::tabs`, `rtxui::tab_pane`)

Example source: [example/tabs.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/tabs.cpp)

---

### `<dialog>`
- **Classification**: Modal Overlay (`rtxui::dialog`)
- **Layer**: Top-layer modal (`z-index: 100`)

#### Keyboard Invariants:
Pressing the `Escape` key automatically dismisses an open dialog and updates the bound `open` property to `false`.

Example source: [example/dialog.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/dialog.cpp)

---

### `<tooltip>`
- **Classification**: Hover Overlay (`rtxui::tooltip`)
- **Layer**: Top-layer popup (`z-index: 1000`)

Example source: [example/tooltip.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/tooltip.cpp)

---

## 6. Typography & Formatting Elements

### `<markdown>`
- **Classification**: Block Component (`rtxui::markdown`)

Example source: [example/hr.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/hr.cpp)

---

## 7. Lists (`<ul>`, `<ol>`, `<li>`)

### Unordered Lists (`<ul>`)
Unordered lists render alternating glyph markers based on structural nesting depth:
- **Level 1**: Disc (`• `)
- **Level 2**: Circle (`○ `)
- **Level 3+**: Square (`■ `)

### Ordered Lists (`<ol>`)
Ordered lists format numbered decimal prefixes (`1. `, `2. `):
- `start` (`integer`, default `1`): Initial counter value.
- `reversed` (`boolean`, default `false`): Counts down rather than up.

### List Items (`<li>`)
- `value` (`integer`): Explicit sequence override within ordered lists.

Example source: [example/lists.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/lists.cpp)

---

## 8. Template Control Flow

### `<if>`, `<elif>`, `<else>`
Conditional evaluation nodes. Direct children of `<if>` branches are mounted or unmounted dynamically:
```xml
<if condition="{has_error}">
  <span class="error">{error_message}</span>
</if>
<elif condition="{is_loading}">
  <span>Loading...</span>
</elif>
<else>
  <span>Ready.</span>
</else>
```

### `<for>`
Repeats template structures across bound collections. Syntax: `<for each="{collection}" as="item">`. The loop index is available as `{$index}` (zero-based).
- `each`: Bound collection expression.
- `as`: Variable alias for collection element.
- `key`: (Optional) Unique identifier field on struct item. Preserves element state and cursor position across sort and filter operations.

### `<slot>` and `<template>` (Content Projection)
Enables reusable components to project child content passed by their caller:
- **Default Slot**: `<slot></slot>` inside a component definition renders all unassigned child elements.
- **Named Slots**: `<slot.header></slot.header>` or `<slot name="header"></slot>` defines named projection targets.
- **Content Injection**: Callers project into named slots via `<template.header>` or `<template name="header">`.
- **Fallback Content**: Markup placed inside `<slot>Fallback</slot>` is rendered if the caller provides no projecting children.

```xml

<div class="card">
  <div class="card-header"><slot.header>Default Header</slot.header></div>
  <div class="card-body"><slot></slot></div>
</div>

<Card>
  <template.header>
    <span>Custom Title</span>
  </template.header>
  <p>Body projected into default slot.</p>
</Card>
```

Example source: [example/slots.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/slots.cpp)

---

# CSS Engine & Attribute Specification

This document provides the formal specification of the CSS styling engine implemented in RTXUI, defining value grammar, cascade and specificity rules, box-model semantics, and the exhaustive property reference.

---

## 1. Engine Formal Grammar

RTXUI implements an inline stylesheet parser and property resolver operating directly over terminal character cells.

```ebnf
Declaration      ::= PropertyName ':' Value ('!important')? ';'
PropertyName     ::= [a-z-]+ | '--' [a-z0-9-]+
Value            ::= Token (Whitespace Token)*

HexColor         ::= '#' ([0-9a-fA-F]{3} | [0-9a-fA-F]{4} | [0-9a-fA-F]{6} | [0-9a-fA-F]{8})
RgbColor         ::= ('rgb(' | 'rgba(') Number ',' Number ',' Number (',' Alpha)? ')'
                   | ('rgb(' | 'rgba(') Number Number Number ('/' Alpha)? ')'
HslColor         ::= ('hsl(' | 'hsla(') Angle (',' | Whitespace) Percentage (',' | Whitespace) Percentage (('/' | ',') Alpha)? ')'
ColorTransform   ::= ('lighten(' | 'darken(' | 'alpha(') (Percentage | Number) ')'
ColorKeyword     ::= 'transparent' | 'orange' | 'red' | 'white' | 'blue' | 'yellow' | 'green' | 'lime' | 'black' | 'gray' | 'grey' | 'cyan' | 'aqua' | 'magenta' | 'fuchsia' | 'silver' | 'maroon' | 'purple' | 'olive' | 'navy' | 'teal'
```

### Coordinate & Dimensional Model
- **Grid Unit**: 1 unit = 1 terminal character cell.
- **Physical Cell Aspect Ratio**: Terminal cells are approximately 1:2 (width:height). An aspect ratio of `2 / 1` produces an approximately square visual block.
- **Default Box Model**: Unlike web browsers which default to `content-box`, RTXUI defaults to `border-box` (`box-sizing: border-box`). Declared `width` and `height` define the outer dimensions including padding and borders.

---

## 2. Cascade, Inheritance & Specificity

### 2.1 Specificity Vector `(A, B, C)`
Selector precedence is determined by a 3-component specificity vector `(A, B, C)`:
1. **$A$ (ID Component)**: Count of ID selectors (`#id`).
2. **$B$ (Class & Pseudo Component)**: Count of class selectors (`.class`), attribute selectors (`[attr]`), and pseudo-classes (`:hover`, `:focus`, `:active`, `:checked`, `:disabled`, `:first-child`, etc.).
3. **$C$ (Type Component)**: Count of element type selectors (`div`, `button`, `span`).

*Note*: Pseudo-elements (`::part(...)`) participate in target isolation rather than global specificity weighting. Negation (`:not(X)`) contributes the specificity of its inner argument $X$.

### 2.2 Precedence Order (Descending)
1. Declarations with `!important` (resolved in reverse cascade order).
2. Inline element styles (`style="..."`).
3. Higher specificity vector `(A, B, C)` (evaluated lexicographically: $A_1 > A_2$, then $B_1 > B_2$, then $C_1 > C_2$).
4. Source declaration order (later rules override earlier rules).
5. Inherited values from parent elements (only properties marked as `inherited`).
6. Engine initial property defaults.

---

## 3. Spacing, Sizing, and Box Model

- `margin`: `<length> | auto`. Initial: `0`. Shorthand margin width on all sides.
- `margin-top`: `<length> | auto`. Initial: `0`. Vertical space above the element.
- `margin-bottom`: `<length> | auto`. Initial: `0`. Vertical space below the element.
- `margin-left`: `<length> | auto`. Initial: `0`. Horizontal space to the left.
- `margin-right`: `<length> | auto`. Initial: `0`. Horizontal space to the right.
- `padding`: `<integer>`. Initial: `0`. Shorthand internal padding on all sides.
- `padding-top`: `<integer>`. Initial: `0`. Internal vertical padding at the top.
- `padding-bottom`: `<integer>`. Initial: `0`. Internal vertical padding at the bottom.
- `padding-left`: `<integer>`. Initial: `0`. Internal horizontal padding at the left.
- `padding-right`: `<integer>`. Initial: `0`. Internal horizontal padding at the right.
- `width`: `<length>`. Initial: `auto`. Constrains element layout width.
- `height`: `<length>`. Initial: `auto`. Constrains element layout height.
- `min-width`: `<length>`. Initial: `auto`. Minimum layout width constraint.
- `max-width`: `<length>`. Initial: `none`. Maximum layout width constraint.
- `min-height`: `<length>`. Initial: `auto`. Minimum layout height constraint.
- `max-height`: `<length>`. Initial: `none`. Maximum layout height constraint.
- `box-sizing`: `content-box | border-box`. Initial: `border-box`. Whether width/height (and their min/max variants) describe the content box or the border box. Default is border-box, unlike web CSS.

### `calc()` Expressions
Length properties accept `calc()` expressions combining discrete cells and percentages:
```css
.sidebar { width: calc(100% - 20); }
.split   { height: calc((100% - 1) / 2); }
```

### `min()`, `max()`, and `clamp()`
- `min(a, b)`: Evaluates to the smaller resolved length.
- `max(a, b)`: Evaluates to the larger resolved length.
- `clamp(min, preferred, max)`: Clamps `preferred` between lower and upper bounds.
```css
.responsive-box { width: clamp(20, 50%, 80); }
```

---

## 4. Borders and Frames

- `border`: `<border-style> | <integer>`. Initial: `none`. Shorthand to configure borders on all sides.
- `border-width`: `<integer>`. Initial: `0`. Border frame cell thickness on all sides.
- `border-top`: `<border-style> | <integer>`. Initial: `0`. Top border frame thickness. A <border-style> keyword selects the frame character set and gives this side a thickness of 1.
- `border-bottom`: `<border-style> | <integer>`. Initial: `0`. Bottom border frame thickness. A <border-style> keyword selects the frame character set and gives this side a thickness of 1.
- `border-left`: `<border-style> | <integer>`. Initial: `0`. Left border frame thickness. A <border-style> keyword selects the frame character set and gives this side a thickness of 1.
- `border-right`: `<border-style> | <integer>`. Initial: `0`. Right border frame thickness. A <border-style> keyword selects the frame character set and gives this side a thickness of 1.
- `border-style`: `<border-style>`. Initial: `none`. Character set mapping style of the frame.
- `border-color`: `<color>`. Initial: `currentcolor`. Color of all border frame lines.
- `border-color-top`: `<color>`. Initial: `currentcolor`. Color of the top border line.
- `border-color-bottom`: `<color>`. Initial: `currentcolor`. Color of the bottom border line.
- `border-color-left`: `<color>`. Initial: `currentcolor`. Color of the left border line.
- `border-color-right`: `<color>`. Initial: `currentcolor`. Color of the right border line.

### 4.1 Border Style Glyph Matrix
RTXUI supports 30 border style keywords mapping directly to Unicode box-drawing and block elements:

Example source: [example/borders.cpp](https://github.com/ArthurSonzogni/RTXUI/blob/main/example/borders.cpp)

---

## 5. Typography and Coloring

- `color`: `<color>`. Initial: `white`. Foreground text character color.
- `foreground-color`: `<color>`. Initial: `white`. Alias for color.
- `background-color`: `<color>`. Initial: `transparent`. Background block container cell color.
- `opacity`: `<number>`. Initial: `1.0`. Transparency value (0.0 for transparent to 1.0 for opaque).
- `text-align`: `left | right | center | justify`. Initial: `left`. Horizontal alignment of inline text flows. justify widens space runs on soft-wrapped lines (never the last line or lines ended by an explicit newline).
- `white-space`: `normal | nowrap | pre | pre-wrap | pre-line | break-spaces`. Initial: `normal`. nowrap/pre disable wrapping; pre-line collapses space runs while honoring newlines. Note: this engine preserves interior whitespace and newlines in all modes, so normal, pre-wrap, and break-spaces behave alike.
- `font-weight`: `bold | bolder | lighter | normal | <number>`.
- `font-style`: `italic | oblique | normal`. Initial: `normal`. Applies italic styling to text (rendered with the terminal's italic attribute).
- `text-decoration`: `underline | double-underline | overline | line-through | strikethrough | blink | none`. Initial: `none`. Text decorations (can specify space-separated lists, e.g. `overline underline`). `overline` renders as SGR 53, which not every terminal implements; those that do not simply draw no line. `none` clears all of them.
- `text-transform`: `uppercase | lowercase | capitalize | none`. Initial: `none`. Case transformation of text (ASCII letters; other characters pass through).
- `letter-spacing`: `<integer> | normal`. Initial: `normal`. Blank cells inserted between characters. Whole cells only; negative values clamp to 0. Spaced words never wrap mid-word.
- `tab-size`: `<integer>`. Initial: `8`. Cells between tab stops; 8 by default. A tab advances to the next multiple of this from the start of its line, counted in cells so a full-width glyph moves the stop by two. Tabs are expanded during layout and never handed to the terminal, so the engine's own column accounting is what decides where they land. Outside white-space: pre and pre-wrap a tab is collapsible whitespace and becomes a single space, as in CSS. 0 removes tabs entirely.
- `line-height`: `<integer> | normal`. Initial: `normal`. Minimum rows each line box occupies (whole rows; values below 1 clamp to 1). Tall inline content can still grow a line further.
- `overflow-wrap`: `anywhere | break-word | normal`. Initial: `anywhere`. How words longer than the line are handled. Unlike CSS the default is anywhere: break at the container edge. normal keeps the word intact and lets it overflow.
- `word-wrap`: `anywhere | break-word | normal`. Initial: `anywhere`. Legacy alias for overflow-wrap.
- `word-break`: `normal | break-all`. Initial: `normal`. break-all treats every character boundary as a break opportunity, wrapping immediately at the boundary of a full line instead of pushing an overflowing word whole to the next line (unlike overflow-wrap, a last-resort fallback for otherwise-unbreakable words).
- `text-overflow`: `clip | ellipsis`. Initial: `clip`. Behavior when text overflows its block container.
- `visibility`: `visible | hidden`. Initial: `visible`. Controls element visibility. Hidden elements keep their layout size.
- `cursor`: `default | pointer`. Initial: `default`. Mouse pointer styling when hovering the element.

### Color Transforms
- `lighten(amount)`: Interpolates toward `#ffffff` in sRGB space.
- `darken(amount)`: Interpolates toward `#000000` in sRGB space.
- `alpha(amount)`: Sets the alpha transparency channel to `amount`.

---

## 6. Custom Properties (`--*` and `var()`)

Properties with a `--` prefix declare custom variables. They inherit down the element hierarchy and resolve during style application.
```css
self {
  --primary-color: rgb(59, 130, 246);
}
.header {
  color: var(--primary-color, white);
}
```
- **Fallback Semantics**: If a variable is missing, `var(--name, fallback)` evaluates the fallback expression. Fallbacks may contain nested `var()` calls.
- **Substitution Limit**: Recursive resolution is capped at 128 expansions to prevent cyclic reference hangs.

---

## 7. Flexbox Layout

- `display`: `none | block | inline | flex | grid | inline-block | inline-flex | inline-grid | flow-root`. Initial: `inline`. Enables the flex/grid layout engine or hides elements.
- `flex-direction`: `row | column | row-reverse | column-reverse`. Initial: `row`. Main formatting axis direction.
- `flex-wrap`: `nowrap | wrap | wrap-reverse`. Initial: `nowrap`. Controls wrapping behavior of flex items.
- `flex-grow`: `<number>`. Initial: `0`. Portion of free space item claims along main axis.
- `flex-shrink`: `<number>`. Initial: `1`. Factor determining how much item shrinks.
- `flex-basis`: `<length>`. Initial: `auto`. Initial size of flex item before free space is distributed.
- `flex`: `shorthand`. Initial: `0 1 auto`. Shorthand for flex-grow, flex-shrink, and flex-basis.
- `order`: `<integer>`. Initial: `0`. Lays a flex item out earlier or later than its document position. May be negative; items sharing a value keep document order.
- `justify-items`: `stretch | start | center | end`. Initial: `stretch`. Inline-axis alignment of items inside their grid cell.
- `justify-self`: `auto | stretch | start | center | end`. Initial: `auto`. Per-item override of justify-items.
- `place-items`: `<align-items> <justify-items>?`. Initial: `stretch`. Shorthand for align-items + justify-items.
- `place-self`: `<align-self> <justify-self>?`. Initial: `auto`. Shorthand for align-self + justify-self.
- `align-items`: `stretch | flex-start | flex-end | center | baseline`. Initial: `stretch`. Alignment of items along the cross axis.
- `align-self`: `auto | stretch | flex-start | flex-end | center | baseline`. Initial: `auto`. Alignment of individual flex item along the cross axis.
- `align-content`: `stretch | flex-start (start) | flex-end (end) | center | space-between | space-around | space-evenly`. Initial: `stretch`. Alignment of flex lines in multi-line flex container. `start` and `end` are accepted as aliases of `flex-start` and `flex-end`.
- `justify-content`: `flex-start (start) | flex-end (end) | center | space-between | space-around | space-evenly`. Initial: `flex-start`. Alignment of items along the main axis. `start` and `end` are accepted as aliases of `flex-start` and `flex-end`.
- `place-content`: `<align-content> <justify-content>?`. Initial: `stretch flex-start`. Shorthand for align-content + justify-content. One value sets both axes; a value valid on only one axis (e.g. `stretch`) leaves the other unchanged.
- `gap`: `<length>`. Initial: `0`. Spacing between flex items.
- `row-gap`: `<length>`. Initial: `0`. Spacing between flex rows/lines.
- `column-gap`: `<length>`. Initial: `0`. Spacing between flex columns/items.

---

## 8. Grid Layout

- `grid-template-columns`: `list of <length>`. Initial: `none`. Defines the column tracks of the grid. Supports repeat(count, track_size).
- `grid-template-rows`: `list of <length>`. Initial: `none`. Defines the row tracks of the grid. Supports repeat(count, track_size).
- `grid-template`: `shorthand`. Initial: `none`. Shorthand for grid-template-rows and grid-template-columns (separated by /).
- `grid-column`: `span <integer> | <integer>`. Initial: `auto`. Sets the column span of the grid item.
- `grid-column-end`: `span <integer> | <integer>`. Initial: `auto`. Alias for grid-column.
- `grid-row`: `span <integer> | <integer>`. Initial: `auto`. Sets the row span of the grid item.
- `grid-row-end`: `span <integer> | <integer>`. Initial: `auto`. Alias for grid-row.
- `grid-gap`: `<length>`. Initial: `0`. Alias for gap.
- `grid-row-gap`: `<length>`. Initial: `0`. Alias for row-gap.
- `grid-column-gap`: `<length>`. Initial: `0`. Alias for column-gap.

---

## 9. Scrolling & Overflow Management

- `overflow`: `visible | hidden | scroll | auto`. Initial: `visible`. Shorthand to configure horizontal & vertical overflow.
- `overflow-x`: `visible | hidden | scroll | auto`. Initial: `visible`. Horizontal layout overflow (visible, hidden, scroll).
- `overflow-y`: `visible | hidden | scroll | auto`. Initial: `visible`. Vertical layout overflow (visible, hidden, scroll).
- `scrollbar-width`: `auto | none`. Initial: `auto`. none hides visual scrollbars while keeping list scrollable.
- `scrollbar-color`: `<color> <color>`. Initial: `auto auto`. Foreground (thumb) and background (track) colors of scrollbars.
- `scroll-speed`: `<integer>`. Initial: `1`. Shorthand scroll step speed multiplier.
- `scroll-speed-x`: `<integer>`. Initial: `1`. Horizontal scroll step distance.
- `scroll-speed-y`: `<integer>`. Initial: `1`. Vertical scroll step distance.
- `scroll-behavior`: `auto | smooth`. Initial: `auto`. Smooth scrolling transitions configuration.

---

## 10. Positioning & Transitions

- `transition`: `property duration timing-function`. Initial: `none`. Shorthand (e.g. transition: background-color 0.2s linear). Easing keywords: linear, ease, ease-in, ease-out, ease-in-out, ease-in-sine, ease-out-sine, ease-in-out-sine, ease-in-quad, ease-out-quad, ease-in-out-quad, ease-in-cubic, ease-out-cubic, ease-in-quart, ease-out-quart, ease-in-quint, ease-out-quint, ease-in-expo, ease-out-expo, ease-in-circ, ease-out-circ, ease-in-back, ease-out-back.
- `position`: `static | relative | absolute | fixed | sticky`. Initial: `static`. Selects positioning flow model. An absolute/fixed box with an auto width or height sizes itself from its content, capped by the space available to it — it is free to be wider than the element it is anchored to, which is what lets a tooltip overhang a narrow trigger. Pinning both opposite edges (top and bottom, or left and right) stretches it between them instead, so inset: 0 fills the nearest positioned ancestor; auto margins on that axis opt back out, keeping the box content-sized and centering it between the edges.
- `inset`: `1-4 <length> values`. Initial: `auto`. Shorthand setting top/right/bottom/left (same expansion as margin).
- `aspect-ratio`: `<w> / <h> | <number> | auto`. Initial: `auto`. Derives an element's auto dimension from whichever of width/height is definite: height-from-width in block, flex, and grid contexts (items and containers), and width-from-height in block contexts and on flex items/containers (grid containers only derive height from width). Ratios are in cells — terminal cells are ~2:1 tall, so 2 / 1 looks square. Content larger than the ratio overflows.
- `top`: `<length>`. Initial: `auto`. Offset relative to top boundary.
- `bottom`: `<length>`. Initial: `auto`. Offset relative to bottom boundary.
- `left`: `<length>`. Initial: `auto`. Offset relative to left boundary.
- `right`: `<length>`. Initial: `auto`. Offset relative to right boundary.
- `z-index`: `<integer> | auto`. Initial: `auto`. Determines rendering paint layers.

---

## 11. List Styling

---

# C++ Engine API & Architecture Specification

This specification defines the public C++ API of RTXUI (`#include <rtxui/rtxui.hpp>`), documenting system contracts, thread-safety invariants, exception guarantees, and the frame execution lifecycle.

---

## 1. Core Architectural Invariants

### 1.1 Concurrency Model
- **UI Thread Affinity**: All component construction, template compilation, DOM mutations, layout resolution, and `Screen::Draw()` operations **must** execute on the designated main UI thread. They are non-reentrant and not thread-safe.
- **Cross-Thread Synchronization**: Background worker threads communicate with UI state exclusively by posting callbacks with `rtxui::PostTask()`. The runner queues them in a mutex-guarded queue and wakes the terminal event loop via a self-pipe (POSIX) or an event object (Windows).

### 1.2 Exception Safety Contract
- RTXUI is strictly non-throwing and compatible with `-fno-exceptions`. No C++ exceptions are thrown or caught across the public API surface.
- Operations subject to failure return `rtxui::expected<T, Error>` or `std::optional<T>`, or encode errors within deterministic state flags.

### 1.3 Memory & Object Ownership
- **Intrusive Smart Pointer (`rtxui::Ref<T>`)**: Components and DOM elements inherit from `rtxui::RefCounted`. `Ref<T>` manages intrusive reference counting, ensuring deterministic destruction on the main UI thread without secondary heap control blocks.
- **Scratch Layout Memory (`rtxui::LayoutArena`)**: The layout engine uses a double-buffered monotonic arena allocator. Box structures and physical fragments are allocated in bulk and recycled per frame, guaranteeing zero layout heap allocations in steady-state rendering.

### 1.4 Deterministic Frame Lifecycle
Every screen update follows an exact 6-stage sequential pipeline:

```
[Event Arrival / Task Wakeup]
             │
             ▼
1. Event Dispatch       : Capture -> Target -> Bubbling phase
             │
             ▼
2. State Mutation       : Handlers mutate bound variables / properties
             │
             ▼
3. Digest Reconciliation: Snapshot diffing detects mutations; dirty DOM subtrees patched
             │
             ▼
4. Layout Computation   : CSS cascade resolved; LayoutTreeBuilder populates LayoutArena;
                          RunLayout() computes geometric bounds and physical fragments
             │
             ▼
5. Rasterization        : Paint() rasterizes fragments into 2D Texture of Cell structs
             │
             ▼
6. Terminal Output      : Texture::RenderDiff() diffs against previous frame;
                          flushed to terminal wrapped in DEC Mode 2026 Synchronized Output
```

---

## 2. Reference Handle: `rtxui::Ref<T>`

Intrusive reference-counted pointer for `rtxui::ComponentBase` instances.

```cpp
template <typename T>
class Ref;
```

---

## 3. Component Base: `rtxui::Component<Derived>`

CRTP base class for user-defined components.

```cpp
template <typename Derived>
class Component : public ComponentBase;
```

### 3.1 Template Declaration
Components provide HTML structure via exactly one of two public members, found at compile time:
1. **`view` Member** (Recommended): A `std::string_view` member variable. Supports runtime [Hot Reload](/guide/hot-reload).
2. **`Setup()` Method**: A non-virtual method returning `std::string_view` (no `override`).

Defining both is a compile error.

```cpp
class CounterCard : public rtxui::Component<CounterCard> {
 public:
  int count = 0;
  void Increment() { count++; }

void InitReflection() override {
    Bind(count);
    Bind(Increment);
  }

std::string_view view = R"html(
    <div class="card">
      <span>Count: {count}</span>
      <button onclick="Increment">+1</button>
    </div>
  )html";
};
```

### 3.2 Registration & Binding Interface
Bindings are registered during component initialization (`InitReflection()` or constructor):

### 3.3 Lifecycle & Interaction Methods
| Method Signature | Invariants & Semantics |
| :--- | :--- |
| `virtual bool OnEvent(Event event)` | Intercepts keyboard/mouse input before DOM dispatch. Return `true` to consume the event. |
| `bool Digest()` | Compares bound members against snapshots; reconciles template DOM if differences are detected. Returns `true` if state changed. |
| `ElementHandle RootElement() const` | Handle to the root element of the expanded component template (null before mounting). |
| `ElementHandle QueryElement(std::string_view selector) const` | Handle to the first element matching `#id`, `.class`, or `tag`, or a null handle. |
| `ComponentBase* QueryComponent(std::string_view selector)` | The component rendered at `selector`, or `nullptr`. |
| `void CaptureMouse() noexcept` | Routes all subsequent mouse events exclusively to this component until released. |
| `void ReleaseMouse() noexcept` | Restores standard mouse hit-testing. |
| `void EnableHotReload()` | Watches the defining source file via `std::source_location` and dynamically reloads the template on disk modification. |

---

## 4. DOM Access: `rtxui::ElementHandle`

A weak, nullable handle to an element of the rendered tree, declared in `<rtxui/element.hpp>`. The element itself is internal; the handle is one pointer with out-of-line methods, so the element's layout never reaches the ABI.

- **Null-safe**: a query that matched nothing gives a null handle. On a null handle, getters return empty values and setters do nothing.
- **Weak**: a handle does not keep its element alive. Once a re-render destroys the element, the handle becomes null instead of dangling.
- **Template-shaped**: `<slot>` wrappers are transparent and text nodes are not children, so the tree matches the template as written.

---

## 5. Terminal Runtime: `rtxui::Screen`

Coordinates terminal I/O, device capability negotiation, and the primary event loop.

```cpp
class Screen {
 public:
  Screen(Ref<ComponentBase> root, std::shared_ptr<TerminalDevice> device = nullptr);
  ~Screen();

void Loop();
  void Step();
  void Draw();
  void Dispatch(Event event);
  void SetSmoothScrollEnabled(bool enabled) noexcept;
};
```

### 5.1 Loop Execution
- `Loop()`: Enters raw terminal mode, hides the cursor, routes signals, and executes the blocking event loop until `Exit()` is triggered.
- `Step()`: Non-blocking execution unit: processes pending terminal I/O, runs scheduled tasks, reconciles dirty state (`Digest()`), and flushes frames to output.
- `Draw()`: Unconditionally executes the layout, paint, and screen diff pass. Output is synchronized using DEC Mode 2026 (`\x1b[?2026h` / `\x1b[?2026l`) to guarantee tear-free updates.

---

## 6. Input Event Model: `rtxui::Event`

Encapsulates terminal input events as a tagged variant.

```cpp
class Event {
 public:
  template <typename T> bool is() const noexcept;
  template <typename T> const T& get() const noexcept;
  template <typename T> const T* get_if() const noexcept;
};
```

---

## 7. Color Representation: `rtxui::Color`

Represents 32-bit RGBA color values for cell background and foreground channels.

```cpp
struct Color {
  uint8_t r = 0;
  uint8_t g = 0;
  uint8_t b = 0;
  uint8_t a = 255;

static Color RGB(uint8_t r, uint8_t g, uint8_t b) noexcept;
  static Color RGBA(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
};

Color Blend(Color over, Color under) noexcept;
```

---

## 8. Asynchronous Task Scheduling: `<rtxui/task.hpp>`

Provides thread-safe task dispatching onto the primary UI event loop.

```cpp
namespace rtxui {
void PostTask(std::function<void()> task);
}
```

### Thread Invariant
`PostTask()` may be called from any thread. On a thread running an event loop it schedules onto that loop; from any other thread (a worker) it schedules onto the application's loop and wakes it immediately. A task posted after the event loop is gone is dropped.