docs(a2ui): consolidate and extend A2UI guides by PupilTong · Pull Request #2771 · lynx-family/lynx-stack

PupilTong · 2026-06-02T08:39:14Z

Summary

Consolidates the six A2UI docs into two reader-oriented guides and extends their content.

docs/overview.md (merges the old overview + architecture): React-vs-A2UI mental model, an end-to-end data-flow diagram, a "how a message becomes UI" walkthrough (store -> processor -> surfaces -> resources -> signals, plus template expansion and the action loop), the full props/lifecycle table, and the subpath export map -- now including the Loading built-in that the old architecture doc omitted.
docs/catalog-guide.md (merges the old catalogs + custom-components + the built-in src/catalog/README.md): a categorized table of all 20 built-in components, the complete list of all 25 basic-catalog functions with their real wire names, the "no catalog/all" rationale, the paste-able all-builtins recipe, custom components with the react hook contract, manifest generation via the public genui a2ui generate catalog CLI, and the catalog API reference.

Supporting changes

Update the README "More Docs" links (EN + ZH).
Fold src/catalog/README.md and readme_zh.md into short stubs that point at the new guide.
Refresh in-source doc pointers in src/index.ts and test/catalog.test.ts.
Repoint the website docs-site config (website/sidebars/genui.ts).
Simplified Chinese mirrors (*_zh.md) updated to match.

Docs only -- no runtime code changed. @lynx-js/genui-a2ui is a private package, so no changeset is required.

Checklist

Tests updated (or not required).
Documentation updated (or not required).
Changeset added (or not required)

Summary by CodeRabbit

Documentation
- Reorganized A2UI docs for clearer structure and navigation
- Added Overview & Architecture guide (EN/ZH) describing runtime, components, and lifecycle
- Added comprehensive Catalog Guide (EN/ZH) covering built-ins, manifests, APIs, and custom components
- Consolidated and removed older architecture/catalog/custom-component pages; added pointers to the new guides
- Updated website navigation to surface the new guides

Merge the overview + architecture docs into docs/overview.md, and the catalogs + custom-components + built-in catalog README into docs/catalog-guide.md. Both are extended and reader-oriented. overview.md: React-vs-A2UI mental model, end-to-end data-flow diagrams, how a message becomes UI (store/processor/surfaces/resources/signals), the full <A2UI> props and lifecycle, and the export map -- now including the Loading built-in that the old architecture doc omitted. catalog-guide.md: a categorized table of all 20 built-in components, the complete list of 25 basic-catalog functions with their real wire names, the "no catalog/all" rationale, the paste-able all-builtins recipe, custom components with the react hook contract, manifest generation via the public CLI, and the catalog API reference. Also: update the README "More Docs" links, fold the src/catalog READMEs into short stubs that point at the new guide, refresh in-source comment pointers, and repoint the website docs-site config (sync sources, routes, nav, and link-rewrite maps). Simplified Chinese mirrors updated to match.

changeset-bot · 2026-06-02T08:39:24Z

⚠️ No Changeset found

Latest commit: ef8c0d0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-06-02T08:39:30Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 490ea38d-e505-4b6d-82eb-92f569477678

📥 Commits

Reviewing files that changed from the base of the PR and between 5fd56a1 and ef8c0d0.

📒 Files selected for processing (2)

packages/genui/a2ui/docs/overview.md
packages/genui/a2ui/docs/overview_zh.md

✅ Files skipped from review due to trivial changes (1)

packages/genui/a2ui/docs/overview.md

🚧 Files skipped from review as they are similar to previous changes (1)

packages/genui/a2ui/docs/overview_zh.md

📝 Walkthrough

Walkthrough

Consolidates A2UI docs by adding English and Chinese overview and catalog-guide pages, removing older architecture/catalogs/custom-components files, updating in-package README pointers and test comments, and updating website sidebar generation and navigation to reference the new pages.

Changes

A2UI Documentation Restructuring

Layer / File(s)	Summary
New overview documentation `packages/genui/a2ui/docs/overview.md`, `packages/genui/a2ui/docs/overview_zh.md`	Introduces overview docs describing package purpose (ReactLynx client runtime), end-to-end message/render flow, internal architecture (MessageStore, MessageProcessor, Resource, SignalStore, React layer), runtime behaviors, exports/subpaths, and `<A2UI>` props/lifecycle.
New catalog guide documentation `packages/genui/a2ui/docs/catalog-guide.md`, `packages/genui/a2ui/docs/catalog-guide_zh.md`	Adds a comprehensive catalog guide covering catalog contract, built-in components & per-component manifests, `basicFunctions`, manifest-driven handshakes, an "every built-in" recipe, custom component authoring (hooks and manifest generation), and catalog API references (`defineCatalog`, `mergeCatalogs`, `serializeCatalog`, `resolveCatalog`, `defineFunction`).
Catalog README consolidation and redirects `packages/genui/a2ui/src/catalog/README.md`, `packages/genui/a2ui/src/catalog/readme_zh.md`, `packages/genui/a2ui/src/index.ts`	Replaces detailed in-file catalog guides with short pointers to `docs/catalog-guide*.md` and updates an inline module comment referencing the guide.
Documentation reference updates `packages/genui/a2ui/README.md`, `packages/genui/a2ui/README_zh.md`, `packages/genui/a2ui/test/catalog.test.ts`	Updates "More Docs" links and internal comments to reference the new overview and catalog-guide files instead of removed/relocated docs.
Website navigation and doc generation configuration `website/sidebars/genui.ts`	Updates doc generation to use `packages/genui/a2ui/docs/overview` and `docs/catalog-guide`, rewrites `A2UI_EN_NAV_ITEMS` and `A2UI_ZH_NAV_ITEMS` to link the new pages, and adjusts language-specific link-replacement tables accordingly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

lynx-family/lynx-stack#2742: Prior A2UI docs/README restructuring touching similar files and navigation.

Suggested reviewers

HuJean
Sherry-hue
gaoachao
fzx2666-fz

"I hopped through README lanes under moonlit code,
I swapped old maps for tidy paths to goad.
New guides take root where scattered notes once stood,
Catalogs and overview now share the wood.
A nibble of links, a tidy trail well-sowed."

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: consolidating existing A2UI documentation into extended guides (overview and catalog-guide).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-06-02T08:42:17Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/genui/a2ui/docs/overview_zh.md`:
- Line 88: Update the Chinese wording in the table row containing "用与 client
可渲染能力一致的 catalog contract 提示模型" to the suggested, more natural phrasing "使用与
client 可渲染能力一致的 catalog contract 提示模型"; locate the string in overview_zh.md (the
Agent 服务 | Server | 你的应用 row) and replace the verb "用" with "使用" so the cell
reads smoothly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 02f100c5-d615-4795-8476-109f9953b23b

📥 Commits

Reviewing files that changed from the base of the PR and between 3794d0c and 647b02e.

📒 Files selected for processing (17)

packages/genui/a2ui/README.md
packages/genui/a2ui/README_zh.md
packages/genui/a2ui/docs/architecture.md
packages/genui/a2ui/docs/architecture_zh.md
packages/genui/a2ui/docs/catalog-guide.md
packages/genui/a2ui/docs/catalog-guide_zh.md
packages/genui/a2ui/docs/catalogs.md
packages/genui/a2ui/docs/catalogs_zh.md
packages/genui/a2ui/docs/custom-components.md
packages/genui/a2ui/docs/custom-components_zh.md
packages/genui/a2ui/docs/overview.md
packages/genui/a2ui/docs/overview_zh.md
packages/genui/a2ui/src/catalog/README.md
packages/genui/a2ui/src/catalog/readme_zh.md
packages/genui/a2ui/src/index.ts
packages/genui/a2ui/test/catalog.test.ts
website/sidebars/genui.ts

💤 Files with no reviewable changes (6)

packages/genui/a2ui/docs/architecture_zh.md
packages/genui/a2ui/docs/custom-components_zh.md
packages/genui/a2ui/docs/catalogs.md
packages/genui/a2ui/docs/custom-components.md
packages/genui/a2ui/docs/architecture.md
packages/genui/a2ui/docs/catalogs_zh.md

codspeed-hq · 2026-06-02T09:23:35Z

Merging this PR will degrade performance by 76.35%

⚠️

Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 80 untouched benchmarks
⏩ 26 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	`BASE`	`HEAD`	Efficiency
❌	`basic-performance-large-css`	16.2 ms	68.6 ms	-76.35%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing PupilTong:claude/romantic-liskov-4efd92 (ef8c0d0) with main (536cbca)}

26 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

PupilTong requested review from HuJean, Sherry-hue, fzx2666-fz and gaoachao as code owners June 2, 2026 08:39

coderabbitai Bot reviewed Jun 2, 2026

View reviewed changes

Comment thread packages/genui/a2ui/docs/overview_zh.md Outdated

docs(a2ui): smooth zh phrasing in overview table (用与 -> 使用与)

5fd56a1

docs(a2ui): add a runnable quick start to the overview guide

ef8c0d0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(a2ui): consolidate and extend A2UI guides#2771

docs(a2ui): consolidate and extend A2UI guides#2771
PupilTong wants to merge 3 commits into
lynx-family:mainfrom
PupilTong:claude/romantic-liskov-4efd92

PupilTong commented Jun 2, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Jun 2, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

codecov Bot commented Jun 2, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

codspeed-hq Bot commented Jun 2, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

PupilTong commented Jun 2, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Supporting changes

Checklist

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

coderabbitai Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

codecov Bot commented Jun 2, 2026

Codecov Report

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codspeed-hq Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will degrade performance by 76.35%

Performance Changes

Footnotes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

PupilTong commented Jun 2, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Jun 2, 2026 •

edited

Loading

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

codspeed-hq Bot commented Jun 2, 2026 •

edited

Loading