Browser & Framework Internals

From component to pixel. A lab-based curriculum that removes the abstraction boundary between application code and what the screen actually does — Chromium and Blink internals, the rendering pipeline, and React/Vue/Redux-class runtimes rebuilt from scratch and then compared against production source.

Driven by browser-framework-internals.md, the specification.

Sibling project: ../frontend-principal-journey/ covers application- and organisation-level frontend engineering. Each builds and deploys as its own book; two of its modules are prerequisites here.

The learning loop

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

Two rules make it work:

  • Predictions are written before observation. A clearly-stated wrong prediction is worth more than a vague right one.
  • Source paths are never handed to you. State a hypothesis, search, confirm or falsify, and record the query that worked. Queries transfer between subsystems; paths rot — see PROGRESS.md §7, which logs six dated instances of exactly that.

Two strands, run in parallel

Browser bi-00 … bi-16 — navigating Chromium · architecture and the process model · HTML parsing · DOM internals · Web IDL and V8 · Chromium C++ · the CSS engine · layout · paint · the compositor and GPU · scheduling · debugging and tracing · tests and WPT · contribution · vertical traces · capstone.

Framework fw-01 … fw-12 — mini-redux · mini-react core · reactivity and signals · deriving Fiber · a Vue-like renderer · template and JSX compilers · a bundler · a router · a query cache · a virtualised list · production source apprenticeship · testing library and DevTools.

The framework strand is what fills the Chromium build's dead time. They join at the cross-layer vertical traces. Full plan: PHASES.md.

mini-browser/ is a spine, not a project: its 15 milestones are interleaved through bi-03 … bi-12, each built immediately before the Blink reading it motivates.

Module layout

bi-07-css-engine/
├── CONCEPTS.md            the explanation
├── references.md          primary sources first
├── docs/
│   ├── analysis.md        invariants, failure modes, what would falsify the model
│   ├── execution.md       the lab
│   ├── observation.md     predictions above the line, results below
│   ├── verification.md    checkpoints that must pass against measured output
│   └── broader-ideas.md   where this recurs in other systems
├── steps/                 ordered tasks with explicit "Done when" gates
└── src/                   runnable harnesses (specs given; implementations are yours)

A module is complete when its verification.md checkpoints pass against measured or observed output, not when its prose has been read.

Getting started

No Chromium build is required for the first two phases. Start with either:

Toolchain: TOOLS.md · Vocabulary: GLOSSARY.md · Tracker: PROGRESS.md

Building the book

bash build.sh                          # writes ./book and ./dist/book
mdbook serve                           # live reload on :3000
python3 ../tools/gen-summary.py browser  # regenerate SUMMARY.md after adding pages

SUMMARY.md is generated, not hand-maintained — ~290 links across 29 modules, where a mistyped one silently drops a page.

A standing rule

Every Chromium path, class name, command and flag here carries a date in PROGRESS.md §7. Re-verify anything older than about six months.

Writing this book turned up several widely-repeated facts that were already retired — the ng_ prefix on Blink layout classes, and TraceWrapperMember<T> for DOM/JS heap synchronisation among them. Both would have been asserted confidently from memory; each took under a minute to check in the tree.