eBrowser — Embedded Web Browser v1.0.0

eBrowser is a lightweight, embeddable web browser engine for EmbeddedOS. Built from scratch in C/C++ with minimal dependencies, it provides HTML5 parsing, CSS styling, box-model layout, software rendering, and HTTP/HTTPS networking — all in a footprint suitable for resource-constrained embedded devices, kiosks, and IoT dashboards.

Headers: #include <ebrowser/*.h> | License: MIT | Backends: SDL2, EoS native, WASM

Architecture Overview

Core Engine: Browser lifecycle, configuration, and embedding API.
HTML Parser: Tokenizer → DOM tree construction with error recovery.
CSS Engine: Stylesheet parsing, cascade, specificity, computed styles.
Layout Engine: Box model, block/inline flow, flexbox, text wrapping.
Rendering: Software rasterizer with SDL2 and EoS display backends.
Network: HTTP/1.1, HTTPS (TLS 1.2/1.3), cookies, connection pooling.
Input: Keyboard, mouse, and touch input abstraction with focus management.
Platform: Portable abstraction layer for SDL2, EoS native, and WebAssembly.

Quick Start
#include <ebrowser/ebrowser.h>

int main(void) {
    eb_config_t cfg = {
        .width = 1024, .height = 768,
        .title = "eBrowser",
        .flags = EB_FLAG_RESIZABLE
    };
    eb_handle_t browser = eb_create(&cfg);
    eb_navigate(browser, "https://example.com");
    eb_run(browser);
    eb_destroy(browser);
    return 0;
}

⚙ Core Engine

Browser lifecycle, configuration, and embedding API. Header: <ebrowser/ebrowser.h>

Configuration

eb_config_t

widthuint32_tInitial window width in pixels (default: 1024)
heightuint32_tInitial window height in pixels (default: 768)
titleconst char *Window title string
flagsuint32_tBitwise OR of EB_FLAG_* constants
user_agentconst char *Custom User-Agent string (NULL = default)
cache_size_mbuint32_tMax cache size in MB (default: 64)
home_urlconst char *Homepage URL (NULL = about:blank)
proxyconst char *HTTP proxy URL (NULL = direct)
Configuration Flags
EB_FLAG_RESIZABLE=0x01 • EB_FLAG_FULLSCREEN=0x02 • EB_FLAG_BORDERLESS=0x04 • EB_FLAG_NO_JS=0x08 • EB_FLAG_KIOSK=0x10 • EB_FLAG_HEADLESS=0x20 • EB_FLAG_HARDWARE_ACCEL=0x40

Lifecycle

eb_handle_t eb_create(const eb_config_t *config)

Create a new browser instance. Initializes the platform backend, rendering surface, and network stack.

Returns

eb_handle_t browser handle, or EB_INVALID_HANDLE on failure.

int eb_navigate(eb_handle_t browser, const char *url)

Navigate to a URL. Initiates DNS resolution, HTTP request, HTML parsing, layout, and rendering pipeline. Non-blocking — the page loads asynchronously.

Returns

0 on success, negative error code on failure.

int eb_run(eb_handle_t browser)

Enter the main event loop. Processes input events, network I/O, layout updates, and rendering. Blocks until the browser window is closed or eb_stop() is called.

int eb_step(eb_handle_t browser)

Process a single frame of the event loop. Use instead of eb_run() when embedding the browser in a custom event loop.

void eb_stop(eb_handle_t browser)

Signal the browser to exit the event loop. eb_run() or eb_step() will return on the next iteration.

void eb_destroy(eb_handle_t browser)

Destroy a browser instance and free all resources (DOM, stylesheets, network connections, cache, rendering surfaces).

Navigation Control

int eb_go_back(eb_handle_t browser) / eb_go_forward(eb_handle_t browser) / eb_reload(eb_handle_t browser)

Navigate to the previous/next page in history, or reload the current page.

const char * eb_get_url(eb_handle_t browser) / eb_get_title(eb_handle_t browser)

Get the current page URL or title.

eb_load_state_t eb_get_load_state(eb_handle_t browser)

Get current load state. Returns EB_LOAD_IDLE, EB_LOAD_CONNECTING, EB_LOAD_LOADING, EB_LOAD_RENDERING, or EB_LOAD_COMPLETE.

📄 HTML Parser

Tokenizer and DOM tree construction with error recovery. Header: <ebrowser/dom.h>

DOM Node Types

eb_dom_node_t

typeeb_node_type_tELEMENT, TEXT, COMMENT, DOCUMENT, DOCTYPE
tagconst char *Tag name (ELEMENT nodes only)
textconst char *Text content (TEXT and COMMENT nodes)
idconst char *Element id attribute (or NULL)
class_nameconst char *Element class attribute (or NULL)
parenteb_dom_node_t *Parent node
first_childeb_dom_node_t *First child node
next_siblingeb_dom_node_t *Next sibling node

DOM Query API

eb_dom_node_t * eb_dom_get_document(eb_handle_t browser)

Get the root document node of the current page’s DOM tree.

eb_dom_node_t * eb_dom_get_element_by_id(eb_handle_t browser, const char *id)

Find the first element with the given id attribute. Returns the matching node or NULL.

eb_dom_node_t ** eb_dom_query_selector_all(eb_handle_t browser, const char *selector, uint32_t *count)

Find all elements matching a CSS selector. Supports tag, class, id, attribute, and descendant selectors. Caller frees the array with eb_free().

eb_dom_node_t * eb_dom_query_selector(eb_handle_t browser, const char *selector)

Find the first element matching a CSS selector.

DOM Attribute & Event API

const char * eb_dom_get_attr(eb_dom_node_t *node, const char *name) / eb_dom_get_text_content(eb_dom_node_t *node) / eb_dom_get_inner_html(eb_dom_node_t *node)

Read attribute values, text content, or serialized inner HTML. Strings returned by text/HTML helpers must be released with eb_free().

int eb_dom_add_event_listener(eb_dom_node_t *node, const char *event, eb_dom_event_cb_t cb, void *ctx)

Attach an event listener. Event names: "click", "input", "submit", "load", "scroll". Callback signature: void (*)(eb_dom_node_t *target, const eb_dom_event_t *evt, void *ctx).

🎨 CSS Engine

Stylesheet parsing, cascade, specificity, and computed styles. Header: <ebrowser/css.h>

eb_stylesheet_t * eb_css_parse(const char *css_text, size_t len)

Parse a CSS string into an internal stylesheet. Supports selectors, properties, media queries, and @-rules. Returns NULL on parse failure.

int eb_css_apply(eb_handle_t browser, eb_stylesheet_t *stylesheet)

Apply a stylesheet to the current document. Triggers cascade recalculation and relayout.

eb_computed_style_t eb_css_computed_style(eb_dom_node_t *node)

Get the fully resolved computed style for a DOM element after cascade, specificity, and inheritance.

void eb_css_free(eb_stylesheet_t *stylesheet)

Free a parsed stylesheet and all associated memory.

Supported CSS Properties

Box Model: margin, padding, border, width, height, max/min-width/height, box-sizing
Typography: font-size, font-weight, font-family, line-height, text-align, text-decoration, color
Layout: display (block, inline, flex, none), position, top/right/bottom/left, float, clear
Flexbox: flex-direction, justify-content, align-items, flex-wrap, flex-grow, flex-shrink, gap
Visual: background-color, background-image, border-radius, opacity, overflow, visibility
Other: cursor, z-index, list-style, @media queries

📐 Layout Engine

Box model computation, block/inline flow, flexbox, and text wrapping. Header: <ebrowser/layout.h>

int eb_layout_compute(eb_handle_t browser)

Compute the layout for the entire document — applies box model, resolves widths/heights, positions elements, wraps text, and produces a layout tree with absolute coordinates.

eb_rect_t eb_layout_get_rect(eb_dom_node_t *node) / eb_layout_get_box_metrics(eb_dom_node_t *node)

Get the bounding rectangle and full box-model metrics (content, padding, border, margin) for an element after layout.

eb_dom_node_t * eb_layout_hit_test(eb_handle_t browser, int32_t x, int32_t y)

Find the topmost DOM element at the given document coordinates (used for click/hover handling).

eb_size_t eb_layout_get_document_size(eb_handle_t browser) / eb_layout_scroll_to(eb_handle_t browser, int32_t x, int32_t y) / eb_layout_get_scroll_pos(eb_handle_t browser)

Document size, scroll position get/set helpers for the viewport.

🎨 Rendering

Software rasterizer with SDL2 and EoS display backends. Header: <ebrowser/render.h>

int eb_render_frame(eb_handle_t browser)

Render the current page to the display surface. Rasterizes backgrounds, borders, text, images, and scrollbars.

int eb_render_text(eb_handle_t browser, const char *text, int32_t x, int32_t y, uint32_t color, uint16_t size) / eb_render_image(eb_handle_t browser, const eb_image_t *img, const eb_rect_t *dest) / eb_render_rect(eb_handle_t browser, const eb_rect_t *rect, uint32_t color, bool filled)

Render text, images, and rectangles for HUD overlays.

int eb_render_to_bitmap(eb_handle_t browser, uint8_t *pixels, uint32_t w, uint32_t h, uint32_t stride)

Render the page to an off-screen RGBA bitmap buffer (headless screenshot).

Rendering Pipeline

Backgrounds → borders → block content → inline/text → positioned elements → scrollbars. Built-in bitmap font with UTF-8 and glyph caching. PNG/JPEG via stb_image. Backends: SDL2 (desktop), EoS framebuffer (embedded), WASM Canvas (web).

🌐 Network Stack

HTTP/HTTPS client, DNS, cookies, connection pooling. Header: <ebrowser/net.h>

eb_net_request_t * eb_net_request(const eb_net_config_t *config)

Create and send an HTTP/HTTPS request. Supports GET, POST, PUT, DELETE. Asynchronous with completion callback.

int eb_net_set_proxy(eb_handle_t browser, const char *proxy_url) / eb_net_set_cookie(...) / eb_net_get_cookie(...) / eb_net_clear_cookies(...) / eb_net_clear_cache(...)

Configure proxy, manage cookies, and clear the HTTP response cache.

⌨ Input Layer

Keyboard, mouse, and touch input abstraction. Header: <ebrowser/input.h>

int eb_input_inject_key(eb_handle_t browser, eb_keycode_t key, eb_key_action_t action, uint32_t modifiers) / eb_input_inject_mouse(...) / eb_input_inject_touch(...)

Inject keyboard, mouse, or touch events. Used for programmatic input, on-screen keyboards, and automated testing.

int eb_input_set_focus(eb_handle_t browser, eb_dom_node_t *node) / eb_input_get_focus(eb_handle_t browser)

Set/get keyboard focus on a DOM element (input, textarea).

💻 Platform Abstraction

SDL2, EoS native, and WASM backends. Header: <ebrowser/platform.h>

int eb_platform_init(eb_platform_t platform) / eb_platform_deinit(void) / eb_platform_get_display_info(eb_display_info_t *info) / eb_platform_get_time_ms(void) / eb_platform_set_clipboard(...) / eb_platform_get_clipboard(...)

Initialize, query, and manage the platform backend. Choose EB_PLATFORM_SDL2, EB_PLATFORM_EOS, EB_PLATFORM_WASM, or EB_PLATFORM_AUTO.

🔒 Security

Content security policies, TLS, and sandboxing. Header: <ebrowser/security.h>

int eb_security_set_policy(eb_handle_t browser, eb_security_policy_t policy) / eb_security_add_allowed_origin(...) / eb_security_set_url_filter(...)

Set the content security policy (EB_POLICY_PERMISSIVE, EB_POLICY_STANDARD, EB_POLICY_STRICT), add allowed origins, and install URL filters.

int eb_tls_set_ca_bundle(eb_handle_t browser, const char *path) / eb_tls_set_verify(eb_handle_t browser, bool verify)

Configure TLS: provide a custom CA bundle or toggle certificate verification.

Security Features

Same-Origin PolicyCross-origin resource access restricted by default
TLS 1.2/1.3Encrypted connections with certificate verification
URL FilteringWhitelist/blacklist for kiosk and parental controls
CSP HeadersContent-Security-Policy HTTP header enforcement
Cookie SecurityHttpOnly, Secure, SameSite attribute support
Mixed ContentHTTP resources blocked on HTTPS pages

💻 CLI Reference

Command-line options for the eBrowser standalone executable.

Usage
ebrowser [OPTIONS] [URL]

ebrowser https://example.com
ebrowser --resolution 800x480 --fullscreen https://dashboard.local
ebrowser --no-js --kiosk https://signage.example.com
ebrowser --headless --screenshot out.png https://example.com

Command-Line Options

--resolution WxHWindow resolution (e.g., 1024x768)
--fullscreenLaunch in fullscreen mode
--no-jsDisable JavaScript execution
--kioskKiosk mode: fullscreen, no UI chrome
--headlessRun without display (server-side rendering)
--cache-size NHTTP cache size in MB (default: 64)
--log-level LEVELerror, warn, info, debug, trace
--proxy URLHTTP proxy URL
--user-agent STRCustom User-Agent string
--screenshot FILESave screenshot to FILE (headless)
--ca-bundle FILECustom CA certificate bundle (PEM)
--no-tls-verifyDisable TLS verification (dev only)
--allowed-originsComma-separated allowed origins
--home URLHomepage URL
--versionPrint version and exit
Embedded Kiosk Example
eb_config_t cfg = {
    .width = 800, .height = 480,
    .title = "Dashboard",
    .flags = EB_FLAG_FULLSCREEN | EB_FLAG_KIOSK | EB_FLAG_NO_JS
};
eb_handle_t b = eb_create(&cfg);
eb_security_set_policy(b, EB_POLICY_STRICT);
eb_security_add_allowed_origin(b, "https://dashboard.local");
eb_navigate(b, "https://dashboard.local");
eb_run(b);
eb_destroy(b);