#+TITLE: ExtBit ProtoUI Reference Engine
#+AUTHOR: ExtBit Engineering & Architecture Group
#+DATE: <2026-08-27 Thu>
#+OPTIONS: toc:2 num:nil

* Overview

*ExtBit ProtoUI* (=.pui=) is an ultra-lightweight, line-based declarative UI streaming protocol. This repository contains the official *C++20 parsing and rendering engine* built for [[https://github.com/ocornut/imgui][Dear ImGui]].

Engineered for zero-trust IPC, terminal toolchains, CLI utilities, and P2P networks (=cpp-libp2p=), this engine parses declarative streams incrementally in a single $O(N)$ zero-heap-allocation pass directly into immediate-mode render loops.

#+BEGIN_QUOTE
📖 *Official Specification:* For the formal EBNF grammar, widget reference, and P2P cryptographic attestation envelopes, please read the official specification: *[[https://extbit.com/protoui]]*
#+END_QUOTE

-----

* Engine Features

- *Zero-Allocation Parser:* Written in C++20 using =std::string_view= slice evaluation, ensuring the parser runs without stalling high-frequency 60 FPS UI threads.
- *Drop-In ImGui Integration:* Renders natively into any existing Dear ImGui context without requiring complex layout abstractions.
- *Reactive Event Dispatching:* Event routing operators (=->=) stream widget state changes and user interactions directly to C++ lambda handlers.

-----

* Integration & Build

** Direct Source Inclusion (Recommended)
The easiest way to integrate ProtoUI into your existing ImGui application is to include the source directly in your build system (CMake, Make, etc.).

Add =ProtoUI/include= to your project's header search paths and compile =ProtoUI/src/ProtoUI.cpp= alongside your project files.

#+BEGIN_SRC c++
#include <extbit/ProtoUI.h>
#+END_SRC

** Building the Static Library (=libProtoUI.a=)
If you prefer to link statically:

#+BEGIN_SRC bash
cd ProtoUI
make IMGUI_DIR=/path/to/imgui
#+END_SRC
This outputs =build/*.o= object files and generates =lib/libProtoUI.a=.

-----

* C++ API Quick Start

This engine is designed to wrap seamlessly inside your existing ImGui render loop. Use =extbit::protoui::Context= to ingest stream payloads and emit ImGui draw calls.

#+BEGIN_SRC c++
#include <extbit/ProtoUI.h>
#include <iostream>

extbit::protoui::Context uiContext;

void InitializeUI() {
    // 1. Bind native action callback for '->' event streams
    uiContext.onAction = [](std::string_view action, const extbit::protoui::StateValue& value) {
        if (action == "extbit:demo.click") {
            std::cout << "Button clicked natively!\n";
        }
    };

    // 2. Parse a minimal ProtoUI Stream
    uiContext.Parse(R"(
@protoui:v1
@title Hello ProtoUI
@kv Status | Engine Initialized
@button Run Diagnostic -> extbit:demo.click
    )");
}

void RenderFrame() {
    // 3. Call inside your main Dear ImGui frame loop
    ImGui::Begin("ProtoUI Window");
    uiContext.Render();
    ImGui::End();
}
#+END_SRC

-----

* Project Status: Under Active Development (v0.1-alpha)

ExtBit ProtoUI is currently in active refinement alongside the ExtBit Console. The underlying DSL specification is stabilized, but C++ engine APIs and layout stack behaviors may undergo minor optimizations. 

-----

* License

ExtBit ProtoUI Reference Implementation is open-source software dual-licensed under the *Apache License 2.0* and the *MIT License*. 
Copyright (c) 2026 *ExtBit LLC*. Created by *Duzy Chan*.