Skip to main content

​
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.
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:
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.