AGenUI

<div align="center">

# AGenUI

**AGenUI is a high-performance A2UI SDK for building native generative UI experiences across iOS, Android, and HarmonyOS.**

<img src="docs/images/hero.gif" alt="AGenUI streaming generative UI across iOS, Android, and HarmonyOS" width="640"/>

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-iOS%20%7C%20Android%20%7C%20HarmonyOS-blue)](#)
[![Android SDK](https://img.shields.io/badge/Android-API%2021%2B-green)](#)
[![iOS](https://img.shields.io/badge/iOS-13%2B-lightgrey)](#)
[![HarmonyOS](https://img.shields.io/badge/HarmonyOS%20NEXT-API%2017%2B-red)](#)

[**Official Website**](https://genui.amap.com) · [**Quick Start**](docs/QuickStart.md) · [**API Reference**](docs/API.md) · [**Contributing**](CONTRIBUTING.md)

English | [中文](README.zh-CN.md)

</div>

> This project is under active development and evolving rapidly. Contributions, feedback, and discussions are warmly welcome.

---

## What's New in v1.2.1

> Released on 2026-07-24

- **Full Font-Weight Support**: All three platforms now support the complete CSS `font-weight` range. iOS and HarmonyOS render true font weights; Android uses real weight on API 28+ with graceful degradation on lower versions.
- **Custom Font Registration**: Supports custom font registration via raw file path using `OH_Drawing_RegisterFont`, with a shared font parser class extracted for reuse.
- **`text-decoration` Tri-Platform Alignment**: Unified `text-decoration` parsing and rendering across iOS, Android, and HarmonyOS to conform to the A2UI standard.
- Changed `getMeasurer` and default interface methods from Java `default` to regular interface methods.
- Added `gap` property description to the component catalog.
- Removed ImageLoader fallback to system image loading on failure.

---

## What is AGenUI?

**AGenUI** is an A2UI SDK that simultaneously supports iOS, Android, and HarmonyOS. Built on and fully implementing the [A2UI v0.9 protocol open-sourced by Google](https://github.com/google/A2UI), it renders the streaming data of LLM-generated interactive UI in real time on mobile devices. Under the hood, it is powered by a cross-platform **shared C++ core engine**, while the three-platform rendering engines consume the component protocol dispatched by the core engine and perform drawing using native system capabilities.

**AGenUI** leverages native system UI capabilities to render **interactive cards, forms, lists, images, media players, and more**, delivering a high-performance, smooth user experience.

<img src="docs/images/a2ui_rendering_effect.png" alt="A2UI components rendering showcase" height="720">

---

## Key Features

- **Real-time streaming rendering** — structured component descriptions are generated by the LLM, arrive incrementally, and update in real time
- **High performance** — native rendering on iOS, Android, and HarmonyOS, maintaining a 120 fps refresh rate in core scenarios such as page scrolling
- **22 built-in components** — 18 A2UI protocol components + 4 SDK extension components
- **Custom component API** — register and extend native components via the custom component API, so the LLM can emit component descriptions by component name
- **Function Call integration** — register client-side tools/functions that the LLM can invoke on demand
- **Design Token & theming** — unified Design Token system and theme modes across all three platforms
- **Light / Dark mode** — built-in light/dark appearance switching

---

## Architecture

AGenUI adopts a **shared C++ core engine + three-platform component rendering engines** design.
The C++ layer implements capabilities shared across all three platforms, including streaming data parsing, virtual component tree management, render data caching, theme/style resolution, and component change diffing. The C++ layer synchronizes the parsed component protocol to the three-platform rendering engines to trigger drawing.

<div align="center">
<img src="docs/images/architecture.svg" alt="AGenUI SDK architecture" width="720"/>
</div>

### Project Directory

| Path | Contents |
|---|---|
| `core/` | C++ core engine — parser, differ, layout, Function Call framework |
| `core/include/` | Public C++ API consumed by platform bridging layers |
| `platforms/ios/` | iOS component renderer + Objective-C bridge |
| `platforms/android/` | Android component renderer + JNI bridge |
| `platforms/harmony/` | HarmonyOS component renderer + NAPI bridge |
| `playground/` | Three-platform demo apps for development & debugging |
| `scripts/` | Build scripts for each platform |

---

## Components

<div align="center">
<img src="docs/images/components.svg" alt="AGenUI built-in components" width="760"/>
</div>

### A2UI Protocol Components

The following 18 components implement the A2UI protocol specification and are supported on all three platforms.

| Component | Description |
|---|---|
| `Text` | Styled text with variant

... (truncated)