---
title: Extend clients and generated UI
description: Share behavior through contracts while keeping each platform's permissions and presentation native.
---

All three clients speak the Impo API. SwiftUI, Compose and React own presentation. Shared contracts define command identity, ownership, events and recovery; they do not force every client to use the same widget implementation.

## Choose the right surface

| Change | Extension path |
| --- | --- |
| A permanent navigation screen | Add an application API contract and a platform screen with loading, empty, error and restored states. |
| A one-off form or visual response | Use the existing `impo_publish_ui` tool and supported A2UI catalog. |
| A new native capability | Define a device tool and implement an adapter on each supporting platform. |
| An action that requires the user's tap | Prepare an owned client action and dispatch only from the foreground interaction. |

## Generated UI: from request to render

The user sends an ordinary Chat or Task message. The Rebyte Agent receives the `impo_publish_ui` schema and authoring instructions, then decides when a card is useful. The durable worker validates the document and publishes an immutable card through the existing tool-result path.

iOS and Android render the catalog with AGenUI. Web uses React and Astryx for the same `impo.mobile.v1` contract. Button actions become ordinary follow-up messages through the client's durable send path. The UI document is not executable authority.

To add a catalog component, update the server validator, shared contract, all supporting renderers and the summary fallback. Keep installed clients that do not understand the new component usable.

## Interactive HTML

Offline HTML games use an opaque sandbox with no host bridge. They cannot read the account, access provider keys or invoke native tools. Web adds an enclosing frame to restrict navigation.

Generated UI is suitable for bounded forms and visual interaction. A persistent application feature with durable local state needs an explicit product contract. Unsent generated-form state can reset when a card unmounts or reloads.

## Native adapters

Register capabilities only while available. A device claims owned pending work before executing it, persists the result before uploading it, and reuses the accepted receipt after a retry. Stream replay never authorizes a second native action.

Keep permission prompts as explicit UI actions. Do not translate empty health data into a denial, or use one phone's grant to act on another. Web does not implement native Health, contacts, background Echo or BLE gadget setup.

## Implementation and checks

- Protocol models: `contracts/`, `ios/Packages/InstantClient`, `android/client`, and `web/src/`.
- Native presentation and adapters: `ios/App/Sources/` and `android/app/src/main/java/ai/impo/`.
- Web presentation: `web/src/`, with the existing Astryx theme and components.

Run the relevant root commands: `test:swift`, `test:android`, `test:web`, and the affected UI checks. Verify recovery, account switching, narrow layouts, keyboard access and dark appearance. Regenerate the Xcode project with `npm run generate:ios` when adding native files.

The [generated UI contract](/docs/source/contracts/generated-ui.md) and [capability contract](https://github.com/impoai/impo/blob/main/contracts/capabilities.md) define supported inputs and fallbacks.