Browser & Framework Internals — Progress
Track: Browser & Framework Internals (
browser-framework-internals.md). The sibling track (frontend-principal-engineering.md) is tracked in fe-00-roadmap/docs/progress.md. Neither claims progress on the other.Map, phases and sequencing rationale: bi-00-roadmap/CONCEPTS.md. Build/debug/trace procedures: bi-00-roadmap/docs/chromium-build-debug-trace.md.
Current phase: 0 — Instrumentation
Current module: bi-03-html-parsing (parsing lab) and bi-01-navigating-chromium (drills)
Status: materials complete through the whole track; awaiting learner execution of Phase 0.
Status values: todo · in progress · lab done · complete · revisit
Shared with the sibling track, do not duplicate: learning-log.md §3 is the source-reading log for both tracks · decisions/ holds ADRs from either.
0. The loop (non-negotiable)
Use it -> predict (written, BEFORE observing) -> build a small version
-> intentionally break it -> debug it -> inspect production source
-> compare architectures -> explain why the complexity exists
-> modify production source where practical
A prediction written after observation is worth nothing. A clearly-stated wrong prediction is worth more than a vague right one.
0b. Source-reading gate (§44)
Not complete until all eight are answered in writing: why does this code exist · what invariant does it maintain · who calls it · what does it call · which process/thread runs it · what happens if removed · how is it tested · what simpler design would fail, and why.
0c. Navigation rule
Source paths are never handed to you. State a hypothesis, search, confirm or falsify, and record the query that worked. Queries transfer; paths rot — see §8.
1. Phase status
Phase 0 — Instrumentation (no build required)
| Module | Status | Lab | Notes |
|---|---|---|---|
| bi-01-navigating-chromium | todo | ☐ drills | 8 timed drills; deliverable is the query log |
| bi-03-html-parsing | todo | ☐ parsing lab | start here; fixtures in src/ |
| Chromium checkout | ✅ done | ~/chromium/src @ 7e6a84f5165fd, 26 GB | |
| Chromium build | ⛔ blocked | toolchain floor — see build guide §2.0 | |
| Architecture map from memory, then corrected | todo | ☐ | |
| DevTools → Perfetto: name 5 trace events | todo | ☐ |
Phase 1 — Parser, DOM, Bindings
| Module | Status | Lab |
|---|---|---|
| bi-02-architecture-process-model | todo | ☐ |
| bi-04-dom-internals | todo | ☐ mini-browser M3 |
| bi-05-bindings-v8 | todo | ☐ mini-binding layer |
| fw-01-mini-redux | todo | ☐ + reading ladder L1 |
Phase 2 — Style
| Module | Status | Lab |
|---|---|---|
| bi-06-chromium-cpp | todo | ☐ (JIT reference) |
| bi-07-css-engine | todo | ☐ mini-browser M4–M6 |
| fw-02-mini-react-core | todo | ☐ stages 1–7 |
Vertical trace 1 — classList.add | todo | ☐ |
Phase 3 — Layout & Paint
| Module | Status | Lab |
|---|---|---|
| bi-08-layout | todo | ☐ mini-browser M7–M9 |
| bi-09-paint | todo | ☐ mini-browser M10–M11 |
| fw-03-reactivity-signals | todo | ☐ both, back to back |
Vertical traces 2, 3 — getBoundingClientRect, DOM insertion | todo | ☐ |
Phase 4 — Compositor, Scheduling, Debugging
| Module | Status | Lab |
|---|---|---|
| bi-10-compositor-gpu | todo | ☐ |
| bi-11-scheduling | todo | ☐ needs fe-01 first |
| bi-12-debugging-tracing | todo | ☐ needs a build |
| fw-04-mini-react-scheduling | todo | ☐ derive Fiber |
| fw-10-virtual-list | todo | ☐ |
| Vertical traces 4, 5, 8 — click, scroll, rAF | todo | ☐ |
Phase 5 — Compilers, Tooling, Production Source
| Module | Status |
|---|---|
| fw-05-vue-renderer | todo |
| fw-06-compilers | todo |
| fw-07-bundler | todo |
| fw-08-router | todo |
| fw-09-query-cache | todo |
| fw-11-production-source | todo |
| fw-12-testing-devtools | todo |
Vertical traces 6, 7 — setState, fetch | todo |
Phase 6 — Tests, WPT, Contribution
| Module | Status |
|---|---|
| bi-13-tests-wpt | todo — needs a build |
| bi-14-contribution | todo — needs a build |
Phase 7 — Capstone
| Module | Status |
|---|---|
| bi-15-vertical-traces | ongoing across phases |
| bi-16-capstone | todo |
2. Vertical trace ledger (§43)
Record the deepest layer genuinely resolved with evidence, not the deepest you can name.
| # | Operation | After | Status | Deepest resolved | Evidence type |
|---|---|---|---|---|---|
| 1 | classList.add | bi-07 | ☐ | ||
| 2 | getBoundingClientRect | bi-08 | ☐ | ||
| 3 | DOM insertion | bi-04 | ☐ | ||
| 4 | click | bi-10/11 | ☐ | ||
| 5 | scroll | bi-10 | ☐ | ||
| 6 | setCount(count+1) | fw-04 | ☐ | ||
| 7 | fetch | bi-02 | ☐ | ||
| 8 | requestAnimationFrame | bi-11 | ☐ |
2b. Archaeology missions (§25)
document.createElement ☐ · classList.add ☐ · getBoundingClientRect ☐ ·
requestAnimationFrame ☐ · fetch ☐ · CSS Grid ☐ · click/input ☐ · accessibility tree ☐
3. Complexity notebook (§46)
Observed complexity:
My simpler design:
What requirement breaks my design:
Production constraint:
Resulting architecture:
Classification: essential architecture | production hardening | accretion (defend it)
| # | Topic | Module | Status |
|---|---|---|---|
| 1 | HTML parser insertion modes | bi-03 | ☐ |
| 2 | Redux middleware vs enhancers | fw-01 | ☐ |
| 3 | Style invalidation sets | bi-07 | ☐ |
| 4 | Layout fragmentation | bi-08 | ☐ |
| 5 | Property trees | bi-09 | ☐ |
| 6 | Pending/active tree split | bi-10 | ☐ |
| 7 | Mojo / multiprocess IPC | bi-02 | ☐ |
| 8 | Two garbage collectors | bi-04 | ☐ |
| 9 | Vue scheduler | fw-03 | ☐ |
| 10 | Fiber (flagship) | fw-04 | ☐ |
| 11 | Hydration | fw-11 | ☐ |
| 12 | Event delegation / synthetic events | fw-11 | ☐ |
4. Contribution ladder (§24)
| Rung | Target | Status | CL |
|---|---|---|---|
| 0 | Build Chromium | ⛔ blocked on toolchain | — |
| 1 | Docs or test-only | ☐ | |
| 2 | Small isolated correctness fix | ☐ | |
| 3 | Blink behaviour bug + regression test | ☐ | |
| 4 | Small rendering/style/layout improvement | ☐ | |
| 5 | Cross-component change | ☐ |
Per rung retain: bug · reproduction · spec · subsystem · source path · call path · test · proposed fix · reviewer feedback · architectural lesson.
Candidate pool: build it in bi-13 lab step 4 from TestExpectations.
5. Lab log
| Lab | Date | Prediction correct? | Time | Biggest surprise |
|---|---|---|---|---|
| parsing (bi-03) | ||||
| navigation drills (bi-01) |
Source-code readings go in fe-00-roadmap/docs/learning-log.md §3.
6. Environment
| Checkout | ~/chromium/src @ 7e6a84f5165fd (VERSION 8002), 26 GB |
| git cache | ~/Library/Caches/depot_tools/git_cache, 24 GB — deletable |
| depot_tools | ~/depot_tools, on PATH via ~/.zshrc |
| Free disk | ~90 GB |
| Host | macOS 15.0 · Xcode 16.2 · SDK 15.2 · M2 Pro / 12 core / 32 GB |
| Build | ⛔ trunk requires macOS 26.2 / Xcode 26.5 |
What still works without a compiler: git grep over the full tree (faster than Code
Search), git log -S archaeology, all in-tree docs, .json5/.idl/.mojom reading — i.e.
everything through Phase 2.
7. Verification log
Chromium moves. Anything unchecked older than ~6 months is suspect.
| Date | Claim | Verdict |
|---|---|---|
| 2026-08-10 | Chromium trunk builds with Xcode 16.2 / SDK 15.2 | FALSE — requires Xcode 26.5 / SDK 26.5 (landed 2026-05-13), hence macOS 26.2+. gn gen can be forced with use_clang_modules=false + use_unified_system_module=false, but compilation fails on missing SDK symbols (posix_spawn_file_actions_addchdir). |
| 2026-08-10 | Blink layout classes are prefixed ng_ | STALE — prefix removed; block_layout_algorithm.cc, constraint_space.h. layout_ng.md doc remains. |
| 2026-08-10 | Chromium bugs live at bugs.chromium.org | STALE — now issues.chromium.org. In-tree docs/contributing.md still has the old reference. |
| 2026-08-10 | fetch --git-cache mirror lives in ~/.cache | FALSE — location is cache_dir in ~/chromium/.gclient; here ~/Library/Caches/depot_tools/git_cache. Roughly doubles peak disk. |
| 2026-08-10 | Blink's HTML fastpath accelerates document parsing | FALSE — TryParsingHTMLFragment is the fragment (innerHTML) path; bails out to the general algorithm on unsupported tags. |
| 2026-08-10 | BackgroundHTMLScanner == the old threaded HTML parser | FALSE — it runs on a worker thread scanning all body data for inline scripts to stream-compile; HTMLPreloadScanner is the main-thread, first-chunk preload scanner. Tree building remains main-thread. |
| 2026-08-11 | Blink keeps DOM/JS heaps in sync via wrapper tracing (TraceWrapperMember<T>) | STALE - deprecated, type removed. Blink uses V8's unified heap: Oilpan is cppgc, which lives in V8, so one collector traces both. Use Member<T> + TraceWrapperV8Reference<T>. Source: platform/bindings/TraceWrapperReference.md. |
| 2026-08-11 | css_properties.json5 declares per-property pipeline invalidation | Confirmed - invalidate: field. 822 property entries, 311 declare it. Distribution: 95 ["layout","paint"], 50 ["paint"], 34 ["layout"], 13 ["layout","scroll-anchor"], 4 ["compositing"], plus reshape, color, text-decoration, ax-style, transform-data. |
| 2026-08-11 | Blink HTML tokenizer/tree-builder size | Confirmed - 76 tokenizer states (html_tokenizer.h), 21 insertion modes (html_tree_builder.h). 7 of 21 modes are table-related; 3 are frameset. |
| 2026-08-11 | Chromium process-model vocabulary | Confirmed - SiteInfo (security principal), SiteInstance (principal instance, ~= agent cluster), BrowsingInstance (browsing context group), ProcessLock (enforcement). Source: docs/process_model_and_site_isolation.md. |
| 2026-08-11 | Blink scheduler policy constants | Confirmed - tasks deferred 2 s after a user gesture; mobile freezes background pages after 5 min; only JS timers are currently throttleable; ScopedPagePauser stops all JS during alert()/print()/breakpoints. Source: platform/scheduler/TaskSchedulingInBlink.md. |
| 2026-08-11 | Oilpan heap partitioning | Confirmed - Node, CSSValue, LayoutObject get typed custom spaces; collection backings get compactable spaces; concurrent marking+sweeping; GC scheduled via the message loop for precision. |
| 2026-08-11 | V8 has four execution tiers | Confirmed in-tree: v8/src/interpreter (Ignition), baseline (Sparkplug), maglev (Maglev), compiler (TurboFan). |
| 2026-08-11 | TestExpectations scale and policy | Confirmed - 9,418 lines. Results vocabulary [ Timeout Crash Pass Failure Skip ]. Policy: a bare [ Skip ] is not allowed; failing tests keep running on bots so flakiness data accrues. |
| 2026-08-11 | Paint architecture | Confirmed - PrePaintTreeWalk does paint invalidation + property-tree building; one PaintController per LocalFrameView; a PaintChunk is "sequential display items sharing a common property tree state"; caching at display-item and subsequence level. |
| 2026-08-11 | cc vocabulary | Confirmed - CompositorFrame = RenderPasses of DrawQuads + metadata; Layer main-thread only, LayerImpl compositor-thread; composited effects are done by modifying the active tree; ElementID is the stable cross-update identifier. |
| 2026-08-11 | Blink generated-input surface | Confirmed - 57 .json5 files under third_party/blink/renderer. runtime_enabled_features.json5 status vocabulary is exactly ["stable","experimental","test"], optionally per-platform. |
| 2026-08-11 | Trace categories are enumerable in-tree | Confirmed - base/trace_event/builtin_categories.h (~500 strings). In core/ alone: blink 204 uses, navigation 41, loading 20, input 17, devtools.timeline 4. |
| 2026-08-10 | fetch --git-cache chromium is the fast-checkout path on macOS | Confirmed — docs/mac_build_instructions.md |
| 2026-08-10 | Parser sources in third_party/blink/renderer/core/html/parser/ | Confirmed — 95 files incl. html_tokenizer.*, html_tree_builder.*, html_construction_site.* |
| 2026-08-10 | Foster parenting: HTMLConstructionSite::{FosterParent,FindFosterSite,ShouldFosterParent}, HTMLStackItem::CausesFosterParenting, HTMLTreeBuilder::ProcessStartTagForInTable | Confirmed against main |
| 2026-08-10 | Build targets //content/shell:content_shell, //:blink_tests, //third_party/blink/renderer/controller:blink_unittests | Confirmed via gn ls |
| 2026-08-10 | Style invalidation machinery: RuleFeatureSet, PendingInvalidationsMap, SelectorChecker::MatchSelector, Element::StyleForLayoutObject | Confirmed — core/css/style-invalidation.md, style-calculation.md |