⚡ Aria

📚 From beginner to expert: AriaTutorial

Want to learn Aria systematically? The companion tutorial repo AriaTutorial provides 20 chapters of progressive bilingual (English/Chinese) tutorials, each chapter accompanied by a minimal demo that compiles and runs.

• Every code block in the body is byte-identical to the source files under demos/; they are not hand-typed illustrative code;
• Each output is the actual stdout of the demo on Windows / MSVC, automatically verified by scripts;
• Each chapter ships with one summary figure (data flow / dependency graph / state machine / timeline), and the numbers in the figures also come from the demo's actual run results;
• The learning path covers: reactive core → collections and forms → binding and adapters → async, diagnostics and testing → a complete application.

🌟 Flagship example: AriaTools

Want to see how Aria lands in a real application first? Start with AriaTools. It is Aria's only flagship cross-platform example, where a single C++ ViewModel drives Qt, iOS, Android and Web. This repository only contains the framework, acceptance tests, and minimal code snippets from the documentation.

🚀 Understand Aria in 30 seconds

Aria splits a UI in two halves: the ViewModel is pure C++ and knows nothing about any UI library; the View is the native controls of each platform. In between sits the BindingEngine, which only recognizes the IViewAdapter interface, so switching platforms only means swapping the adapter.

Top half — ViewModel (pure C++, unit-testable, shared across all platforms)

// AA 制账单：总额 ÷ 人数 = 每人多少
struct BillViewModel {
    aria::Property<double> bill{100.0};   // 可读写的状态
    aria::Property<int>    people{2};

    // Computed 是只读派生值。它的依赖不用手写：首次求值时读到了
    // bill 和 people，就自动记下这两个依赖。
    aria::Computed<double> per_person{[this] {
        return bill.get() / people.get();
    }};
};

This code contains no UI at all, and no #include of any UI library — it can be tested from the command line.

Bottom half — View-side wiring (a dozen lines per platform; the UI itself is still written natively for each platform)

Let's clear up the most common misconception: the UI is not written in C++. Buttons, layouts, and animations are still written with Qt Designer, Storyboard, Compose, or HTML. The dozen lines below are just wiring code that "hands existing controls to the engine", always in three steps — ① create a platform adapter ② use it to create the BindingEngine ③ bind the controls to Properties.

auto adapter = std::make_shared<aria::adapters::qt6::QtAdapter>();
aria::binding::BindingEngine engine{adapter};

BillViewModel vm;
// label_view 包住你在 Qt Designer 里拖出来的那个 QLabel
aria::adapters::qt6::QtView label_view{real_label};
engine.bind_text_projected(vm.per_person, label_view,
    [](https://github.com/dqsjqian/Aria/blob/HEAD/double v) { return std::format("¥{:.2f}", v); });

#import "aria/adapters/uikit/UIKitAdapter.hpp"

auto adapter = std::make_shared<aria::adapters::uikit::UIKitAdapter>();
aria::binding::BindingEngine engine(adapter, ui_dispatcher,
    aria::binding::BindingEngine::DispatchPolicy::SmartMarshal);

// 把 Storyboard 里的 UILabel* 包一层，C++ 侧就能绑它
auto label = std::make_shared<aria::adapters::uikit::UIKitView>(self.totalLabel);
engine.bind_text_projected(vm.per_person, *label,
    [](https://github.com/dqsjqian/Aria/blob/HEAD/double v) { return std::format("¥{:.2f}", v); });

#import "aria/adapters/appkit/AppKitAdapter.hpp"

auto adapter = std::make_shared<aria::adapters::appkit::AppKitAdapter>();
aria::binding::BindingEngine engine(adapter, ui_dispatcher,
    aria::binding::BindingEngine::DispatchPolicy::SmartMarshal);

auto label = std::make_shared<aria::adapters::appkit::AppKitView>(self.totalField);
engine.bind_text_projected(vm.per_person, *label, /* ... */);

// 在 Android UI 线程上调用，传进来的是真实的 android.view.View 对象
auto adapter = std::make_shared<aria::adapters::jni::JniAdapter>(env);
aria::binding::BindingEngine engine(adapter);

aria::adapters::jni::JniView total_view(env, total_text_view);
engine.bind_text_projected(vm.per_person, total_view,
    [](https://github.com/dqsjqian/Aria/blob/HEAD/double v) { return std::format("¥{:.2f}", v); });   // → TextView

aria::adapters::http::HttpAdapterConfig config;
config.port = 9090;
auto http = std::make_shared<aria::adapters::http::HttpAdapter>(config);

// "控件"在这里是字符串 ID，对应浏览器里的 DOM 元素
auto& total = http->register_view("total", "text");

aria::binding::BindingEngine engine{http};
engine.bind_text_projected(vm.per_person, total,
    [](https://github.com/dqsjqian/Aria/blob/HEAD/double v) { return std::format("¥{:.2f}", v); });
http->start();  // Property 变化经 SSE 推给浏览器，用户操作经 REST 回来

This is the point: the five wiring code blocks look almost identical, while the BillViewModel above has not had a single word changed. What you're swapping across platforms is these dozen lines, not the business logic.

After wiring — just change the data, and the UI updates itself

After binding on each platform above, the rest is platform-agnostic. The following snippet behaves identically on all five, with no hand-written refresh code:

BillViewModel vm;                       // per_person = 100/2 = ¥50.00
// ... 按上面任意一个平台绑定到 label ...

vm.people = 4;                          // label → ¥25.00
vm.bill   = 200.0;                      // label → ¥50.00

Change either bill or people, and per_person is recomputed and pushed to the label — because its dependencies were automatically recorded when the Computed was first evaluated. You never wrote any "when people changes, update the label" code.

A detail:

// 逐个改 → 每次都推一次，label 会闪过中间值
vm.bill = 300.0;    // label → ¥150.00  ← 中间态
vm.people = 4;      // label → ¥75.00

// 包进 batch → 只在结束时推一次，不出现中间态
aria::reactive::batch([&] {
    vm.bill   = 1200.0;
    vm.people = 8;
});                 // label → ¥150.00（一次）

Another default behavior that saves you headaches: if the final result equals the current value, not a single notification is sent. For example, after that, setting bill=600, people=4 in a batch (still 150) won't disturb the label.

See the whole architecture in a single diagram — top is the pure C++ ViewModel, middle is the BindingEngine (recognizing only the IViewAdapter interface), bottom is the five native adapters:

Keep reading: Binding guide · Platform adapters guide · Cookbook · AriaTools (a complete application across Qt / iOS / Android / Web).

🎯 Positioning and trade-offs

Aria does one thing: extract the reactive engine and binding layer out of UI frameworks, and make it a pure C++ library that supports C++23 and is not tied to any UI toolkit.

The ViewModel is a plain C++ class — it does not inherit from any framework base class, requires no macros, and needs no code generator. The UI layer plugs in via IViewAdapter; currently five adapters are implemented in the repo: Qt6 / AppKit / UIKit / JNI / HTTP. Swapping UI toolkits does not require touching the ViewModel.

Understand the costs first:

Suitable for: projects that already have a C++ business core, need to reuse the same logic across multiple platforms, and want each platform to keep native UI. Not suitable for: "one codebase spanning platforms including the UI" scenarios — that's the territory of complete UI frameworks like Flutter or Qt Quick, which each have mature reactive binding solutions. Aria does not aim to replace them.

✨ Core features

• 📦 Templated reactive core — Property<T> / Computed<T> / Effect / Command<> / ObservableList<T> / Validator<T> share the same reactive dependency graph engine. Computed auto-tracks dependencies; reactive::batch / reactive::untracked precisely control the scope of notifications.
• 🔌 Shared base library and ABI layer — aria::core auto-links aria::abi, unifying the reactive graph across shared libraries, along with diagnostics and signal storage. The ABI requires consistent compiler, standard library, build options, and major version; templates and their host types must be recompiled after updates.
• ⚡ C++ coroutines — Task<T>, executors, co_await schedule_on(pool); async code reads like sync code.
• 🖥 Adapter abstraction (IViewAdapter) — Qt6 / AppKit / UIKit / JNI / HTTP; any UI toolkit can be driven by the same business logic.

🏗 Architecture (10 modules)

┌────────────────────────────────────────────────────────────────────────┐
│                         应用层 (Application)                            │
└────────────────────────────────┬───────────────────────────────────────┘
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
   │ Qt6 适配器    │    │ JNI 适配器    │    │ HTTP 适配器   │     (可选模块；
   │ (Win/Mac/Lin)│    │  (Android)   │    │ REST/SSE Web │      按需启用)
   │ AppKit/UIKit │    │              │    │ WASM 按需评估   │
   └──────┬───────┘    └──────┬───────┘    └──────┬───────┘
          └───────────────────┴───────────────────┘
                              ▼
              ┌─────────────────────────────────┐
              │    aria-binding  (SHARED)       │
              │  BindingEngine + IViewAdapter   │
              └────────────────┬────────────────┘
                               │
        ┌──────────────────────┴───────────────────────┐
        ▼                                              ▼
┌───────────────────┐                       ┌────────────────────┐
│ aria-runtime      │                       │  aria-async        │
│ (SHARED .dylib)   │                       │   (仅头文件)        │
│ EventBus          │                       │ Task<T>            │
│ Container         │                       │ Scheduler          │
│ Dispatcher        │                       │ Executor           │
│ Logger            │                       │ schedule_on        │
└───────┬───────────┘                       └─────────┬──────────┘
        └──────────────────┬─────────────────────────┘
                           ▼
              ┌─────────────────────────────┐
              │ aria-core  (仅头文件)        │
              │ Property / Computed / Cmd   │
              │ ObservableList / Validator  │
              │ Subscription                │
              └────────────┬──────────────┘
                             ▼
              ┌─────────────────────────────┐
              │  aria-abi  (SHARED)      │
              │ 类型擦除 Signal/Slot         │
              │ ABI 稳定，无模板              │
              └─────────────────────────────┘

📋 Environment requirements

• CMake >= 3.20
• Compiler with full C++20 support:
  • GCC >= 12 (on Windows, the MSYS2 UCRT64 toolchain works)
  • Clang >= 15 (on macOS/iOS, AppleClang 15+ is sufficient)
  • MSVC v143 / Visual Studio 2022 (Windows, details below)
• C++23 is selectable via -DCMAKE_CXX_STANDARD=23; the minimum requirement remains C++20, see evaluation.
• (Optional) Qt6 >= 6.4 (for the Qt6 adapter)

Windows supports both MSYS2 UCRT64 (GCC) and MSVC / Visual Studio 2022 toolchains. Use whichever is in your team stack — the same source tree builds the full framework + tests + adapters without branches or forks.

🚀 Quick start

git clone https://github.com/dqsjqian/Aria.git
cd Aria
cmake -B build/flavors/release -DCMAKE_BUILD_TYPE=Release
cmake --build build/flavors/release -j
ctest --test-dir build/flavors/release --output-on-failure

build/ is a container for the build tree; do not configure directly into it. See the unified layout at the top of scripts/build.sh.

🔧 One-click build scripts

# macOS / Linux
scripts/build.sh             # Release
scripts/build.sh tests       # Release + 跑测试
scripts/build.sh asan        # Debug + AddressSanitizer + UBSan
scripts/build.sh tsan        # Debug + ThreadSanitizer

# Windows —— MSYS2 UCRT64（GCC + Ninja）
scripts\build.ps1            # Release
scripts\build.ps1 tests
scripts\build.ps1 asan
scripts\build.ps1 tsan       # Debug + ThreadSanitizer（MSVC 不支持，见下）

# Windows —— MSVC / Visual Studio 2022
scripts\build-msvc.ps1       # Release（使用 build/flavors/msvc/ 目录）
scripts\build-msvc.ps1 tests
scripts\build-msvc.ps1 debug

🛠 Windows toolchains

# 1. 安装 Visual Studio 2022 Build Tools（或完整 IDE），勾选
#    "Desktop development with C++" + "C++ CMake tools"。
# 2. （可选）安装 Qt 6 的 msvc2022_64 组件。
# 3. 任意 PowerShell 窗口里：
scripts\build-msvc.ps1 tests

# 1. 从 https://www.msys2.org 安装 MSYS2
# 2. 打开 "MSYS2 UCRT64" 终端：
pacman -Syu
pacman -S --needed mingw-w64-ucrt-x86_64-toolchain \
                   mingw-w64-ucrt-x86_64-cmake \
                   mingw-w64-ucrt-x86_64-ninja git
# 3. （可选）把 C:\msys64\ucrt64\bin 加入 PATH
# 4. 从任意终端执行：
scripts\build.ps1 tests

📦 Using it in your own project

Option A — install first, then find_package (recommended for production):

cmake -S . -B build/flavors/release -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build/flavors/release -j && sudo cmake --install build/flavors/release

find_package(aria 2.0 CONFIG REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE aria::aria)
# 也可以按需选择模块：aria::core / ::async / ::runtime / ::binding

Aria shared libraries in the Linux package resolve other Aria libraries from the same directory. Keep them together; after moving the SDK, reconfigure projects that use it with the new install path.

Option B — embed directly (no install):

add_subdirectory(third_party/aria EXCLUDE_FROM_ALL)
target_link_libraries(my_app PRIVATE aria::core aria::async)

💻 Flagship example

AriaTools is the only flagship cross-platform example: a single C++ ViewModel drives Qt, iOS, Android and Web, all four gated by CI. It is also the reference implementation for the two Android integration forms (Compose side-channel and typed JniAdapter). The Aria repo itself no longer hosts application examples; framework behavior is pinned by tests/acceptance/ and per-module tests, and the docs only keep minimal snippets focused on a single concept.

⚙️ Build options

👋 Hello, world

The previous section needed a UI adapter. To see pure reactivity in the console, no UI is required:

#include "aria/aria.hpp"
using namespace aria;

Property<int> count{0};

// Computed 不需要显式依赖列表 —— 首次求值时读到了 count，
// 就自动记下这个依赖。
Computed<std::string> label([&]{
    return "count = " + std::to_string(count.get());
});

Command<> increment([&]{ count = count.get() + 1; });

// bind 建立订阅：先立刻用当前值调一次，之后 label 每次变化都再调一次。
// 返回的 Subscription 是这条订阅的"遥控器"，它决定订阅活多久 ——
// 所以必须接住。写成 `label.bind(...);` 丢掉返回值，临时对象立即析构，
// 订阅在这一行就断了，后面什么都不会打印（bind 标了 [[nodiscard]]，
// 编译器会警告你）。
auto sub = label.bind([](https://github.com/dqsjqian/Aria/blob/HEAD/const std::string& s) { std::cout << s << '\n'; });
// ↑ 这一行就已经打印了 "count = 0"（initial sync）

increment();   // → "count = 1"
increment();   // → "count = 2"

// sub 析构时自动退订，不需要手写反注册；也可以提前主动断开：
sub.release();
increment();   // 不再打印任何东西

sub simply expresses the subscription lifetime with scope: while the variable is alive, the subscription is alive; when the variable goes away, the subscription auto-detaches. In a real UI, this Subscription is usually stored as a member of the View; when the View is destroyed the subscription is released, so no callback ever reaches a destructed control.

⚡ Async programming (C++ coroutines)

#include "aria/async/task.hpp"
#include "aria/async/executor.hpp"
using namespace aria::async;

Task<std::string> fetch_user(int id) {
    co_await schedule_on(network_pool);     // 跳到工作线程
    auto raw = http::get("/users/" + std::to_string(id));
    co_await schedule_on(main_dispatcher);   // 切回 UI 线程
    co_return parse(raw);
}

🌍 Cross-platform mapping

🖼 Cross-platform results

The big picture — three real apps from one framework:

Below are the Aria framework in action in real applications — a single C++ ViewModel across multiple platforms with native shells. AriaTools (a cross-platform workbench with 17 modules, Qt / iOS / Android / Web), AriaAgent (a Provider-agnostic LLM Agent GUI), OpenRead (a cross-platform book-source engine, HTTP/SSE Web shell) all use Aria 1.x in production form. All screenshots are from stable releases; one build, shared across platforms with the same C++ business core.

AriaTools — Cross-platform workbench (17 modules)

Aria's flagship cross-platform example: one ViewModel running on four platforms. The left-side navigation — cart / theme switch / Framework Lab / Echo and other modules — is all driven by ObservableList, Computed, and reactive::batch.

Platform	Screenshot	Adapter
macOS (Qt6)		aria-qt6
iOS / UIKit		aria-uikit
Android (Compose side-channel)		aria-jni
Web (HTTP/REST/SSE)		aria-http

AriaAgent — LLM Agent GUI

A Provider-agnostic Agent GUI built with Aria + Qt6: true streaming SSE, tool-call chain visualization, permission approval, Markdown rendering.

View	Screenshot
Main view (conversation)
Settings (General / Model / Plugins / Agent Presets)

OpenRead — Cross-platform book-source engine

A book-source management Web app driven by the Aria HTTP adapter: left-side source list + right-side book card grid, with full-text search, subscriptions, and debugging all in one place. The same C++ core drives both the REST/SSE thin client and SSR Web forms.

View	Screenshot
Book-source management (Web / REST+SSE)
Book-source management (Web / SSR)

The screenshots above are from the macOS example app. Other platforms reuse the same ViewModel; native control appearance is determined by the platform, Qt styles, and the host app. For the Windows / Linux build and test status, refer to CI.

🧪 Test status

ctest --test-dir build/flavors/release --no-tests=error --output-on-failure

Tests cover reactive state, collection events, async cancellation, binding lifecycle, ABI, and adapter contracts; the tests actually enabled depend on build options and platform. See CI results and the lifecycle contract, error model.

📊 Performance benchmarks

2026-09-13, Apple M3 Pro / Apple Clang 21 / C++20 Release (-O3 -DNDEBUG). Below is the median of average latencies across five paired runs; the original is eeb613f, and the new measurement snapshot is the 2.0 refactor commit c33850d.

Performance went up and down: carrying event data and maintaining sort correctness after batched modifications also has a cost. For full scenarios, complexity, remaining regressions, and how to reproduce, see the performance notes.

📋 Framework contract

All non-trivial behaviors are pinned in numbered contract documents, each contract having a stable ID (e.g., L-13 / E-22 / LD-7).

The public API reference is auto-built and published from the main branch. To upgrade from 1.2.x, read the 2.0 migration guide.

🗺 Roadmap

Aria is open source (MIT License), with the source hosted on GitHub. The single source of truth for the to-do and deferred lists is docs/ROADMAP.md; see CHANGELOG.md for the current capability snapshot.

🤝 Contributing guide

Contributions welcome! Discuss architecture changes in an Issue first.

• Code style is governed by .clang-format and .clang-tidy
• All changes must pass ctest --output-on-failure
• New features require tests in the corresponding modules/*/tests/ suite

🙏 Acknowledgements

• doctest — lightweight testing framework
• nlohmann_json — JSON for Modern C++
• cpp-httplib — HTTP/HTTPS server
• OpenSSL — TLS 1.2/1.3 (version in third_party/openssl/VERSION.dat)
• CPM.cmake — CMake dependency management

📄 License

MIT © 2026 aria contributors