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 (e.g., cpp-libp2p).

Unlike heavy serialization formats (JSON, XML, HTML/CSS), ProtoUI requires zero string escaping and zero quotes for layout definitions, 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 heavy AST allocation overhead.
  • Human-Centric Authoring: Designed to be written intuitively using standard Unix shell echo. Employs implicit text paragraphs with bracket-scoped formatting.
  • Zero-Allocation Parsing: Parsed in native C++ using std::string_view and a flat std::variant token stream for zero-heap-thrashing render loops.
  • Contextual Scoping: Layout containers use standard empty line separators for scope popping, eliminating tag-matching friction.

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

  1. Command Tokens: UI layout commands begin with an @ prefix immediately followed by the primitive identifier (e.g., @table, @button). Level modifiers may be attached via colon (e.g., @title denotes level 0; @title:1 denotes level 1).
  2. Implicit Prose: Any line not beginning with @ or # is automatically parsed as a rich-text paragraph. Text naturally wraps, and standalone backslashes (\) force hard line breaks.
  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 in table and kv structures.
  5. Action Binding (->): The rightward arrow operator (->) routes user interactions to dynamic RPC methods or IPC handlers using strict function-call syntax (e.g., -> namespace:method(arg"value")=).

2.3Title Hierarchy Levels

The @title directive enforces a zero-indexed hierarchy:
@title
Root section title (level = 0).
@title:1
Primary sub-section (level = 1), nested under @title (level 0).
@title:2
Secondary sub-section (level = 2), nested under @title:1.

Subsequent implicit prose at any title level becomes child text nodes of that title container.

2.4Scope 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>) and creates a paragraph margin for text.
  • Consecutive Empty Lines (k): Pops k levels off the layout state stack.

3Inline Rich Text & Extensions

ProtoUI handles prose, styling, dynamic state, and interactions via a unified, single-pass inline tokenizer leveraging bracketed decorators.

  • Text Styling: [`modifier`: `text`]
    Modifiers can be structural (b, i, u) or semantic colors (ok, warn, critical). They can be chained with dot notation.Example: [b.warn: High memory usage]
  • State Bindings: :`scope`.`key`
    Injects reactive variables directly into text or widgets.Example: Program counter at :evm.pc
  • Hover Tooltips: [`token`][`modifier`: `Tooltip`]
    Attaches a tooltip to the preceding word, icon, or styled span.Example: [warn: Paused][.b.critical: Halted at breakpoint]
  • Interactive Links: [link.`modifier`: `Label` [`Tooltip`] -> `action()`]
    Embeds clickable dispatches mid-sentence.Example: Click [link: Connect [.i: Dial node] -> net:connect(target"/ip4/127.0.0.1")] to join.=
  • Inline Code: ` `text or :state` `
    Monospaced code spans. Can contain nested spans, state bindings, or tooltips.

4Primitive Widget Reference

@title
Syntax: @title[:level] [:symbol] <text>
ImGui Mapping: ImGui::TextColored scaled by hierarchy level. Unadorned @title defaults to level=0 (workspace root title). Colon suffixes (:@title:1, :@title:2) designate sub-titles belonging to level 0.
@alert
Syntax: @alert <type> <text>
ImGui Mapping: Styled callout banner (critical, warning, info)
@kv
Syntax: @kv [:symbol] <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
@code
Syntax: @code :state.key [Tooltip] OR multi-line fenced block
ImGui Mapping: Monospaced background container. Supports live state references and syntax-colored child spans.
@input
Syntax: @input [:symbol] <placeholder> [-> <action>]
ImGui Mapping: ImGui::InputText(placeholder), binds $value in action arguments.
@toggle
Syntax: @toggle <bool> <label> [-> <action>]
ImGui Mapping: ImGui::Checkbox(label, &state)
@button
Syntax: @button [:symbol] <label> [-> <action>]
ImGui Mapping: ImGui::Button(label)
@badge
Syntax: @badge [:symbol] <type> <label>
ImGui Mapping: Inline colored pill button (ok, warn, critical)

5Complete Example Stream (.pui)

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

This implicit prose paragraph alerts the operator that the current network state is [ok: :net.status], but strict contract validation failed. 
\
Click [link.b.warn: Read Documentation -> extbit:docs.open(topic="chainid")] or execute a manual override via the console.

@divider

@title:1 Telemetry Overview & Details
@kv Chain ID | 8453
@kv RPC Node | [link: https://mainnet.base.org -> extbit:rpc.open(url="https://mainnet.base.org";)]

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

@divider

@title:1 Execution Stack Trace
@tree Execution Stack
  # Dynamic state code block with container tooltip
  @code `:evm.pc [cyan: PUSH1] :evm.stack_top` [.b: Active Opcode Frame]

  @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(address=$value)

  @hbox
    @toggle true Enable Sandbox -> extbit:sandbox.toggle()
    @button Book Audit -> extbit:b2b.book_audit()

6Reference C++ Engine Architecture

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

6.1Type-Safe Variant Tokenization

ProtoUI prevents cyclic dependencies and heavy heap allocations by defining a flat Element stream:
using Element = std::variant<std::string, Span, StateRef, HoverText, Inline, Code, Extension>;

6.2Execution Flow Logic

  1. Line Ingestion: Read stream input using std::string_view to avoid heap memory copying.
  2. Empty Line Evaluator: If line.empty(), invoke PopScopeStack() to close open ImGui groups, tables, or trees.
  3. Token Matcher: Match command prefix (std::unordered_map<std::string_view, RenderFunc, StringHash, std::equal_to<>>). Evaluates level suffix for title nodes (level = 0 for bare @title, level = n for @title:n).
  4. Inline Delegation: Lines missing an @ command prefix are routed to TokenizeInlineStream(), converting raw strings to std::vector<Element> for instant ImGui rendering.
  5. Collapsed Tree Optimization: When @tree evaluates to false (collapsed), skip child line execution until the matching scope terminator is reached.

7Security, Attestation & Licensing

7.1P2P Stream Verification

To prevent malicious stream injection (e.g., phishing buttons or spoofed security alerts) over decentralized networks, ProtoUI streams MAY be wrapped in an EIP-712 / Ed25519 Cryptographic Envelope:
@sig 0x7f8a...9c2b
@publisher extbit.com
@protoui:v1
...

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

7.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, HarfBuzz text-shaping pipelines, cryptographic attestation modules, and payment routing rails remain closed-source.