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

# Gen-UI (SDUI)

> What Gen-UI means in this repo today, what is stable, and what is still evolving.

# Gen-UI in FERAL

Gen-UI is server-driven UI (SDUI): the brain emits structured UI payloads and
the client renders known component contracts.

## Stable today

* SDUI payload rendering in the web client (`SduiRenderer`).
* Incremental updates via `sdui_patch`.
* Third-party app install/open/dispatch API surface (`/api/apps/...`).
* Manifest signing + AppSurface sandbox + strict postMessage schema.
* Per-surface schema-version cache invalidation.

## Stable contract strategy for publishers

Use explicit contract versions in your app manifest:

* `manifest.contract.manifest_schema_version`
* `manifest.contract.a2ui_version`
* `surfaces[*].schema_version`
* `surfaces[*].action_contract`

Full policy (what to bump and when):

* [Gen-UI contracts & versioning](/genui/contracts)

## Headless vs UI

You can ship headless-first today:

* install: `POST /api/apps/install`
* render: `POST /api/apps/{app_id}/surfaces/{surface_id}/render`
* dispatch: `POST /api/apps/{app_id}/dispatch`

UI is still first-class for users, but agent integrations can run directly on
the headless API contract without building bespoke frontends.

## Deterministic traces

Hybrid surface renders emit replay/audit traces under the hybrid cache tree
(`_render_traces/*.jsonl`) with source, schema versions, and action contract
context. This is the debugging path for render drift and failure analysis.

## What this is not

* Not arbitrary HTML generation.
* Not "any component works everywhere instantly."
* Not a guarantee of parity across every client surface yet.