# csscascade
A modern, Rust-native **CSS Cascade & Style Resolution Engine** designed for building browser‑like rendering pipelines. `csscascade` takes an HTML (and later SVG) DOM tree and produces a **style-resolved static tree** ready for layout and painting.
This crate implements the hardest and most fundamental part of a rendering engine: the transformation from loosely-typed DOM nodes + CSS rules into a **fully computed, normalized, strongly-typed tree**.
Future support for SVG is planned (HTML + SVG share >90% of style logic).
---
## What this crate does
### ✔ 1. Parse and walk an HTML/XML tree
Accepts a DOM-like tree (any structure implementing the crate's DOM traits).
### ✔ 2. Perform full CSS cascade
- Selector matching
- Specificity and importance resolution
- Inheritance
- Initial values
- Presentation attribute mapping (SVG-ready)
- Shorthand expansion
### ✔ 3. Produce a Style‑Resolved Tree
A new tree where **every node has its final computed style** attached.
This tree contains:
- resolved display modes
- resolved text properties
- resolved sizing/box model values
- resolved transforms & opacity
- fully computed inline and block styles
### ✔ 4. Ready for layout engine consumption
`csscascade` does **not** perform layout.
It outputs a static, fully resolved element tree specifically designed to be fed into your layout engine (block/inline/flex/grid/etc.).
### ✔ 5. Ready for painting after layout
Since the style is computed and normalized, the next stages can be:
- layout engine
- display list generation
- painting/rendering
---
## Why this crate exists
Rendering HTML and SVG is deceptively hard. Even before layout and paint, a renderer must:
- parse the DOM
- run the CSS cascade
- normalize presentation attributes
- compute final styles
- build a static, render‑ready tree
None of these steps are specific to a browser — they are fundamental requirements for **any** engine that wants to render HTML or SVG, whether for graphics, documents, UI, or design tools.
The goal of `csscascade` is **not** to help you build a browser. Instead, it’s designed for developers building:
- static HTML/SVG renderers
- document processors
- canvas-based UI engines
- PDF or image generators
- design tools (like Figma‑style or illustration tools)
- “bring your own renderer” pipelines
It handles the universally hard parts (CSS cascade, style normalization, static tree production) so your engine can focus on **layout and painting**, not CSS correctness.
---
## Intended Audience
### ✔ 1. Engine and renderer authors (non‑browser)
This crate is specifically for people building a **static** renderer — not a real DOM, not a browser, not an interactive layout engine.
If you:
- want to parse HTML/SVG once
- resolve styles correctly
- produce a clean, immutable tree
- feed it to your own layout + painting pipeline
…then `csscascade` is designed for you.
### ✔ 2. Tools that need correct CSS without a browser
For example:
- SVG → PNG converters
- HTML → PDF generators
- print engines
- design tools
- WASM/canvas engines
### ✖ Not for browser makers
If you need:
- live DOM mutation
- dynamic style recalculation
- reflow/repaint cycles
- incremental layout
- event-driven DOM
…this crate intentionally does **not** target that use case.
---
## What this crate produces
`csscascade` outputs a **style‑resolved static tree** — every node has fully computed CSS applied, ready for layout.
### (planned) Optional layout integration
A future feature flag will allow the crate to output a **layout‑computed, render‑ready tree**, so you can plug it directly into your painter.
---
```
Input DOM Tree (HTML / XML / SVG)
↓
csscascade (this crate)
↓
Style‑Resolved Static Tree
↓
Layout Engine
↓
Painting
```
### Style‑Resolved Tree
Each node in the output tree includes:
- tag name
- attributes
- fully computed CSS style
- resolved defaults
- resolved inheritance
- normalized values
This tree is static and does not update unless the DOM or styles change.
---
## Goals
### Primary Goals
- Accurate CSS cascade implementation
- Browser-inspired computed style model
- Shared resolution logic for HTML and SVG
- Zero heap allocations in hot paths where possible
- Fast traversal + predictable output
### Future Goals
- SVG presentation attribute mapping
- CSS variables (`var()`) resolution
- Support for user-agent stylesheets
- Inline style parsing
- @media evaluation hooks
---
## Non‑Goals (for now)
- Layout algorithms (block, inline, flex, grid)
- Painting or rasterization
- Selector parsing (bring your own or implement separately)
- JavaScript‑style dynamic live updates
These are intentionally separate stages.
---
## Example Usage
```rust
use csscascade::{Cascade, StyledTree};
use your_dom_library::Document;
let dom: Document = parse_html("<div class=\"title\">Hello</div>");
let css = "
.title {
font-size: 24px;
font-weight: bold;
}
";
let cascade = Cascade::new(css);
let styled: StyledTree = cascade.apply(&dom);
// Pass styled to your layout engine
layout_engine.layout(&styled);
```
---
## Philosophy & Design Principles
- **Engine‑agnostic:** DOM input is not tied to any specific parser.
- **Format‑agnostic:** HTML and SVG share a unified style pipeline.
- **Separation of concerns:** Cascade is separate from layout, paint, and parsing.
- **Deterministic:** Same input always yields the same resolved tree.
- **Modern CSS:** Designed for progressive extension (variables, calc, etc.).
---
## Roadmap
- [ ] SVG presentation attributes → CSS mapping
- [ ] CSS variable resolution
- [ ] Custom property support
- [ ] UA stylesheet injection
- [ ] Integration examples (HTML, SVG, Grida Canvas)
- [ ] Full W3C cascade compliance test suite
---
## License
MIT or Apache-2.0 (TBD)
---
## Contributing
Contributions are welcome!
If you're building a rendering engine, layout system, or visualization tool, this crate aims to be the foundational CSS cascade layer you can rely on.
---
## Status
⚠️ **Early development** — API may change as SVG support and additional CSS features are added.