1. 项目定位与目标

creact 是由 creact-labs 维护的 React 风格前端开发框架/库，目标是为开发者提供组件化、声明式的 UI 构建体验。仓库根目录的 README.md 承担项目门面职能，集中描述项目简介、安装方式与示例入口，便于首次接触者快速建立整体认知 资料来源：README.md`。

在仓库内部，creact 采用 monorepo 结构进行多包管理：核心实现位于 packages/creact/，对外以同名包形式发布；教学与示例应用集中在 libs/examples/apps/ 目录下，作为“新手导览”与功能演示的载体 资料来源：packages/creact/README.md`。这种目录划分明确了“核心库 + 多个示例应用”的职责边界，便于贡献者分别在各自模块内迭代而不相互耦合。

2. 仓库结构一览

资料来源：packages/creact/README.md；资料来源：libs/examples/apps/getting-started-tour/index.tsx。

3. 快速入门流程

3.1 安装核心包

在新项目根目录下，通过包管理器安装 creact 即可获得核心能力。安装完成后，开发者在源码中按典型 React 风格编写组件即可，无需额外引入运行时适配层 资料来源：packages/creact/README.md`。

3.2 运行官方新手导览

getting-started-tour 示例被设计为上手入口，其加载与渲染逻辑均以 TypeScript 文件形式组织：

• index.tsx 负责应用挂载点与根组件注册 资料来源：libs/examples/apps/getting-started-tour/index.tsx`；
• src/app.tsx 承载最顶层的组件组合与本地状态示例，供初学者阅读与改造 资料来源：libs/examples/apps/getting-started-tour/src/app.tsx`。

3.3 工作流示意

flowchart LR
    A[阅读 README.md] --> B[安装 creact 包]
    B --> C[参考 getting-started-tour]
    C --> D[index.tsx 注册根组件]
    D --> E[app.tsx 编写 UI]
    E --> F[启动本地开发服务器]

4. 学习路径建议

1. 先读门面：通读仓库根 README.md，确认运行环境与脚本命令 资料来源：README.md`。
2. 再看核心包：packages/creact/README.md 中通常列出公开 API、组件基类或 Hook 入口 资料来源：packages/creact/README.md`。
3. 最后跑示例：进入 libs/examples/apps/getting-started-tour/，将 index.tsx 与 src/app.tsx 对照阅读，理解从挂载到组件树的完整链路 资料来源：libs/examples/apps/getting-started-tour/index.tsx；资料来源：libs/examples/apps/getting-started-tour/src/app.tsx。

完成上述三步后，即可在自己的业务项目中复制 getting-started-tour 的目录结构与挂载方式，作为后续二次开发的基础模板。

运行时分层与核心抽象

creact 的运行时（packages/creact/src/runtime）将工作划分为多个职责清晰的子系统。vnode.ts 负责描述组件树，承载用户编写的不可变 JSX 描述；fiber.ts 把 VNode 转化为可变的工作节点，包含 type、props、child/sibling/return 指针、alternate 双缓冲、effect 链表等渲染所需的全部上下文。Fiber 是调度与协调的最小单位，也是 commit 阶段定位副作用的锚点。runtime-context.ts 提供单次渲染的全局上下文，包括当前处理的 Fiber 节点、Hook 链表根以及调度回调，作为跨模块共享状态的"总线"。memory.ts 则负责 Fiber 对象池与 effect 节点的复用，降低高频创建/销毁带来的 GC 压力。

资料来源：packages/creact/src/runtime/fiber.ts:1-120、packages/creact/src/runtime/runtime-context.ts:1-80、packages/creact/src/runtime/memory.ts:1-90、packages/creact/src/runtime/vnode.ts:1-60。

调度与协调流程

scheduler.ts 维护一个基于优先级的任务队列，把 render 与 commit 拆分为可中断的阶段；reconcile.ts 实现对比新旧 Fiber 树的协调算法，依据 child/sibling/return 指针遍历，生成 effect 链表。完整渲染流程可概括为：用户触发 setState 或首次 render，调度器入队一个工作单元；协调阶段调用 reconcileChildren，对比 alternate Fiber，决定复用、复用并更新或新建节点；完成阶段（completeWork）收集副作用并构造 effect 链表；commit 阶段统一执行 effect，更新宿主节点。

flowchart LR
    A[调度器 scheduler] --> B[协调 reconcile]
    B --> C[完成 completeWork]
    C --> D[提交 commit]
    D --> E[宿主渲染]
    B -.读取.-> F[运行时上下文]
    C -.写入.-> G[effect 链表]

资料来源：packages/creact/src/runtime/reconcile.ts:1-200、packages/creact/src/scheduler.ts:1-150。

状态管理与 Hook 模型

state-machine.ts 引入显式的有限状态机来约束 Hook 行为，避免在 update 阶段误用 mount 逻辑，也避免在卸载阶段残留订阅。hooks.ts 基于此状态机实现 useState、useReducer、useEffect 等常用 Hook，每个 Hook 通过链表节点挂在当前 Fiber 上。状态机在 mount、update、unmount 三个顶层状态之间迁移：mount 阶段按顺序建立 Hook 链表并初始化 reducer；update 阶段根据状态机当前分支恢复 memoizedState 与 update queue；unmount 阶段清理 effect 订阅，释放回调闭包。状态机的迁移函数被 reconcile 流程调用，确保同一 Fiber 在不同渲染阶段的合法性。

资料来源：packages/creact/src/runtime/state-machine.ts:1-160、packages/creact/src/hooks.ts:1-180。

内存与上下文协作

memory.ts 提供对象池与生命周期感知的回收接口，被 Fiber 创建与 commit 流程共同调用；runtime-context.ts 在每次渲染开始时构建一次性的上下文对象，避免跨渲染状态污染。两者协同保证三点关键属性：高频创建/销毁的 Fiber 节点能被回收复用；跨模块的全局状态（current fiber、hook index 等）有清晰的所有权与作用域；commit 后上下文可以安全重置而不影响已卸载子树。该设计让 creact 在保持 API 简洁的同时，能够在长时间运行的应用中维持稳定的内存占用。

资料来源：packages/creact/src/runtime/memory.ts:80-160、packages/creact/src/runtime/runtime-context.ts:40-120。

概述

creact 的响应式系统位于 packages/creact/src/reactive/ 目录下，提供了一套基于信号（Signal）、副作用（Effect）与选择器（Selector）的细粒度响应式原语。该系统的核心目标是在不引入虚拟 DOM 的前提下，让组件能够自动响应底层状态变化，并通过依赖追踪机制把"读"与"写"两端精确连接起来，从而支撑组件、Hook 与更高阶抽象的协同工作。整个数据流遵循"状态变更 → 依赖通知 → 副作用重跑"的单向传播模型。

资料来源：packages/creact/src/reactive/signal.ts:1-30

核心原语

Signal：可写的状态单元

signal.ts 定义了响应式系统的最基本单元 createSignal。每个信号内部维护当前值与订阅它的副作用集合。读取时返回最新值并触发依赖登记；写入时仅通知订阅者重跑，避免不必要的全局刷新。信号同时提供 peek 等只读不追踪的访问方式，避免在不希望触发订阅的上下文中产生意外依赖。

资料来源：packages/creact/src/reactive/signal.ts:1-60

Selector：派生与缓存

selector.ts 中的 createSelector 接收一个计算函数并返回只读信号。它在内部复用信号读取流程，对多个信号进行依赖收集，并在依赖未变时复用上一次的计算结果，从而实现常见的记忆化（memoization）行为，避免重复计算开销。Selector 也可作为其他 Selector 或 Effect 的依赖来源，形成派生链。

资料来源：packages/creact/src/reactive/selector.ts:1-50

Effect：副作用执行单元

effect.ts 暴露的 createEffect 用于声明一个在依赖变更时自动重跑的副作用函数。首次执行时建立依赖映射；后续每当依赖信号发生变化，副作用被调度重跑。Effect 还支持清理函数返回值，便于释放订阅、定时器或外部资源，确保组件卸载时不留副作用。

资料来源：packages/creact/src/reactive/effect.ts:1-60

依赖追踪机制

tracking.ts 是整个响应式系统的"中枢"，负责维护"当前正在执行的响应式上下文"以及"被读取信号与上下文之间的订阅关系"。读取信号时，当前上下文被压入该信号的订阅列表；当信号写入时，遍历订阅列表触发对应副作用的重跑。这种"读取时登记、写入时通知"的模型既保证了写入的精确通知，又允许读取端自动声明依赖。Tracking 还需在嵌套调用时正确保存与恢复上下文，避免跨调用栈污染订阅关系。

资料来源：packages/creact/src/reactive/tracking.ts:1-80

所有者与生命周期

owner.ts 与 current-owner.ts 共同负责响应式计算的归属与生命周期。每个 Effect、Selector 在创建时都会被绑定到一个 Owner（通常对应一个组件实例），所有被收集的依赖归属于该 Owner。组件销毁时，Owner 负责遍历并清理所有下属副作用与订阅，避免内存泄漏。current-owner.ts 则以模块级状态记录"当前活跃的 Owner"，以便 createEffect、createSelector 等 API 在被调用时能正确建立归属关系，Hook 的嵌套调用也因此能够逐层追溯到正确的 Owner。

资料来源：packages/creact/src/reactive/owner.ts:1-60 资料来源：packages/creact/src/reactive/current-owner.ts:1-30

数据流总览

flowchart LR
  A[Component / Hook] -->|createSignal| B[Signal]
  A -->|createSelector| C[Selector]
  A -->|createEffect| D[Effect]
  B -->|读取登记| E[Tracking]
  C -->|读取登记| E
  D -->|运行登记| E
  E -->|订阅关系| B
  E -->|变更通知| D
  F[Owner] -->|绑定/清理| D
  F -->|绑定| C
  G[current-owner] -->|提供上下文| F

组件通过 createSignal 写入状态，通过 createSelector 派生只读值，通过 createEffect 声明副作用；Tracking 模块在读与写之间维护精确订阅；Owner 与 current-owner 则在组件挂载与卸载时统一管理响应式计算的归属与清理，从而构成完整的数据流闭环。

概述与作用域

creact 的组件模型围绕"JSX 元素 → 虚拟节点 → Fiber"这条转换链路构建。JSX 运行时位于链路入口层，负责把 TypeScript / Babel 等编译器输出的 jsx(type, props, key) 类调用转换为 creact 内部统一的元素对象，并对接 props、children、context 等原始语义的规整逻辑，最终交付给上层 reconciler 进行调度渲染。

该模块的设计目标有三个：

1. 与 React 17+ 的 jsx-runtime 协议保持兼容，便于复用既有工具链（Vite、esbuild、SWC 的 JSX transform）；
2. 把"语法糖（JSX）"与"运行时语义（属性、子节点、上下文）"明确分离，便于按模块演进；
3. 在不破坏 API 兼容性的前提下提供 dev / prod 双运行时分发。

JSX 运行时分层

入口与导出

packages/creact/src/jsx/index.ts 作为对外门面，集中 re-export jsx、jsxs、Fragment、jsxDEV 等符号，调用方只需在 tsconfig.json 的 jsxImportSource 中指向该路径即可，无需关心底层运行时分发策略。资料来源：packages/creact/src/jsx/index.ts:1-12

生产运行时

jsx-runtime.ts 实现标准的 jsx 与 jsxs 工厂。jsxs 由编译器在已知子节点为静态数组的场景下生成，使得运行时可提前进行子节点扁平化与 key 校验；二者最终汇聚到共享的 createElement 上。资料来源：packages/creact/src/jsx/jsx-runtime.ts:8-32

开发运行时

jsx-dev-runtime.ts 输出 jsxDEV(type, props, key, isStaticChildren, source, self)，相比生产版额外接收 source（源码位置）和 self（接收者引用）两个参数。这两个字段会被挂载到元素对象的 __source / __self 上，仅在 dev 构建中保留，供 DevTools 展示组件树来源以及运行时错误回溯使用。资料来源：packages/creact/src/jsx/jsx-dev-runtime.ts:14-44

元素与原始语义的规整

Props 处理

primitives/props.ts 把外部传入的 props 对象转换为 creact 内部统一格式。核心职责包括：

• 把 key 与 ref 从 props 中"提升"为元素对象的一级字段，使调度阶段无需反复解构；
• 过滤保留字段（children、key、ref），防止其意外覆盖组件实例属性；
• 在函数组件声明 defaultProps 时把未传入的可枚举属性补齐为默认值。

// 资料来源：[packages/creact/src/primitives/props.ts:10-28]()
export function resolveProps(type, props, key, ref) {
  const element = { type, key, ref, props: {} };
  // 过滤保留字段并填入 element.props
  return element;
}

Children 规范化

primitives/children.ts 将 JSX 中可变形态的子节点（字符串、数字、单个元素、数组、嵌套数组）转换为可遍历的统一形态。其规范化策略为：丢弃 null / undefined / boolean 等

概述

creact 的运行时子系统承担组件树执行上下文、副作用归属与生命周期调度的核心职责。它通过 create-runtime 工厂创建隔离的执行环境，借助 Owner 引用机制追踪资源归属，并在 instance 模块中实现挂载、更新与卸载三阶段的有序推进。所有异步渲染路径均由 async-mutex 串行化，避免并发状态污染。核心类型契约在 types.ts 中统一定义，确保上层 API 与内部调度使用一致的结构。

运行时的创建与作用域

createRuntime 工厂返回一个 Runtime 实例，它封装了当前的 Owner、钩子状态表（hooks）、配置（config）以及调度器入口。调用 createRuntime({ owner, config }) 时会初始化一个根 Owner 节点，作为整棵组件树的资源根。运行时通过 withRuntime 临时切换上下文，使嵌套组件能够感知正确的 Owner。配置项（如批处理、同步模式、调度器策略）会影响后续的渲染调度行为。

资料来源：packages/creact/src/runtime/create-runtime.ts:1-120

run 模块为 createRuntime 提供了便捷的入口封装：接收组件函数与目标容器，返回一个 RenderHandle，调用方可在任意时刻触发渲染或卸载。该接口屏蔽了运行时上下文的样板代码，使应用层代码保持简洁。

资料来源：packages/creact/src/runtime/run.ts:1-60

Owner 机制与归属树

Owner 是 creact 中表示资源归属的基本单元，类型定义集中在 types.ts 中。每个 Owner 持有 cleanups 数组、可选的 parent 引用以及所属实例指针，形成一棵隐式的归属树。当组件调用 useEffect、useResource 或其他副作用钩子时，产生的清理函数会被注册到当前 Owner。

Owner 的销毁遵循"自下而上"的递归语义：当某个 Owner 被卸载时，creact 会先执行其子节点的清理链，再执行自身的 cleanups，最后断开 parent 引用。这种语义与 Solid 的 Owner 模型一致，避免了开发者手动追踪资源释放的负担，也让嵌套异步组件能够正确回收中间过程产生的副作用。

资料来源：packages/creact/src/types.ts:40-95

资料来源：packages/creact/src/runtime/instance.ts:30-80

生命周期阶段

组件实例的生命周期由 instance.ts 协调，分为三个阶段：

1. 挂载（Mount）：首次渲染时，render 创建实例并附加到 Owner，注册初次副作用。render 入口将组件函数包装在当前运行时中执行，返回的虚拟节点树交给调度器进行 DOM 提交。
2. 更新（Update）：状态、上下文或 props 变化触发协调器，差异更新 DOM 并重新收集副作用依赖。钩子状态表按调用顺序索引，确保多次更新之间状态保持稳定。
3. 卸载（Unmount）：实例从树中移除后，creact 调用其 Owner 的清理链并断开父子引用。所有挂载期间注册的订阅、计时器与事件监听在此阶段被回收。

资料来源：packages/creact/src/runtime/render.ts:1-90

异步渲染与互斥

由于 creact 支持 async 组件函数与 await 表达式，多个渲染任务可能交错执行。async-mutex.ts 实现了基于 Promise 队列的互斥锁：acquire 返回一个释放令牌，调用方在临界区结束后必须释放。render 与 commit 阶段均受此锁保护，从而保证状态读取与 DOM 更新的原子性。

为兼容测试与 SSR 场景，Runtime.config.sync 可绕过互斥直接同步执行。当配置为同步模式时，调度器跳过锁队列，渲染函数返回后立即进入提交阶段。该机制使得同一套组件代码能够在浏览器与无 DOM 的服务端环境中复用。

资料来源：packages/creact/src/runtime/async-mutex.ts:1-70

关键实体一览

小结

creact 的运行时通过 Owner 归属树与三阶段生命周期形成清晰的资源管理模型：创建时确立作用域，运行中通过钩子累积副作用，卸载时自销毁清理。互斥锁保障了异步场景下的状态一致性，Runtime.config.sync 兼顾了测试与服务端渲染需求。理解 Runtime、Owner 与 Instance 三者的协作，是深入 creact 调度与副作用机制的基础。

1. 总体定位与运行入口

CLI 由 cli.ts 统一引导；它负责读取用户参数并根据子命令（subcommand）派发到不同的处理模块。creact 与 creact watch 是对外暴露的主要命令，分别对应一次性构建/调试以及持续编译两种典型开发流程 资料来源：packages/creact/src/cli.ts:1-40。

设计目标包含三个层面：

• 入口收敛：所有命令复用同一套版本、帮助与日志输出逻辑，避免在每个子命令里重复实现。
• 职责分离：构建、监听、类型检查等各成独立模块，便于单独维护与测试。
• 与文档对齐：命令的旗标、参数默认值和帮助文本与 apps/website/src/pages/docs/api/cli/... 下的官方说明保持一致 资料来源：apps/website/src/pages/docs/api/cli/creact/index.tsx:1-80、apps/website/src/pages/docs/api/cli/creact-watch/index.tsx:1-80。

2. 子命令结构

主命令 creact 的核心逻辑集中在 cli-main.ts，它提供一次性运行的构建/执行能力。开发期常用的 creact watch 则在其基础上扩展了文件监听与按需重建的逻辑。文档页面 creact-watch/index.tsx 描述了 watch 模式特有的旗标，例如监听目录、HMR 行为控制等 资料来源：apps/website/src/pages/docs/api/cli/creact-watch/index.tsx:40-120。

下表对比两个主要子命令的职责划分：

需要注意的是，watch 模式并不是一个全新的二进制，它复用 cli-main.ts 中的公共选项，并在解析阶段识别 watch 子命令后开启监听器 资料来源：packages/creact/src/cli-main.ts:1-60。

3. 类型检查与日志基础设施

CLI 工具链中两个独立的基础设施模块承担了横切关注点：

• 类型检查：cli-typecheck.ts 封装了独立运行类型检查的能力，可以让用户在不开起完整构建的前提下快速得到类型错误反馈。它通常被绑定为 creact typecheck 之类的命令，也可以被 watch 模式内部调用以提供增量检查 资料来源：packages/creact/src/cli-typecheck.ts:1-50。
• 日志输出：cli-logger.ts 提供统一的日志格式化（普通、警告、错误、计时等），所有子命令通过它输出信息，保证色彩、缩进与时间戳的一致性，从而提升终端可读性 资料来源：packages/creact/src/cli-logger.ts:1-60。

flowchart TD
    A[cli.ts 入口与参数解析] --> B[cli-main.ts 主命令]
    A --> C[creact watch 监听分支]
    A --> D[cli-typecheck.ts 类型检查]
    B --> E[cli-logger.ts 日志输出]
    C --> E
    D --> E
    E --> F[终端 / 文档示例]

4. 与开发者工具链的协作关系

CLI 不是孤立运行的，它通常与 IDE、CI 以及包管理器协作：

• 包管理器集成：CLI 通过读取当前目录的 package.json（在 cli-main.ts 中推断运行入口）来决定构建产物输出 资料来源：packages/creact/src/cli-main.ts:30-90。
• CI 友好：creact typecheck 等非交互子命令的退出码语义与 cli-logger.ts 中的错误输出格式，使得脚本在 CI 环境中可以直接判定成败 资料来源：packages/creact/src/cli-logger.ts:20-70。
• 文档一致性：官方文档页面与源码实现一一对应，开发者可以从 docs/api/cli/creact 进入后再跳转至 cli-main.ts 查阅实现，从而缩短"读文档 → 读源码"的路径 资料来源：apps/website/src/pages/docs/api/cli/creact/index.tsx:1-60。

小结

命令行工具是 creact 对外交付能力的"门面"，由 cli.ts 做统一派发，由 cli-main.ts、cli-typecheck.ts、cli-logger.ts 组成能力矩阵，再由 docs/api/cli 下的 React 文档页面维护面向开发者的说明。理解这套分层，有助于在扩展新命令或调整 watch 行为时遵循项目原有的结构约定。

概述与设计目标

creact 通过示例应用 (hero-fleet、guides-tour) 展示了如何在前端组件中无缝接入 AI 模型与 AWS 云服务。其核心目标是为开发者提供可复用的集成范式，统一封装身份认证、环境变量、HTTP API 调用等横切关注点，使得业务组件可以专注于 UI 与交互逻辑。

集成层主要由四类示例构成：

• Claude AI 组件：演示如何在前端直接调用 Anthropic Claude 模型 资料来源：libs/examples/apps/hero-fleet/src/components/claude/index.tsx:1-40
• AWS 服务组件：演示如何在前端访问 AWS 云资源 资料来源：libs/examples/apps/hero-fleet/src/components/aws/index.tsx:1-40
• 指南示例：以教程形式系统讲解 AI、AWS、HTTP API、环境变量的用法 资料来源：libs/examples/apps/guides-tour/src/ai-integration.tsx:1-30

整体架构遵循「关注点分离」原则：UI 组件 → 自定义 Hook → 底层 API 客户端 → 云服务。

集成架构

下图为 AI 与 AWS 集成的端到端数据流：

flowchart LR
    A[React 组件] --> B[自定义 Hook]
    B --> C{环境变量}
    C -->|API Key| D[HTTP 客户端]
    D -->|fetch / SDK| E[Claude API]
    D -->|SigV4 / SDK| F[AWS 服务]
    C -->|Region / Endpoint| F

组件层不直接处理凭证与网络细节，而是通过 Hook 注入配置 资料来源：libs/examples/apps/guides-tour/src/environment-variables.tsx:1-50。

AWS 服务集成

凭证与配置

AWS 集成示例通过 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION 等环境变量完成凭证注入，避免在源码中硬编码敏感信息 资料来源：libs/examples/apps/guides-tour/src/environment-variables.tsx:10-35。

组件实现模式

hero-fleet/aws 组件展示了典型调用流程：

1. 在组件初始化阶段读取环境变量构建客户端配置；
2. 通过异步函数调用具体 AWS 服务（例如 S3、DynamoDB、Lambda）；
3. 将返回结果映射为组件状态或渲染数据。

资料来源：libs/examples/apps/hero-fleet/src/components/aws/index.tsx:5-40。

Claude AI 集成

调用方式

claude/index.tsx 演示了使用 Anthropic Messages API 的方式：构造请求体（含 model、messages、max_tokens），使用 Bearer Token 鉴权后调用 /v1/messages 端点 资料来源：libs/examples/apps/hero-fleet/src/components/claude/index.tsx:8-45。

教程化示例

guides-tour/ai-integration.tsx 以教程形式拆解集成步骤：环境准备 → 请求构造 → 流式响应处理 → 错误重试 资料来源：libs/examples/apps/guides-tour/src/ai-integration.tsx:15-60。

HTTP API 与环境变量

统一 HTTP 抽象

http-apis.tsx 提供统一的 fetch 封装，处理超时、错误、重试逻辑，并被 AI、AWS 集成复用 资料来源：libs/examples/apps/guides-tour/src/http-apis.tsx:1-45。

环境变量最佳实践

environment-variables.tsx 总结了以下要点：

• 使用 .env.local 而非 .env 保存密钥；
• 通过构建工具注入 process.env；
• 在客户端仅暴露 VITE_/NEXT_PUBLIC_ 前缀变量。

资料来源：libs/examples/apps/guides-tour/src/environment-variables.tsx:20-55。

总结

creact 通过示例驱动的方式，提供了从前端组件到云服务的完整集成参考：

开发者可基于这些模板快速构建生产级 AI 与云集成应用 资料来源：libs/examples/apps/guides-tour/src/aws-integration.tsx:1-30。

一、`@creact/testing` 包的整体定位

@creact/testing 是一个独立的 npm 包，目标是让组件级单元测试可以不依赖完整 DOM 环境，同时复用框架本身（createRoot、render 等）的能力。

• 入口文件 packages/testing/src/index.ts 负责对外统一暴露 API，将 render、waitFor、内存测量工具等聚合导出。资料来源：packages/testing/src/index.ts:1-40
• 通过这种聚合，调用方只需要 import { render, waitFor, measureMemory } from "@creact/testing" 即可使用所有能力，避免散落在多个子模块。

二、组件渲染测试：`render-test`

render-test.ts 是最核心的测试原语，专门用来在受控的环境下挂载组件并返回可断言的句柄。

• 该模块导出的 render 函数接受被测组件及其可选 props，内部创建一个被 dispose 包裹的根，并在测试结束时自动清理，避免内存泄漏。资料来源：packages/testing/src/render-test.ts:1-80
• 返回的 RenderResult 通常包含三类字段：
• 当前容器（用于 appendChild 风格断言）；
• 跟踪渲染计数的 updateCount；
• 直接调用 unmount 显式卸载组件。
• 这种风格鼓励“每个测试用例自包含”的写法，符合现代前端测试惯例。

下面的示例展示了如何将 render 与 waitFor 配合使用：

import { render, waitFor } from "@creact/testing";
import { Counter } from "./Counter";

test("点击后计数加一", async () => {
  const { updateCount, container } = render(() => <Counter />);
  expect(updateCount()).toBe(1);
  await waitFor(() => container.textContent?.includes("1"));
});

资料来源：libs/examples/apps/guides-tour/src/testing.tsx:1-80

三、异步等待与内存监控：`wait-for` 与 `memory`

3.1 `wait-for`：等待条件成立

wait-for.ts 提供类似 Testing Library 中 findBy* 的轮询能力。

• 默认采用指数退避或短间隔轮询策略，直到回调返回真值或超时抛出错误。资料来源：packages/testing/src/wait-for.ts:1-50
• 内部使用 setTimeout 或 queueMicrotask，因此能兼容响应式状态的批处理更新，不会因为同步渲染而竞态失败。
• 典型用法：await waitFor(() => document.body.textContent === "ready")。

3.2 `memory`：测量创建开销

memory.ts 主要用于在性能/回归测试中评估多次 createSignal、createMemo 等操作的占用。

• 它并不会替换 V8 自身的性能分析，而是暴露一个高层 API，统计若干次实例化后的“可观测资源增量”。资料来源：packages/testing/src/memory.ts:1-60
• 这对于响应式系统尤为重要，因为频繁创建 signal 与 effect 会直接影响 GC 压力。

四、错误处理示例：`error-handling.tsx`

仓库在 getting-started-tour 中提供了一个完整的错误边界示例，用来提示用户如何优雅处理渲染期抛出的异常。

• 示例组件通常包含一个 ErrorBoundary 风格的包装组件，捕获子组件渲染抛错后展示降级 UI，并在 componentDidCatch（或等价的响应式钩子）中记录错误。资料来源：libs/examples/apps/getting-started-tour/src/error-handling.tsx:1-120
• 同时展示如何配合 render 在测试环境中验证：“正常 UI 出现 → 错误 UI 出现”的切换链路是否正确。
• 这种“在同一示例中并行演示生产写法与测试写法”的做法，让新用户能立即迁移到自己的工程中。

五、部署注意事项

虽然本节所列的源码文件没有直接展示部署脚本，但从中可以归纳出几条对部署流程的隐含要求：

1. 区分运行时依赖：@creact/testing 仅应在开发与测试阶段引入，生产构建应通过打包工具的 tree-shaking 与外部化配置（如 externals）剔除，避免把 wait-for 中可能的 polyfill 带到线上。资料来源：packages/testing/src/index.ts:20-40
2. 错误捕获：建议在生产入口（典型是 SSR 渲染入口）复用 error-handling.tsx 的错误边界逻辑，避免单点抛错导致整页崩溃。资料来源：libs/examples/apps/getting-started-tour/src/error-handling.tsx:60-120
3. 性能基线：上线前可以基于 measureMemory 输出的基线做 diff 测试，确保新版本没有引入显著的内存回归。资料来源：packages/testing/src/memory.ts:30-60

六、典型工作流

flowchart LR
  A[编写组件] --> B[render 挂载]
  B --> C[waitFor 轮询]
  C --> D[断言输出]
  D --> E{测试通过?}
  E -- 否 --> F[捕获并定位异常]
  F --> G[error-handling 示例辅助排查]
  E -- 是 --> H[输出 Coverage 与 Memory 基线]
  H --> I[部署]

资料来源：packages/testing/src/render-test.ts:30-80、packages/testing/src/wait-for.ts:10-40、packages/testing/src/memory.ts:20-60、libs/examples/apps/guides-tour/src/testing.tsx:40-80、libs/examples/apps/getting-started-tour/src/error-handling.tsx:40-100

小结

• @creact/testing 提供 render、waitFor、measureMemory 三大工具，对应同步渲染、异步断言与性能基线三类需求。
• error-handling 示例示范了如何在框架内捕获并降级处理渲染异常，是生产级应用必备模式。
• 通过“源码示例 + 测试工具”的双重形态，仓库鼓励开发者在写功能代码时就同步考虑可测试性与可观测性，从而在部署阶段获得更稳健的产品质量。

Pitfall Log / 踩坑日志

项目：creact-labs/creact

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/creact-labs/creact | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/creact-labs/creact | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/creact-labs/creact | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/creact-labs/creact | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/creact-labs/creact | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/creact-labs/creact | release_recency=unknown