feat(htmlcss): Chromium-parity L0 suite — 65 fixtures + 13 renderer fixes

.agents/skills/cg-reftest/SKILL.md

@@ -325,34 +325,32 @@ against the current suite config, move its entry from `coverage` →
 `exact`. Do **not** lower the exact suite's floor to fit new entries;
 the bar exists so regressions are loud.
 
-Per-fixture `.reftest.json` sidecars **do not exist** anymore. All
-config lives in the suite file.
+All per-fixture config lives in the suite file. There are no
+per-fixture `.reftest.json` sidecars.
 
 #### Suite JSON shape
 
 ```json
 {
   "name": "L0.exact",
   "description": "Byte-exact fixtures; any drop = regression.",
-  "gate": { "threshold": 0, "aa": false, "floor": 1.0 },
+  "gate": { "threshold": 0, "aa": true, "floor": 1.0 },
   "defaults": {
     "wait_for": ["fonts", "networkidle"],
-    "extra_css": ["../_reftest/hide-text.css"],
+    "extra_css": [
+      "../_reftest/hide-text.css",
+      "../_reftest/transparent-body.css"
+    ],
     "full_page": true
   },
-  "fixtures": [
-    {
-      "path": "../L0/box-dimensions.html",
-      "viewport": { "width": 600, "height": 522 }
-    }
-  ]
+  "fixtures": [{ "path": "../L0/box-dimensions.html" }]
 }
 ```
 
 - `defaults` — applied to every fixture. Each fixture entry can override any field.
 - `fixtures[].path` and every `extra_css[]` path resolve **relative to the suite file**.
-- `viewport.height` must match cg's cull height for the diff to succeed; render cg once and read `WxH` to calibrate.
 - `gate.threshold` / `gate.aa` are inputs to the pixelmatch diff; `gate.floor` is the aggregate pass bar on similarity.
+- **`aa: true` (default)** → pixelmatch `includeAA: false`. Pixelmatch's AA detector fires and excludes anti-aliased edge pixels from the diff count, separating rasterizer edge noise (Skia vs. Blink) from real divergence. Set `aa: false` for strict byte-exact accounting (e.g. probing an AA-class regression).
 
 #### The three-step pipeline
 
@@ -395,9 +393,13 @@ cp "${TMPDIR:-/tmp}/grida-htmlcss-goldens/"*.png target/refbrowser/L0.exact/actu
 **3. Diff via `@grida/reftest`** — format-agnostic, same bucket layout
 and `report.json` schema as the Rust and refig runners.
 
-Default refbrowser diff: **`--threshold 0`** (pixelmatch strictest,
-AA off). Pass each fixture's similarity against the suite's
-`gate.floor` — for `L0.exact`, that's `1.0` (100.00% byte-exact).
+Default refbrowser diff: **`--threshold 0`** (pixelmatch's tightest
+color-delta) with **AA-ignore mode on by default** (`aa: true` →
+`includeAA: false`; pixelmatch's Vysniauskas AA detector fires and
+excludes edge AA pixels from the diff count). Pass `--no-aa` to flip
+to strict byte-exact accounting. Pass each fixture's similarity
+against the suite's `gate.floor` — for `L0.exact`, that's `1.0`
+(100.00% similarity with AA detection active).
 
 ```sh
 pnpm --filter @grida/reftest exec reftest \
@@ -419,43 +421,46 @@ Pass bar: the suite's `gate.floor`. For `L0.exact`, anything below
 100.00% is a real divergence from Blink (rounding policy, layout
 math, AA emission, etc.) — not noise. See "Reading the score" below.
 
-### Reading the score — do not trust it naively
-
-The similarity score is `1 - diff_pixels / scoring_pixels`, where
-`scoring_pixels ≈ width × height` of the screenshot. **The denominator
-is the whole canvas, not the subject under test.**
-
-This has two consequences you must internalize before reading any
-report:
-
-1. **Background dominates the score.** A fixture that paints a
-   100×100 subject on a 600×800 canvas has 92% background. A renderer
-   that emits _nothing_ for the subject still scores ~92%. A
-   renderer that paints the subject at 50% accuracy scores ~96%.
-   Neither number means what it naively looks like.
-2. **Small fixtures inflate. Full-bleed fixtures are honest.** A
-   card-in-corner composition will always look "good" on the score
-   even when broken; a composition that fills the viewport gives
-   numeric feedback proportional to real error.
-
-**Fixture-authoring rule:** size the fixture so the subject under
-test fills as much of the canvas as practical. Viewport height
-tuned to the subject's bounding box (via the suite entry's
-`viewport.height`) is the usual lever. Padding/margins around the
-subject are scoring dead weight — use them only when the test is
-_about_ spacing.
-
-**Reviewing rule:** never report a similarity number without
-eyeballing the diff PNG. A 96% score on a sparse fixture and a 96%
-score on a full-bleed fixture are _orders of magnitude_ apart in
-severity. The diff image is the source of truth; the score is a
-coarse index.
-
-For a true "fraction of the subject that matches," author a
-probe-friendly fixture (see the probe test section) and assert on
-specific pixels, or mask the background to transparent so
-`mask: alpha` counts only subject pixels. Plain refbrowser scores
-cannot give you that signal.
+### Scoring model — content mask
+
+The similarity score is `1 - diff_pixels / scoring_pixels`.
+`scoring_pixels` is the count of pixels where either side has
+`alpha > 0` — the content mask, not the full canvas. Three
+coupled defaults wire this up:
+
+- **Chromium** screenshots with `omitBackground: true` (in
+  `refbrowser_render.ts`). Root canvas default bg is dropped; PNG
+  alpha encodes "did the CSS cascade draw here?"
+- **cg** clears its Skia surface with `Color::TRANSPARENT` and
+  renders at viewport dims (in `examples/golden_htmlcss.rs`).
+- **Both sides** apply `_reftest/transparent-body.css` via
+  `extra_css`. `!important` forces `html, body { background:
+transparent }`, so fixtures with `body { background: #fff }`
+  still produce a content mask without being edited.
+
+Chromium and cg produce identical alpha masks on every L0.exact
+fixture. Diffs that appear under `alpha > 0` are genuine pixel
+differences.
+
+**AA-ignore on by default** (`aa: true` → pixelmatch
+`includeAA: false`). The Vysniauskas AA detector excludes
+anti-aliased edge pixels from the diff count. Combined with the
+content mask, this yields:
+
+| pattern             | strict (`--no-aa`) | default (`--aa`) | meaning                                                                                                      |
+| ------------------- | ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------ |
+| **pass**            | 100%               | 100%             | identical — no action.                                                                                       |
+| **AA noise**        | 99.9+%             | 100%             | Skia/Blink rasterizer edge jitter on curves, radii, tilted geometry. Safe to ignore.                         |
+| **real divergence** | <100%              | <100%            | renderer bug or non-AA rasterizer mismatch (dither lattice, multi-color miter wedges). Inspect the diff PNG. |
+
+**Reviewing rule:** always eyeball the diff PNG. A fixture below
+100% with `aa: true` has mismatched pixels that pixelmatch could
+not explain as edge AA — treat as real.
+
+**Fixture-authoring rule:** the content mask excludes blank bg, so
+there's no need to shrink viewports for scoring density. Focus on
+minimality (one concept per fixture). Probe tests remain the tool
+for vision-free pixel assertions at known coordinates.
 
 **Per-fixture fields inside a suite entry** — all optional,
 defaults shown; any field set on an entry overrides `defaults`.
@@ -484,9 +489,10 @@ defaults shown; any field set on an entry overrides `defaults`.
 
 **Pre-built helper stylesheets** under `fixtures/test-html/_reftest/`:
 
-| File            | Effect                                                                                                                         |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `hide-text.css` | `color: transparent` + `line-height: 1`. Zeros glyph coverage and pins line-box height. Use when a fixture isn't testing text. |
+| File                   | Effect                                                                                                                                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hide-text.css`        | `color: transparent` + `line-height: 1`. Zeros glyph coverage and pins line-box height. Use when a fixture isn't testing text.                                                                      |
+| `transparent-body.css` | Forces `html, body { background: transparent !important }`. Enables the content mask (alpha>0 = drawn). Both L0 suites apply this by default; drop from `extra_css` for fixtures testing canvas bg. |
 
 Add more helpers here as divergence patterns emerge. Keep each one
 scoped to a single concern (hide text, normalize scrollbars, force
@@ -558,9 +564,10 @@ PR description; let the score carry the truth.
 - **Scrollbar width** — default `full_page: true` captures document
   height and sidesteps scrollbar chrome; flip only when testing
   scrollbar geometry.
-- **Dimension drift** — changing a fixture's layout invalidates its
-  `viewport.height` in the suite entry. Re-run `golden_htmlcss` with
-  `--suite`, update the entry's `viewport.height`, re-run refbrowser.
+- **Dimensions** — cg renders at viewport dims (`width × height`);
+  Chromium screenshots `fullPage` at the same viewport. Setting an
+  explicit `viewport.height` is optional and only useful to trim
+  scoring area for very tall fixtures.
 
 **Oracle type summary:**
 

.agents/skills/cg-reftest/scripts/refbrowser_render.ts

@@ -216,6 +216,8 @@ async function renderOne(
     fullPage: config.full_page,
     animations: "disabled",
     caret: "hide",
+    // Alpha encodes "CSS drew here" — used as content mask by scoring.
+    omitBackground: true,
   });
 
   await page.close();

.agents/skills/fixtures/SKILL.md

@@ -43,6 +43,13 @@ edge case** that the codebase supports or intends to support. This includes:
   filename alone should tell you what's being tested.
 - **Labeled specimens.** Within a fixture, label each test case with the
   value being exercised so both humans and heuristics can identify regions.
+  Keep labels short, and pin the dimensions of any container holding a
+  label (flex item, grid cell, stretched block) so font-advance-width
+  differences between engines can't leak into box geometry. When a test
+  pipeline offers a text-neutralizing stylesheet (e.g.
+  `fixtures/test-html/_reftest/hide-text.css` for the htmlcss reftests),
+  prefer that over stripping the label — keeping the text helps the next
+  reader understand the fixture.
 - **Match the fixture's subject to the viewport policy.** For refbrowser
   fixtures under `fixtures/test-html/`, **paint / visual-property**
   fixtures should size their root to a preset viewport (via `min-height`)

crates/grida-canvas/examples/golden_htmlcss.rs

@@ -125,13 +125,14 @@ fn render_to_png(
 ) {
     let picture =
         htmlcss::render(html, width, height, fonts, &htmlcss::NoImages).expect("render failed");
-    let cull = picture.cull_rect();
-    let w = cull.width().max(1.0) as i32;
-    let h = cull.height().max(1.0) as i32;
+    // Full-viewport dims match Chromium's fullPage footprint; transparent clear
+    // lets PNG alpha double as the reftest content mask.
+    let w = width.max(1.0) as i32;
+    let h = height.max(1.0) as i32;
 
     let mut surface = surfaces::raster_n32_premul((w, h)).expect("surface");
     let canvas = surface.canvas();
-    canvas.clear(Color::WHITE);
+    canvas.clear(Color::TRANSPARENT);
     canvas.draw_picture(&picture, None, None);
 
     let image = surface.image_snapshot();

crates/grida-canvas/src/htmlcss/collect.rs

@@ -871,7 +871,7 @@ fn collect_inline_items(el: &StyledElement, items: &mut Vec<InlineRunItem>) {
 /// Returns `None` if the element has no visual box decoration.
 fn build_inline_decoration(el: &StyledElement) -> Option<InlineBoxDecoration> {
     let bg = el.background.first().and_then(|l| match l {
-        BackgroundLayer::Solid(c) if c.a > 0 => Some(*c),
+        BackgroundLayer::Solid { color, .. } if color.a > 0 => Some(*color),
         _ => None,
     });
 
@@ -1185,6 +1185,10 @@ fn extract_style(tag: &str, style: &ComputedValues) -> StyledElement {
     // Flex child
     el.flex_grow = style.clone_flex_grow().0;
     el.flex_shrink = style.clone_flex_shrink().0;
+    el.flex_basis = match &pos.flex_basis {
+        style::values::generics::flex::FlexBasis::Size(s) => extract_size(s),
+        style::values::generics::flex::FlexBasis::Content => CssLength::Auto,
+    };
 
     // Grid container
     if el.display == types::Display::Grid {
@@ -1571,34 +1575,49 @@ fn extract_gradient_interpolation(
 
 fn extract_border_radius(style: &ComputedValues) -> CornerRadii {
     let b = style.get_border();
-    let lp = |lp: &style::values::computed::NonNegativeLengthPercentage| -> f32 {
-        lp.0.to_length().map(|l| l.px()).unwrap_or(0.0)
+    // Returns (px, percent_fraction). Percent is deferred to paint time,
+    // where the border-box w/h is known (CSS Backgrounds 3 §5.3).
+    let lp = |v: &style::values::computed::NonNegativeLengthPercentage| -> (f32, f32) {
+        match length_percentage_to_css(&v.0) {
+            CssLength::Px(p) => (p, 0.0),
+            CssLength::Percent(p) => (0.0, p),
+            CssLength::Calc { px, percent } => (px, percent),
+            CssLength::Auto => (0.0, 0.0),
+        }
     };
+    let (tl_x, tl_x_pct) = lp(&b.border_top_left_radius.0.width);
+    let (tl_y, tl_y_pct) = lp(&b.border_top_left_radius.0.height);
+    let (tr_x, tr_x_pct) = lp(&b.border_top_right_radius.0.width);
+    let (tr_y, tr_y_pct) = lp(&b.border_top_right_radius.0.height);
+    let (br_x, br_x_pct) = lp(&b.border_bottom_right_radius.0.width);
+    let (br_y, br_y_pct) = lp(&b.border_bottom_right_radius.0.height);
+    let (bl_x, bl_x_pct) = lp(&b.border_bottom_left_radius.0.width);
+    let (bl_y, bl_y_pct) = lp(&b.border_bottom_left_radius.0.height);
     CornerRadii {
-        tl_x: lp(&b.border_top_left_radius.0.width),
-        tl_y: lp(&b.border_top_left_radius.0.height),
-        tr_x: lp(&b.border_top_right_radius.0.width),
-        tr_y: lp(&b.border_top_right_radius.0.height),
-        br_x: lp(&b.border_bottom_right_radius.0.width),
-        br_y: lp(&b.border_bottom_right_radius.0.height),
-        bl_x: lp(&b.border_bottom_left_radius.0.width),
-        bl_y: lp(&b.border_bottom_left_radius.0.height),
+        tl_x,
+        tl_y,
+        tr_x,
+        tr_y,
+        br_x,
+        br_y,
+        bl_x,
+        bl_y,
+        tl_x_pct,
+        tl_y_pct,
+        tr_x_pct,
+        tr_y_pct,
+        br_x_pct,
+        br_y_pct,
+        bl_x_pct,
+        bl_y_pct,
     }
 }
 
 fn extract_size(
     size: &GenericSize<style::values::computed::NonNegativeLengthPercentage>,
 ) -> CssLength {
     match size {
-        GenericSize::LengthPercentage(lp) => {
-            if let Some(len) = lp.0.to_length() {
-                CssLength::Px(len.px())
-            } else if let Some(pct) = lp.0.to_percentage() {
-                CssLength::Percent(pct.0)
-            } else {
-                CssLength::Auto
-            }
-        }
+        GenericSize::LengthPercentage(lp) => length_percentage_to_css(&lp.0),
         _ => CssLength::Auto,
     }
 }
@@ -1610,15 +1629,7 @@ fn extract_max_size(
 ) -> CssLength {
     use style::values::generics::length::GenericMaxSize;
     match size {
-        GenericMaxSize::LengthPercentage(lp) => {
-            if let Some(len) = lp.0.to_length() {
-                CssLength::Px(len.px())
-            } else if let Some(pct) = lp.0.to_percentage() {
-                CssLength::Percent(pct.0)
-            } else {
-                CssLength::Auto
-            }
-        }
+        GenericMaxSize::LengthPercentage(lp) => length_percentage_to_css(&lp.0),
         _ => CssLength::Auto, // None, MaxContent, MinContent, FitContent, etc.
     }
 }
@@ -1653,11 +1664,22 @@ fn extract_background(style: &ComputedValues, current_color: CGColor) -> Vec<Bac
     let bg = style.get_background();
     let mut layers: Vec<BackgroundLayer> = Vec::new();
 
-    // 1. Background color (bottom layer)
+    // 1. Background color (bottom layer). Per CSS Backgrounds 3 §2.5 the
+    //    color uses the `background-clip` value from the *final* layer
+    //    entry in the list.
     if let Some(abs) = bg.background_color.as_absolute() {
         let c = abs_color_to_cg(abs);
         if c.a > 0 {
-            layers.push(BackgroundLayer::Solid(c));
+            let color_clip = bg
+                .background_clip
+                .0
+                .last()
+                .map(extract_bg_clip)
+                .unwrap_or(BackgroundBox::BorderBox);
+            layers.push(BackgroundLayer::Solid {
+                color: c,
+                clip: color_clip,
+            });
         }
     }
 
@@ -2771,10 +2793,10 @@ fn map_overflow(ov: style::values::specified::box_::Overflow) -> types::Overflow
 fn abs_color_to_cg(color: &AbsoluteColor) -> CGColor {
     let srgb = color.to_color_space(ColorSpace::Srgb);
     CGColor::from_rgba(
-        (srgb.components.0.clamp(0.0, 1.0) * 255.0) as u8,
-        (srgb.components.1.clamp(0.0, 1.0) * 255.0) as u8,
-        (srgb.components.2.clamp(0.0, 1.0) * 255.0) as u8,
-        (srgb.alpha.clamp(0.0, 1.0) * 255.0) as u8,
+        (srgb.components.0.clamp(0.0, 1.0) * 255.0).round() as u8,
+        (srgb.components.1.clamp(0.0, 1.0) * 255.0).round() as u8,
+        (srgb.components.2.clamp(0.0, 1.0) * 255.0).round() as u8,
+        (srgb.alpha.clamp(0.0, 1.0) * 255.0).round() as u8,
     )
 }