poxk/falco

Purpose and entry points

Falco is a Rust browser engine that renders local HTML or HTTP URLs to PNG, or runs an interactive desktop browser window. The CLI is src/main.rs; reusable rendering APIs and the primary render orchestration are in src/lib.rs. Cargo defines the Rust package and feature boundaries in Cargo.toml.

Active rendering pipeline

The active path is legacy HTML/CSS/DOM compatibility code:

1. Parse HTML into a legacy DOM.

2. Extract/merge document and optional external CSS, then cascade styles.

3. Build layout boxes and paint into a canvas.

4. Encode PNG or present the canvas in a window.

Core stages: src/html/mod.rs, src/dom/mod.rs, src/css/mod.rs, src/style/mod.rs, src/layout/mod.rs, src/paint/mod.rs, src/png/mod.rs.

JavaScript mutation bridge

Before final layout, inline scripts execute in Falco’s custom JS runtime. The renderer converts the legacy DOM to the newer spec DOM, attaches it to the JS context, runs scripts, serializes mutated spec DOM back to HTML, then reparses it through the legacy rendering path. This is the key compatibility boundary between JS mutation and legacy layout. Relevant paths: src/js_runner.rs, src/js_tjs.rs, src/tjs/mod.rs, src/html/spec/serializer.rs.

Styling and geometry

style applies UA defaults, inheritance, and cascade results to DOM nodes. layout consumes styled nodes and handles block/inline flow plus flex, grid, table, float, and absolute positioning; specialized algorithms are split by layout mode. Painting consumes layout output for text, box decoration, gradients, shadows, alpha compositing, and SVG content. Paths: src/style/mod.rs, src/layout/mod.rs, src/layout/grid.rs, src/layout/table.rs, src/paint/mod.rs, src/svg/renderer.rs.

Resource loading and outputs

Inputs can be local files, HTTP URLs, data URLs, and image resources. HTTP/1.1 loading currently uses ureq; images are decoded/scaled and incorporated into paint. PNG is emitted by an in-repo encoder. Interactive mode owns navigation, history, input/focus, scrolling, and cached incremental redraw. Paths: src/net/mod.rs, src/image/mod.rs, src/png/mod.rs, src/window/mod.rs.

Alternate/spec and runtime subsystems

Spec-compliant HTML parsing, DOM features, and CSS Selectors 4 exist but are mostly not wired into the renderer; serializer/spec DOM are exceptions used by the JS bridge. Async web APIs and security algorithms are similarly largely scaffolded or unenforced. Key paths: src/html/spec/tokenizer.rs, src/html/spec/tree_builder.rs, src/dom/spec/mod.rs, src/css/spec/mod.rs, src/web_runtime/event_loop.rs, src/security/mod.rs.

Runtime and platform boundaries

The engine is a Rust native binary/library. The JS engine is in-process, with interpreter/VM and a Linux x86_64-specific JIT path. Desktop window mode requires a display and falls back to PNG headlessly. Network access uses HTTP/1.1 through ureq; HTTP/2, WebSocket, caching, cookies, TLS/security validation, WebGL/video, and sandbox facilities exist in separate modules but are not all active in rendering. Paths: src/tjs/interpreter.rs, src/tjs/jit.rs, src/net/cookies.rs, src/net/websocket.rs, src/security/cert.rs.