chore: document GenUI for React developers by PupilTong · Pull Request #2702 · lynx-family/lynx-stack

PupilTong · 2026-05-25T07:24:26Z

Summary

Rebased the branch onto the latest origin/main (7468b479).
Moved the external A2UI README pair into packages/genui/a2ui/ as README.md and README_zh.md.
Wired the website GenUI sidebar to generate English and Chinese A2UI guide pages from those package READMEs.
Folded the user-facing catalog extraction details into the A2UI README, including @a2uiCatalog, TypeDoc metadata mapping, supported/unsupported prop types, scanner behavior, and CLI options.
Removed the separate website A2UI Catalog Extractor guide entry and cleanup stale generated extractor docs from the sidebar sync helper.
Added website workspace dev dependencies on @lynx-js/a2ui-cli and @lynx-js/a2ui-reactlynx, with the lockfile updated.
Kept the public docs oriented toward external React/ReactLynx app developers: CLI examples use npx @lynx-js/a2ui-cli, the playground points only to https://lynx-stack.dev/a2ui/, and local/internal playground usage stays out of the docs.

Validation

./node_modules/.bin/dprint check .github/genui-website.instructions.md packages/genui/a2ui/README.md packages/genui/a2ui/README_zh.md website/sidebars/genui.ts
git diff --check
git diff --cached --check
Ran the GenUI sidebar sync helper directly with jiti and confirmed it returns only /guide/genui/a2ui and /zh/guide/genui/a2ui entries.
Confirmed stale generated website/docs/**/guide/genui/a2ui-catalog-extractor.md files are removed after sync.
./node_modules/.bin/rspress build still stops before site build because the existing API sidebar expects website/temp/react.api.json, which is not present in this checkout.

changeset-bot · 2026-05-25T07:24:31Z

⚠️ No Changeset found

Latest commit: d881a8a

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-05-25T07:24:39Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds comprehensive GenUI documentation (English and Chinese), introduces documentation instructions for GenUI workflows and transports, and standardizes CLI usage by making npx @lynx-js/a2ui-cli generate catalog the public entry point while marking the extractor as internal.

Changes

GenUI Documentation and CLI Realignment

Layer / File(s)	Summary
Documentation standards and guidelines `.github/genui-docs.instructions.md`	New instruction file specifying how to document GenUI workflows (Catalog→Agent→Client), clarify A2UI payload distinctions, describe transport behaviors (REST/SSE/AbortController), and standardize `a2ui-cli` command naming and wording.
Core GenUI user documentation (English) `packages/genui/Readme.md`	Complete user guide covering GenUI/A2UI mental model, quickstart commands, endpoints and payload shapes, client rendering via `MessageStore` and `<A2UI>`, REST/SSE transport guidance, operational best practices, glossary, and product direction.
Core GenUI user documentation (Chinese) `packages/genui/Readme_zh.md`	Parallel Chinese documentation covering concepts, quickstart, Catalog/CLI/Agent/Client workflows, transport layer examples (REST/SSE), event handling conventions, Playground usage, and glossary.
CLI entry point restructuring `packages/genui/a2ui-catalog-extractor/README.md`, `packages/genui/a2ui-catalog-extractor/readme.zh_cn.md`, `packages/genui/a2ui-cli/README.md`, `packages/genui/a2ui-prompt/README.md`	Updated package READMEs (English and Chinese) to position `@lynx-js/a2ui-catalog-extractor` as an internal extraction engine. Redirected users to `npx` @lynx-js/a2ui-cli `generate catalog` as the public entry point for catalog generation and added repository-internal API notes; normalized command references across CLI docs.

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested reviewers:

HuJean
Sherry-hue

I’m a rabbit with a tiny pen,
I hop through docs and tidy then.
CLI doors set straight and clear,
GenUI whispers in the ear.
Hooray — the guides are here! 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'chore: document GenUI for React developers' clearly and concisely summarizes the main purpose of the PR—adding documentation to orient React developers to GenUI/A2UI.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch hw/codex/genui-readme-docs

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-05-26T05:25:55Z

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!

codspeed-hq · 2026-05-26T05:46:09Z

Merging this PR will not alter performance

✅ 81 untouched benchmarks
⏩ 26 skipped benchmarks¹

_{Comparing hw/codex/genui-readme-docs (d881a8a) with main (0d8a8b1)²}

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. ↩
No successful run was found on main (7468b47) during the generation of this report, so 0d8a8b1 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

relativeci · 2026-05-26T05:49:30Z

React External

#1791 Bundle Size — 699.5KiB (0%).

d881a8a(current) vs 7468b47 main#1787(baseline)

Bundle metrics no changes

	Current #1791	Baseline #1787
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`3`	`3`
Modules	`17`	`17`
Duplicate Modules	`5`	`5`
Duplicate Code	`7.13%`	`7.13%`
Packages	`0`	`0`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #1791	Baseline #1787
Other	`699.5KiB`	`699.5KiB`

Bundle analysis report Branch hw/codex/genui-readme-docs Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-05-26T05:49:32Z

React Example

#8675 Bundle Size — 238KiB (0%).

d881a8a(current) vs 7468b47 main#8671(baseline)

Bundle metrics no changes

	Current #8675	Baseline #8671
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`4`	`4`
Modules	`204`	`204`
Duplicate Modules	`81`	`81`
Duplicate Code	`44.59%`	`44.59%`
Packages	`2`	`2`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #8675	Baseline #8671
IMG	`145.76KiB`	`145.76KiB`
Other	`92.24KiB`	`92.24KiB`

Bundle analysis report Branch hw/codex/genui-readme-docs Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-05-26T05:49:34Z

Web Explorer

#10252 Bundle Size — 903.53KiB (0%).

d881a8a(current) vs 7468b47 main#10248(baseline)

Bundle metrics no changes

	Current #10252	Baseline #10248
Initial JS	`45.06KiB`	`45.06KiB`
Initial CSS	`2.22KiB`	`2.22KiB`
Cache Invalidation	`0%`	`0%`
Chunks	`9`	`9`
Assets	`11`	`11`
Modules	`231`	`231`
Duplicate Modules	`11`	`11`
Duplicate Code	`27.12%`	`27.12%`
Packages	`10`	`10`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #10252	Baseline #10248
JS	`499.15KiB`	`499.15KiB`
Other	`402.16KiB`	`402.16KiB`
CSS	`2.22KiB`	`2.22KiB`

Bundle analysis report Branch hw/codex/genui-readme-docs Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-05-26T05:49:35Z

React Example with Element Template

#944 Bundle Size — 204.36KiB (0%).

d881a8a(current) vs 7468b47 main#940(baseline)

Bundle metrics no changes

	Current #944	Baseline #940
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`4`	`4`
Modules	`124`	`124`
Duplicate Modules	`50`	`50`
Duplicate Code	`45.19%`	`45.19%`
Packages	`2`	`2`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #944	Baseline #940
IMG	`145.76KiB`	`145.76KiB`
Other	`58.61KiB`	`58.61KiB`

Bundle analysis report Branch hw/codex/genui-readme-docs Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-05-26T05:49:38Z

React MTF Example

#1809 Bundle Size — 208.94KiB (0%).

d881a8a(current) vs 7468b47 main#1805(baseline)

Bundle metrics no changes

	Current #1809	Baseline #1805
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`3`	`3`
Modules	`199`	`199`
Duplicate Modules	`78`	`78`
Duplicate Code	`44.08%`	`44.08%`
Packages	`2`	`2`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #1809	Baseline #1805
IMG	`111.23KiB`	`111.23KiB`
Other	`97.71KiB`	`97.71KiB`

Bundle analysis report Branch hw/codex/genui-readme-docs Project dashboard

^{Generated by RelativeCI Documentation Report issue}

github-actions · 2026-05-26T06:22:55Z

UI Judge

GEQI weighted score: 64.1 / 100 across 8 examples.
Average visual-correctness score: 3.3 / 5.

Dimension	Weight	Average	Results	Status
Usability & Interaction	30%	3.3 / 5	8	OK
Visual & Aesthetics	25%	3.4 / 5	8	OK
Consistency & Standards	15%	3.3 / 5	8	OK
Architecture & UX Writing	15%	3.1 / 5	8	OK
Accessibility & Performance	15%	2.9 / 5	8	OK

#	Example	Visual Correctness	Usability & Interaction (30%)	Visual & Aesthetics (25%)	Consistency & Standards (15%)	Architecture & UX Writing (15%)	Accessibility & Performance (15%)	GEQI	Page	Status
1	recs	2 / 5	2 / 5	4 / 5	3 / 5	2 / 5	2 / 5	53 / 100	preview	OK
2	cast-grid	5 / 5	5 / 5	4 / 5	5 / 5	5 / 5	4 / 5	92 / 100	preview	OK
3	citywalk-list	2 / 5	2 / 5	3 / 5	2 / 5	2 / 5	2 / 5	45 / 100	preview	OK
4	fridge-search	3 / 5	3 / 5	3 / 5	4 / 5	4 / 5	3 / 5	66 / 100	preview	OK
5	trip-planner	2 / 5	2 / 5	3 / 5	2 / 5	2 / 5	2 / 5	45 / 100	preview	OK
6	weather-current	5 / 5	5 / 5	4 / 5	4 / 5	4 / 5	4 / 5	86 / 100	preview	OK
7	product-card	5 / 5	5 / 5	4 / 5	4 / 5	4 / 5	4 / 5	86 / 100	preview	OK
8	workout-plan	2 / 5	2 / 5	2 / 5	2 / 5	2 / 5	2 / 5	40 / 100	preview	OK

Details

Result 1

Example: recs
Dimension: visual-correctness
Visual correctness: 2 / 5
GEQI dimensions:
- Usability & Interaction: 2 / 5 (30%)
- Visual & Aesthetics: 4 / 5 (25%)
- Consistency & Standards: 3 / 5 (15%)
- Architecture & UX Writing: 2 / 5 (15%)
- Accessibility & Performance: 2 / 5 (15%)
Task: The A2UI playground preview should show date-night dining recommendations for Moonlight Terrace, Pinewood Bistro, and Sea Breeze Kitchen.

Result 2

Example: cast-grid
Dimension: visual-correctness
Visual correctness: 5 / 5
GEQI dimensions:
- Usability & Interaction: 5 / 5 (30%)
- Visual & Aesthetics: 4 / 5 (25%)
- Consistency & Standards: 5 / 5 (15%)
- Architecture & UX Writing: 5 / 5 (15%)
- Accessibility & Performance: 4 / 5 (15%)
Task: The A2UI playground preview should show a cast grid for the short film Night Notes, including Lin Xia and Zhou Ning cast cards.

Result 3

Example: citywalk-list
Dimension: visual-correctness
Visual correctness: 2 / 5
GEQI dimensions:
- Usability & Interaction: 2 / 5 (30%)
- Visual & Aesthetics: 3 / 5 (25%)
- Consistency & Standards: 2 / 5 (15%)
- Architecture & UX Writing: 2 / 5 (15%)
- Accessibility & Performance: 2 / 5 (15%)
Task: The A2UI playground preview should show weekend citywalk coffee picks with Rooftop Brew Room, Corner Canvas Lab, and Late Sun Roastery.

Result 4

Example: fridge-search
Dimension: visual-correctness
Visual correctness: 3 / 5
GEQI dimensions:
- Usability & Interaction: 3 / 5 (30%)
- Visual & Aesthetics: 3 / 5 (25%)
- Consistency & Standards: 4 / 5 (15%)
- Architecture & UX Writing: 4 / 5 (15%)
- Accessibility & Performance: 3 / 5 (15%)
Task: The A2UI playground preview should show refrigerator search results with Siemens, Hualing, Haier, and Midea product cards.

Result 5

Example: trip-planner
Dimension: visual-correctness
Visual correctness: 2 / 5
GEQI dimensions:
- Usability & Interaction: 2 / 5 (30%)
- Visual & Aesthetics: 3 / 5 (25%)
- Consistency & Standards: 2 / 5 (15%)
- Architecture & UX Writing: 2 / 5 (15%)
- Accessibility & Performance: 2 / 5 (15%)
Task: The A2UI playground preview should show a Kyoto 48-hour trip planner with Day 1 and Day 2 itinerary sections, including Monkey Park Viewpoint.

Result 6

Example: weather-current
Dimension: visual-correctness
Visual correctness: 5 / 5
GEQI dimensions:
- Usability & Interaction: 5 / 5 (30%)
- Visual & Aesthetics: 4 / 5 (25%)
- Consistency & Standards: 4 / 5 (15%)
- Architecture & UX Writing: 4 / 5 (15%)
- Accessibility & Performance: 4 / 5 (15%)
Task: The A2UI playground preview should show the current weather for Austin, TX, including clear skies with light breeze.

Result 7

Example: product-card
Dimension: visual-correctness
Visual correctness: 5 / 5
GEQI dimensions:
- Usability & Interaction: 5 / 5 (30%)
- Visual & Aesthetics: 4 / 5 (25%)
- Consistency & Standards: 4 / 5 (15%)
- Architecture & UX Writing: 4 / 5 (15%)
- Accessibility & Performance: 4 / 5 (15%)
Task: The A2UI playground preview should show a Wireless Headphones Pro product card with a visible Add to Cart action.

Result 8

Example: workout-plan
Dimension: visual-correctness
Visual correctness: 2 / 5
GEQI dimensions:
- Usability & Interaction: 2 / 5 (30%)
- Visual & Aesthetics: 2 / 5 (25%)
- Consistency & Standards: 2 / 5 (15%)
- Architecture & UX Writing: 2 / 5 (15%)
- Accessibility & Performance: 2 / 5 (15%)
Task: The A2UI playground preview should show a weekly workout plan with five days from Monday Ramp-Up through Friday Conditioning.

Workflow run

PupilTong changed the title ~~[codex] document GenUI for React developers~~ chore: document GenUI for React developers May 25, 2026

Sherry-hue previously approved these changes May 25, 2026

View reviewed changes

PupilTong dismissed Sherry-hue’s stale review via 67e6a49 May 25, 2026 07:34

PupilTong force-pushed the hw/codex/genui-readme-docs branch from 3394819 to 67e6a49 Compare May 25, 2026 07:34

PupilTong marked this pull request as ready for review May 25, 2026 07:56

PupilTong self-assigned this May 25, 2026

PupilTong requested review from HuJean and Sherry-hue May 25, 2026 13:28

PupilTong added 8 commits May 26, 2026 13:09

docs: introduce genui readmes

997ab4f

docs: add genui cli guidance

b1feb1c

docs: align genui cli entrypoint

7071e5e

docs: use npx for genui cli commands

828b47f

docs: link hosted genui playground

5f934f9

docs: keep playground guidance hosted only

ac75f7c

docs: orient genui readmes to app developers

d859900

docs: publish genui readmes through website

40123ef

PupilTong force-pushed the hw/codex/genui-readme-docs branch from d2f91e0 to 40123ef Compare May 26, 2026 05:22

PupilTong requested review from fzx2666-fz and gaoachao as code owners May 26, 2026 05:22

docs: fold catalog extractor guide into a2ui

d881a8a

HuJean approved these changes May 26, 2026

View reviewed changes

PupilTong enabled auto-merge (squash) May 26, 2026 06:58

PupilTong merged commit c19a419 into main May 26, 2026
88 of 90 checks passed

PupilTong deleted the hw/codex/genui-readme-docs branch May 26, 2026 06:59

coderabbitai Bot mentioned this pull request May 26, 2026

refactor(genui): add @lynx-js/genui #2712

Merged

3 tasks

coderabbitai Bot mentioned this pull request Jun 3, 2026

docs(a2ui): add system prompts guides #2782

Merged

3 tasks

Conversation

PupilTong commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

changeset-bot Bot commented May 25, 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 May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Uh oh!

codecov Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

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

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

relativeci Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React External

#1791 Bundle Size — 699.5KiB (0%).

Uh oh!

relativeci Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React Example

#8675 Bundle Size — 238KiB (0%).

Uh oh!

relativeci Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Web Explorer

#10252 Bundle Size — 903.53KiB (0%).

Uh oh!

relativeci Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React Example with Element Template

#944 Bundle Size — 204.36KiB (0%).

Uh oh!

relativeci Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React MTF Example

#1809 Bundle Size — 208.94KiB (0%).

Uh oh!

github-actions Bot commented May 26, 2026

UI Judge

Result 1

Result 2

Result 3

Result 4

Result 5

Result 6

Result 7

Result 8

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

PupilTong commented May 25, 2026 •

edited

Loading

changeset-bot Bot commented May 25, 2026 •

edited

Loading

coderabbitai Bot commented May 25, 2026 •

edited

Loading

codecov Bot commented May 26, 2026 •

edited

Loading

codspeed-hq Bot commented May 26, 2026 •

edited

Loading

relativeci Bot commented May 26, 2026 •

edited

Loading

relativeci Bot commented May 26, 2026 •

edited

Loading

relativeci Bot commented May 26, 2026 •

edited

Loading

relativeci Bot commented May 26, 2026 •

edited

Loading

relativeci Bot commented May 26, 2026 •

edited

Loading