UECA-React

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 designed specifically for AI code generation and human verification.

What's new in 3.0

• 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 below.
• 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 | | 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

• 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
• AI-Friendly: Designed for easy code generation and AI assistance

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 with complete working applications developed with GitHub Copilot AI assistance:

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

🔗 Demo 2: Storybook
📂 Source Code: GitHub Repository

🔗 Demo 3: UECA-React API Documentation
📂 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.

Skills for AI assistants

The package also ships agent skills in skills/, so an assistant working in your project follows the framework's own instructions instead of guessing at them:

• ueca-app-development — writing components: the struct/hook/getFC pattern, state and bindings, lifecycle, model caching, the message bus, and a symptom-indexed list of the mistakes that fail silently.
• ueca-app-architecture — a whole application: a complete barebone app to scaffold from, where each concern belongs, and a staged plan for migrating an existing React app.

Make them visible to your assistant by copying them into your project — .claude/skills/ is where Claude Code looks:

cp -r node_modules/ueca-react/skills/* .claude/skills/

skills/README.md covers symlinking and a postinstall hook, so the skills track the version of the library you actually have installed.

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