# poxk/falco architecture

> Architecture diagram of the GitHub repository poxk/falco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poxk/falco
- Repository: https://github.com/poxk/falco

## Overview

#### 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`.

Main entry points: [`src/net/mod.rs`](https://github.com/poxk/falco/blob/main/src/net/mod.rs) (Resource loader), [`src/dom/spec/mod.rs`](https://github.com/poxk/falco/blob/main/src/dom/spec/mod.rs) (Spec DOM), [`src/dom/mod.rs`](https://github.com/poxk/falco/blob/main/src/dom/mod.rs) (Legacy DOM), [`src/paint/mod.rs`](https://github.com/poxk/falco/blob/main/src/paint/mod.rs) (Painter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host & output"]
  node_cargo["Cargo package<br/>Rust package<br/>[Cargo.toml]"]
  node_cli["CLI entry point<br/>native binary<br/>[main.rs]"]
  node_renderer["Render orchestration<br/>library API<br/>[lib.rs]"]
  node_png["PNG encoder<br/>image output<br/>[mod.rs]"]
  node_window["Interactive window<br/>desktop UI<br/>[mod.rs]"]
end

subgraph group_pipeline["Active render pipeline"]
  node_html["Legacy HTML parser<br/>[mod.rs]"]
  node_dom["Legacy DOM<br/>render DOM<br/>[mod.rs]"]
  node_css["CSS extraction &amp; parse<br/>CSS pipeline<br/>[mod.rs]"]
  node_style["Style cascade<br/>styling<br/>[mod.rs]"]
  node_layout["Layout engine<br/>geometry<br/>[mod.rs]"]
  node_paint["Painter<br/>raster paint<br/>[mod.rs]"]
end

subgraph group_js["JavaScript bridge"]
  node_js_runner["Script mutation bridge<br/>render bridge<br/>[js_runner.rs]"]
  node_tjs["Custom JS runtime<br/>in-process JS engine<br/>[mod.rs]"]
  node_serializer["Spec DOM serializer<br/>HTML serializer<br/>[serializer.rs]"]
end

subgraph group_resources["Resources"]
  node_net["Resource loader<br/>HTTP/1.1 loader<br/>[mod.rs]"]
  node_image["Image decode &amp; scale<br/>image resource<br/>[mod.rs]"]
end

subgraph group_spec["Alternate/spec subsystems"]
  node_spec_dom["Spec DOM<br/>alternate DOM<br/>[mod.rs]"]
  node_spec_html["Spec HTML parser<br/>alternate parser<br/>[tokenizer.rs]"]
  node_spec_css["Spec CSS/selectors<br/>alternate CSS<br/>[mod.rs]"]
  node_web_runtime["Web runtime<br/>async web APIs<br/>[event_loop.rs]"]
  node_security["Security subsystem<br/>security algorithms<br/>[mod.rs]"]
end

node_cargo -->|"builds"| node_cli
node_cli -->|"invokes"| node_renderer
node_renderer -->|"loads input/resources"| node_net
node_net -->|"HTML source"| node_html
node_html -->|"parses to"| node_dom
node_dom -->|"before final layout"| node_js_runner
node_js_runner -->|"converts to"| node_spec_dom
node_js_runner -->|"executes inline scripts"| node_tjs
node_tjs -->|"mutates"| node_spec_dom
node_spec_dom -->|"serializes"| node_serializer
node_serializer -->|"reparse mutated HTML"| node_html
node_dom -->|"extracts styles"| node_css
node_net -->|"external CSS"| node_css
node_css -->|"cascade input"| node_style
node_dom -->|"nodes"| node_style
node_style -->|"styled nodes"| node_layout
node_layout -->|"layout boxes"| node_paint
node_net -->|"image resources"| node_image
node_image -->|"decoded images"| node_paint
node_paint -->|"canvas"| node_png
node_paint -->|"canvas"| node_window
node_spec_html -.->|"builds"| node_spec_dom
node_spec_css -.->|"selector support"| node_spec_dom
node_web_runtime -.->|"runtime APIs"| node_tjs
node_security -.->|"security support"| node_net

click node_cargo "https://github.com/poxk/falco/blob/main/Cargo.toml"
click node_cli "https://github.com/poxk/falco/blob/main/src/main.rs"
click node_renderer "https://github.com/poxk/falco/blob/main/src/lib.rs"
click node_html "https://github.com/poxk/falco/blob/main/src/html/mod.rs"
click node_dom "https://github.com/poxk/falco/blob/main/src/dom/mod.rs"
click node_css "https://github.com/poxk/falco/blob/main/src/css/mod.rs"
click node_style "https://github.com/poxk/falco/blob/main/src/style/mod.rs"
click node_layout "https://github.com/poxk/falco/blob/main/src/layout/mod.rs"
click node_paint "https://github.com/poxk/falco/blob/main/src/paint/mod.rs"
click node_png "https://github.com/poxk/falco/blob/main/src/png/mod.rs"
click node_window "https://github.com/poxk/falco/blob/main/src/window/mod.rs"
click node_js_runner "https://github.com/poxk/falco/blob/main/src/js_runner.rs"
click node_tjs "https://github.com/poxk/falco/blob/main/src/tjs/mod.rs"
click node_serializer "https://github.com/poxk/falco/blob/main/src/html/spec/serializer.rs"
click node_net "https://github.com/poxk/falco/blob/main/src/net/mod.rs"
click node_image "https://github.com/poxk/falco/blob/main/src/image/mod.rs"
click node_spec_dom "https://github.com/poxk/falco/blob/main/src/dom/spec/mod.rs"
click node_spec_html "https://github.com/poxk/falco/blob/main/src/html/spec/tokenizer.rs"
click node_spec_css "https://github.com/poxk/falco/blob/main/src/css/spec/mod.rs"
click node_web_runtime "https://github.com/poxk/falco/blob/main/src/web_runtime/event_loop.rs"
click node_security "https://github.com/poxk/falco/blob/main/src/security/mod.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cargo,node_cli,node_renderer,node_png,node_window toneBlue
class node_html,node_dom,node_css,node_style,node_layout,node_paint toneAmber
class node_js_runner,node_tjs,node_serializer toneMint
class node_net,node_image toneRose
class node_spec_dom,node_spec_html,node_spec_css,node_web_runtime,node_security toneIndigo
```

## Components

### Host & output

- [Cargo package](https://github.com/poxk/falco/blob/main/Cargo.toml): Rust package · Defines package and feature boundaries. · `Cargo.toml`
- [CLI entry point](https://github.com/poxk/falco/blob/main/src/main.rs): native binary · Renders URLs to PNG or starts desktop mode. · `src/main.rs`
- [Render orchestration](https://github.com/poxk/falco/blob/main/src/lib.rs): library API · Coordinates loading, scripting, layout, and output. · `src/lib.rs`
- [PNG encoder](https://github.com/poxk/falco/blob/main/src/png/mod.rs): image output · In-repository PNG emission. · `src/png/mod.rs`
- [Interactive window](https://github.com/poxk/falco/blob/main/src/window/mod.rs): desktop UI · Owns navigation, input, scrolling, history, and redraw cache. · `src/window/mod.rs`

### Active render pipeline

- [Legacy HTML parser](https://github.com/poxk/falco/blob/main/src/html/mod.rs): HTML parser · `src/html/mod.rs`
- [Legacy DOM](https://github.com/poxk/falco/blob/main/src/dom/mod.rs): render DOM · `src/dom/mod.rs`
- [CSS extraction & parse](https://github.com/poxk/falco/blob/main/src/css/mod.rs): CSS pipeline · Merges document and external stylesheets. · `src/css/mod.rs`
- [Style cascade](https://github.com/poxk/falco/blob/main/src/style/mod.rs): styling · Applies UA defaults, inheritance, and cascade. · `src/style/mod.rs`
- [Layout engine](https://github.com/poxk/falco/blob/main/src/layout/mod.rs): geometry · Handles flow, flex, grid, tables, floats, and positioning. · `src/layout/mod.rs`
- [Painter](https://github.com/poxk/falco/blob/main/src/paint/mod.rs): raster paint · Draws text, decorations, compositing, and SVG. · `src/paint/mod.rs`

### JavaScript bridge

- [Script mutation bridge](https://github.com/poxk/falco/blob/main/src/js_runner.rs): render bridge · Converts between legacy rendering and script-visible spec DOM. · `src/js_runner.rs`
- [Custom JS runtime](https://github.com/poxk/falco/blob/main/src/tjs/mod.rs): in-process JS engine · Interpreter with Linux x86_64 JIT path. · `src/tjs/mod.rs`
- [Spec DOM serializer](https://github.com/poxk/falco/blob/main/src/html/spec/serializer.rs): HTML serializer · Returns mutated script DOM as HTML for legacy reparse. · `src/html/spec/serializer.rs`

### Resources

- [Resource loader](https://github.com/poxk/falco/blob/main/src/net/mod.rs): HTTP/1.1 loader · Loads local, HTTP, data URL, and external resources via ureq. · `src/net/mod.rs`
- [Image decode & scale](https://github.com/poxk/falco/blob/main/src/image/mod.rs): image resource · `src/image/mod.rs`

### Alternate/spec subsystems

Mostly scaffolded outside the active renderer.

- [Spec DOM](https://github.com/poxk/falco/blob/main/src/dom/spec/mod.rs): alternate DOM · Used by the JavaScript bridge; otherwise not the active render DOM. · `src/dom/spec/mod.rs`
- [Spec HTML parser](https://github.com/poxk/falco/blob/main/src/html/spec/tokenizer.rs): alternate parser · Tokenizer and tree builder are mostly unwired to rendering. · `src/html/spec/tokenizer.rs`
- [Spec CSS/selectors](https://github.com/poxk/falco/blob/main/src/css/spec/mod.rs): alternate CSS · Selectors 4 subsystem is mostly outside active rendering. · `src/css/spec/mod.rs`
- [Web runtime](https://github.com/poxk/falco/blob/main/src/web_runtime/event_loop.rs): async web APIs · Event-loop APIs are largely scaffolded. · `src/web_runtime/event_loop.rs`
- [Security subsystem](https://github.com/poxk/falco/blob/main/src/security/mod.rs): security algorithms · Validation and sandbox facilities are not fully enforced. · `src/security/mod.rs`

## Connections

- Cargo package → CLI entry point: builds
- CLI entry point → Render orchestration: invokes
- Render orchestration → Resource loader: loads input/resources
- Resource loader → Legacy HTML parser: HTML source
- Legacy HTML parser → Legacy DOM: parses to
- Legacy DOM → Script mutation bridge: before final layout
- Script mutation bridge → Spec DOM: converts to
- Script mutation bridge → Custom JS runtime: executes inline scripts
- Custom JS runtime → Spec DOM: mutates
- Spec DOM → Spec DOM serializer: serializes
- Spec DOM serializer → Legacy HTML parser: reparse mutated HTML
- Legacy DOM → CSS extraction & parse: extracts styles
- Resource loader → CSS extraction & parse: external CSS
- CSS extraction & parse → Style cascade: cascade input
- Legacy DOM → Style cascade: nodes
- Style cascade → Layout engine: styled nodes
- Layout engine → Painter: layout boxes
- Resource loader → Image decode & scale: image resources
- Image decode & scale → Painter: decoded images
- Painter → PNG encoder: canvas
- Painter → Interactive window: canvas
- Spec HTML parser → Spec DOM: builds
- Spec CSS/selectors → Spec DOM: selector support
- Web runtime → Custom JS runtime: runtime APIs
- Security subsystem → Resource loader: security support