# https://github.com/creact-labs/creact Project Manual
Generated at: 2026-07-14 04:36:27 UTC
## Table of Contents
- [Introduction and Getting Started](#page-1)
- [Runtime Engine: Fiber Model, Reconciliation, and State Machine](#page-2)
- [Reactive System: Signals, Effects, and Dependency Tracking](#page-3)
- [JSX Runtime, Components, and Control Flow Primitives](#page-4)
- [Stores, Context, and Owner-Based Memory](#page-5)
- [CLI Tooling, Watch Mode, and Testing Utilities](#page-6)
- [AI Integration with Claude and Cloud Deployment](#page-7)
- [Runtime Boundaries, Error Handling, and Operations](#page-8)
## Introduction and Getting Started
### Related Pages
Related topics: [Runtime Engine: Fiber Model, Reconciliation, and State Machine](#page-2), [Reactive System: Signals, Effects, and Dependency Tracking](#page-3), [JSX Runtime, Components, and Control Flow Primitives](#page-4)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/creact-labs/creact/blob/main/README.md)
- [packages/creact/README.md](https://github.com/creact-labs/creact/blob/main/packages/creact/README.md)
- [apps/website/src/pages/landing/index.tsx](https://github.com/creact-labs/creact/blob/main/apps/website/src/pages/landing/index.tsx)
- [apps/website/src/pages/docs/getting-started/installation/index.tsx](https://github.com/creact-labs/creact/blob/main/apps/website/src/pages/docs/getting-started/installation/index.tsx)
- [apps/website/src/i18n/resources/en/docs/getting_started/installation.json](https://github.com/creact-labs/creact/blob/main/apps/website/src/i18n/resources/en/docs/getting_started/installation.json)
- [libs/examples/apps/getting-started-tour/first-entry.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/getting-started-tour/first-entry.tsx)
# Introduction and Getting Started
CReact is an open-source project that provides a React-compatible component model and rendering pipeline, packaged as a workspace of libraries, documentation, and example applications. This page introduces the repository's purpose, explains how the project is organized, and walks through the minimum steps required to install the core package and render a first component.
## What CReact Is
CReact (short for "Component React") is positioned by its maintainers as a component-based UI library that exposes APIs familiar to developers who already know React. The top-level landing page describes the project as the entry point users reach from the documentation site, and the surrounding workspaces (packages, apps, libs) show the same library being consumed in three different contexts: as a published package, as the engine that powers the documentation site, and as the runtime for example apps.
Source: [README.md:1-40]()
Source: [apps/website/src/pages/landing/index.tsx:1-60]()
Source: [packages/creact/README.md:1-40]()
## Repository Layout
The monorepo is split into three top-level workspaces that mirror the audiences the project serves:
| Directory | Purpose | Audience |
|-----------|---------|----------|
| `packages/creact` | The core library source and its own README. | Library authors and consumers. |
| `apps/website` | The marketing and documentation site, including the `docs/getting-started/installation` route and the i18n resources under `i18n/resources/en/docs/`. | End users reading docs. |
| `libs/examples` | Runnable example apps, including the `getting-started-tour` app used as a tour entry. | Developers learning the API. |
This three-part structure means the same `creact` package that is documented under `apps/website/src/pages/docs/getting-started/installation/` is also the package executed by `libs/examples/apps/getting-started-tour/first-entry.tsx`, which keeps documentation and examples in lock-step with the library source.
Source: [apps/website/src/pages/docs/getting-started/installation/index.tsx:1-40]()
Source: [libs/examples/apps/getting-started-tour/first-entry.tsx:1-40]()
## Installing the Core Package
The installation route under `docs/getting-started/installation` is the canonical onboarding entry for new users. The English i18n resource at `apps/website/src/i18n/resources/en/docs/getting_started/installation.json` supplies the localized copy that the page renders, including the steps, the package name, and the manager command shown to the reader. Because the strings live in a JSON resource rather than being hard-coded into the route component, the same installation instructions can be translated without touching the React tree.
In practice, installation follows the standard Node.js package-manager pattern: the user picks a package manager, the documentation shows the corresponding `add` / `install` command referencing the `creact` package, and the user then imports the runtime APIs from the same package in their own entry file. The `first-entry.tsx` example in `libs/examples/apps/getting-started-tour` is the concrete reference for what that entry file looks like after installation.
Source: [apps/website/src/pages/docs/getting-started/installation/index.tsx:40-120]()
Source: [apps/website/src/i18n/resources/en/docs/getting_started/installation.json:1-60]()
Source: [packages/creact/README.md:20-80]()
## A Minimal First Entry
The smallest meaningful CReact program is the "first entry" sample in `libs/examples/apps/getting-started-tour/first-entry.tsx`. It demonstrates the three pieces every CReact application needs:
1. Import the entry/render API and the component-creation API from the installed `creact` package.
2. Define a component that returns a tree of elements describing the UI to render.
3. Call the render entry point with that component and a target DOM container.
The same shape applies whether the target is the documentation site, an example app, or a user project. Once the first component renders successfully, subsequent learning material — hooks, state, event handling, and the broader API surface — is built on top of this starting point rather than introduced as a parallel concept.
Source: [libs/examples/apps/getting-started-tour/first-entry.tsx:1-80]()
## Suggested Workflow After Installation
The recommended progression for a new user, derived from how the repository itself is wired, looks like this:
```mermaid
flowchart LR
A[Read README] --> B[Install creact package]
B --> C[Write first-entry.tsx]
C --> D[Render component]
D --> E[Explore libs/examples]
E --> F[Build app in apps/website or own project]
```
Each arrow corresponds to a file in this page: the top-level `README.md` is the starting point, the installation route on the documentation site teaches `npm`/`pnpm` setup, the `getting-started-tour` app shows the first component, and the broader `libs/examples` directory plus the `apps/website` source become the next references once the basics work.
Source: [README.md:1-80]()
Source: [apps/website/src/pages/landing/index.tsx:1-80]()
Source: [apps/website/src/pages/docs/getting-started/installation/index.tsx:1-80]()
Source: [apps/website/src/i18n/resources/en/docs/getting_started/installation.json:1-40]()
Source: [libs/examples/apps/getting-started-tour/first-entry.tsx:1-60]()
## Where to Go Next
After completing the steps above, the natural next stops inside the repository are:
- The `packages/creact` directory, to read the library's own README and exported API surface.
- Additional entries under `libs/examples/apps/`, to see slightly larger programs that exercise more of the API.
- The remaining `docs/getting-started/*` routes on the website, which continue the onboarding flow beyond installation into concepts, configuration, and common patterns.
Together these three workspaces — package, examples, and website — form the complete "Introduction and Getting Started" experience for CReact.
---
## Runtime Engine: Fiber Model, Reconciliation, and State Machine
### Related Pages
Related topics: [Reactive System: Signals, Effects, and Dependency Tracking](#page-3), [JSX Runtime, Components, and Control Flow Primitives](#page-4), [Stores, Context, and Owner-Based Memory](#page-5)
Related Source Files
The following source files were used to generate this page:
- [packages/creact/src/runtime/fiber.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/fiber.ts)
- [packages/creact/src/runtime/reconcile.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/reconcile.ts)
- [packages/creact/src/runtime/state-machine.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/state-machine.ts)
- [packages/creact/src/runtime/instance.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/instance.ts)
- [packages/creact/src/runtime/render.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/render.ts)
- [packages/creact/src/runtime/run.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/run.ts)
- [packages/creact/src/runtime/types.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/types.ts)
- [packages/creact/src/runtime/scheduler.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/scheduler.ts)
- [packages/creact/src/runtime/element.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/element.ts)
# Runtime Engine: Fiber Model, Reconciliation, and State Machine
The `creact` runtime engine is the core subsystem that turns a tree of component invocations into an interactive UI instance. It owns three tightly coupled responsibilities: building and mutating a **Fiber tree** that represents the current render, running a **reconciliation** algorithm that diffs new renders against that tree, and driving a finite **state machine** that governs a fiber's lifecycle from creation through effect commit and unmount.
## High-Level Architecture
The runtime is split into small cooperating modules under `packages/creact/src/runtime`:
| Module | Responsibility |
| --- | --- |
| `fiber.ts` | Defines the `Fiber` node type, its linked-list sibling/child/return pointers, and its `flags` bitmask. |
| `reconcile.ts` | Implements `reconcileFiber` / `reconcileChildren` to compare a previous fiber with a new element and produce work. |
| `state-machine.ts` | Encodes the fiber `Status` enum (`Pending`, `Mounted`, `Unmounted`, `Dirty`) and transitions between them. |
| `instance.ts` | Holds per-fiber runtime state: hooks list, refs, context, pending effects. |
| `render.ts` | Creates the initial root fiber and exposes `render(element, container)`. |
| `run.ts` | Orchestrates the work loop, walking the fiber tree and committing effects. |
| `scheduler.ts` | Schedules microtask re-renders when state changes are detected. |
Together they implement a cooperative, single-pass reconciler that mirrors React's mental model but is small enough to read end-to-end. Source: [packages/creact/src/runtime/fiber.ts:1-80](), [packages/creact/src/runtime/render.ts:1-60]().
## Fiber Model
A fiber is the unit of work. It is a plain object with three pointer fields (`child`, `sibling`, `return`) that link it into a tree without nested arrays, allowing the renderer to walk it iteratively. Source: [packages/creact/src/runtime/fiber.ts:12-78]().
Key fields on a fiber include:
- `type` — the component function or host element name the fiber represents.
- `props` / `children` — the props passed to that component.
- `instance` — the associated `Instance` object holding hooks and refs.
- `flags` — a bitmask of pending work (`Placement`, `Update`, `Deletion`, `Effect`).
- `status` — current state-machine status.
- `alternate` — the previous fiber from the prior render, used as the diff source.
Sibling fibers are stored as a singly linked list via `sibling`, so `reconcileChildren` can iterate them with `while (current !== null)`. Source: [packages/creact/src/runtime/reconcile.ts:40-95](), [packages/creact/src/runtime/fiber.ts:60-78]().
## Reconciliation
Reconciliation is triggered whenever a component re-renders. The scheduler enqueues a microtask, which calls `run.ts`'s work loop. The loop calls `reconcileFiber(parent, previous, next)` for each work unit. Source: [packages/creact/src/runtime/reconcile.ts:1-40](), [packages/creact/src/runtime/run.ts:20-70]().
The algorithm follows three rules:
1. **Same type, same key** — reuse the previous fiber, copy its `instance`, and update `props`. Mark with `Update` flag if props changed.
2. **Different type** — mark the old fiber with `Deletion`, create a new fiber with `Placement`, and let commit tear it down.
3. **Children** — call `reconcileChildren(parent, oldChildren, newChildren)` which pairs old and new fibers by position (and key when present), producing a new sibling chain.
The result of reconciliation is a fiber tree where each node carries flags describing the work to perform; no DOM or effect runs yet. Source: [packages/creact/src/runtime/reconcile.ts:60-140]().
## State Machine
Each fiber is driven through a small finite state machine defined in `state-machine.ts`:
- `Pending` — newly created, not yet committed.
- `Mounted` — committed to the host and visible.
- `Dirty` — re-render scheduled but not yet processed.
- `Unmounted` — removed from the host, eligible for cleanup.
Transitions are invoked from the work loop and from commit hooks. For example, a freshly created fiber is `Pending`, becomes `Mounted` after `commitMount`, transitions to `Dirty` when `markDirty(fiber)` is called from a state setter, and reaches `Unmounted` when the parent places a `Deletion` flag on it. Source: [packages/creact/src/runtime/state-machine.ts:1-90](), [packages/creact/src/runtime/run.ts:80-130]().
```mermaid
stateDiagram-v2
[*] --> Pending: createFiber
Pending --> Mounted: commitMount
Mounted --> Dirty: markDirty (setState)
Dirty --> Pending: beginWork
Mounted --> Unmounted: Deletion flag
Dirty --> Unmounted: Deletion flag
Unmounted --> [*]
```
The instance module cooperates with the state machine: `instance.ts` exposes `enqueueEffect(fiber, effect)` and `runEffects(fiber)` which only fire effects when the fiber is `Mounted`, preventing leaks from already-unmounted trees. Source: [packages/creact/src/runtime/instance.ts:30-110]().
## Work Loop and Commit
`run.ts` is the orchestrator. Its main loop performs begin-work (reconciliation) and complete-work (commit) in two passes:
- **Begin phase** — walks `root.child` recursively, calling `reconcileFiber` to compute flags.
- **Complete phase** — walks back up via `return`, applying `Placement`, `Update`, and `Deletion` flags to the host and firing effects in commit order.
The scheduler ensures `beginWork` is called at most once per microtask batch, coalescing multiple `setState` calls from a single event into one render. Source: [packages/creact/src/runtime/scheduler.ts:1-60](), [packages/creact/src/runtime/run.ts:40-100]().
## Summary
The runtime engine is a small, self-contained React-like core. The fiber model provides the data structure, reconciliation provides the diff, and the state machine guarantees each fiber transitions through a well-defined lifecycle before effects can run. Together they form a predictable pipeline: `createFiber → reconcile → commit → effects`, with the scheduler batching state changes and `instance.ts` storing per-fiber hooks. Reading `fiber.ts`, `reconcile.ts`, `state-machine.ts`, `run.ts`, and `instance.ts` in that order gives a complete picture of how `creact` turns function calls into a working UI.
---
## Reactive System: Signals, Effects, and Dependency Tracking
### Related Pages
Related topics: [Runtime Engine: Fiber Model, Reconciliation, and State Machine](#page-2), [Stores, Context, and Owner-Based Memory](#page-5)
Related Source Files
The following source files were used to generate this page:
- [packages/creact/src/reactive/signal.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/signal.ts)
- [packages/creact/src/reactive/effect.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/effect.ts)
- [packages/creact/src/reactive/selector.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/selector.ts)
- [packages/creact/src/reactive/tracking.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/tracking.ts)
- [packages/creact/src/reactive/owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/owner.ts)
- [packages/creact/src/reactive/current-owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/current-owner.ts)
# Reactive System: Signals, Effects, and Dependency Tracking
## Overview and Scope
The `packages/creact/src/reactive/` directory implements the fine-grained reactivity layer of creact. It provides three primitive building blocks — **signals** for mutable state, **selectors** (computed/derived values) for read-only derivations, and **effects** for side-effecting reactions — together with a dependency-tracking subsystem and an *owner* hierarchy that manages lifecycle, teardown, and propagation.
The reactive layer is intentionally decoupled from the renderer. It exposes a synchronous, pull-based graph where reading a signal inside an effect registers the effect as a subscriber; writing the signal later schedules the effect to run again. The owner subsystem layers a parent/child tree on top of this graph so that nested reactions are disposed atomically.
Source: [packages/creact/src/reactive/signal.ts:1-1](), [packages/creact/src/reactive/effect.ts:1-1](), [packages/creact/src/reactive/owner.ts:1-1]().
## Core Primitives: Signals and Selectors
A **signal** is a reactive cell holding a value. Reading it (`signal.value`) records the current subscriber, and writing it (`signal.value = next`) notifies every recorded subscriber. Internally, a signal stores its current value, a flag indicating whether listeners exist, and a set or linked list of dependent subscribers populated through the tracker.
Source: [packages/creact/src/reactive/signal.ts:1-1]().
A **selector** (computed) is a pure, read-only derivation built from other signals/selectors. It memoizes its result: the derivation function only re-runs when one of its tracked dependencies actually changes. If no upstream value has changed, accessing the selector returns the cached value and does not trigger downstream work. Selectors therefore break dependency chains and prevent redundant effect re-runs.
Source: [packages/creact/src/reactive/selector.ts:1-1]().
The relationship is:
| Primitive | Mutability | Re-runs when | Use case |
|-----------|------------|--------------|----------|
| Signal | Read/Write | Set explicitly | Local state |
| Selector | Read-only | Upstream signal changes | Derived state |
| Effect | Side-effect | Any tracked dependency changes | DOM, subscriptions |
## Dependency Tracking
The `tracking.ts` module centralises the *currently collecting subscriber*. Before a reactive read (signal or selector access) executes, it pushes the current subscriber (the effect being constructed, or another selector) onto an internal listener slot; after the read returns, the recorded subscriber is added to the signal's dependency set.
Source: [packages/creact/src/reactive/tracking.ts:1-1]().
This indirection lets every read API share one mechanism. The pattern is roughly:
```ts
const prev = activeSubscriber;
activeSubscriber = currentEffect;
try {
return signal.value; // signal appends `currentEffect` to its deps
} finally {
activeSubscriber = prev;
}
```
Source: [packages/creact/src/reactive/tracking.ts:1-1]().
Because the tracking uses a *push-then-pull* model — the effect pushes itself as the listener and pulls the signal value — dependencies are discovered lazily, only those actually touched during execution are subscribed. This avoids over-subscription and keeps invalidation cheap.
## Effects and the Owner Hierarchy
An **effect** is a function executed once initially (to discover its dependencies), and re-executed whenever any of those dependencies change. Effects are scheduled rather than run synchronously to avoid inconsistent intermediate states and to batch multiple writes in the same tick.
Source: [packages/creact/src/reactive/effect.ts:1-1]().
The **owner** module gives the flat reactive graph a tree structure. An owner represents a scope (typically a component or a user-created scope). Effects and selectors created inside an owner are registered with that owner; when the owner is disposed, all child reactions are torn down together. Nested owners create nested lifecycles — a parent disposing does not affect siblings, and children cannot outlive their parent.
Source: [packages/creact/src/reactive/owner.ts:1-1]().
The `current-owner.ts` module maintains the "ambient" owner reference — the owner currently being constructed — so that every `createSignal`, `createSelector`, or `createEffect` call can self-register without the caller passing it explicitly. This is analogous to React's context stack or Vue's `currentInstance`.
Source: [packages/creact/src/reactive/current-owner.ts:1-1]().
## Propagation and Teardown Workflow
The end-to-end flow of a write is:
```mermaid
sequenceDiagram
participant User
participant Signal
participant Tracker
participant Effect
participant Owner
User->>Tracker: begin tracking (push current effect)
User->>Signal: read .value
Signal->>Tracker: register effect as subscriber
Note over Signal,Effect: Effect is now subscribed
User->>Signal: write new value
Signal->>Effect: notify (schedule)
Effect->>Effect: re-run synchronously or on flush
Owner->>Effect: dispose on teardown
Effect->>Signal: unsubscribe from all deps
```
Source: [packages/creact/src/reactive/signal.ts:1-1](), [packages/creact/src/reactive/effect.ts:1-1](), [packages/creact/src/reactive/tracking.ts:1-1](), [packages/creact/src/reactive/owner.ts:1-1]().
When a component (or any scope) unmounts, the framework calls `dispose()` on its owner. The owner walks its child effects and selectors, invokes any user-supplied cleanup, and removes the effect from every signal's subscriber list. After this, the effect will never fire again even if its former dependencies mutate. This guarantees that DOM updates and other side effects cannot leak after teardown.
Source: [packages/creact/src/reactive/owner.ts:1-1](), [packages/creact/src/reactive/effect.ts:1-1]().
## Design Notes
- **Synchronous reads, batched writes.** Reads register dependencies immediately; writes trigger notifications that may be queued and flushed together to coalesce re-runs.
- **Dynamic dependencies.** Because tracking happens at execution time, effects can branch on conditions and only subscribe to the dependencies they actually touch.
- **Memory safety.** The owner tree ensures no effect outlives its scope; the dependency set on each signal is cleaned when its subscribers dispose.
- **Decoupling from rendering.** The reactive layer knows nothing about the DOM or component tree; it only orchestrates *who depends on whom* and *when to re-run*. The renderer layer above it consumes effects to produce VDOM updates.
Source: [packages/creact/src/reactive/signal.ts:1-1](), [packages/creact/src/reactive/selector.ts:1-1](), [packages/creact/src/reactive/effect.ts:1-1](), [packages/creact/src/reactive/tracking.ts:1-1](), [packages/creact/src/reactive/owner.ts:1-1](), [packages/creact/src/reactive/current-owner.ts:1-1]().
---
## JSX Runtime, Components, and Control Flow Primitives
### Related Pages
Related topics: [Introduction and Getting Started](#page-1), [Runtime Engine: Fiber Model, Reconciliation, and State Machine](#page-2), [Stores, Context, and Owner-Based Memory](#page-5)
Related Source Files
The following source files were used to generate this page:
- [packages/creact/src/jsx/index.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/jsx/index.ts)
- [packages/creact/src/jsx/jsx-runtime.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/jsx/jsx-runtime.ts)
- [packages/creact/src/jsx/jsx-dev-runtime.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/jsx/jsx-dev-runtime.ts)
- [packages/creact/src/flow/for.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/flow/for.ts)
- [packages/creact/src/flow/show.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/flow/show.ts)
- [packages/creact/src/flow/switch.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/flow/switch.ts)
# JSX Runtime, Components, and Control Flow Primitives
## Overview
The JSX runtime, components, and control flow primitives constitute the developer-facing surface of creact. They provide the syntactic bridge from JSX to creact's reactive node graph, define how user-authored components are composed and executed, and ship a small set of optimized built-ins for the most common dynamic UI patterns: lists, conditionals, and multi-way switches. Together, these modules let users write declarative, fine-grained reactive views without manually wiring up effects or DOM mutations. Source: [packages/creact/src/jsx/index.ts](), [packages/creact/src/flow/for.ts](), [packages/creact/src/flow/show.ts](), [packages/creact/src/flow/switch.ts]().
## JSX Runtime Entry Points
The JSX runtime is split into three modules so that the same JSX syntax can be served in both development and production, and so that tooling can rely on stable entry points for `tsconfig.json` `"jsxImportSource"` and Babel's `@jsxImportSource`.
`packages/creact/src/jsx/jsx-runtime.ts` exposes the classic `jsx`, `jsxs`, `Fragment`, and `jsxTemplate` helpers used when TypeScript or Babel is configured with `react-jsx` / `react-jsxdev` against the creact import source. `packages/creact/src/jsx/jsx-dev-runtime.ts` mirrors this surface for development builds, providing `jsxDEV` so that JSX expressions retain debug-friendly shapes with `key`, `ref`, and source-location metadata. The aggregated re-exports and type definitions live in `packages/creact/src/jsx/index.ts`, which is the module users typically import via `import { ... } from 'creact'`. Source: [packages/creact/src/jsx/index.ts](), [packages/creact/src/jsx/jsx-runtime.ts](), [packages/creact/src/jsx/jsx-dev-runtime.ts]().
The runtime functions do not create DOM eagerly; they construct lightweight element descriptors. Hosting these descriptors into reactive scopes is what enables fine-grained updates later on. Source: [packages/creact/src/jsx/jsx-runtime.ts]().
## Components
User components are plain functions whose body is invoked once during composition. Unlike diffing-based frameworks, creact does not re-run the component body when props change. Instead, the reactive expressions inside the component re-evaluate independently when the signals they read change. A component returns a JSX node (typically via the runtime helpers), and creact reconciles the reactive graph rooted at that return value. Source: [packages/creact/src/jsx/index.ts](), [packages/creact/src/jsx/jsx-runtime.ts]().
This model has two practical consequences for authors: functions stay cheap because they are not re-invoked, and side effects must be wrapped in reactive primitives so they only run on real dependency changes rather than every parent re-render. Component children are passed as a special `children` prop, which the runtime ultimately hosts into the returned element so that nested reactivity composes naturally.
## Control Flow Primitives
creact ships three built-in families of control flow components under `packages/creact/src/flow/`. They are preferable to naïve `.map(...)` and ternary expressions because they preserve stable identities for items and branches across updates, which keeps DOM and effect bookkeeping cheap. Source: [packages/creact/src/flow/for.ts](), [packages/creact/src/flow/show.ts](), [packages/creact/src/flow/switch.ts]().
### Lists with ``
`for.ts` exports `For`, which iterates over an array-like source by tracking each item's identity (typically by a user-provided `each` accessor and the array reference itself). `}>{(item, index) => ...}` reuses existing nodes for items that survive across updates and inserts or removes nodes only at the boundaries where the array actually changed, rather than rebuilding the list on every mutation. Source: [packages/creact/src/flow/for.ts]().
### Conditional with ``
`show.ts` provides `Show` for single-branch conditionals. `{value => ...}` mounts its children when the condition is truthy, optionally receiving the unwrapped value as the callback argument, and swaps in `fallback` otherwise. Because `when` is read through creact's reactive accessor, the conditional re-evaluates automatically when the underlying signal flips, without re-running any enclosing component. Source: [packages/creact/src/flow/show.ts]().
### Multi-Branch with `` / ``
`swith.ts` (and matching `Match`) handles N-way conditionals analogous to a chain of `` calls but more efficient when exactly one branch must be active. Consumers wrap ordered `...` children inside a `` parent; creact picks the first matching branch and mounts only that subtree. Source: [packages/creact/src/flow/switch.ts]().
## Relationship Between the Three Layers
At runtime, a user's JSX is first lowered into element descriptors by the JSX runtime. Component function bodies wrap reactive expression nodes into the returned descriptor. Control flow primitives are themselves just components that own their own reactive bookkeeping, so they slot in wherever any other component would. The boundary that matters most is that the JSX runtime is *not* a reconciler — it only describes intent. The actual updating behavior is driven by reactive primitives and the control flow components that know how to handle common diff shapes efficiently. Source: [packages/creact/src/jsx/jsx-runtime.ts](), [packages/creact/src/flow/for.ts](), [packages/creact/src/flow/show.ts](), [packages/creact/src/flow/switch.ts]().
### Compact API Map
| Construct | File | Purpose |
| --- | --- | --- |
| `jsx` / `jsxs` / `Fragment` | `jsx/jsx-runtime.ts` | Production JSX compilation targets |
| `jsxDEV` | `jsx/jsx-dev-runtime.ts` | Development JSX with debug metadata |
| Aggregated types & entry | `jsx/index.ts` | Public surface used by `import 'creact'` |
| `` | `flow/for.ts` | Identity-stable list rendering |
| `` | `flow/show.ts` | Reactive single-branch conditional |
| `` / `` | `flow/switch.ts` | Ordered multi-branch conditional |
---
## Stores, Context, and Owner-Based Memory
### Related Pages
Related topics: [Runtime Engine: Fiber Model, Reconciliation, and State Machine](#page-2), [Reactive System: Signals, Effects, and Dependency Tracking](#page-3), [AI Integration with Claude and Cloud Deployment](#page-7)
Related Source Files
The following source files were used to generate this page:
- [packages/creact/src/store/store.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/store/store.ts)
- [packages/creact/src/primitives/context.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/primitives/context.ts)
- [packages/creact/src/reactive/owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/owner.ts)
- [packages/creact/src/reactive/current-owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/current-owner.ts)
- [packages/creact/src/runtime/memory.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/memory.ts)
- [apps/website/src/i18n/resources/en/docs/architecture/memory_system.json](https://github.com/creact-labs/creact/blob/main/apps/website/src/i18n/resources/en/docs/architecture/memory_system.json)
# Stores, Context, and Owner-Based Memory
The Memory System in `creact` unifies three cooperating primitives — **Stores**, **Context**, and **Owner-Based Memory** — to give reactive components a deterministic way to share, scope, and dispose of state. Together they replace the ad-hoc globals and prop-drilling patterns typical of component frameworks with a single owner-tracked memory model. The architecture treats a `Store` as the unit of durable data, a `Context` as the propagation channel between producers and consumers, and the `Owner` as the disposer that ties a memory lifetime to the component that requested it. `Source: [apps/website/src/i18n/resources/en/docs/architecture/memory_system.json:1-]()` summarizes this design at the documentation level.
## Stores: Reactive State Containers
A `Store` is a reactive container holding a typed value plus the metadata needed to subscribe to its changes. It is implemented in the `store` module and is the canonical place where application state lives, independent of any particular component tree. Stores expose a minimal surface — read access, write access, and change subscription — so they can be passed through context, returned from hooks, or stored on an owner without losing reactivity. `Source: [packages/creact/src/store/store.ts:1-]().`
Because a store is just a value envelope, it composes naturally with the rest of the reactive system: any signal, ref, or computed value nested inside it is tracked under the active `Owner`, which means memory cleanup flows through the store automatically when the owning component unmounts. `Source: [packages/creact/src/reactive/owner.ts:1-]().`
| Primitive | Role | Lifecycle | Primary file |
|---|---|---|---|
| `Store` | Holds shared reactive state | Tied to an owner via subscription | `store/store.ts` |
| `Context` | Propagates stores down the tree | Resolved per-render | `primitives/context.ts` |
| `Owner` | Tracks subscriptions for disposal | Created per reactive scope | `reactive/owner.ts` |
| `Memory` | Runtime that records/teardowns memory | Scoped to current owner | `runtime/memory.ts` |
## Context: Provid[packages/creact/src/reactive/current-owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/current-owner.ts)
- [packages/creact/src/runtime/memory.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/memory.ts)
ing and Resolving Values
`Context` is the primitive a component uses to **publish** a value to its descendants and **consume** the nearest published value during render. Defined in `primitives/context.ts`, it pairs a provider (used by an ancestor component, often wrapping a `Store`) with a consumer (used by any descendant to read it). Context is the only sanctioned way to pass a `Store` across component boundaries without prop drilling. `Source: [packages/creact/src/primitives/context.ts:1-]().`
The provider-consumer relationship is resolved dynamically at render time: when a consumer runs inside a reactive scope, the renderer walks up the current owner chain via `current-owner.ts` to locate the closest provider and binds the store to that scope. This means re-parenting a subtree automatically redirects reads to the new nearest provider, without consumers having to be rewritten. `Source: [packages/creact/src/reactive/current-owner.ts:1-]().`
```mermaid
flowchart TD
A[Root Owner] --> B[Provider: Store X]
B --> C[Consumer reads Store X]
B --> D[Provider: Store Y]
D --> E[Consumer reads Store Y]
C -.schedules.-> F[Reactive Runtime]
E -.schedules.-> F
F --> G[Memory: dispose on unmount]
```
## Owner-Based Memory: Scoped Lifetime
The `Owner` is the bookkeeping object that records every memory subscription a component creates while it is rendering. Defined in `reactive/owner.ts`, an owner is automatically constructed on each reactive entry (function component, effect, or memo) and is linked to its parent owner through `current-owner.ts`, forming a tree that mirrors the component tree. `Source: [packages/creact/src/reactive/owner.ts:1-]().`, `Source: [packages/creact/src/reactive/current-owner.ts:1-]()`
The `runtime/memory.ts` module is the executor that operations consult: whenever a store subscription, ref, effect, or context binding is registered, it calls the memory runtime to attach that record to the active `Owner`. When the owner is disposed (because its component is removed or its effect is re-run), the runtime walks the recorded list and tears every entry down in reverse order — closing subscriptions, releasing callbacks, and allowing garbage collection of the captured values. `Source: [packages/creact/src/runtime/memory.ts:1-]().`
This owner-tracked model is what makes the memory system "automatic": developers create stores and effects freely, and they are guaranteed to be cleaned up exactly once, exactly when the component that owns them leaves the tree. The documentation confirms this is the intended contract for the architecture. `Source: [apps/website/src/i18n/resources/en/docs/architecture/memory_system.json:1-]()`
## End-to-End Flow
A typical lifecycle combining all three primitives works as follows. A top-level component creates a `Store`, wraps it in a `Context.Provider`, and renders. Each descendant uses the context hook to obtain the store; the consumer reads the value and, by virtue of executing under the current owner, registers a subscription in `runtime/memory.ts`. If the top-level component unmounts, its owner is disposed, and the runtime tears down every store subscription recorded under it, reclaiming memory deterministically. `Source: [packages/creact/src/store/store.ts:1-]()`, `Source: [packages/creact/src/primitives/context.ts:1-]()`, `Source: [packages/creact/src/runtime/memory.ts:1-]()`
Because stores, contexts, and owners are layered concerns — **data**, **transport**, **lifetime** — the API stays small while the memory guarantees remain uniform across components, effects, and external integrations.
## [packages/creact/src/store/store.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/store/store.ts)
- [packages/creact/src/primitives/context.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/primitives/context.ts)
- [packages/creact/src/reactive/owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/owner.ts)
---
## CLI Tooling, Watch Mode, and Testing Utilities
### Related Pages
Related topics: [Introduction and Getting Started](#page-1), [AI Integration with Claude and Cloud Deployment](#page-7)
Related Source Files
The following source files were used to generate this page:
- [packages/creact/src/cli.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/cli.ts)
- [packages/creact/src/cli-main.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/cli-main.ts)
- [packages/creact/src/cli-typecheck.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/cli-typecheck.ts)
- [packages/creact/src/cli-logger.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/cli-logger.ts)
- [packages/testing/src/index.ts](https://github.com/creact-labs/creact/blob/main/packages/testing/src/index.ts)
- [packages/testing/src/render-test.ts](https://github.com/creact-labs/creact/blob/main/packages/testing/src/render-test.ts)
# CLI Tooling, Watch Mode, and Testing Utilities
## Purpose and Scope
The creact framework ships a developer-facing toolchain distributed across two workspaces: the CLI tooling under `packages/creact/src/` and the testing utilities under `packages/testing/src/`. Together they cover the "author → iterate → validate" loop. The CLI drives project-level commands such as running the development server and performing type checking, while the testing package provides low-level helpers that mount creact components in test environments.
This page documents the structure of these modules, the role each file plays, and how they cooperate to deliver watch-mode development and component rendering tests.
## CLI Module Architecture
The CLI is intentionally factored into four small modules rather than a single file. This keeps the entry surface narrow and lets each concern evolve independently.
- `cli.ts` is the entry point. It parses `process.argv`, resolves the requested subcommand, and dispatches control to the matching handler.
- `cli-main.ts` hosts the implementations of the primary commands (development server, build) and the watch loop used during development.
- `cli-typecheck.ts` isolates type-checking logic so it can be invoked standalone or as part of a wider pipeline.
- `cli-logger.ts` centralizes the formatting of CLI output, ensuring that messages from different commands share a consistent style.
```mermaid
flowchart LR
User([Developer]) --> Argv[process.argv]
Argv --> Entry[cli.ts]
Entry --> Main[cli-main.ts]
Entry --> Typecheck[cli-typecheck.ts]
Main --> Logger[cli-logger.ts]
Typecheck --> Logger
Main --> Watcher[(File Watcher)]
```
This separation lets type checking and logging evolve without touching command logic, and lets command bodies grow without the entry module growing in lockstep.
Source: [packages/creact/src/cli.ts:1-200]()
Source: [packages/creact/src/cli-main.ts:1-200]()
Source: [packages/creact/src/cli-typecheck.ts:1-200]()
Source: [packages/creact/src/cli-logger.ts:1-200]()
## Watch Mode and Development Workflow
Watch mode is not implemented as a standalone file; it is part of the development command path inside `cli-main.ts`. When the developer starts the development command, the CLI initializes a file watcher and enters a loop that reacts to filesystem events. Each iteration typically performs four steps:
1. Detect changed files via the watcher.
2. Re-run the relevant compiler or transform on those files.
3. Optionally invoke `cli-typecheck.ts` to surface incremental type errors.
4. Emit user-facing status through `cli-logger.ts`.
Because the logger is shared across all CLI commands, watch-loop output follows exactly the same conventions as one-shot commands. Keeping the watch loop inside `cli-main.ts` rather than promoting it to a separate file means it can reuse the command's own configuration and pipeline without redundant setup, and the type checker can be plugged in as a stage of the same workflow.
Source: [packages/creact/src/cli-main.ts:1-200]()
Source: [packages/creact/src/cli-typecheck.ts:1-200]()
Source: [packages/creact/src/cli-logger.ts:1-200]()
## Testing Utilities
The testing package occupies its own workspace and exposes a focused API for rendering creact components in isolation. Its public surface is defined by `packages/testing/src/index.ts`, which re-exports the helpers developers import in their test files.
The core implementation lives in `packages/testing/src/render-test.ts`. This module provides the `render` function, which mounts a creact component tree into a host environment (typically a DOM-like test container) and returns inspection handles. Tests use those handles to query the rendered output, trigger updates, or unmount the tree.
Keeping the render implementation in its own module — and the public re-exports in `index.ts` — lets the testing package add additional helpers (for example, server-side rendering or snapshot utilities) without bloating the entry module. Test files import only what they need, and the underlying implementation can change without affecting import sites.
Source: [packages/testing/src/index.ts:1-200]()
Source: [packages/testing/src/render-test.ts:1-200]()
## How the Pieces Fit Together
The CLI and testing packages do not share code directly, but they share architectural conventions. Both favor small, single-purpose modules; both isolate the public entry point from the implementation; and both rely on a clear separation between the exported API and the internal helpers. The CLI focuses on orchestrating the whole project (compile, watch, type-check), while the testing package focuses on isolating individual components for verification.
This separation keeps the developer experience consistent — the CLI is where projects start and iterate, and the testing utilities are where individual components are validated — without coupling the two concerns.
Source: [packages/creact/src/cli.ts:1-200]()
Source: [packages/testing/src/index.ts:1-200]()
## Summary
In summary, creact's CLI tooling is organized around `cli.ts` (entry and dispatch), `cli-main.ts` (command bodies and the watch loop), `cli-typecheck.ts` (type checking), and `cli-logger.ts` (shared output formatting). The watch-mode lifecycle lives in `cli-main.ts` and reuses the shared logger and optional type checker. The testing package provides rendering utilities through `index.ts` (re-exports) and `render-test.ts` (the render implementation). Together these modules form a cohesive developer toolchain for authoring, iterating on, and verifying creact components.
---
## AI Integration with Claude and Cloud Deployment
### Related Pages
Related topics: [Stores, Context, and Owner-Based Memory](#page-5), [Runtime Boundaries, Error Handling, and Operations](#page-8)
Related Source Files
The following source files were used to generate this page:
- [libs/examples/apps/hero-fleet/src/components/claude/index.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/hero-fleet/src/components/claude/index.tsx)
- [libs/examples/apps/hero-fleet/src/components/aws/index.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/hero-fleet/src/components/aws/index.tsx)
- [libs/examples/apps/hero-fleet/src/components/channel/index.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/hero-fleet/src/components/channel/index.tsx)
- [libs/examples/apps/hero-fleet/src/components/generate-html/index.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/hero-fleet/src/components/generate-html/index.tsx)
- [libs/examples/apps/hero-fleet/src/components/web-site/index.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/hero-fleet/src/components/web-site/index.tsx)
- [libs/examples/apps/hero-fleet/src/app/index.tsx](https://github.com/creact-labs/creact/blob/main/libs/examples/apps/hero-fleet/src/app/index.tsx)
# AI Integration with Claude and Cloud Deployment
## Overview and Scope
The `hero-fleet` example application is a demonstration workspace within the creact monorepo that showcases how AI-driven code generation composes with cloud infrastructure tooling. It pairs Anthropic's Claude model with AWS deployment utilities to produce and publish generated artifacts (HTML pages, web sites, channel payloads) directly from a React/creact front-end.
`Source: [libs/examples/apps/hero-fleet/src/app/index.tsx:1-40]()`
The application is not a production system; it is a reference implementation illustrating the boundaries between three concerns: (1) invoking a large language model, (2) transforming model output into deployable assets, and (3) pushing those assets to a cloud provider.
`Source: [libs/examples/apps/hero-fleet/src/components/claude/index.tsx:1-30]()`
## Component Layout
The front-end is decomposed into five feature components, each owning one capability. The root `app` component coordinates their composition and shared state.
| Component | Responsibility |
|-----------|----------------|
| `claude/` | Wraps the Claude API call and surfaces model responses |
| `aws/` | Wraps the cloud upload / deployment routine |
| `channel/` | Marshals a "generation request" into a transportable payload |
| `generate-html/` | Renders Claude's output as an HTML artifact |
| `web-site/` | Bundles generated HTML plus metadata into a publishable site |
`Source: [libs/examples/apps/hero-fleet/src/app/index.tsx:20-80]()`
This separation lets each integration be swapped independently — for example, replacing Claude with another provider only requires changes inside `claude/index.tsx`, while `aws/index.tsx` remains untouched.
`Source: [libs/examples/apps/hero-fleet/src/components/aws/index.tsx:1-40]()`
## Claude Integration
The `claude` component encapsulates the model invocation. It owns the request payload, the streaming or batched response handling, and any client-side post-processing before handing the text back to the rest of the app.
`Source: [libs/examples/apps/hero-fleet/src/components/claude/index.tsx:30-120]()`
Downstream components treat the Claude wrapper as a pure producer of text: they receive a string (or token stream) and decide what to do with it. The `generate-html` consumer interprets Claude output as markup, while `web-site` consumes a richer structure that may include titles, sections, and assets.
`Source: [libs/examples/apps/hero-fleet/src/components/generate-html/index.tsx:1-60]()`
`Source: [libs/examples/apps/hero-fleet/src/components/web-site/index.tsx:1-60]()`
The `channel` component sits between Claude and the generators, acting as a normalized envelope so that any future input source (not just Claude) can feed the same downstream pipeline.
`Source: [libs/examples/apps/hero-fleet/src/components/channel/index.tsx:1-50]()`
## Cloud Deployment via AWS
The `aws` component is responsible for shipping the generated assets to AWS. It accepts a finished artifact from `generate-html` or `web-site`, uploads it to the configured storage / hosting target, and returns a deployment handle (typically a URL or ARN) that the UI can display or hand to subsequent steps.
`Source: [libs/examples/apps/hero-fleet/src/components/aws/index.tsx:40-140]()`
Deployment configuration (bucket names, region, credentials) is expected to be supplied at the call site rather than hard-coded inside the component, keeping `aws/index.tsx` reusable across environments.
`Source: [libs/examples/apps/hero-fleet/src/components/aws/index.tsx:60-90]()`
## End-to-End Workflow
A typical user interaction follows this sequence:
1. The app collects the user's intent and forwards it through the `channel` envelope.
2. `claude` invokes the model and returns generated text.
3. `generate-html` or `web-site` shapes that text into a concrete artifact.
4. `aws` uploads the artifact and returns a deployment reference.
5. The app renders the reference back to the user.
```mermaid
flowchart LR
A[User Intent] --> B[channel]
B --> C[claude]
C --> D[generate-html / web-site]
D --> E[aws]
E --> F[Deployed URL]
F --> G[UI Result]
```
`Source: [libs/examples/apps/hero-fleet/src/app/index.tsx:40-100]()`
`Source: [libs/examples/apps/hero-fleet/src/components/channel/index.tsx:50-80]()`
## Design Observations
- Each feature component exposes a narrow, replaceable surface, which is the principal pedagogical point of `hero-fleet`.
- The Claude boundary and the AWS boundary are intentionally distant in the component tree: no component other than `app` knows about both, which keeps responsibilities clean.
- Credentials, prompts, and bucket configuration are all expected at the call site, leaving the example components free of secrets and environment-specific values.
`Source: [libs/examples/apps/hero-fleet/src/components/claude/index.tsx:120-160]()`
`Source: [libs/examples/apps/hero-fleet/src/components/aws/index.tsx:140-180]()`
---
## Runtime Boundaries, Error Handling, and Operations
### Related Pages
Related topics: [Runtime Engine: Fiber Model, Reconciliation, and State Machine](#page-2), [JSX Runtime, Components, and Control Flow Primitives](#page-4), [AI Integration with Claude and Cloud Deployment](#page-7)
Related Source Files
The following source files were used to generate this page:
- [packages/creact/src/runtime/create-runtime.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/create-runtime.ts)
- [packages/creact/src/runtime/async-mutex.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/async-mutex.ts)
- [packages/creact/src/runtime/plain-objects-equal.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/runtime/plain-objects-equal.ts)
- [packages/creact/src/flow/error-boundary.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/flow/error-boundary.ts)
- [packages/creact/src/types.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/types.ts)
- [apps/website/src/i18n/resources/en/docs/architecture/runtime_boundaries.json](https://github.com/creact-labs/creact/blob/main/apps/website/src/i18n/resources/en/docs/architecture/runtime_boundaries.json)
# Runtime Boundaries, Error Handling, and Operations
This page describes how the creact runtime defines its execution boundaries, isolates and surfaces errors, and exposes the core operations consumed by user code and internal subsystems. The content is bounded to the runtime package, the flow error boundary, shared type definitions, and the architecture documentation entry that frames the topic. Source: [apps/website/src/i18n/resources/en/docs/architecture/runtime_boundaries.json:1-1]()
## 1. Runtime Boundaries and the Async Mutex
The runtime is created through a single factory and operates as the boundary between user code (signals, computations, side effects) and the scheduling/notification machinery underneath. `createRuntime` returns the public surface that components and primitives interact with, while keeping mutation, subscription, and disposal private to the package. Source: [packages/creact/src/runtime/create-runtime.ts:1-1]()
Concurrency within the runtime is regulated by an async mutex that serializes access to shared mutable state. Because computations and effects can be scheduled from microtasks, timers, and async sources, the mutex guarantees that one logical unit of work holds the runtime state at a time, preventing torn reads and inconsistent observers. Source: [packages/creact/src/runtime/async-mutex.ts:1-1]()
The mutex exposes a minimal contract built around three operations: `acquire()` resolves when the caller obtains exclusive access, `release()` returns the lock and wakes the next waiter, and `runExclusive(fn)` is a convenience wrapper that acquires the lock, runs the supplied function, and releases it deterministically even when the function throws. This contract keeps "run this work inside the runtime" an explicit decision rather than an implicit one, which is the core of the boundary model.
## 2. Error Handling via the Error Boundary
Component-level failures are isolated by the flow error boundary, a control-flow primitive distinct from the runtime mutex. The boundary wraps a subtree, catches thrown values during render or effect execution, and renders a fallback instead of propagating the failure upward. Source: [packages/creact/src/flow/error-boundary.ts:1-1]()
Operationally, the boundary maintains a "did catch" flag that is reset on each commit and set when an error is captured. Children are rendered conditionally on this flag: the boundary renders its children; if a child throws (synchronously during render, or asynchronously inside an effect scheduled by the boundary) the throw is intercepted; the flag is set, and the fallback node is rendered on the next pass; a reset callback exposed by the boundary clears the flag so the children can be retried.
This pattern keeps the boundary's contract synchronous from the consumer's perspective while still tolerating async throws, because the runtime's mutex guarantees that the recovery path observes a consistent state. Source: [packages/creact/src/runtime/async-mutex.ts:1-1]()
## 3. Core Operations: Equality and Shared Types
Equality is treated as an explicit runtime operation rather than an implicit `===`. The `plainObjectsEqual` helper compares two records key-by-key, recursing into nested plain objects and short-circuiting on the first mismatch. It is used by reactive primitives that need to decide whether a value change should propagate to subscribers, and it deliberately avoids walking class instances or functions so that referential identity is preserved for non-plain values. Source: [packages/creact/src/runtime/plain-objects-equal.ts:1-1]()
The shared type module defines the vocabulary that ties these pieces together. It exposes the runtime shape, including the operation handles returned by `createRuntime`; the error boundary props and the fallback node type; and the discriminated shape of values flowing through the system (plain objects, primitives, signals, computations). Source: [packages/creact/src/types.ts:1-1]()
By centralizing the types, the runtime, the equality helper, and the boundary all speak the same language about what constitutes a "value", a "node", and an "operation", which prevents drift between the scheduler, the recovery path, and the public API.
## 4. How the Pieces Compose
The diagram below shows how a user operation flows from the public API through the boundary, into the runtime, and back out as a notification or a recovered render.
```mermaid
flowchart TD
A[User code: read/write/compute] --> B[createRuntime surface]
B --> C{async-mutex acquire}
C --> D[Mutate internal state]
D --> E[plainObjectsEqual vs last snapshot]
E -- changed --> F[Schedule subscribers]
E -- unchanged --> G[Skip]
F --> H[Release lock]
G --> H
H --> I[Notify effect / boundary]
I -- thrown --> J[error-boundary fallback]
I -- ok --> K[Commit]
```
Two boundaries are visible: the mutex, which separates "inside the runtime" from "outside", and the error boundary, which separates "healthy subtree" from "recovered subtree". Equality sits between them as the gate that decides whether a state change is worth crossing the notification boundary. Source: [packages/creact/src/runtime/plain-objects-equal.ts:1-1]()
Together, these files describe a runtime whose discipline is "one owner of state, one place to recover from failure, one definition of equality". Every other module in creact depends on this discipline rather than re-implementing it, which is why the runtime boundary, error boundary, and equality helper live in dedicated files and are wired together through the shared type contract.
---
---
## Pitfall Log
Project: creact-labs/creact
Summary: Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.
## 1. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/creact-labs/creact
## 2. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/creact-labs/creact
## 3. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/creact-labs/creact
## 4. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/creact-labs/creact
## 5. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/creact-labs/creact
## 6. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/creact-labs/creact