ExtBit ProtoUI Specification & Grammar (.pui)

1Overview & 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.

💻 C++ Reference Engine & Implementation: https://github.com/extbit/ProtoUI

2Formal Grammar & Lexical Rules

2.1Specification Version

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

@protoui:v1

2.2Line Lexing Rules

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

2.3Scope 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.

2.4Code Block Exceptions

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

@code
PUSH1 0x80
PUSH1 0x40

MSTORE
@code

3Primitive 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)

4Complete Example Stream (.pui)

@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

5Reference C++ Engine Architecture

The official C++ reference parser and ImGui rendering engine is available at https://github.com/extbit/ProtoUI. It is implemented in zero-allocation C++20 using an explicit stack machine.

5.1Execution Flow Logic

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

6Security, Attestation & Licensing

6.1P2P 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:

@sig 0x7f8a...9c2b
@publisher extbit.eth
@protoui:v1
...

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

6.2Open-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.

August 27, 2026