https://github.com/danielwpz/lark-a2ui-renderer
A2UI renderer for Feishu/Lark
https://github.com/danielwpz/lark-a2ui-renderer
Last synced: 29 days ago
JSON representation
A2UI renderer for Feishu/Lark
- Host: GitHub
- URL: https://github.com/danielwpz/lark-a2ui-renderer
- Owner: danielwpz
- License: mit
- Created: 2026-04-29T05:08:45.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-06T13:07:58.000Z (about 2 months ago)
- Last Synced: 2026-05-06T15:15:06.616Z (about 2 months ago)
- Language: TypeScript
- Size: 120 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# lark-a2ui-renderer
`lark-a2ui-renderer` is an experimental renderer for turning a constrained
[A2UI](https://a2ui.org/) v0.8 surface into Feishu/Lark Card JSON 2.0.
The goal is to make chat-card UI portable: an LLM or host application can
produce A2UI messages, and this library compiles them into a Lark interactive
card while preserving a stable callback contract back to A2UI `userAction`
events.
For the upstream protocol and specification, see the official A2UI site:
. This project implements a Lark-oriented subset and a few
experimental extensions; it is not an official A2UI renderer.
## What It Does
- Validates a Lark-oriented subset of A2UI v0.8.
- Maintains A2UI surface state and data model updates.
- Renders supported components into Feishu/Lark Card JSON.
- Embeds callback envelopes in interactive controls.
- Converts Lark `card.action.trigger` callbacks into normalized A2UI
`userAction` events.
The library does not send messages, call LLMs, store application state, or make
business decisions. Those responsibilities stay with the host application.
## Current Scope
- A2UI protocol: v0.8, following the stable protocol published at
.
- Target platform: Feishu/Lark interactive cards.
- Catalog id: `urn:a2ui:catalog:lark-card:v0_8`.
- Implementation language: TypeScript.
The supported catalog is intentionally smaller than the full A2UI standard
catalog. It focuses on components that map cleanly into an IM card surface:
text, layout, buttons, forms, text input, choices, and date input.
The repository also documents an experimental dynamic data source extension for
live surfaces such as a pixel clock. That extension is not official A2UI v0.8.
It is tracked separately in
[docs/dynamic-data-sources.md](docs/dynamic-data-sources.md).
> Notice: the packaged `skills/` authoring skill is static-only and does not
> include dynamic data source instructions or runtime support.
## Basic Usage
```ts
import { SurfaceStore, renderSurface, normalizeCallback } from "lark-a2ui-renderer/v0_8";
const store = new SurfaceStore();
store.applyMessages(a2uiMessages);
const rendered = renderSurface(store.getSurface("request_form"));
// Host app sends rendered.card through Feishu/Lark OpenAPI.
const userAction = normalizeCallback(store.getSurface("request_form"), normalizedCallbackInput);
// Host app routes userAction to application logic or an LLM.
```
## Project Status
This is still an experimental package. The core renderer, callback normalizer,
semantic fixtures, LLM generation tests, and real Lark card-send matrix are in
place. The repository also includes a distributable agent skill for authoring
and validating this A2UI subset.
The catalog and platform mapping may change as more real callback and rendering
behavior is verified.
Development notes, integration setup, and agent-specific operating guidance live
in [AGENTS.md](AGENTS.md).
## License
MIT