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
86 changes: 64 additions & 22 deletions doc/10_metrics/ui/web_perf_round10_2026-09-13.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,13 +80,50 @@ node — each a Dict lookup keyed on the whole multi-kilobyte merged declaration
string plus an array return — and six backwards linear scans over a table of
hundreds of entries.

## Target B: the `<template`-absent fast path

`_html_without_inert_template_sources` now probes `find_from(lower, "<template",
0)` once — a native substring scan — and returns `source` unchanged when the
substring is absent. That is exactly what the walk returns in that case: the
`name == "template"` branch is never taken, so `parts` ends as the single
element `source.substring(0, source.len())`.
## Correction (same day, PR #911): the first probe was WRONG

**PR #910 shipped a probe for the contiguous substring `<template`, and that is
not equivalent to the walk.** The walk derives its tag name from
`lower.substring(lt + 1, gt).trim()`, so `< template>` and `</ template>` reach
`name == "template"` while containing no contiguous `<template` — the fast path
returned a document whose template body the walk elides. The #910 fixture set
had no whitespace-after-`<` shape, which is exactly why its spec passed.

Fixed in #911, round-9 order: the shapes were added to the adversarial fixture
FIRST and the spec confirmed **failing** on them
(`[12] MISMATCH fast_len=68 slow_len=34`, `[13] MISMATCH fast_len=70
slow_len=34`), then the probe was replaced by `_html_template_tag_present`,
which mirrors the walk's own derivation: for each literal `template` occurrence,
walk back over whitespace, optionally one `/` and more whitespace, and test for
`<`. Bounded by the occurrence count (2-3 per catalog page), not the document
length.

A bare-word probe (`find_from(lower, "template", 0)`) would have been trivially
correct and is **not** usable: `grep -ic template` finds the word on all eight
catalog pages (prose and `grid-template-*`), so it would have deleted the entire
win. That fixture row is in the spec so the shortcut cannot be taken later.

Re-measured on the corrected probe, 2 alternating pairs on a much busier host
(`sel_match` 911-947 vs the 608-681 of the sweep below):

| pair | pp_css before | after | cas_tail b/a | sel_match b/a |
|---|---|---|---|---|
| 1 | 1223 | **554** | 889 / 877 | 947 / 916 |
| 2 | 1165 | **551** | 861 / 855 | 944 / 911 |

Same **-55%**, controls flat within each pair, 8/8 digests identical on all four
runs. (Those digests differ from the set recorded further down for `html` —
`2ecbe24a29e7ef3c` vs `85a685ca46fc3527` — because unrelated commits landed on
`main` between the two sweeps; both SIDES of every pair agree, which is what the
gate asserts.)

## Target B: the template-elide fast path

`_html_without_inert_template_sources` now answers "can the walk's
`name == "template"` branch fire at all?" via `_html_template_tag_present` and
returns `source` unchanged when it cannot. That is exactly what the walk returns
in that case: the branch is never taken, so `parts` ends as the single element
`source.substring(0, source.len())`.

The probe is deliberately made on the WHOLE lowered source rather than on the
walk's script/style-skipping view. A `<template` that appears only inside a
Expand All @@ -104,16 +141,19 @@ walk provably returns its input. The walk itself is untouched, split out as
wrapper and the walk and compares the results byte-for-byte.

Two tiers, the shape round 9 established: the eight catalog pages (all of which
take the fast path — none contains `<template` at all) plus twelve adversarial
documents — a real `<template>` body, a template with attributes, nested
templates, an unclosed template, a stray `</template>` with no opener,
`<template` inside a `<script>` body, `<template` inside a `<style>` body,
`<templatex>` (a prefix that is not the tag), uppercase `<TEMPLATE>`, a document
with no tags, and the empty document.

**2/2 examples pass, 0 mismatches.** Unlike round 9 this one found no
divergence — which is the expected outcome for a guard whose skipped branch is
provably a no-op, and is reported as such rather than dressed up.
take the fast path) plus sixteen adversarial documents — a real `<template>`
body, a template with attributes, nested templates, an unclosed template, a
stray `</template>` with no opener, a template tag inside a `<script>` body and
inside a `<style>` body, `<templatex>` (a prefix that is not the tag), uppercase
`<TEMPLATE>`, a document with no tags, the empty document, `< template>`,
`<\n\ttemplate>` / `</ template>`, `</ template>`, and a document carrying the
bare word `template` in prose and in `grid-template-columns`.

**2/2 examples pass, 0 mismatches** — but only after the correction above. The
first twelve fixtures passed against a probe that was genuinely wrong; the four
added in #911 are the ones that did the work. The lesson is round 9's, restated:
a fixture set that does not attack the fast path's own assumption proves
nothing.

### A/B evidence

Expand Down Expand Up @@ -183,10 +223,12 @@ sub-timers and these two comments survive, in
`_final_overflow_axis_in_decls`.

**What the next round should try instead**, now that the split is known:
`tail_inline` (~247 ms) is three unmemoized
`apply_decls_without_display_on_writing_mode` calls on `inline_normal` /
`combined_important_decls` / `inline_important`; extending the existing cascade
memo boundary to cover them (key = current `memo_key` + the three strings,
`tail_inline` (~247 ms) is the single unmemoized
`apply_decls_without_display_on_writing_mode` call on `inline_normal` — the
sibling calls on `combined_important_decls` and `inline_important` both sit at
the ~44 ms timer floor, i.e. they cost nothing on this catalog. Extending the
existing cascade memo boundary to cover it (key = current `memo_key` + that
string,
leaving `final_display` and `empty_cells_hide` outside, which read inputs not in
the key) is a memo-key change, not an array-passing change, and so does not hit
the copy cost that killed design 1. `tail_overflow` (~271 ms) needs the six
Expand All @@ -209,7 +251,7 @@ across 4/4 pairs. Against the round-2 baseline, the cumulative effect of rounds
| gate | verdict |
|---|---|
| Draw IR sha256, 8/8 pages | byte-identical across all 8 A/B runs (and every exploratory run): `5cdf8386bad82f0c 85a685ca46fc3527 76c359e483e11e84 2efd1c8c294b705e a16ea7c83d459a5a 616ad24659d7779e 4cf797f8c3a8f3a4 56097a5a1ce50dda` |
| `web_template_elide_fastpath_equivalence_spec` (new) | **2/2 pass**, 8 catalog pages + 12 adversarial documents, 0 mismatches |
| `web_template_elide_fastpath_equivalence_spec` (new) | **2/2 pass**, 8 catalog pages + 16 adversarial documents, 0 mismatches (1 real divergence caught and fixed first — see the correction at the top) |
| GPU boundary audit | `PASS — 2 frame(s) audited, host_pixel_iterations=0, readbacks_per_frame<=1, submits_per_frame<=1` |
| 53 `*selector*` / `*style*` / `*cascade*` / `*inherit*` specs + `web_cold_pipeline_memo_spec` | verdict lines **byte-identical before vs after** (35 OK, 18 pre-existing ERROR) |

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -810,20 +810,55 @@ fn _html_without_inert_template_sources(source: text) -> text:
# 125/152/251 ms on html/css-layout/css-paint, 571 ms of the 892 ms
# eight-page total) because it visits EVERY tag of the document and scans
# each tag name a character at a time in interpreted Simple -- to elide
# `<template>` bodies that most documents do not have. A document with no
# `<template` substring anywhere has nothing to elide: the loop below never
# takes the `name == "template"` branch, so `parts` ends as the single
# element `source.substring(0, source.len())` and the join returns `source`
# unchanged. The probe is a native `find_from` over the already-lowered
# copy, and it is deliberately made on the WHOLE source rather than on the
# walk's script/style-skipping view: a `<template` that only appears inside
# a `<script>` body makes the probe fall through to the full walk, which
# then classifies it exactly as before. The fast path can therefore only
# trigger where the walk provably returns the input.
if find_from(lower, "<template", 0) < 0:
# `<template>` bodies that most documents do not have. A document in which
# the `name == "template"` branch can never fire has nothing to elide: the
# loop leaves `parts` as the single element `source.substring(0,
# source.len())` and the join returns `source` unchanged.
#
# The probe is deliberately made on the WHOLE lowered source rather than on
# the walk's script/style-skipping view: a template tag appearing only
# inside a `<script>` body makes the probe fall through to the full walk,
# which classifies it exactly as before. The fast path can therefore only
# fire where the walk returns its input.
#
# **The first cut probed `"<template"` and was WRONG** -- the walk derives
# its tag name from `lower.substring(lt + 1, gt).trim()`, so `< template>`
# (and `</ template>`) reach `name == "template"` while containing no
# contiguous `<template`. That divergence was found by adding the shape to
# the equivalence fixture; see `_html_template_tag_present` for the probe
# that actually mirrors the walk's own name derivation.
if not _html_template_tag_present(lower):
return source
_html_without_inert_template_sources_scan(source)

fn _is_html_space(c: text) -> bool:
c == " " or c == "\t" or c == "\n" or c == "\r"

# True when `lower` (an already-lowercased document) can produce a tag whose
# name is `template` under the walk's own derivation: `<`, optional whitespace,
# optionally `/` and more whitespace, then the name. A bare `template` in prose
# or in a `grid-template` property therefore does not cost the fast path --
# which matters, because all eight catalog pages contain the bare word.
#
# Bounded by the number of `template` occurrences, not by the document length,
# and each occurrence is examined by walking backwards over whitespace only.
fn _html_template_tag_present(lower: text) -> bool:
var at = find_from(lower, "template", 0)
while at >= 0: # cpu-lane-loop-ok: one iteration per literal `template` occurrence in the document (2-3 on every catalog page), not per character
var p = at - 1
# cpu-lane-loop-ok: walks back over the whitespace immediately before ONE occurrence
while p >= 0 and _is_html_space(lower[p:p + 1]):
p = p - 1
if p >= 0 and lower[p:p + 1] == "/":
p = p - 1
# cpu-lane-loop-ok: whitespace between `<` and `/` of ONE closing tag
while p >= 0 and _is_html_space(lower[p:p + 1]):
p = p - 1
if p >= 0 and lower[p:p + 1] == "<":
return true
at = find_from(lower, "template", at + 1)
false

# The full tag walk, unchanged. Kept as its own function so the equivalence
# oracle below can drive it directly and compare it with the fast path.
fn _html_without_inert_template_sources_scan(source: text) -> text:
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""
## Purpose and audience
Purpose: Prove the round-10 `<template`-absent fast path in
Purpose: Prove the round-10 template-elide fast path in
`_html_without_inert_template_sources` returns exactly what the full tag walk
(`_html_without_inert_template_sources_scan`) returns, for every document.
Audience: browser-engine maintainers.
Expand All @@ -9,30 +9,42 @@ Web-perf round 10 (doc/10_metrics/ui/web_perf_round10_2026-09-13.md) sub-timed
`pp_css_us` for the first time and found this one function carrying 571 ms of
the 892 ms eight-page CSS-parse total -- it walks EVERY tag of the document and
scans each tag name a character at a time in interpreted Simple, in order to
elide `<template>` bodies that most documents do not contain. The fast path is
a single native `find_from(lower, "<template", 0)` probe: when the substring is
absent the walk provably returns its input unchanged, so the wrapper returns
`source` directly.
elide `<template>` bodies that most documents do not contain. The fast path
answers "can the walk's `name == "template"` branch fire at all?" and returns
`source` unchanged when it cannot.

"Provably" is the claim this spec tests rather than asserts. The oracle is
That question is the whole spec. The oracle is
`simple_web_layout_debug_template_elide_equivalence(html)`, which runs BOTH the
wrapper and the walk and returns "OK" only when the two results are
byte-identical.

**The first cut (PR #910) got the question wrong and this spec is why the
second one is right.** It probed for the contiguous substring `<template`, but
the walk derives its tag name from `lower.substring(lt + 1, gt).trim()` -- so
`< template>` and `</ template>` reach `name == "template"` with no contiguous
`<template` anywhere, and the fast path returned a document whose template body
the walk elides. Adding those rows made this spec FAIL (`[12] MISMATCH
fast_len=68 slow_len=34`), and the probe was replaced by
`_html_template_tag_present`, which mirrors the walk's own derivation: `<`,
optional whitespace, optionally `/` and more whitespace, then the name.

Coverage is two-tier, the same shape round 9's selector-equivalence spec used:
the eight shared catalog pages give real documents at real scale (and contain
no `<template` at all, which is exactly the fast path being taken), and the
adversarial fixtures below give the shapes the catalog never contains -- a real
`<template>` body, nested templates, an unclosed template, a stray
`</template>` with no opener, `<template` inside a `<script>` body and inside a
`<style>` body (where the walk's script/style skipping means the tag is NOT a
template but the probe still sees the substring, so the slow walk runs and must
agree), `<templatex>` (a prefix match that is not the tag), a template whose
tag carries attributes, and a document with no tags at all.
the eight shared catalog pages give real documents at real scale (all of which
take the fast path), and the adversarial fixtures below give the shapes the
catalog never contains -- a real `<template>` body, nested templates, an
unclosed template, a stray `</template>` with no opener, a template tag inside
a `<script>` body and inside a `<style>` body (where the walk's script/style
skipping means the tag is NOT a template but the probe still fires, so the slow
walk runs and must agree), `<templatex>` (a prefix that is not the tag), a
template whose tag carries attributes, uppercase `<TEMPLATE>`, a tagless
document, the empty document, the three whitespace-in-tag shapes above, and a
document carrying the bare word `template` in prose and in `grid-template`
(which must NOT cost the fast path -- every catalog page contains it, so a
probe on the bare word would delete the whole win).
"""

"""
Traceability: REQ-BROWSER-ENGINE-TEMPLATE-ELIDE-FASTPATH-001 — the `<template`-absent fast path must return exactly what the full tag walk returns.
Traceability: REQ-BROWSER-ENGINE-TEMPLATE-ELIDE-FASTPATH-001 — the template-elide fast path must return exactly what the full tag walk returns.
"""
# @cover src/lib/gc_async_mut/gpu/browser_engine/simple_web_html_layout_renderer_core.spl 1%
use std.spec.*
Expand Down Expand Up @@ -62,13 +74,27 @@ val ADVERSARIAL: [text] = [
"<html><body><templatex><p>not a template</p></templatex></body></html>",
"<html><body><TEMPLATE><p>upper</p></TEMPLATE><b>k</b></body></html>",
"plain text with no tags at all",
""
"",
# The shapes that BROKE the first cut of the fast path (PR #910), which
# probed for the contiguous substring `<template`. The walk derives its tag
# name from `lower.substring(lt + 1, gt).trim()`, so whitespace after `<`
# (and between `<` and `/`) still reaches `name == "template"` while the
# contiguous substring is absent -- the fast path returned the document
# unchanged where the walk elided a body.
"<html><body>< template><p>inert</p></template><b>k</b></body></html>",
"<html><body><\n\ttemplate><p>inert</p></ template><b>k</b></body></html>",
"<html><body><template><p>inert</p></ template><b>k</b></body></html>",
# The bare word `template` with no tag before it must NOT cost the fast
# path: every catalog page contains it (prose and `grid-template`), so a
# probe on the bare word would delete the whole win.
"<html><head><style>.g { grid-template-columns: 1fr; }</style></head>" +
"<body><p>a template is a pattern</p></body></html>"
]

describe "web template-elide fast path equivalence":
it "agrees with the full tag walk on every catalog page":
# oracle: every shared catalog document takes the fast path (none of
# them contains `<template`) and must still produce the walk's output.
# them contains a template tag) and must still produce the walk output.
expect(catalog_verdict("overview")).to_equal("OK")
expect(catalog_verdict("html")).to_equal("OK")
expect(catalog_verdict("css-layout")).to_equal("OK")
Expand All @@ -81,7 +107,7 @@ describe "web template-elide fast path equivalence":
it "agrees with the full tag walk on every adversarial shape":
# oracle: real templates, nested, unclosed, stray-close, script/style
# bodies mentioning the tag, a prefix that is not the tag, uppercase,
# attributes, a tagless document and the empty document.
# attributes, a tagless document, the empty document, and the whitespace-in-tag shapes that broke the first cut.
var mismatches = ""
var i = 0
while i < ADVERSARIAL.len():
Expand Down
Loading
Loading