# ADR-0007: Closed application component manifest

**Status:** Accepted

**Date:** 2026-07-11

## Context

AgentsKit owns the portable standard `UIElement` union and its validator. Applications also need custom semantic components whose model-produced props are untrusted and whose native implementations differ across React, React Native, and Ink.

Extending or copying the upstream union would create a competing generative-UI protocol. Letting renderers accept arbitrary component names or unchecked props would make model output executable UI configuration.

## Decision

`@agentskit/chat` owns a closed application component manifest. Each entry has a stable key and a Zod props schema. A component render frame is usable only when its v1 envelope is valid, its key is registered, and its props pass that registered schema. Otherwise resolution is inert and returns a typed, non-retryable diagnostic.

`@agentskit/chat-protocol` owns the framework-neutral render frame, semantic selection event, safe decoder, shared fixtures, and the wire schema for the semantic fallback established by ADR-0003. `@agentskit/chat` delegates its existing fallback parser to that schema and retains its public formatting API. This supersedes ADR-0003 only where it originally assigned schema ownership to `@agentskit/chat`; it avoids defining the same boundary twice. Native renderer packages own presentation and interaction mechanics only; they emit the same validated event.

`ChoiceList` is the first registered application component. Its props contain a prompt and 1–20 uniquely identified choices. Selection can reference only an id in the validated frame.

## Consequences

- AgentsKit remains the sole owner of standard generative UI, controller lifecycle, and framework bindings.
- Unknown keys and invalid frames or props cannot call application callbacks.
- React, React Native, Ink, and future renderers share identity, props, fallback, and event semantics without sharing UI primitives.
- Adding a component is an explicit registry and documentation change; changing required v1 semantics requires a new protocol version and ADR.