[路线图 / Roadmap] v0.1.0 后完善实验性 React 19 绑定 / Complete the experimental React 19 binding after v0.1.0

[tiye]

中文

目标

在 v0.1.0 恢复基线之上，把 react.mbt 从可用的客户端实验推进为一致、可测试的 React 19 绑定，同时明确保持实验性状态。

当前进度

• 总体：9/9 项完成（100%）。
• 阶段 1：4/4 完成（100%）。
• 阶段 2：3/3 完成（100%）。
• 阶段 3：2/2 完成（100%）；[P1] 统一发布元数据并发布下一实验版本 / Normalize release metadata and ship the next experimental release #17 的 GitHub Release、mooncakes 0.2.0、下游 4/4 与 PR test(release): 修正下游 helper 调用 / fix downstream helper call #30 verifier 固化均已完成。

已交付基线

• feat: add stable React node keys #11 / PR feat: add stable React node keys #11：稳定 VirtualNode keys，浏览器回归拒绝 React diagnostics。
• [P0] Add typed React Context bindings #19 / PR feat: add typed React context bindings #20：typed React Context。
• [P0] 扩展真实 React 符合度覆盖 / Expand real React conformance coverage #12 / PR fix: 保持重复渲染时组件身份稳定 / preserve component identity across repeated renders #21：稳定 component identity；React 19.2.8 StrictMode、batching、root/ref conformance。
• [P0] 加固 ref 与无效属性语义 / Harden ref and invalid prop semantics #13 / PR fix: 加固 ref 与表单属性语义 / harden ref and form prop semantics #22：Rules of Hooks、DOM ref 生命周期与 form prop 语义。
• [P1] 完善 React 19 Forms 和 Actions 支持 / Complete React 19 Forms and Actions support #18 / PR feat: 完善 React 19 Forms 与 Actions / complete React 19 Forms and Actions #23：React 19 Forms、async Actions、optimistic state 与 form status。
• [P1] 增加 Portal 并明确 Hydration/SSR 范围 / Add portals and define hydration and SSR scope #16 / PR feat: 完善 Portal 与 Hydration/SSR / complete portals and hydration scope #24：Portals、root options 与基础 Hydration/SSR。
• [P1] 增加外部 store 与组件集成 API / Add external-store and component integration APIs #14 / PR feat: 外部 store 与类型化组件集成 / external stores and typed component integration #25：external store、memo/lazy/Suspense、JS component bridge 与 imperative handle。
• [P2] 生成更广泛的 HTML/SVG typed helpers / Generate broader HTML and SVG typed helpers #15 / PR feat: 生成类型化 HTML/SVG helpers / generate typed HTML and SVG helpers #26：54 个生成式 typed HTML/SVG helpers、全量 smoke matrix、幂等/interface gate 与真实 DOM conformance。
• 当前 main 基线：MoonBit 54/54、Chromium 7/7、React/page diagnostics 0、生成 helper 54/54、生产构建与 CI 通过。

阶段 1：正确性与应用基础

• feat: add stable React node keys #11
• [P0] 扩展真实 React 符合度覆盖 / Expand real React conformance coverage #12
• [P0] 加固 ref 与无效属性语义 / Harden ref and invalid prop semantics #13
• [P0] Add typed React Context bindings #19

阶段 2：React 19 应用集成

• [P1] 完善 React 19 Forms 和 Actions 支持 / Complete React 19 Forms and Actions support #18 — PR feat: 完善 React 19 Forms 与 Actions / complete React 19 Forms and Actions #23：Forms、Actions 与 async/optimistic 语义
• [P1] 增加 Portal 并明确 Hydration/SSR 范围 / Add portals and define hydration and SSR scope #16 — PR feat: 完善 Portal 与 Hydration/SSR / complete portals and hydration scope #24：Portals、root options 与基础 Hydration/SSR
• [P1] 增加外部 store 与组件集成 API / Add external-store and component integration APIs #14 — PR feat: 外部 store 与类型化组件集成 / external stores and typed component integration #25：External store 与组件集成 API

阶段 3：API 广度与发布纪律

• [P2] 生成更广泛的 HTML/SVG typed helpers / Generate broader HTML and SVG typed helpers #15 — PR feat: 生成类型化 HTML/SVG helpers / generate typed HTML and SVG helpers #26：生成 HTML/SVG typed helpers
• [P1] 统一发布元数据并发布下一实验版本 / Normalize release metadata and ship the next experimental release #17 — PR release: 准备可复现的 v0.2.0 发布 / prepare reproducible v0.2.0 release #27–test(release): 修正下游 helper 调用 / fix downstream helper call #30：registry 精确 0.2.0、下游 4/4、artifact 核验与 immutable tag/verifier 解耦全部完成

#17 当前量化证据

• moon.mod / package.json：2/2 对齐 0.2.0。
• Changelog：7 个 release sections，GitHub 远端 6/6 历史 tags 覆盖，Unreleased 条目 0；本地私有 tag 不计入公开账本。
• 工作树与 clean clone：MoonBit 54/54、Chromium 7/7、diagnostics 0、production build 成功。
• GitHub Release 制品：17 文件、47,050 bytes、SHA-256 1631dd35bfeeb190d293ee33dcbf7d4cb0c826340cbb82fdbaf5e4683b7fc955、SHA256SUMS 下载核验通过、意外文件 0。
• 历史缺口已处理：GitHub v0.1.0 未曾发布到 mooncakes.io；新的 0.2.0 已由 Actions 发布，并由全新下游模块精确验证 4/4。
• 发布验证 artifact：mooncakes-0.2.0-verification，artifact id 9747734053，SHA-256 6a140f815127d7d808b7af49db64a66ab33980bef6752dc31cf37e1089871960。

完成结论

• 9/9 路线图项目完成；阶段 1、2、3 均为 100%。
• React 19 绑定的正确性、应用集成、API 广度与发布纪律均有固定的量化门禁；后续工作应作为新一轮路线图管理。

后续 PR 统一质量门槛

1. 公共 API 行为映射到固定 React 版本官方契约，PR 列出符合点。
2. FFI/转换逻辑有确定性 MoonBit 回归；生命周期、DOM 或调度行为有真实 React 浏览器用例。
3. 报告单测总数、浏览器场景数、React/page diagnostics 数量和生产构建结果。
4. React warnings/errors、page errors 和未处理 rejection 必须为 0。
5. 公共接口检查 moon info diff；生成内容通过 moon fmt、幂等检查和 git diff --check。
6. 测试验证可观察结果或精确调用/生命周期计数，不能只验证“代码能运行”。
7. Issue 与 PR 的中文、英文说明分区展示，证据逐项对应指标。
8. 覆盖率区分 MoonBit runner 与真实浏览器，并为 DOM/async 路径提供浏览器证据。
9. 生成 API 报告条目数、类别覆盖、幂等性和既有接口兼容结果。
10. 发布只允许从 clean clone/main tag 执行；版本、Changelog、release title、制品 checksum 与精确下游安装必须有自动门禁和日志。

---

English

Goal

Build on the restored v0.1.0 baseline and move react.mbt from a capable client-side experiment toward a coherent, tested React 19 binding while keeping its experimental status explicit.

Current progress

• Overall: 9/9 items complete (100%).
• Phase 1: 4/4 complete (100%).
• Phase 2: 3/3 complete (100%).
• Phase 3: 2/2 complete (100%); [P1] 统一发布元数据并发布下一实验版本 / Normalize release metadata and ship the next experimental release #17 has the GitHub Release, mooncakes 0.2.0, downstream 4/4, and PR test(release): 修正下游 helper 调用 / fix downstream helper call #30 verifier persistence complete.

Delivered baseline

• feat: add stable React node keys #11 / PR feat: add stable React node keys #11: stable VirtualNode keys; browser regressions reject React diagnostics.
• [P0] Add typed React Context bindings #19 / PR feat: add typed React context bindings #20: typed React Context.
• [P0] 扩展真实 React 符合度覆盖 / Expand real React conformance coverage #12 / PR fix: 保持重复渲染时组件身份稳定 / preserve component identity across repeated renders #21: stable component identity plus React 19.2.8 StrictMode, batching, root/ref conformance.
• [P0] 加固 ref 与无效属性语义 / Harden ref and invalid prop semantics #13 / PR fix: 加固 ref 与表单属性语义 / harden ref and form prop semantics #22: Rules of Hooks, DOM-ref lifecycle, and form-prop semantics.
• [P1] 完善 React 19 Forms 和 Actions 支持 / Complete React 19 Forms and Actions support #18 / PR feat: 完善 React 19 Forms 与 Actions / complete React 19 Forms and Actions #23: React 19 Forms, async Actions, optimistic state, and form status.
• [P1] 增加 Portal 并明确 Hydration/SSR 范围 / Add portals and define hydration and SSR scope #16 / PR feat: 完善 Portal 与 Hydration/SSR / complete portals and hydration scope #24: portals, root options, and basic Hydration/SSR.
• [P1] 增加外部 store 与组件集成 API / Add external-store and component integration APIs #14 / PR feat: 外部 store 与类型化组件集成 / external stores and typed component integration #25: external stores, memo/lazy/Suspense, JS component bridge, and imperative handles.
• [P2] 生成更广泛的 HTML/SVG typed helpers / Generate broader HTML and SVG typed helpers #15 / PR feat: 生成类型化 HTML/SVG helpers / generate typed HTML and SVG helpers #26: 54 generated typed HTML/SVG helpers, an all-helper smoke matrix, idempotence/interface gates, and real-DOM conformance.
• Current main baseline: MoonBit 54/54, Chromium 7/7, zero React/page diagnostics, generated helpers 54/54, successful production build, and green CI.

Phase 1: correctness and application foundations

• feat: add stable React node keys #11
• [P0] 扩展真实 React 符合度覆盖 / Expand real React conformance coverage #12
• [P0] 加固 ref 与无效属性语义 / Harden ref and invalid prop semantics #13
• [P0] Add typed React Context bindings #19

Phase 2: React 19 application integration

• [P1] 完善 React 19 Forms 和 Actions 支持 / Complete React 19 Forms and Actions support #18 — PR feat: 完善 React 19 Forms 与 Actions / complete React 19 Forms and Actions #23: Forms, Actions, and async/optimistic semantics
• [P1] 增加 Portal 并明确 Hydration/SSR 范围 / Add portals and define hydration and SSR scope #16 — PR feat: 完善 Portal 与 Hydration/SSR / complete portals and hydration scope #24: portals, root options, and basic Hydration/SSR
• [P1] 增加外部 store 与组件集成 API / Add external-store and component integration APIs #14 — PR feat: 外部 store 与类型化组件集成 / external stores and typed component integration #25: external-store and component integration APIs

Phase 3: API breadth and release discipline

• [P2] 生成更广泛的 HTML/SVG typed helpers / Generate broader HTML and SVG typed helpers #15 — PR feat: 生成类型化 HTML/SVG helpers / generate typed HTML and SVG helpers #26: generated HTML/SVG typed helpers
• [P1] 统一发布元数据并发布下一实验版本 / Normalize release metadata and ship the next experimental release #17 — PRs release: 准备可复现的 v0.2.0 发布 / prepare reproducible v0.2.0 release #27–test(release): 修正下游 helper 调用 / fix downstream helper call #30: exact registry 0.2.0, downstream 4/4, artifact verification, and immutable-tag/verifier decoupling complete

Current quantitative evidence for #17

• moon.mod / package.json: 2/2 aligned at 0.2.0.
• Changelog: 7 release sections, 6/6 historical GitHub tags covered, Unreleased entries: 0; local-only tags do not enter the public ledger.
• Working tree and clean clone: MoonBit 54/54, Chromium 7/7, zero diagnostics, successful production build.
• GitHub Release artifact: 17 files, 47,050 bytes, SHA-256 1631dd35bfeeb190d293ee33dcbf7d4cb0c826340cbb82fdbaf5e4683b7fc955; downloaded SHA256SUMS passes, unexpected files: 0.
• Historical gap resolved: GitHub v0.1.0 was never published to mooncakes.io; the new 0.2.0 was published by Actions and passed exact fresh-downstream verification 4/4.
• Publication verification artifact: mooncakes-0.2.0-verification, artifact id 9747734053, SHA-256 6a140f815127d7d808b7af49db64a66ab33980bef6752dc31cf37e1089871960.

Completion

• All 9/9 roadmap items are complete; phases 1, 2, and 3 are each at 100%.
• The React 19 binding's correctness, application integration, API breadth, and release discipline now have fixed quantitative gates; further work should be managed as a new roadmap cycle.

Shared quality gate for future PRs

1. Public API behavior maps to official contracts for the pinned React version, with conformance points listed in the PR.
2. FFI/conversion logic has deterministic MoonBit regressions; lifecycle, DOM, or scheduling behavior has real React browser cases.
3. Report total unit tests, browser scenarios, React/page diagnostics, and production build results.
4. React warnings/errors, page errors, and unhandled rejections must all be zero.
5. Public interfaces inspect moon info; generated content passes formatting, idempotence, and git diff --check.
6. Tests verify observable results or exact call/lifecycle counts, not merely execution.
7. Issues and PRs present Chinese and English separately, with evidence mapped to metrics.
8. Coverage distinguishes the MoonBit runner from real-browser execution and supplies browser evidence for DOM/async paths.
9. Generated APIs report entry count, category coverage, idempotence, and existing-interface compatibility.
10. Releases run only from a clean clone/main tag; version, Changelog, release title, artifact checksum, and exact downstream installation require automated gates and retained logs.

[tiye]

Release groundwork is implemented in PR #8: the module is prepared as version 0.1.0, MoonBit package creation is verified, and a tag-driven GitHub Release workflow packages the MoonBit archive. Registry publication remains an explicit maintainer action after MoonBit login, so no registry credential is added to CI.

[tiye]

PR #9 maintenance update: CI is green after completing the TodoMVC controlled toggle-all reducer/checkbox flow and converting filters to real, keyboard-accessible links while preventing client-side hash navigation. The Chromium regression now verifies toggle-all, per-item completion, filters, clearing, editing, and creation. Current evidence: 37 MoonBit tests, 7 uncovered lines (mostly entrypoint/dead defensive branches), production build, and green CI: https://github.com/Respo/react.mbt/actions/runs/33239510793. The release remains intentionally pending PR review and merge to main.

[tiye]

Release preflight on PR #9 head 59b1213 completed successfully: moon update, moon check --target js, moon test (37 passed), moon info/fmt with no diff, yarn build, and moon package --list. The package archive was produced at _build/publish/tiye-react-0.1.0.zip. The only build diagnostic remains LightningCSS warning about the third-party todomvc-app-css input::input-placeholder selector; Vite still completes successfully. Tagging and publishing remain pending review/merge of PR #9.

[tiye]

Released v0.1.0 from merged PR #9. The GitHub Release workflow completed successfully and attached tiye-react-0.1.0.zip (MoonBit package archive). Registry publication remains a separate maintainer action when credentials and publication scope are ready.

[tiye]

中文

路线图 9/9 完成（100%），阶段 1/2/3 均为 100%。最后一项 #17 已随 PR #30 合并闭环：GitHub Release、mooncakes 0.2.0、精确下游 4/4 和 verifier 固化均已完成。

最终基线：MoonBit 54/54、Chromium 7/7、React/page diagnostics 0、生成 helper 54/54、production build 成功。后续新增范围应进入下一轮中英文路线图，并继续沿用本 Issue 的量化质量门槛。

---

English

The roadmap is 9/9 complete (100%), with phases 1/2/3 each at 100%. The final item, #17, closed with PR #30: GitHub Release, mooncakes 0.2.0, exact downstream 4/4, and verifier persistence are all complete.

Final baseline: MoonBit 54/54, Chromium 7/7, zero React/page diagnostics, generated helpers 54/54, and a successful production build. New scope should enter a new bilingual roadmap cycle and retain this Issue's quantitative quality gates.