Documentation
¶
Overview ¶
Package engine is the pure-Go Remove-Unused-CSS (RUCSS) engine for the WPMgr performance suite. Given a rendered HTML document and the CSS that styles it, Purge returns the subset of CSS whose selectors actually match the document (plus everything that must be retained for correctness: runtime-state pseudos, referenced @keyframes/@font-face, and live custom properties).
Accuracy model. The engine is a STATIC analyser over one HTML snapshot:
- Selector matching uses cascadia against the parsed DOM. A selector is kept iff at least one of its comma-separated parts matches an element.
- Runtime-state pseudos (:hover/:focus/…) and pseudo-elements (::before/…) cannot match a static snapshot, so a selector that reduces to a bare runtime pseudo is kept unconditionally, and one with a runtime pseudo attached to a host element is kept iff the (pseudo-stripped) host matches.
- @media/@supports/@container recurse and are emitted only if ≥1 inner rule survives; @keyframes survive iff a surviving rule animates their name; @font-face survive iff a surviving rule references their font-family; @charset/@import/@namespace are always kept.
- Custom properties (--x) are kept iff transitively referenced via var() by a surviving declaration.
Graceful degradation. The engine NEVER panics. Malformed HTML is parsed leniently by x/net/html (which always yields a tree); a fatal CSS parse error, an empty selector budget, or a recovered panic all fall back to returning the FULL input CSS unchanged with Stats.FellBack=true and a Stats.Note explaining why. A keep-all result is always safe (it can only fail to shrink, never break the page).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Stats ¶
type Stats struct {
// OriginalBytes / UsedBytes are the byte lengths of the input and output CSS.
OriginalBytes int
UsedBytes int
// ReductionPct is 100*(1 - UsedBytes/OriginalBytes), 0 when OriginalBytes==0.
ReductionPct float64
// SelectorsTotal counts every comma-separated selector part seen across all
// rulesets; SelectorsKept/Dropped partition them by the keep decision.
SelectorsTotal int
SelectorsKept int
SelectorsDropped int
// RulesTotal / RulesKept count whole rulesets (a ruleset is dropped when none
// of its selector parts survive).
RulesTotal int
RulesKept int
// FellBack is true when the engine returned the input CSS unchanged because
// it could not safely purge (see Note).
FellBack bool
// Note is a short human-readable explanation, set on fallback or for
// noteworthy conditions (empty on a clean purge).
Note string
}
Stats summarises a purge pass for telemetry and the rucss_results row.
func Purge ¶
Purge removes unused CSS rules from cssBytes relative to the document in htmlBytes. safelist is a list of selector patterns (substring or /regex/ form, see compileSafelist) that force-retain any selector they match. The returned usedCSS is the minimised stylesheet; stats describes the pass; err is non-nil only for programmer errors (today: never — all failures degrade to keep-all with FellBack=true).
Source Files