Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions doc/00_llm_process/feature_expert/web_render_css_parity/skill.md
Original file line number Diff line number Diff line change
Expand Up @@ -325,3 +325,44 @@ rather than the `<ul>`; the 247/79/492 mismatch counts are one structural
divergence cascading, not hundreds of defects. Rank pages with the PIXEL
differ and trust the geometry report only above the first desync.
`doc/08_tracking/bug/web_geometry_differ_li_reparented_desyncs_nth_paths_2026-09-13.md`

## Round 7 (2026-09-13) — the TOP half landed; the shape that made it possible

The symmetric top-margin case above is now CLOSED, and it did **not** need the
pre-pass the round-6 note predicted. `LayoutResult` gained `leading_margin_t`
(the exact mirror of `trailing_margin_b`) and the block child loop does a
**two-phase correction** with the `offset_layout_subtree` that was already in
the file: place the child from its DECLARED margin-top, then re-offset the whole
child subtree by the difference against its EFFECTIVE one,
`collapse(declared, child.leading_margin_t)`. The effective value is only
knowable after the child is laid out, which is exactly the objection — the
answer is to move the box afterwards, not to measure it beforehand.

Three things that cost a probe each, all now pinned as AC in
`test/01_unit/browser_engine/first_child_top_margin_collapse_spec.spl`:
- **`<li>` is the case the catalog actually exercises** (the feature-inventory
pages carry ~100 each) and it has a `::marker` as its FIRST node. Check that
the marker does not consume `child_count == 0` before the escape test, or the
fix silently does nothing on every list. AC-9.
- **Out-of-flow first children** must not donate a margin to the block. AC-10.
- **Nesting must yield ONE margin, not one per level** — the recursion is in
returning the escaped margin upward, not in adding it at each level. AC-8.

The exclusion set was deliberately copied from
`block_bottom_margin_collapses_through` INCLUDING the height clamps, even though
CSS does let a top margin escape a fixed-height block. Widening it would move
boxes the trailing half still holds; the remaining case is recorded, not guessed.

**`::marker` bites the key scheme too, in a second place.** The 2026-09-12 fix
corrected the geometry differ's `_layout_tag`; the renderer's own
`_simple_web_layout_element` still counted markers, so every hit-test and
animation target key inside an `<li>` was off by one ordinal. All three copies
of the scheme (Chrome walker, differ, renderer) now exclude `::`-prefixed tags.
If you touch one, grep for the other two.

**6th measurement gotcha (macOS):** the PIXEL differ is impractically slow here
— one `html` page did not finish rendering the Simple side in 20 minutes, and
Chrome itself hits the 90 s screenshot alarm on every page. Budget the geometry
differ instead, and never A/B across two trees: check the two
`browser_engine/*.spl` files out at `HEAD~1` in the SAME worktree for the before
side (`.claude/rules/testing.md` § Measurement traps).
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Web renderer: a first child's TOP margin never collapses through its block

- status: OPEN
- status: FIXED 2026-09-13 (Chrome parity round 7)
- area: lib / browser_engine layout
- found: 2026-09-13, Chrome parity round 6
- file: `src/lib/gc_async_mut/gpu/browser_engine/simple_web_html_layout_renderer_layout.spl`
Expand Down Expand Up @@ -52,3 +52,57 @@ tag; generalising it is the work.
test/01_unit/browser_engine/li_last_child_margin_collapse_spec.spl

and add the three rows above as expectations; they fail by exactly 16 px.

## Fix (round 7, 2026-09-13)

`LayoutResult` gains `leading_margin_t`, the exact mirror of the round-6
`trailing_margin_b`, and `block_top_margin_collapses_through` mirrors
`block_bottom_margin_collapses_through`'s exclusion set (documents, non-block
display, out-of-flow, floats, BFC roots, widget panels, flex/grid items, and —
conservatively — every height clamp).

The chicken-and-egg the record identified is resolved with the two-phase
mechanics `offset_layout_subtree` already serves elsewhere, not with a pre-pass:
the block child is laid out at the advance computed from its DECLARED
margin-top, and immediately afterwards the caller recomputes the advance from
the child's EFFECTIVE top margin (`collapse_margins_signed(declared,
child.leading_margin_t)`) and translates the child subtree by the difference.
When this block itself collapses its top through, the whole effective margin is
pulled back out (`corrected_top_advance = 0`), `cy` un-advances, the height
shrinks by it, and the margin is returned as this block's `leading_margin_t` for
its own parent to collapse — so nesting N wrappers still yields ONE margin.
The `<body>` hand-rolled case in the same loop is kept and now uses the
effective margin too.

`src/lib/gc_async_mut/gpu/browser_engine/simple_web_html_layout_renderer_layout.spl`
— `LayoutResult.leading_margin_t` (:173), `block_top_margin_collapses_through`
(after `offset_layout_subtree`), the correction block in the block child loop.

## Specs (both required by .claude/rules/testing.md)

- Reproducing: `test/01_unit/browser_engine/first_child_top_margin_collapse_spec.spl`
AC-1..AC-3 are the three rows of the symptom table above (24 / 50 / 42).
- Generalization (same file, adjacent paths): AC-4..AC-6 pin the cases that must
NOT collapse (top padding, `overflow:hidden` BFC, explicit height), AC-7 pins
that the escaped margin still separates the block from what precedes it, AC-8
pins that two nested wrappers yield ONE margin rather than one per level,
**AC-9** pins a `<li>` — whose synthesised `::marker` is its first NODE, so a
block loop that counted it could never let the real first child's margin
escape — and **AC-10** pins that an out-of-flow (absolutely positioned) first
child does not donate its margin to the block.

Sabotage triple: with `block_top_margin_collapses_through` forced to `false`,
AC-1/2/3/8 fail and AC-4/5/6/7 still pass; restored, 10/10 pass. The round-6
trailing-half spec `li_last_child_margin_collapse_spec.spl` stays 12/12.

## Known limit left open by the round-7 fix

The escape is computed for the FIRST in-flow child only. A first child that is
itself **self-collapsing** (an empty block whose own top and bottom margins
collapse into one, handled by the `self_collapsing` branch in the same loop)
forwards its collapsed margin to the next sibling through `prev_margin_b`, and
that sibling is no longer `child_count == 0`, so its margin is placed inside the
block rather than joining the escape. Closing it needs an "still at the block's
top edge" flag carried across self-collapsing children rather than a
`child_count == 0` test. Not probed against a Chrome oracle in round 7 — stated
as the next thing to measure, not as a measured defect.
Original file line number Diff line number Diff line change
Expand Up @@ -89,3 +89,22 @@ cache key and `identity` (without that, bold and regular would share a cache
entry and the first one measured would win); THEN (3) `st.bold` /
`st.font_style_italic` passed at the `resolve_font_metrics_with_language` call
site in `..._core.spl`. Step 1 is in files this lane does not own.

## Round 7 (2026-09-13) — re-confirmed blocked, on a macOS host this time

Round 7 was briefed to close this and did not, for the same reason round 5 gave,
re-verified independently on macOS rather than taken on trust:

- `assets/fonts` holds exactly ONE static bold face tree-wide,
`google-fonts/ofl/unifrakturcook/UnifrakturCook-Bold.ttf` (blackletter
display) — `find assets -iname "*Bold*"` returns that single path.
- `browser_sans_font_candidates` / `browser_mono_font_candidates`
(`src/lib/nogc_sync_mut/text_layout/font_provider.spl:68-85`) list bundled
variable fonts plus `/usr/share/fonts/...` Linux regular faces. On macOS those
Linux paths do not exist at all, so the candidate set is the variable Noto
faces and nothing else.

Step 1 of the closure order recorded above (a static bold candidate list, or
`fvar` instancing in the TTF loader) is therefore still the blocker, and it is
still in files this lane does not own. Adding the weight argument first would
still change no advance. Left OPEN deliberately; not worked around.
Original file line number Diff line number Diff line change
Expand Up @@ -51,3 +51,23 @@ quoting only the flattering one.
2. Remove the `not tag.starts_with("::")` clause: the same row reports
`dw 119, dh 85`, and the `<p>` sibling reports `dw 730`.
3. Restore: `dw 5, dh 1` again.

## Round 7 (2026-09-13) — the SECOND copy of the key scheme had the same defect

The 2026-09-12 fix corrected `_layout_tag` in the differ. It did not correct the
renderer's own copy: `_simple_web_layout_element`
(`src/lib/gc_async_mut/gpu/browser_engine/simple_web_html_layout_renderer.spl:124`),
which feeds `_simple_web_node_target_key` and the bulk animation target-key
pass, skipped `#text`/`style`/`script`/`title`/`head`/`meta`/`link`/`base` but
NOT `::marker` — while the geometry differ's walker comment claims the two
mirror each other "byte-for-byte". They did not: every hit-test and CSS
animation target key for an element inside an `<li>` was off by one ordinal, so
a pointer event or an animation keyed by path addressed the wrong node.

Fixed by excluding any `::`-prefixed tag there too, so all three copies of the
scheme (Chrome walker, differ, renderer) now agree.

Spec: `test/01_unit/browser_engine/li_marker_nth_path_key_spec.spl` — AC-1 the
block inside an `<li>` is `path:0/0/0`, AC-2 a second element child keeps
ordinal 1, AC-3 a block outside any list is unaffected. Sabotage (swap `"::"`
for a string no tag starts with): AC-1 and AC-2 fail, AC-3 still passes.
134 changes: 134 additions & 0 deletions doc/10_metrics/ui/web_chrome_parity_round7_2026-09-13.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# Chrome ↔ pure-Simple web parity — round 7 (2026-09-13, macOS)

Host: macOS (Darwin 25.5.0), worktree
`.claude/worktrees/agent-aabafaf9bfca3aa6a`, binary
`build/cargo-r2/release/simple` (interpreter execution mode), Chrome
`/Applications/Google Chrome.app`. Pixel differ
`scripts/check/check-chrome-catalog-pixel-diff.shs` at 900x760; geometry differ
`scripts/check/check-chrome-layout-geometry-diff.shs` at `GEOM_DIFF_HEIGHT=20000`.

**Both sides of the A/B were measured in THIS worktree with THIS binary**, per
`.claude/rules/testing.md` § Measurement traps ("never A/B across two trees").
BEFORE = the same tree with only the two `src/lib/.../browser_engine/*.spl`
files checked out at `HEAD~1`; AFTER = the same tree with them restored.
Nothing else differs. The round-6 figures quoted in the round-7 brief were
measured on another host and are NOT used as the before column.

## Items

### (d) nth-path desync inside `<li>` — FIXED, but not the item the brief described

The brief's framing ("the differ's DOM path for list items skips the
`::marker`") was already closed on 2026-09-12 in the differ itself
(`_layout_tag` excludes `::`-prefixed tags). What was still open is the
**renderer's own copy of the same scheme**:

- Root cause: `_simple_web_layout_element`,
`src/lib/gc_async_mut/gpu/browser_engine/simple_web_html_layout_renderer.spl:124`
— skipped `#text`/`style`/`script`/`title`/`head`/`meta`/`link`/`base` but not
`::marker`, which the foundation pass synthesises as every `<li>`'s FIRST
child (`..._foundation.spl:1128`, "First child by construction"). The Chrome
walker in `check-chrome-layout-geometry-diff.shs:80-82` claims these mirror
each other "byte-for-byte"; they did not. Every hit-test and CSS-animation
target key for an element inside an `<li>` was off by one ordinal.
- Fix: exclude any `::`-prefixed tag there too, so the Chrome walker, the
geometry differ and the renderer now agree.
- Spec: `test/01_unit/browser_engine/li_marker_nth_path_key_spec.spl` (3 AC).
- This does NOT affect the pixel differ (it keys nothing) and does not move the
per-page numbers below; it is a correctness fix on the interaction path.

**Still open and NOT this defect:** `<li>` boxes attributed to the enclosing
`<section>` rather than the `<ul>`, which is what actually desyncs the geometry
report on `html` after `path:0/0/4/3` —
`doc/08_tracking/bug/web_geometry_differ_li_reparented_desyncs_nth_paths_2026-09-13.md`.
Round 7 narrowed it by one step but did NOT establish the root: Draw IR
parentage is copied straight from `nodes[i].parent`
(`..._paint_layout.spl:3117-3125`), so the emitter itself does not invent a
parent. Two candidates remain live and neither is established — (i) the parsed
tree really does give the `<li>` the `<section>` as parent, or (ii) the `<ul>`
emits no Draw IR command (invisible / no paint) and the differ's own
`_index_of_id` / `_seen` handling of a missing intermediate ancestor produces
the shift. Not closed in round 7.

### (a) first-child TOP margin collapse-through — FIXED

- Root cause: `simple_web_html_layout_renderer_layout.spl` — the caller advances
`cy` by `collapse_margins_signed(prev_margin_b, cst.margin_t)` BEFORE
`layout_with_style` runs, so the round-6 trailing-margin shape
(`trailing_margin_b`, known only after the children are laid out) could not be
mirrored.
- Fix: `LayoutResult.leading_margin_t` + `block_top_margin_collapses_through`
(exclusion set mirrored from the bottom half) + a two-phase correction using
the existing `offset_layout_subtree`: the child is placed from its DECLARED
margin-top, then re-offset by the difference against its EFFECTIVE one
(`collapse(declared, child.leading_margin_t)`). When the block itself
collapses through, the whole effective margin is pulled back out, the height
shrinks by it, and it is returned for the parent to collapse — so N nested
wrappers yield ONE margin.
- Specs: `test/01_unit/browser_engine/first_child_top_margin_collapse_spec.spl`
(10 AC: 3 reproducing + 7 generalization, incl. `<li>`/`::marker` and an
out-of-flow first child). Sabotage: forcing the predicate to `false` fails
AC-1/2/3/8 and leaves AC-4..7 green.
- Record: `doc/08_tracking/bug/web_first_child_top_margin_never_collapses_through_2026-09-13.md`
flipped to FIXED with the mechanism and the sabotage triple.

### (c) bold advances — re-confirmed BLOCKED, not attempted

Re-verified on this macOS host rather than taken on trust: `find assets -iname
"*Bold*"` returns exactly one face tree-wide (`UnifrakturCook-Bold.ttf`,
blackletter display), and `browser_sans_font_candidates`
(`src/lib/nogc_sync_mut/text_layout/font_provider.spl:68-77`) otherwise lists
bundled VARIABLE fonts plus `/usr/share/fonts/...` Linux regular faces that do
not exist on macOS at all. Step 1 of the closure order (a static bold candidate
list, or `fvar` instancing in the TTF loader) is still in files this lane does
not own; adding the weight argument first would change no advance and would be
unused code. Round-7 note appended to
`doc/08_tracking/bug/web_inline_bold_face_advances_never_selected_2026-09-12.md`.

### (b) tables — not started

`table_layout_spec` 0/7 is a multi-hour item on its own and was correctly
deprioritised behind (d)/(a) per the brief's own ordering. Existing record:
`doc/08_tracking/bug/web_table_shrink_to_fit_and_ua_defaults_missing_2026-09-12.md`.

## Per-page geometry differential (lower is better)

**The pixel differ could not be run on this host.** Chrome hits the 90 s
`--screenshot` alarm on every catalog page, and one `html` Simple render had
still not produced a `.ppm` after 20 minutes — in BOTH lib states, so it is the
host, not the change. Two attempts were made (full catalog, then a 3-page
subset) and both were abandoned. The brief's stop criterion ("html/css-layout/
animation each drop by >=2 pixel points") is therefore **unevaluable in this
round**; it is not reported as met or unmet. The geometry differ is substituted
because it renders Draw IR without rasterising.

| page | compared | mismatched BEFORE | mismatched AFTER | delta |
|---|---|---|---|---|
| css-layout | 376 | 359 | 359 | 0 |
| animation | 81 | 79 | 79 | 0 |

`css-layout.geometry_diff.md` is **byte-identical** between the two runs
(`diff -q` rc=0; total |dy| over the 200 root-mismatch rows is 38114 on both
sides). That is a real result, not a failed measurement: the page carries 113
elements with a 16 px top margin, but the collapse-through predicate excludes
flex/grid items and any parent with top padding or a border, which is what a
card-based CSS demo page is made of. The two fixes are pinned by the
oracle-backed specs below, not by this page.

Both sides used the same worktree, the same binary and the same Chrome; the
BEFORE side differs only by `git checkout HEAD~1 --` on the two
`browser_engine` lib files.

## Neighbouring specs

| spec | result |
|---|---|
| `li_last_child_margin_collapse_spec` (round-6 twin) | 12/12 |
| `anonymous_block_spec` | 4/4 |
| `layout_paint_contract_pin_spec` | 6/6 |
| `inline_content_area_half_leading_spec` | 4/4 |
| `flex_wrap_auto_width_item_spec` | 4/4 |
| `grid_repeat_minmax_track_list_spec` | 4/4 |
| `inline_run_advance_and_break_boxes_spec` | 5/5 |
| `layout_text_node_spec` | 4/4 |
| `ifc_linebox_spec` | **0/10 — PRE-EXISTING**, fails identically with the two lib files reverted to `HEAD~1`; not caused by this change |
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,16 @@ fn _simple_web_layout_element(node: HNode) -> bool:
node.tag != "#text" and node.tag != "style" and
node.tag != "script" and node.tag != "title" and
node.tag != "head" and node.tag != "meta" and
node.tag != "link" and node.tag != "base"
node.tag != "link" and node.tag != "base" and
# Pseudo-element boxes (`::marker`, synthesised as every <li>'s FIRST
# child) are not DOM elements: Chrome's querySelectorAll walk cannot
# see them, so counting them here shifted the nth-path ordinal of
# every real child inside a list item by one. The geometry differ
# already excludes them from its own key scheme
# (doc/08_tracking/bug/web_layout_geometry_differ_counts_marker_boxes_
# as_elements_2026-09-12.md); these hit-test / animation target keys
# claim to mirror that scheme byte-for-byte and did not.
not node.tag.starts_with("::")
)

fn _simple_web_element_child_ordinal(
Expand Down
Loading
Loading