SPECIFICATION.org

#+title: ExtBit ProtoUI Specification & Grammar (.pui)
#+author: ExtBit Engineering & Architecture Group
#+date: <2026-08-27 Thu>
#+created: 2026-08-27
#+updated: 2026-08-27
#+description: Official technical specification and formal grammar for ExtBit ProtoUI (.pui)—an ultra-lightweight, line-based declarative UI streaming protocol engineered for C++, CLI toolchains, and P2P networks.
#+keywords: protoui, pui grammar, extbit, imgui, c++, p2p ui, declarative ui, zero-trust, stream protocol
#+options: toc:2 num:nil
#+tags: specification protoui grammar c++ p2p ui

* Overview & Design Philosophy

*ExtBit ProtoUI* (=.pui=) is an open, line-based declarative UI streaming specification designed for real-time IPC, terminal toolchains, and P2P networks (=cpp-libp2p=).

Unlike heavy serialization formats (JSON, XML, HTML/CSS), ProtoUI requires *zero string escaping* and *zero quotes*, parsing incrementally line-by-line in a single =O(N)= pass directly into immediate-mode renderers (Dear ImGui).

- *Wire Efficiency:* Streamed raw over Unix Sockets, =stdout= pipes, or WebSockets without AST construction overhead.
- *Human-Centric Authoring:* Designed to be written intuitively using standard Unix shell =echo= or Markdown-like formatting.
- *Zero-Allocation Parsing:* Parsed in native C++ using =std::string_view= for zero-heap-allocation render loops.
- *Contextual Scoping:* Layout containers use standard empty line separators for scope popping, eliminating tag-matching friction.

-----

* Formal Grammar & Lexical Rules

** Specification Version
Every ProtoUI stream MUST begin with a protocol version declaration header on line 1:

#+begin_example
@protoui:v1
#+end_example

** Line Lexing Rules
1. *Command Tokens:* Commands begin with an =@= prefix immediately followed by the primitive identifier (e.g., =@title=, =@table=, =@button=).
2. *Whitespace:* Leading and trailing whitespace on any line is ignored during lexing.
3. *Comments:* Standalone lines starting with =#= (after trimming whitespace) are treated as developer comments and ignored by the parser.
4. *Data Piping (|):* Vertical bars (=|=) delimit parameters, columns, and key-value boundaries.
5. *Action Binding (->):* The rightward arrow operator (=->=) routes user interactions (button clicks, inputs, toggles) to dynamic RPC methods or IPC handlers.

** Scope Termination via Blank Lines
Scope management for layout blocks (=@vbox=, =@hbox=, =@table=, =@tree=) relies on empty lines (=\n\n=):

- *Single Empty Line:* Pops one layout container off the C++ render state stack (=std::stack<LayoutState>=).
- *Consecutive Empty Lines (=k=):* Pops =k= levels off the layout state stack.

** Code Block Exceptions
To prevent source code containing empty lines from breaking layout scopes, the =@code= primitive uses fence-toggle delimiters:

#+begin_example
@code
PUSH1 0x80
PUSH1 0x40

MSTORE
@code
#+end_example

-----

* Primitive Widget Reference

- =@title= :: *Syntax:* =@title <text>= \\
  *ImGui Mapping:* =ImGui::TextColored(HeaderColor, text)=

- =@alert= :: *Syntax:* =@alert <type> <text>= \\
  *ImGui Mapping:* Styled callout banner (=critical=, =warning=, =info=)

- =@kv= :: *Syntax:* =@kv <key> | <value>= \\
  *ImGui Mapping:* =ImGui::TextDisabled(key)= + =ImGui::Text(value)=

- =@gauge= :: *Syntax:* =@gauge <0.0-1.0> <label>= \\
  *ImGui Mapping:* =ImGui::ProgressBar(value, ImVec2(-1,0), label)=

- =@sparkline= :: *Syntax:* =@sparkline <v1,v2,...> <label>= \\
  *ImGui Mapping:* =ImGui::PlotLines("", values, count, 0, label)=

- =@divider= :: *Syntax:* =@divider= \\
  *ImGui Mapping:* =ImGui::Separator()=

- =@tree= :: *Syntax:* =@tree <label>= \\
  *ImGui Mapping:* =ImGui::TreeNode(label)=

- =@table= :: *Syntax:* =@table <col1> | <col2> | ...= \\
  *ImGui Mapping:* =ImGui::BeginTable(id, col_count)=

- =@vbox= :: *Syntax:* =@vbox= \\
  *ImGui Mapping:* =ImGui::BeginGroup()= (Vertical alignment)

- =@hbox= :: *Syntax:* =@hbox= \\
  *ImGui Mapping:* =ImGui::SameLine()= stream chaining

- =@input= :: *Syntax:* =@input <placeholder> [-> <action>]= \\
  *ImGui Mapping:* =ImGui::InputText(placeholder)=

- =@toggle= :: *Syntax:* =@toggle <bool> <label> [-> <action>]= \\
  *ImGui Mapping:* =ImGui::Checkbox(label, &state)=

- =@link= :: *Syntax:* =@link <label> [-> <target>]= \\
  *ImGui Mapping:* Clickable text link (=ImGui::TextColored=)

- =@button= :: *Syntax:* =@button <label> [-> <action>]= \\
  *ImGui Mapping:* =ImGui::Button(label)=

- =@badge= :: *Syntax:* =@badge <type> <label>= \\
  *ImGui Mapping:* Inline colored pill button (=ok=, =warn=, =critical=)

-----

* Complete Example Stream (.pui)

#+begin_src text
@protoui:v1
# --- ExtBit Security Policy & Audit Telemetry ---
@title Contract Security Trace
@alert critical Missing ChainID Validation

@kv Chain ID | 8453
@kv RPC Node | @link https://mainnet.base.org -> extbit:rpc.open

@gauge 0.85 Memory Usage
@sparkline 0.1, 0.4, 0.6, 0.3, 0.9, 0.2 RPC Latency (ms)

@divider

@tree Execution Stack
  @code
  PUSH1 0x80
  PUSH1 0x40
  MSTORE
  CALLVALUE
  @code

  @kv Call Value | 0.00 ETH
  @badge ok Stack Clean

@table Function | Gas | Risk
initialize | 21000 | @badge ok Low
withdraw   | 45000 | @badge critical High

@divider

@vbox
  @input Enter Wallet Address... -> extbit:wallet.set

  @hbox
    @link Read Documentation -> https://docs.extbit.com
    @toggle true Enable Sandbox -> extbit:sandbox.toggle
    @button Book Audit -> extbit:b2b.book_audit
#+end_src

-----

* Reference C++ Engine Architecture

The reference C++ parser is implemented in zero-allocation C++20 using an explicit stack machine.

** Execution Flow Logic
1. *Line Ingestion:* Read stream input using =std::string_view= to avoid heap memory copying.
2. *Comment Filter:* Skip lines matching =line.starts_with('#')=.
3. *Empty Line Evaluator:* If =line.empty()=, invoke =PopScopeStack()= to close open ImGui groups, tables, or trees.
4. *Token Matcher:* Match command prefix using an $O(1)$ flat hash map jump table (=std::unordered_map<std::string_view, RenderFunc>=).
5. *Collapsed Tree Optimization:* When =@tree= evaluates to =false= (collapsed), skip child line execution until the matching scope terminator is reached.

-----

* Security, Attestation & Licensing

** P2P Stream Verification
To prevent malicious stream injection (e.g., phishing buttons or spoofed security alerts) over decentralized networks (=cpp-libp2p=), ProtoUI streams MAY be wrapped in an *EIP-712 / Ed25519 Cryptographic Envelope*:

#+begin_example
@sig 0x7f8a...9c2b
@publisher extbit.eth
@protoui:v1
...
#+end_example

Unsigned P2P streams or streams with invalid signature envelopes are visually isolated inside a restricted sandbox shell within the ExtBit Console.

** Open-Core Licensing Model
- *ProtoUI Specification & C++ Core Parser:* Dual-licensed under *MIT / Apache 2.0* for free, universal adoption across open-source CLI tools, Rust/Go utilities, and Web3 engines.
- *ExtBit Console & Pro Widgets:* Proprietary software of *ExtBit LLC*. Advanced enterprise widgets, cryptographic attestation modules, and payment routing rails remain closed-source.