UECA-React

The React framework for applications that AI agents write and people verify.

UECA-React is a framework for building scalable React applications with a unified and encapsulated component architecture. It simplifies development by hiding the complexities of React and MobX behind a consistent component pattern. The framework is designed specifically for AI code generation and human verification: it ships the agent skills that teach an assistant the pattern, and a trace viewer that shows you what the generated application actually does.

Built for AI agents

UECA-React is built for projects where AI agents write the code and people stay in control of it — a web application or a site alike.

• One shape to generate, one shape to review. Every component is the same three declarations — a struct, a model hook and a functional component — with the struct's sections in one documented order. An agent that has seen one component has seen the pattern, and a reviewer checks the same short list on every file.
• The instructions ship in the package. skills/ holds two agent skills: ueca-app-development for writing components — the pattern, state and bindings, lifecycle, model caching, the message bus — and ueca-app-architecture for a whole application — a complete barebone app to scaffold from, where each concern belongs, and how to move an existing app across: rewrite it from its documentation, or migrate a React app in stages. They describe the published API only, so they hold for any project.
• Mistakes are loud, or written down. Mistakes the framework detects throw and reach globalSettings.errorHandler, rather than being logged and dropped. The ones that fail silently are listed by symptom in the skills, so an agent looks the cause up instead of guessing.
• You can see what was built. The trace viewer draws the running application — its components, its message bus and its bindings — and UECA.trace saves the same record as JSON or as a Mermaid diagram for an agent to read.
• The demos are built this way. All three live demos are developed with AI agents, each working from a CLAUDE.md and the two skills.

Give your agent the skills — .claude/skills/ is where Claude Code looks:

npx ueca-react-skills

That copies both skills into .claude/skills/, replacing any earlier copy so nothing stale survives an upgrade. Your own skills in that directory are left alone, and --dest puts them wherever your agent reads its instructions instead.

Installing the package runs nothing: there is no postinstall hook, so the skills arrive when you ask for them and not before. Re-run the command after upgrading ueca-react, or put it in a postinstall of your own.

skills/README.md covers --dest for an agent that reads its instructions elsewhere, the manual alternatives, and the lines to add to whichever file your agent reads first.

What's new in 3.2

• StrictMode, properly. deinit runs after a component has re-rendered, React 19 builds one model per hook call, and React 18 is tested — the whole suite runs on it in CI.
• Quiet mistakes now throw. An id that clashes with a member of its owner, a child hook that changed between mounts, a param written over a cached child and a hook assigned to a model each used to misbehave without a word; each now throws, saying what to change.
• New: render={false} on any component element, a message bus of your own (createMessageBus and useCustomMessaging), and StructHooks for declaration files.
• No more lost values. A new Date, RegExp, Map or Set is no longer taken for no change, and a failing lifecycle hook reaches errorHandler under Node too.

The changelog has the detail, including the four mistakes that now throw.

What's new in 3.1

• Views keep their identity. A model's View is built once and stays the same component type, so re-rendering a component no longer remounts what is under it — a plain React component inside a UECA view keeps its useState, its refs and its effects.
• A bound plain array is handed over once. A getter that keeps returning the same array no longer assigns, copies and compares it on every run, and isEqual is linear: three comparisons of equal 100,000-item values took 25 s and take 0.2 s.
• A new trace viewer, built as a UECA-React application of its own, with a records table that draws only the rows on screen — a 52,240-record trace pastes in a quarter of a second where it took six.

The changelog has the detail, including the one thing an application can notice: an in-place change to a plain, non-observable source array no longer reaches a bound property.

What's new in 3.0

That is not a mock-up — go press the button yourself. All three live demos ship <UECA.TraceViewerButton/> in the corner. Open one, click it, and the viewer above opens on the application you are looking at, with its own trace in it. Each demo's source sits next to its link.

• A visual Trace Viewer, in the box. Drop <UECA.TraceViewerButton/> at the root of an application and watch it run — the component tree, the message bus and every binding, live. See below.
• Every mistake is reported. Assignments that used to be logged and dropped now throw, and reach globalSettings.errorHandler.
• React.StrictMode is supported — and the leak it exposed is fixed for everyone else too.
• Bindings converge, or say why they cannot. An onChanging rewrite now reaches the far end of a chain, and arrays sync in place at roughly twice the speed.
• The framework's own agent instructions ship with it. skills/ carries the component pattern and the whole-application architecture, so an AI assistant working in your project follows them instead of guessing at them. See Built for AI agents.
• This release has breaking changes. See Upgrading from 2.x and the changelog.

Installation

To install UECA-React, run the following command:

npm install ueca-react

Ensure that your project also has the following dependencies installed:

• react
• react-dom
• mobx
• mobx-react

Compatible React versions: 16–19. Make sure your react-dom version matches your react version.

Quick start

Every UECA component is the same three declarations — a struct, a model hook, and a functional component:

import * as UECA from "ueca-react";

type ButtonStruct = UECA.ComponentStruct<{
    props: {
        caption: string;
        disabled: boolean;
    };

    events: {
        onClick: () => void;
    };
}>;

type ButtonParams = UECA.ComponentParams<ButtonStruct>;
type ButtonModel = UECA.ComponentModel<ButtonStruct>;

function useButton(params?: ButtonParams): ButtonModel {
    const struct: ButtonStruct = {
        props: {
            // `id` comes first: it drives the DOM id, the full path, bus addressing and the model cache.
            id: useButton.name,
            caption: "",
            disabled: false
        },

        events: {
            onClick: () => {
                console.log(`${model.fullId()} clicked`);
            },

            // Generated for every property, with no declaration needed.
            onChangeDisabled: (value) => {
                console.log(`${model.fullId()} disabled=${value}`);
            }
        },

        View: () => (
            <button 
                id={model.htmlId()}
                disabled={model.disabled}
                onClick={() => model.onClick?.()}
            >
                {model.caption}
            </button>
        )
    };

    // Declared after the struct, which closes over it. Later calls return the same model.
    const model = UECA.useComponent(struct, params);
    return model;
}

const Button = UECA.getFC(useButton);

export { type ButtonModel, useButton, Button };

Use it as a component, or drive it through its model:

<Button 
    caption="Save"
    disabled={false}
    onClick={() => save()}
/>

For more detailed information, check out the full documentation.

Tracing and the Trace Viewer

Every model creation, lifecycle hook, render, property change, binding sync, cache decision and bus message is a structured trace record. The viewer ships with the library and reads them live.

// A button pinned to a screen corner, opening the viewer over your application:
<UECA.TraceViewerButton/>

// ...or the panel embedded wherever you want it:
<UECA.TraceViewer height={600}/>

Both are development tools, and a closed viewer costs nothing — the viewer page is a separate chunk that is downloaded only when it is opened.

Five views over one trace:

View	What it shows
Table	every record, filterable by kind, component and text; click one for the full detail. Above 200 rows it draws only the rows on screen
Timeline	when things happened, and what happened together
Sequence	messages and calls between components, as a sequence diagram
Tree	the component hierarchy the trace built
Graph	the component tree with the message bus and binding wiring drawn on it — and the trace played through it

You do not need any UI at all:

UECA.globalSettings.tracing = { capture: 5000 };  // record silently, even with the console quiet
UECA.trace.records();                             // everything captured
UECA.trace.save("trace.json");                    // reopen it in the viewer
UECA.trace.save("flow.mmd");                      // ...or write a Mermaid sequence diagram

window.UECA is globalSettings, so window.UECA.trace.save() works from a devtools console with nothing imported and no rebuild.

Features

• Built for AI Agents: One pattern to generate and to review, with the agent skills in the package
• Unified Component Pattern: Consistent structure for all components
• Type-Safe: Full TypeScript support with comprehensive type definitions
• MobX Integration: Automatic reactivity without manual state management
• Automatic onChange Events: Auto-generated event handlers for every property (e.g., onChangeCaption for caption prop)
• Lifecycle Hooks: Built-in lifecycle management — in through constr → init → draw → mount, out through erase → unmount → deinit
• Message Bus: Decoupled inter-component communication
• Property Bindings: Bidirectional data binding between components
• Tracing and the Trace Viewer: A structured trace of everything the framework does, and a viewer for it
• Error Containment: A failing view is contained to its own component, and errors reach one handler

Upgrading from 2.x

3.0 is a breaking release. The short list — the changelog has the detail:

• Mistakes that used to be logged now throw: assigning a non-function to an event, assigning to a declared method or child model, a binding passed for cacheable, two siblings claiming one id, and a parameter that switches between a binding and a value.
• unicast and castTo throw before dispatching when more than one subscriber matches.
• A message that declares no payload now takes no argument — unicast("Msg", undefined) is a compile error, unicast("Msg") is correct.
• draw and erase must be synchronous.
• A children-section constant is an initial value and is no longer re-asserted when a cached model remounts. A JSX prop still is.
• id and cacheable no longer accept a binding, and no longer generate onChange/onChanging events.
• hashHtmlId is read from globalSettings, not from window.

Live Demos

See UECA-React in action in complete working applications, developed with AI agents — GitHub Copilot at first, Claude Code since.

Every one of them ships <UECA.TraceViewerButton/>: the button in the corner opens the trace viewer on the running application, so you can watch the component tree, the message bus and the bindings of code you can read in the same tab.

🔗 Demo 1: Showcase
📂 Source Code: GitHub Repository

🔗 Demo 2: UECA-React API Documentation
📂 Source Code: GitHub Repository

🔗 Demo 3: MUI Components
📂 Source Code: GitHub Repository

API Documentation

Comprehensive API Documentation is also available, and the package ships the programming guide in the docs folder.

The guide:

• Introduction to UECA-React
• Component Guide
• State Management
• Message Bus
• Lifecycle Hooks
• Property Bindings
• Tracing

docs/raw/index.md is the contents page, and docs/tools/trace-viewer.html reads a saved trace with no application running. The agent skills are in skills/ — see Built for AI agents.

Support

For questions, issues, or feature requests, please use the GitHub issue tracker.

License

This project is licensed under the ISC License - see the LICENSE file for details.

Author

Aleksey Suvorov
Email: [email protected]
Website: cranesoft.net
GitHub: nekutuzov
Npm: nekutuzov
Dev.to: nekutuzov