交付可运行的首个组件示例 / Ship a runnable first-component example

[tiye]

中文

用户可见结果

• 新增 yarn example:first-component：从 clean checkout 编译并运行一个真实的 typed-store 组件。
• 命令在一屏输出初始 closed UI、Toggle_disclosure serializable action 和更新后的 open UI。
• docs/quick-start.md 现在链接可编译的 component source，而不是维护第二份 FAQ 教程实现。

安全与生命周期

• examples/first_component/component.kk 只使用 import explore/react；renderer、inspection、runtime 和 state tree plumbing 只在明确标注为 advanced 的 main.kk host 中出现。
• author-surface check 现同时禁止业务/example component 直接导入 author internals 或 advanced framework modules，并继续允许显式 host/tests 边界。
• 示例使用 snapshot store、稳定 feature boundary 和一个有限 action；不改变浏览器 runtime、HMR 或现有 app state 的生命周期语义。

文档

• 更新 README、quick start、component authoring guide、开发指南与路线图。
• .koka-example/ 已加入忽略列表，避免示例 build artifact 进入工作树。

验证

• yarn example:first-component
• yarn test:koka
• yarn check
• 真实浏览器回归：Todo 新增，Lab 路由往返后状态保留，控制台无 warning/error。

关联 issue

Closes #24

English

User-visible result

• Added yarn example:first-component, which compiles and runs one real typed-store component from a clean checkout.
• The command prints an initial closed UI, the serializable Toggle_disclosure action, and the updated open UI on one screen.
• docs/quick-start.md now links to compiled component source instead of maintaining a second FAQ tutorial implementation.

Safety and lifecycle

• examples/first_component/component.kk uses only import explore/react; renderer, inspection, runtime, and state-tree plumbing exist only in the explicitly advanced main.kk host.
• The author-surface check now rejects both author internals and advanced framework modules in business/example components while keeping explicit host/test boundaries valid.
• The example uses a snapshot store, stable feature boundary, and one finite action. It does not change browser-runtime, HMR, or existing app-state lifecycle semantics.

Documentation

• Updated the README, quick start, component authoring guide, developer guide, and roadmap.
• Added .koka-example/ to ignores so example build artifacts do not enter the working tree.

Verification

• yarn example:first-component
• yarn test:koka
• yarn check
• Real-browser regression: add a Todo, navigate to Lab and back with state preserved, and confirm no console warnings/errors.

Related issue

Closes #24

[coderabbitai]

Warning

Review limit reached

Next included review available in 23 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f78017cd-990e-44c9-8c34-aeec11393879

📥 Commits

Reviewing files that changed from the base of the PR and between a2e44af and 6d405ef.

📒 Files selected for processing (11)

• .gitignore
• Agents.md
• PLAN.md
• README.md
• docs/component-authoring.md
• docs/quick-start.md
• examples/first_component/component.kk
• examples/first_component/main.kk
• package.json
• scripts/check-author-surface.mjs
• scripts/run-first-component.mjs

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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