> ## 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.

# Renderer contract 0.1

> The pre-alpha consumer boundary for rendering, streaming, resources, actions, and presentation.

# Rixx UI Renderer Contract 0.1

## Status

This is the pre-alpha consumer boundary. The renderer remains private at
`0.0.0`; language, protocol, and catalog identifiers use the independent
experimental version `0.1`.

## Product

Rixx UI is a React renderer for AI response content. A host supplies accumulated
RUI source and owns the message, model call, transport, tools, persistence,
authentication, and business logic.

Existing prose-only paths can use `MarkdownRenderer`; structured answers use
`RUIRenderer`. Both share Markdown repair, URL/image policy, external-link
confirmation, themes, localization, and errors.

```tsx theme={null}
<RUIRenderer
  config={config}
  data={trustedApplicationData}
  streamStatus="streaming"
  onAction={({ name, input }) => hostDispatch(name, input)}
>
  {accumulatedSource}
</RUIRenderer>
```

The primary configuration API is `defineRUI`, with `defineComponent` and
`defineAction`. One config creates matching generation instructions, component
contracts, runtime registry, retrieval metadata, and action descriptions.

## Source fragment profile

Models emit the host-embedded fragment profile:

```rui theme={null}
root = Answer(children=[body])
body = RichText(format="markdown", text="A **formatted** answer.")
```

The host/compiler supplies protocol version, catalog ID, surface, base revision,
transaction ID, and commit after provider completion. Full-envelope documents
remain an advanced/internal form for fixtures and protocol tooling.

## Streaming

`RUIRenderer` accepts the complete accumulated source string and incrementally
processes only appended characters. Complete physical statements can create an
inert provisional preview. An open built-in `RichText` string may additionally
produce a display-only provisional overlay, with complete JSON escapes decoded
and incomplete Markdown repaired for stable token-level presentation. It never
enters the protocol graph. Components, props, graph structure, and resource
budgets validate before authoritative preview. Syntax-complete images can load
progressively, after commit, or only on click according to `resourceTiming`.
Links become visually stable during preview but remain inert. Actions, fields,
clipboard operations, form submission, and custom components remain disabled
until authoritative commit.

Malformed physical lines and catalog-invalid nodes are quarantined while valid
later statements continue streaming. Source replacement or `retryKey` resets
compilation. Cancelled, failed, truncated, and provider-incomplete streams
produce typed diagnostics, retain the last safe preview, and never become
committed UI.

## Content

Core currently includes structured prose, sanitized CommonMark/GFM RichText,
highlighted code, citations, cards, layout, tabs, accordions, metrics, data
tables, ten chart types, KaTeX math, sanitized committed Mermaid diagrams, and
local forms that emit one action payload. Raw HTML, MDX, JavaScript, CSS,
model-selected imports, and model-defined executable behavior are forbidden.

Inside RUI, Markdown exists only as a sanitized `RichText` payload. The separate
`MarkdownRenderer` accepts Markdown directly. Catalog and Markdown images share
one responsive loader. The default progressive mode loads syntax-complete,
credential-free HTTPS images with no referrer, lazy loading, async decoding, and
failure placeholders. `committed` and `manual` timing are available for more
private applications. A host `imagePolicy` can narrow or deny every mode.

## URLs and actions

URL strings may appear in approved component props. External HTTPS links use a
default review dialog with Copy, Cancel, and Open; direct mode is explicit. A
host `urlPolicy` can narrow or deny links and `onNavigate` can mediate opening.
Image loading uses the separate `imagePolicy`; navigation approval never grants
image/resource access.

Generated actions are declarative requests by name. Strict configs reject
unregistered action references and validate emitted payloads against action JSON
Schemas before notifying the host. Rixx UI does not execute tools or business
logic. The production host still authenticates and authorizes the user, requests
confirmation when needed, executes effects, and owns auditing/idempotency.

## Presentation and localization

`Renderer` and `RUIRenderer` accept one typed `options` object. `theme` is
`light`, `dark`, or `system`; system mode uses CSS media queries and does not
add a JavaScript media listener. `locale`, `currency`, and optional `timeZone`
control metrics, table cells and sorting, dates, chart axes, chart tooltips, and
percent shares. `direction` is `ltr`, `rtl`, or `auto` and is emitted on the
surface. Portaled controls receive matching theme and language context.

Defaults are `system`, `en-US`, `USD`, `UTC`, and `auto`, making SSR and
hydration deterministic. Localized hosts should pass the same explicit options
on server and client. Resolved options are canonicalized, frozen, and exposed to
typed custom components. Invalid values fail with an option-specific error.

Chart plotting coordinates remain explicitly LTR so axes and geometry stay
predictable; surrounding captions, legends, tooltips, and data tables follow the
surface direction.

## Public direction

Intended consumer APIs:

* `RUIRenderer`
* `MarkdownRenderer`
* `defineRUI`
* `defineComponent`
* `defineAction`
* `fromMarkdown`
* `RUIStreamStatus`
* `@rixx-ui/react/server` prompt and source helpers
* Frozen `RUIActionEvent`, `RUINavigationEvent`, `RUIRenderEvent`, and
  `RUIErrorEvent` host callback objects
* Static or functional `fallback` with a frozen `RUIFallbackEvent`

`Renderer`, normalized snapshots, protocol records, stores, compiler classes,
and session infrastructure are advanced/internal APIs without public stability
guarantees during pre-alpha development.

## Core and widget boundary

The intended stable core is rich text, code, answer/layout primitives, metrics,
data tables, charts, citations, streaming, validation, themes, typed custom
components, local forms, math, and diagrams. Forms own temporary local values
and emit one validated host event; the host owns persistence, authorization, and
submission effects.

Future video/audio, maps, file previews, and other application-specific features
should remain logical widget packs selected only when relevant.

## Development-only infrastructure

The repository's OpenRouter adapter, Hono session API, SQLite store, browser
session client, and Studio are private local development tools. They exercise
generation, repair, replay, and inspection but are not required by or planned as
dependencies of the renderer product.