> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixxui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rixx UI Language 0.1

> Experimental syntax, streaming semantics, bindings, and validation rules for RUI source.

# Rixx UI Language 0.1

## Status

Version `0.1` is experimental. Workspace packages remain private at `0.0.0`
during active development.

## Goals

* Compact, reliable model output.
* Progressive parsing of complete physical statements.
* Stable node identity and legal forward references.
* Data-only, non-executable component composition.
* Precise validation and bounded repair diagnostics.

## Host-embedded fragment

This is the normal model-facing form used by `RUIRenderer`:

```rui theme={null}
root = Answer(children=[title, body])
title = Heading(text="Welcome", level=1)
body = RichText(text="A **safe** generated answer.", format="markdown")
```

The host supplies the internal envelope: language/catalog version, surface, base
revision, transaction ID, and commit. Models emit assignments only. The trusted
host synthesizes `@commit root=root` after provider completion and validates the
complete transaction before exposing its commit record.

## Full-envelope document

Fixtures, compiler tools, and advanced protocol integrations may use:

```rui theme={null}
@rui version="0.1" catalog="rixx.core@0.1" surface="main" base=0 transaction="tx-welcome"
root = Text(text="A safe generated interface.")
@commit root=root revision=1
```

`@rui` must be first when present. `revision` must equal `base + 1` when
explicit. Header and revision defaults are accepted only when a trusted host
provides the missing envelope.

## Statements

Each non-empty physical line is one statement. `#` starts a comment outside a
JSON string. Calls, arrays, and objects do not span physical lines. Lines,
statements, expression depth, source bytes, graph nodes, edges, and protocol
records have implementation-enforced budgets.

During model generation, malformed physical lines are quarantined with bounded
diagnostics and parsing resumes at the next line. Valid siblings remain
available for provisional rendering. Unknown or catalog-invalid nodes are
dropped without weakening catalog or action validation. Final commit still
requires a valid reachable root, resolved references, and an acyclic graph.

```ebnf theme={null}
document        = [header, newline],
                  {blank | assignment, newline},
                  commit, [newline] ;
header          = "@rui", argument, {spacing, argument} ;
commit          = "@commit", argument, {spacing, argument} ;
assignment      = identifier, spacing, "=", spacing, expression ;
expression      = string | number | boolean | null | reference |
                  array | object | call ;
call            = component-name, "(", [arguments], ")" ;
arguments       = named-arguments | positional-arguments ;
named-arguments = argument, {",", argument} ;
argument        = identifier, "=", expression ;
reference       = identifier, {".", identifier} ;
array           = "[", [expression, {",", expression}], "]" ;
object          = "{", [object-entry, {",", object-entry}], "}" ;
object-entry    = (identifier | string), ":", expression ;
```

Component calls require named arguments. Registered pure functions and
validation rules may use their documented positional form.

## Assignments and references

An ordinary identifier defines one component node:

```rui theme={null}
save = Button(label="Save", action="customer.save")
```

An identifier beginning with `$` defines literal local surface data. Calls are
not permitted in declarations.

Runtime reference roots:

| Root       | Meaning                                |
| ---------- | -------------------------------------- |
| `$data`    | Read-only committed protocol/tool data |
| `$context` | Read-only host context                 |
| `$draft`   | Read-only host-provided draft values   |
| `$item`    | Current item inside an `Each` template |

Forward node references are valid if they resolve before commit. Unknown local
references, duplicate IDs, unsafe object keys, cycles, and excessive graph depth
are errors.

## Functions

Pure functions are allowlisted by the compiler. Current functions include
comparisons, boolean composition, conditional values, fallback, count/sum,
formatting, and responsive values. They cannot execute arbitrary code, perform
I/O, or mutate application state.

## Commit and previews

`@commit` is final and names one local root in authored documents. Model-facing
hosts append it only after the provider stream completes. Complete validated
statements may produce an inert provisional preview. A preview cannot activate
actions, external navigation, fields, clipboard behavior, or custom components.
A syntax-complete image may load according to host-selected progressive,
committed, or manual timing. The renderer may display safely decoded text from
an open built-in `RichText(format="markdown", text="...")` string as a
display-only overlay. The overlay does not create a protocol record. A malformed
later line cannot erase the last safe preview. Only a fully validated committed
transaction enables capabilities.

## Catalog validation

After parsing, the selected catalog validates:

* Registered component names.
* Closed prop schemas and values.
* Required/optional props and enums.
* Child cardinality.
* Binding representations.
* Graph and resource budgets.

Strict catalogs validate action names during compilation and payload schemas
before host notification. Production authentication, authorization,
confirmation, execution, and idempotency remain host responsibilities.

## Rich text and URLs

Top-level RUI is not Markdown. A `RichText` component may explicitly contain
sanitized CommonMark/GFM with `format="markdown"`. Raw HTML, MDX, scripts, style
attributes, and unapproved image loading are disabled. Fenced code highlighting
is implemented with trusted renderer code.

HTTPS URL values may appear in citation or RichText link props. External links
become visible while streaming but remain inert until commit, then use a review
dialog unless direct mode is selected. Catalog `Image` and Markdown images share
one timing and policy pipeline. Progressive loading is the default; committed
and manual modes avoid provisional requests. Navigation policy never implies
image policy.

## Explicit exclusions

Version `0.1` excludes raw HTML, CSS, model-provided SVG, JavaScript, JSX/MDX,
dynamic imports, arbitrary expressions, tool execution, network definitions,
model-defined event handlers, and executable third-party widgets.