发布渐进式组件作者 API / Publish a progressive component authoring surface

[tiye]

中文

目标

让第一次使用 Respo 的组件作者先通过 elements、keyed components、typed stores/actions 和 effects 四个概念完成日常开发，而不必先理解 state entries、registry、snapshot transport 或 runtime handler。

改动

• 新增双语 quick start，用一个 FAQ feature 串联 stateless view、typed store、keyed list 与 persistent feature。
• 新增双语单页 component author API，固定 positional content、labelled configuration 与 trailing-lambda lifecycle boundary 的推荐写法。
• 将 VDOM、event registry 与 runtime entry 的只读查询实现从 core/state 移到 explore/react/inspection。
• 将 registered callback 执行、scheduled effect 与 snapshot transport 的真实实现从 state 移到 explore/react/runtime。
• 保持业务 view 只依赖 core/action/state；host 与 tests 显式导入 advanced modules，没有增加 re-export facade 或单行 forwarding wrapper。
• 更新 README、PLAN 与 Agents 开发引导，使 authoring tasks 成为入口，并记录后续模块拆分约束。

验证

• yarn test:koka：70 / 70 通过。
• yarn check：Koka 编译与 Vite production build 通过。
• quick start 完整示例通过 Koka library 编译检查。
• 业务 demo view advanced-import guard 通过。
• 浏览器验证新增任务、typed action 切换、editor local-store 输入与整页 reload 后 snapshot 恢复；无 warning/error。

Review 重点

• 三个 authoring modules 与两个 advanced modules 的边界是否符合使用者心智模型。
• quick start 是否足够渐进，且没有泄漏 runtime/tree/registry 细节。
• 真实实现迁移是否保持 API 行为并避免包装层。

关联 issue：#13

English

Goal

Let a first-time Respo component author complete everyday work through four concepts—elements, keyed components, typed stores/actions, and effects—without first learning about state entries, registries, snapshot transport, or runtime handlers.

Changes

• Add a bilingual quick start that connects a stateless view, typed store, keyed list, and persistent feature in one FAQ example.
• Add a bilingual one-page component author API with consistent positional content, labelled configuration, and trailing-lambda lifecycle boundaries.
• Move the real read-only VDOM, event-registry, and runtime-entry query implementations from core/state to explore/react/inspection.
• Move registered callback execution, scheduled effects, and snapshot transport implementations from state to explore/react/runtime.
• Keep business views dependent only on core/action/state; hosts and tests import advanced modules explicitly, with no re-export facade or one-line forwarding layer.
• Update README, PLAN, and Agents guidance so authoring tasks are the entry point and future module-splitting constraints remain documented.

Verification

• yarn test:koka: 70 / 70 passed.
• yarn check: Koka compilation and the Vite production build passed.
• The complete quick-start example passed Koka library compilation.
• The business-demo advanced-import guard passed.
• Browser coverage verified task creation, typed-action toggling, editor local-store input, and snapshot restoration after a full reload, with no warnings or errors.

Review focus

• Whether the three authoring modules and two advanced modules match the user mental model.
• Whether the quick start is progressive without leaking runtime/tree/registry details.
• Whether implementation movement preserves behavior without adding wrappers.

Closes #13

[Copilot]

Pull request overview

This PR formalizes a progressive-disclosure component authoring surface for Respo by (1) documenting the “normal path” as elements, keyed components, typed stores/actions, and effects, and (2) physically separating advanced host/testing functionality into dedicated modules (explore/react/runtime and explore/react/inspection) so business views can stay on core/action/state.

Changes:

• Add bilingual authoring docs: a task-oriented quick start and a one-page component author API reference.
• Split advanced implementations out of authoring modules: move snapshot transport + callback/effect runners to runtime, and read-only VDOM/registry/runtime queries to inspection.
• Update tests/boilerplate/docs to import the new advanced modules explicitly, and refresh repository guidance (README/PLAN/Agents) to match the new boundaries.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Adds “start with component authoring” entry path and updates module map to include runtime/inspection and new docs.
PLAN.md	Updates the module-splitting plan/status to reflect the completed authoring vs advanced-module separation.
Agents.md	Updates the onboarding flow and codifies the “business views only import core/action/state” boundary.
explore/react/core.kk	Removes test/devtools VDOM query helpers from the authoring core surface.
explore/react/state.kk	Removes host/testing-oriented runtime/inspection helpers from the authoring state surface.
explore/react/runtime.kk	Introduces host-only runtime module for registered callback execution, scheduled effects, and snapshot transport.
explore/react/inspection.kk	Introduces inspection module for read-only VDOM, event-registry, and runtime-tree queries for tests/devtools.
docs/quick-start.md	Adds bilingual quick start that teaches the four authoring concepts via a cohesive FAQ feature example.
docs/component-authoring.md	Adds bilingual one-page “preferred author API” inventory and clearly documents advanced-module audiences.
demo/tests/support.kk	Updates test harness utilities to import and use runtime/inspection helpers explicitly.
demo/tests/basics.kk	Updates tests to use moved runtime/inspection APIs (registered handlers, snapshot helpers, vnode queries).
demo/tests/todocases.kk	Imports runtime/inspection for snapshot/inspection helpers used in todo tests.
demo/tests/statecases.kk	Imports runtime/inspection for snapshot/inspection helpers used in state tree tests.
demo/tests/labcases.kk	Imports inspection for registry/vnode queries used in lab tests.
demo/tests/dialogcases.kk	Imports inspection for registry/vnode/runtime-tree queries used in dialog tests.
demo/tests/appharness.kk	Imports runtime/inspection for harness-level snapshot/handler execution and inspection calls.
boilerplate/browserapp.kk	Updates the browser host to import runtime/inspection for snapshot transport and registry warnings/queries.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.