Browser & Framework Internals

"Source reading answers what could happen. Tracing answers what did happen." — the rule that decides which instrument to reach for, earned in bi-12

A lab-based curriculum that removes the abstraction boundary between application code and pixels. It has one objective, stated as a question you should eventually be able to answer completely:

What happens after setCount(count + 1) — through the framework scheduler, the DOM, Blink's style and layout, paint, the compositor, and the GPU — and which of those stages are skipped, and why?

Everything else is instrumental to that.

How it is built

Two strands run in parallel, joining at the cross-layer traces:

  • Browser (bi-00 … bi-16) — Chromium's process model, the HTML parser, DOM internals, the V8 binding layer, the CSS engine, layout, paint, the compositor, scheduling, tracing, tests, and the contribution workflow.
  • Framework (fw-01 … fw-12) — a Redux, a React core, a signals runtime, a concurrent scheduler, a Vue-like renderer, compilers, a bundler, a router, a query cache and a virtualised list — each built before the production equivalent is read.

The framework strand exists partly to fill the Chromium build's dead time, which is measured in hours. Serialising the two adds months and delays every comparison the curriculum is built on.

Three rules

Predict before observing. Every lab asks for a written prediction first. A clearly-stated wrong prediction is worth more than a vague right one, and a prediction made after observation is worth nothing at all.

Build before reading. Derive a simplified version, break it, then use production source to discover the constraints that forced the extra complexity. Reading Fiber before deriving it produces recognition, not understanding.

Never memorise a path. State a hypothesis, search, confirm or falsify, and record the query that worked. In the course of writing this book two widely-repeated facts turned out to be retired — the ng_ prefix on Blink's layout classes, and TraceWrapperMember<T> for keeping the DOM and JavaScript heaps in sync. Both would have been asserted confidently from memory; each took under a minute to check in the tree. Every Chromium claim here therefore carries a date in PROGRESS.md §7.

What you need to start

Nothing but a browser. Phases 0–2 require no local Chromium build — source navigation, spec mapping, archaeology and tracing all work on stock Chrome plus a checkout, and treating the build as a gate is the standard way this track stalls. See TOOLS.md.

Start with bi-03 — HTML Parsing: predict four DOMs, then write a tree builder that agrees with the browser. The harness is in bi-03-html-parsing/src/, and it deliberately ships no expected output — the browser is the oracle, so you have to observe before you can check.

What you should be able to do at the end

Draw Chromium's processes and their trust boundaries · locate the implementation of any browser behaviour · explain HTML → DOM → style → layout → paint → compositing in implementation terms · determine whether a change triggers style, layout, paint or compositor work · trace a Web API from JavaScript through the bindings · set native breakpoints and read a cross-process trace · locate and modify browser-engine tests · connect implementation to specification · produce an upstream-quality Chromium change · and hold working implementations of a React-like runtime, a Vue-like reactive system, a Redux-like store, a router, a query cache, signals, a virtualised list and a compiler.

And, above all: explain not only how these systems work, but why their complexity exists — and which of it is essential, which is hardening, and which is accretion nobody has dared remove.