# libweb

**Repository Path**: xinligg/libweb

## Basic Information

- **Project Name**: libweb
- **Description**: 一个用 C11 编写的小型浏览器引擎库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# libweb

`libweb` is a small embeddable web rendering engine written in C11.  It is
deliberately built like a miniature browser: an HTML parser, a CSS cascade and
layout engine, a software rasterizer, and a DOM with a JavaScript runtime.  The
rendering side uses software canvas, while the scripting side uses
[quickjs](https://github.com/quickjs-ng/quickjs).

The main library is about **0.8 MB** in a release archive (including its
anti-aliased bitmap fonts and the vendored SVG rasterizer).  It has no mandatory dependency other than libc and
libm.  PNG/JPEG/GIF and HTTPS support are enabled automatically when
zlib/libjpeg/giflib/OpenSSL are found at build time, and a system CJK font is
used through FreeType when available.

## Features

HTML

- tolerant tokenizer/tree builder with implicit `html`/`head`/`body`
- implied end tags for `p`, `li`, `dt`/`dd`, table rows/cells, options, headings
- attributes, comments, doctype, raw-text elements (`script`, `style`, `title`,
  `textarea`), common named and numeric character references
- fragment parsing used by `innerHTML`, `document.write` and the C API

CSS

- selectors: type, `*`, `.class`, `#id`, descendant, child `>`, adjacent `+`,
  sibling `~`, attribute selectors, `:first-child`, `:last-child`,
  `:only-child`, `:root`, `:link`, `:hover`, `:focus`, `:nth-child`
- cascade with user-agent/author/inline origins, specificity, source order and
  `!important`; inheritance
- properties: display, position, visibility, colors, backgrounds, fonts,
  line-height, text align/decoration/indent, white-space, margins, padding,
  borders, width/height/min/max, list styles, opacity, overflow, top/right/
  bottom/left, z-index, flex/grid properties
- CSS custom properties (`--x`) and `var(--x, fallback)` with inheritance and
  copy-on-write sharing
- stylesheet rules indexed by rightmost id/class/tag, with per-node candidate
  filtering and match de-duplication
- width-based `@media` queries are evaluated against the current viewport;
  `@supports`/`@layer` bodies are applied optimistically
- shorthands: margin, padding, border, border sides, background, font,
  list-style; inline `style` attributes
- compact built-in user-agent stylesheet

Layout and paint

- block and inline formatting, line boxes, whitespace collapsing, `pre`
  handling, wrapping, text alignment and justification
- simplified left/right floats, absolute/fixed/relative positioning with
  `top/right/bottom/left`, `z-index`, `box-sizing: border-box`
- flexbox subset: row/column and reverse direction, grow/shrink/basis, gap,
  justify-content, align-items/self, `order`, single-line layout
- grid subset: `grid-template-columns` with px/percent/fr/auto/repeat, gap,
  row-major auto placement
- margins (sibling collapsing), borders, padding, auto margins, percentages,
  inline-blocks with shrink-to-fit, replaced image boxes, `overflow:hidden`
  clipping
- list markers (disc/circle/square/decimal/alpha/roman)
- software RGBA rasterizer with anti-aliased text, borders, backgrounds and
  scaled images; output to caller-provided pixels or a full-page buffer
- embedded Latin bitmap faces plus on-demand FreeType fallback for CJK and
  other scripts
- hit testing, hover/focus tracking, default link navigation

JavaScript (quickjs-ng)

- DOM: `Node`, `Element`, `Text`, `Document`, traversal, mutation, attributes,
  `classList`, `style`/`getComputedStyle`, `innerHTML`, `textContent`,
  `querySelector(All)`, `getElementById`, `getElementsBy*`, geometry
- events: `addEventListener`/`removeEventListener`/`dispatchEvent`, capture and
  bubble phases, `preventDefault`/`stopPropagation`, inline `on*` handlers,
  `DOMContentLoaded` and `load`
- timers and scheduling: `setTimeout`/`setInterval`, `clear*`,
  `requestAnimationFrame`, `queueMicrotask`
- platform: `console`, `alert`, `location`, `navigator`, `performance.now`,
  `innerWidth`/`innerHeight`, synchronous `fetch` (resolved through a Promise)
- scripts are executed in document order, including external `src` scripts

Loading

- `file:`, `data:` and plain file paths
- HTTP/1.1 and HTTPS GET (OpenSSL) with redirects, chunked bodies, keep-alive
  connection reuse and timeouts
- parallel resource prefetch pool, engine-level resource cache, static module
  import discovery, and decoded-image cache
- relative URL resolution, percent-decoding, base64 data URIs, `<base href>`
- images: PNG (zlib), JPEG (libjpeg), GIF (giflib, first frame), BMP and binary PPM
- SVG through the vendored nanosvg/nanosvgrast: inline `<svg>` and external
  `<img src="*.svg">`, basic shapes, paths, groups, transforms, viewBox,
  gradients, styles and CSS `fill`/`stroke`/`stroke-width`
- common jQuery 3.x DOM/event patterns (`createDocumentFragment`,
  `createHTMLDocument`, `document.scripts`, `currentScript`, `createEvent`)

## Building

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
```

Requirements: a C11 compiler, CMake >= 3.16.  zlib, libjpeg, giflib, OpenSSL,
FreeType, Fontconfig and SDL2 are optional.  SDL2 is only used by the
`webview-sdl` example.  quickjs-ng is
vendored in `third_party/quickjs` (MIT), and nanosvg in
`third_party/nanosvg` (zlib).  Set `LIBWEB_CJK_FONT=/path/to/font`
to override the CJK fallback font, `LIBWEB_FONT_DIR=/a:/b` to replace the
directories the installed-font database scans; `LIBWEB_TLS_INSECURE=1` disables
certificate verification (testing only).

## Command line

```sh
# render the top of a page to a PPM image
./build/webview page.html -o page.ppm

# render the whole document, and run timers for a second
./build/webview page.html --full --wait 1000 -o full.ppm --size

# print the serialized DOM, document text, or both
./build/webview page.html --dump
./build/webview page.html --text

# evaluate JavaScript before rendering
./build/webview page.html --eval "document.body.style.background='#eee'"

# interactive viewer (when SDL2 is available)
./build/webview-sdl page.html
```

## Embedding

```c
#include "libweb.h"

web_options o;
web_options_init(&o);             /* 1024x768, JavaScript enabled */
o.width = 800;
o.height = 600;

web_engine *engine = web_engine_new(&o);
web_page *page = web_page_load_url(engine, "file:///tmp/page.html");

uint8_t *pixels = malloc(800 * 600 * 4);
web_page_render_rgba(page, pixels, 800 * 4);   /* RGBA, top-left origin */

/* run timers/rAF for 16 virtual milliseconds, then render again */
web_page_run_events(page, 16);

char *err = NULL;
web_page_eval(page, "document.title = 'changed'", "app.js", &err);
if (err) { fprintf(stderr, "%s\n", err); web_free_error(err); }

web_page_free(page);              /* frees the DOM and its JS wrappers */
web_engine_free(engine);          /* frees the shared UA stylesheet */
free(pixels);
```

Scroll with `web_page_scroll()`, navigate with `web_page_navigate()`, click with
`web_page_click(x, y)`, or replace an existing document with
`web_page_set_html()`.  The C DOM API is intentionally small; complex document
access is available from JavaScript.

Fonts default to the compiled-in bitmap face (generated from DejaVu Sans by
`tools/gen_font.py`), so a page renders identically on a machine with no fonts
installed. `web_engine_set_font_config()` can name installed families for the
two classes the cascade distinguishes - default text and `monospace`.  With
Fontconfig built in (it is optional, like FreeType) the name is matched the way
the rest of the desktop matches it - aliases like `serif` / `sans-serif`,
language preferences, weight and slant - and an unknown name is substituted
rather than rejected.  Without Fontconfig the engine walks the usual font
directories (or the colon separated `LIBWEB_FONT_DIR`) and matches the family
name itself; `LIBWEB_FONT_DIR` also forces that walk in a Fontconfig build,
which keeps the tests independent of the host configuration.  An empty config
or a codepoint the resolved family has no glyph for falls back to what the
engine did before.  After changing the config, call
`web_page_invalidate_fonts()` on the pages: it drops the computed styles and
the boxes but keeps the DOM, JS state and scroll position.  The resolution only
runs when a family is actually configured, and a build without FreeType simply
ignores the config and keeps the bitmap face.  `web_font_families()` lists the
names a settings UI can offer - the same Fontconfig families (or the walked
index), sorted and deduplicated - and its `monospace_only` argument keeps the
families with fixed-width faces for a monospace picker.

## Architecture

| file | responsibility |
| --- | --- |
| `src/html.c` | HTML tokenizer and simplified tree builder |
| `src/dom.c` | DOM nodes, mutation, queries, serialization |
| `src/css.c` | CSS tokenizer, selectors, declarations, stylesheet parser |
| `src/style.c` | UA stylesheet, cascade, inherited/computed styles |
| `src/layout.c` | box tree, block/inline layout, line breaking, hit testing |
| `src/paint.c` | software RGBA rasterizer |
| `src/font.c`, `font_data.c` | bitmap font (regular/bold/italic), Fontconfig / directory font index, FreeType faces |
| `src/image.c` | PNG/JPEG/GIF/BMP/PPM decoding |
| `src/svg.c` | inline SVG serialization and nanosvg rasterization |
| `src/js.c` | quickjs-ng runtime, DOM bindings, events, timers, fetch |
| `src/net.c`, `src/url.c` | HTTP/file/data loading and URL resolution |
| `src/page.c` | public lifecycle API, viewport, events, navigation |

Layout is rebuilt lazily after mutations.  The layout tree is disposable and
paint never allocates per glyph; the font tables are static and glyphs are
nearest-neighbour scaled from a 16 px source.  Text is measured by advancing the
same glyph metrics used for painting.

## Performance

The engine is still single-threaded for DOM/style/layout, but the common
bottlenecks are removed:

- network resources are fetched by a small worker pool, deduplicated in an
  engine cache, and kept on reusable HTTP/TLS connections
- stylesheets are reparsed only when a `<style>`/`<link>` actually changes, not
  on every hover or DOM mutation
- rule matching is indexed by the rightmost selector key instead of scanning
  every rule for every node; custom-property maps are shared copy-on-write
- `getElementById` uses an id index, and repeated JS selector queries reuse
  parsed selectors
- painting culls off-viewport boxes, lines, glyphs and image regions; decoded
  images are shared through the resource cache

On a local x86-64 Linux Release build:

| scenario | before | after |
| --- | --- | --- |
| 1200 nodes with 1200 class rules, layout+render | ~0.161 s | ~0.024 s |
| 12 same-host resources with 150 ms server latency | ~1.97 s | ~0.46 s |

The second case benefits from parallel prefetch plus keep-alive reuse. These are
micro-benchmarks, not browser-vs-browser scores.

## Deliberate limitations

This is a compact engine, not a Chromium replacement.  Missing or approximate
features include full float/text-wrap interaction, flex wrapping and baseline
alignment edge cases, grid spanning/auto-flow variants, table column
algorithms/border collapse, background images/gradients, CSS
transforms/animations, web fonts, form control state, `XMLHttpRequest`,
workers, cookies and a real event loop.  SVG support covers shapes, paths,
gradients and presentation/CSS paint; SVG `<text>`, `<use>`, filters,
masks and SMIL animation are not rendered.  Incremental layout and damage-rect
repaint are not implemented yet: a DOM/style change still rebuilds layout and
paints the visible viewport, though off-screen content is culled.  Non-width
media features are approximated (for example dark mode is treated as off).
`fetch` is synchronous.  Text outside the embedded Latin faces and the FreeType
fallback renders as `?`.

The parser follows HTML's tolerant spirit rather than the full tree-construction
algorithm, so pathological markup may produce a different tree than a browser.

## License

The engine and examples are MIT licensed (see `LICENSE`).  quickjs-ng is MIT
licensed; see `third_party/quickjs/LICENSE` and the generated font notice in
`tools/gen_font.py`.