Frontend Principal Journey

This repository is also a book. Build it with bash build.sh (or mdbook serve for live reload) and read it at http://localhost:3000. Start with the Introduction, the Phases & Modules index, and Toolchain Setup.

Modules fe-01 … fe-06 are built and measured: 22 experiments drive a real browser over CDP, and every table in the book is regenerated by npm run all inside that module's src/. See PHASES.md for status.

A structured learning repository for developing from frontend foundations through Principal/Distinguished-level frontend and web platform engineering.

Two tracks run in parallel, each driven by a specification file and organised as numbered module directories.

frontend-principal-journey/
├── frontend-principal-engineering.md    # spec: broad frontend track
├── browser-framework-internals.md       # spec: systems-construction track
│
├── fe-00-roadmap/ … fe-NN-…/            # FRONTEND track modules
├── fe-00-roadmap/docs/progress.md       #   ← its tracker
│
├── bi-00-roadmap/ … bi-16-capstone/     # BROWSER INTERNALS track modules
├── fw-01-… … fw-12-…/                   #   framework-internals strand
├── mini-browser/                        #   the spine, threaded through bi-03…bi-12
└── PROGRESS.md                          #   ← browser/framework tracker

Each module directory contains CONCEPTS.md (the explanation), docs/ (execution steps, observations, verification checkpoints), and src/ (runnable code).

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

Track 1 — Frontend Principal Engineering

Spec: frontend-principal-engineering.md · Map: fe-00-roadmap/docs/curriculum-map.md · Tracker: fe-00-roadmap/docs/progress.md

Web foundations, JS/TS, HTML/CSS, React and framework architecture, state, APIs, networking, performance, accessibility, security, testing, design systems, platform engineering, build tooling, monorepos, microfrontends, rendering architectures, observability, reliability, CI/CD, i18n, mobile web, workers, WASM, migrations, ADRs, technical decision-making.

Track 2 — Browser & Framework Internals

Spec: browser-framework-internals.md · Map: bi-00-roadmap/CONCEPTS.md · Tracker: PROGRESS.md · Build guide: bi-00-roadmap/docs/chromium-build-debug-trace.md

Browser strand — navigating Chromium · architecture and process model · HTML parsing · DOM internals · bindings and V8 · Chromium C++ · CSS engine · layout · paint · compositor and GPU · scheduling · debugging and tracing · tests and WPT · contribution · vertical traces · capstone.

Framework strand — mini-redux · mini-react (core, then scheduling) · reactivity and signals · Vue-like renderer · compilers · bundler · router · query cache · virtualized list · production source apprenticeship · testing library and DevTools.

The two strands run in parallel and join at the vertical traces.

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 this 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 the verification log in PROGRESS.md §7 for dated evidence of exactly that.

How the tracks connect

Frontend Principal Engineering        Browser & Framework Internals
   architectural + org judgment          removes abstraction boundaries
              └──────────┬──────────────────────┘
                         ▼
                Principal Frontend SME

Cross-track sequencing is recorded in bi-00-roadmap/CONCEPTS.md §6 and fe-00-roadmap/docs/curriculum-map.md §2. It runs in both directions: the frontend track's execution-model module precedes Blink scheduling, while the internals track's mini-React precedes any reading about Fiber.

Shared across both tracks: learning-log.md (source readings, struggles, open questions) and decisions/ (ADRs).

Using this with coding agents

Browser/framework work: work from browser-framework-internals.md; continue the next bi- or fw- module; verify all Chromium paths, commands and class names against current upstream before relying on them, and log the result in PROGRESS.md §7.

Framework implementation: teach the conceptual model, implement a minimal version, then compare against production source. Never start from production source.

Application/platform work: work from frontend-principal-engineering.md; use the internals track only when underlying behaviour materially affects the topic.

Frontend Principal Engineering — Measured

"When advice is repeated confidently and cheaply, measure it before you design around it." — heuristic earned in Phase 1 of this curriculum

A lab-based curriculum for becoming the frontend subject-matter expert for a large engineering organisation. Every claim in it is measured in a real browser, and every measurement is reproducible with one command.

What makes this different

Most frontend curricula are prose. This one is a measurement harness with prose attached.

Twenty-two experiments drive Chrome for Testing 149 over the Chrome DevTools Protocol — forcing garbage collection, parsing heap snapshots, dumping the real accessibility tree, sampling the renderer's own style and layout accounting, and dispatching trusted keyboard input. Every table in every chapter came out of a script in that module's src/, and npm run all regenerates it.

That constraint produced results that contradict widely-repeated advice:

Each of those had a real effect somewhere, misremembered as a general rule. Learning to tell the difference is the actual curriculum.

The loop

Every module runs the same sequence, and the order is not negotiable:

Understand → Predict → Implement → Break → Debug → Measure → Compare → Explain

Predict is the load-bearing step. A prediction you get right needs no correction; a prediction you get wrong localises the defect in your model precisely. Every step file opens with a prediction you are asked to commit to in writing before running anything.

Measurement honesty

Three practices are enforced throughout, because performance work fails quietly:

Harness bugs are documented, not fixed silently. Every module hit at least one, and all produced clean, plausible, wrong data — a reused JavaScript realm that voided 39 of 40 trials, INP computed per-event instead of per-interaction, a shared page letting one variant's leak contaminate the next, shared inline-cache state that reported doubles as 4× faster than integers. They live in each module's docs/measured-results.md under "harness failure modes", because the reflex they teach outlasts any individual number.

Unexplained results stay unexplained. One measurement in fe-03 reproduced, had its leading hypothesis tested and rejected, and was then abandoned because the effect is 0.6 nanoseconds. It is recorded as an open question, not dressed up as a finding. Knowing when to stop investigating is the same judgement as knowing when to stop optimising.

Every module states what its numbers do not prove. One machine, one browser version, synthetic content, no network. The ratios transfer; the milliseconds do not.

How to use this book

1. Read Toolchain Setup — Node 18+ and a Chrome binary is the whole dependency list.
2. Read the Curriculum Map for the dependency graph and why the ordering is what it is.
3. Start at fe-01. Each module is self-contained:

fe-NN-<name>/
├── CONCEPTS.md          # the "why" and the mental model — read first
├── references.md        # specifications first; excluded sources named and justified
├── docs/
│   ├── measured-results.md  # every number, with the browser version
│   ├── analysis.md          # trade-offs, decision rules, what breaks at scale
│   ├── execution.md         # tool versions, quick start, method notes
│   ├── verification.md      # pass/fail checkpoints with expected output
│   ├── observation.md       # how to read the evidence, and its limits
│   └── broader-ideas.md     # where the mechanism reappears later
├── steps/               # predict → run → expected output → what just happened
└── src/                 # the experiments. `npm install && npm run all`

4. Do the Principal Engineer Review at the end of each module in writing. Several questions are about refusing work with arithmetic, which is most of the practical value.

Three tracks

Siblings, not stages. The frontend track develops judgment; the internals tracks remove abstraction boundaries. The measured-evidence discipline described above is fully applied to the fe- track so far; the bi- and fw- tracks share the structure and are at an earlier stage of that treatment.

Source of truth

This book is derived from two specification files, which remain authoritative:

• Frontend Principal Engineering — the 46-area curriculum spec
• Browser & Framework Internals — the sibling depth track

Where the book and the specifications disagree, the specifications win.

Phases & Modules

This repository holds three parallel tracks, all sharing the same module shape:

They are siblings, not stages. The frontend track develops judgment; the internals tracks remove abstraction boundaries. Cross between them when a topic genuinely stalls without the other — the hooks are enumerated in the Curriculum Map §2.

The phase structure below applies to the frontend track. The bi- and fw- tracks are ordered but not phased; see their own roadmap modules (bi-00, fw-01).

Seven phases, 51 modules, plus a continuous AI-assisted-engineering spine. The ordering is derived from real dependencies, not topic popularity — see the Curriculum Map for the dependency graph and the five load-bearing chains.

Legend: ✅ built & measured · 🟡 scaffolded · ⬜ planned

Phase 1 — Platform Substrate · Foundation → Senior

Before any abstraction, know what the abstraction is hiding.

Gate 1 → 2: predict execution order and rendering timing of unfamiliar async code unaided · find a leak from a heap-snapshot diff · read a waterfall and name the bottleneck class.

Phase 2 — Framework Mechanics · Senior

A framework is a scheduling and diffing policy with ergonomics attached.

Phase 3 — Architecture & Data · Senior → Staff

A frontend is a distributed system with a rendering engine attached.

Phase 4 — Quality Attributes · Staff

These are properties of the architecture, and they are measurable.

Phase 5 — Quality Engineering · Staff

Thousands of tests can still produce low confidence.

Phase 6 — Platform & Delivery · Staff → Principal

You stop building applications and start building the conditions under which others build them.

Phase 7 — Principal Judgment · Principal → Distinguished

The work is now decisions, influence, and being right about reversibility.

The spine — AI-assisted engineering

Specification areas §20–24 are not a phase. They run continuously from Phase 1, because deferring them means practising the workflows only after your judgement is good enough not to need practice. The governing rule: an agent may produce anything whose failure modes you can enumerate yourself.

Sibling tracks

Browser Internals (bi-00 … bi-16) — Chromium architecture, the HTML parser, DOM internals, the V8 binding layer, the CSS engine, layout, paint, the compositor, scheduling, tracing, Web Platform Tests, and the contribution workflow. Start at bi-00.

Framework Internals (fw-01 … fw-12) — build a Redux, a React core, a signals runtime, a concurrent scheduler, a Vue renderer, a template compiler, a bundler, a router, a query cache and a virtualised list, then read the production sources. Start at fw-01.

Both derive from Browser & Framework Internals and are tracked in PROGRESS.md.

Toolchain Setup

What you need, in the order you need it. Phases 0–2 of the browser track require no local Chromium build — that is deliberate, and it is what keeps the track moving while a 100 GB checkout and a toolchain upgrade happen in the background.

Tier 0 — needed on day one (zero cost)

That is enough for bi-01, bi-03, and all of fw-*.

DevTools settings worth changing once

• CPU throttling 4×/6× — unthrottled desktop results are not evidence about your users.
• Rendering panel: paint flashing, layer borders, scroll-performance issues, frame rendering stats.
• Performance panel: enable "Screenshots" and "Memory".
• Experiments: enable the timeline's advanced rendering instrumentation if offered.

Tier 1 — the checkout (large, but useful before it compiles)

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git ~/depot_tools
export PATH="$PATH:$HOME/depot_tools"          # add to ~/.zshrc
mkdir ~/chromium && cd ~/chromium
caffeinate fetch --git-cache chromium

Budget the disk honestly. Measured on the reference machine (2026-08-10):

The mirror location comes from cache_dir in ~/chromium/.gclient — it is not ~/.cache, and confusing the two sends you deleting the wrong thing. fetch --git-cache roughly doubles peak storage; the mirror is a cache and can be deleted once src is synced.

What the checkout gives you before it ever compiles

This is the part people miss. Without a working compiler you still get:

git grep -n 'CausesFosterParenting' -- third_party/blink/renderer/core/html/parser/
git log -S'mac_sdk_official_version = "26.5"' -- build/config/mac/mac_sdk.gni
git log --follow --oneline -- <file>          # survives the ng_* renames

git grep over 30M lines returns in well under a second — faster than Code Search — and git log -S is the archaeology tool the source-reading ladder depends on. Plus every in-tree document, every .json5, .idl, and .mojom.

Tier 2 — the build (needed from Phase 3)

cd ~/chromium/src
gn gen out/Default

out/Default/args.gn:

is_debug = false                    # release codegen: much faster builds
is_component_build = true           # small dylibs, fast incremental links — essential
symbol_level = 1                    # function names + lines
blink_symbol_level = 2              # full symbols where you set breakpoints
dcheck_always_on = true             # keep assertions: the highest-value learning flag

autoninja -C out/Default content_shell    # prefer this over `chrome`
gn ls out/Default | grep -E ':(content_shell|blink_tests)$'   # never guess target names

dcheck_always_on = true is the flag most people omit and the one that matters most for learning: DCHECKs are Blink's invariants written as executable assertions, so breaking one produces a message naming the invariant instead of a confusing misrender.

Known blocker on the reference machine

Chromium trunk requires macOS 26.2+ / Xcode 26.5+ / SDK 26.5 (the requirement landed 2026-05-13). On macOS 15.0 / Xcode 16.2 the build fails on missing SDK symbols such as posix_spawn_file_actions_addchdir, and no gn flag can fix it — __builtin_available is a runtime check but the symbol must exist at compile time.

Full diagnosis, the two gn workarounds that get gn gen through, and the ranked options are in the build guide §2.0.

Tier 3 — debugging and tests

echo "command script import ~/chromium/src/tools/lldb/lldbinit.py" >> ~/.lldbinit

Attach to a renderer, not the browser process:

out/Default/Content\ Shell.app/Contents/MacOS/Content\ Shell \
  --renderer-startup-dialog --disable-hang-monitor <url>
lldb -p <pid printed by the dialog>

--disable-hang-monitor matters: without it, sitting at a breakpoint for 30 seconds gets your renderer killed and you lose the state you were inspecting.

Tests:

autoninja -C out/Default blink_tests
third_party/blink/tools/run_web_tests.py -t Default fast/forms
out/Default/content_shell --run-web-tests <path>

Known failures live in third_party/blink/web_tests/TestExpectations (9,418 lines) — which is also your candidate pool for a first contribution.

Building this book

bash build.sh          # installs a pinned mdBook if absent, writes ./book and ./dist/book
mdbook serve           # live reload at http://localhost:3000
python3 tools/gen-summary.py   # regenerate SUMMARY.md after adding modules or steps

SUMMARY.md is generated, not hand-maintained: a module has up to 13 pages across ~35 modules, and a mistyped link silently drops a page from the book.

A standing rule

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

This is not pedantry. In the course of writing this book, two widely-repeated facts turned out to be retired — the ng_ prefix on Blink layout classes, and TraceWrapperMember<T> for DOM/JS heap synchronisation — and both would have been asserted confidently from memory. Each took under a minute to check in the tree.

Glossary

Terms used across all three tracks, with the precision the modules rely on. Where a definition is quoted or measured from the Chromium tree, the date is given — Chromium moves, and a stale definition is worse than none. See PROGRESS.md §7 for the verification log.

Browser architecture

Browser process — the privileged process. Owns UI, navigation, permissions, disk, cookies, and process allocation. Trusts nothing a renderer tells it.

Renderer process — sandboxed, hosts Blink and V8 for one or more same-site documents. Assumed to be compromised; this assumption generates most of Chromium's architecture.

GPU process — executes GL/Vulkan commands and runs the display compositor (viz). Isolated because graphics drivers are both fragile and a large attack surface.

Network service — owns sockets, TLS, and the HTTP cache. Renderers never hold a socket.

Blink — the rendering engine: HTML, DOM, CSS, style, layout, paint, events, Web APIs. Lives in third_party/blink/renderer. Not the same thing as "the renderer process".

V8 — the JavaScript and WebAssembly engine. A separate project. document is not a V8 concept; Node.js has V8 and no DOM.

cc — the compositor, in //cc. Runs in the renderer process, across the main thread and the compositor ("impl") thread. Not the GPU process.

viz — the display compositor, in the GPU process. Aggregates CompositorFrames from every renderer plus browser UI into the frame that is presented.

Mojo — Chromium's IPC system. A message pipe is a pair of endpoints; a .mojom file declares interfaces of messages; a Remote sends and a Receiver receives. Dispatch is a scheduled task, not a function call — ordering is guaranteed per pipe and not across pipes.

Associated interface — a Mojo interface sharing a pipe with a parent, which restores ordering between them. Seeing one usually means somebody was bitten by an ordering bug.

Process model (verified 2026-08-11, docs/process_model_and_site_isolation.md)

Site — scheme + eTLD+1 (https://example.com). Not an origin. a.example.com and b.example.com are the same site, because document.domain historically let them script each other synchronously.

SiteInfo — the security principal: what data an execution context may access.

SiteInstance — the principal instance, and the core unit of the process model. Any two documents with the same principal in the same browsing context group must share a process, because they have synchronous access to each other. Corresponds roughly (not exactly) to the HTML spec's agent cluster.

BrowsingInstance — the browsing context group: tabs and frames that can reach each other (window.opener, named targets, nested frames). rel="noopener" exists to keep a new page out of the group.

ProcessLock — the enforcement point. Restricts which sites may load in a RenderProcessHost and which data it may access. Granularity may be a site, an origin, a scheme, or "any site".

Site isolation — one renderer per site, including out-of-process iframes. Defends against a compromised renderer, not merely against script: after Spectre, "the data was never in that process" replaced "the checks stop it".

Rule of Two — code must not do all three of: process untrustworthy input, in an unsafe language, without a sandbox. Pick at most two. Explains most of Chromium's utility processes.

Rendering pipeline

Flat tree — the node tree with shadow content slotted in. Style and layout operate on this, not the node tree. Slot assignment does not change parentNode.

ComputedStyle — the fully-resolved property set for an element. Immutable and shared between elements that resolve identically; inline styles and unique selectors defeat the sharing.

RuleFeatureSet — the index built from stylesheets: for each feature (class, id, attribute, pseudo-class) it records what would need invalidating if that feature changed. Its entries are invalidation sets (descendant, sibling, nth, part/slotted), with a fallback to whole-subtree invalidation when precision is impossible.

invalidate: — a field in core/css/css_properties.json5 declaring, per property, which pipeline stage a change dirties. Measured 2026-08-11: 822 property entries, 311 declare it — 95 ["layout","paint"], 50 ["paint"], 34 ["layout"], 4 ["compositing"].

LayoutObject / LayoutBox — boxes participating in layout. Not one-per-element: display:none produces none, and anonymous boxes are synthesised.

ConstraintSpace — the immutable input to a layout algorithm (available size, fragmentation state, writing mode). Explicit inputs are what make layout results cacheable.

Fragment — an immutable geometry result. A box may produce several (pagination, multicol, inline splitting), which is why getClientRects() can return more than one rectangle.

Logical vs physical coordinates — layout thinks in inline/block, start/end; paint thinks in top/left. Code written physically breaks in RTL and vertical writing modes.

PrePaint — the phase that walks the layout tree to do paint invalidation and build paint property trees.

Display item — one recorded drawing command. Paint produces a recording, not pixels.

PaintChunk — "sequential display items that share a common property tree state". Change a property-tree node and the chunk's state changes while its contents do not — which is the entire transform/opacity fast path.

Property trees — four separate trees: transform, clip, effect, scroll. Separate so a scroll or a fade changes one node rather than re-recording the world.

Stacking context — an atomic unit of paint order. Created by opacity < 1, transform, filter, will-change, contain: paint, isolation, and others. Why opacity: 0.99 "fixes" z-index bugs.

Compositor (verified 2026-08-11, cc/README.md)

Layer / LayerImpl — the same concept on the main thread / the compositor thread. The type name tells you the thread.

Active tree — the layers and property trees used to submit a frame. Composited effects — scrolling, pinch, animation — are done by modifying the active tree, which is why they survive a blocked main thread.

Pending tree — the tree being rastered. Becomes active only when its tiles are ready, so half-rastered content is never shown.

CompositorFrame — a set of RenderPasses (lists of DrawQuads) plus metadata: instructions for drawing a scene, not pixels.

ElementID — a stable identifier across updates, used to attribute composited animations. The same role key plays in a reconciler.

Tile — a subdivision of a layer, rastered independently and prioritised by viewport proximity. Outrunning raster produces checkerboarding, which is deliberate: a consistent frame now beats a correct frame late.

Damage rect — the region that actually changed, so the GPU redraws only that.

Scheduling (verified 2026-08-11, platform/scheduler/TaskSchedulingInBlink.md)

Rendering opportunity — the point at which the browser runs rAF, observers, style, layout, paint, and commit. Not a task you can post.

Microtask checkpoint — drains the microtask queue exhaustively, including microtasks enqueued during the drain. Not a yield point: no rendering, no input.

Pausing — ScopedPagePauser enters a nested run loop during alert(), print(), or a debugger breakpoint. No JavaScript runs.

Deferring — tasks are deferred for 2 seconds after a user gesture, on the bet that another gesture is coming.

Freezing — background pages are frozen after 5 minutes on mobile; on desktop by heuristics based on which APIs the page uses.

Throttling — currently applies to JS timers only (setTimeout/setInterval).

INP — Interaction to Next Paint = input delay + processing + presentation. Two of the three terms are not your handler.

LoAF — Long Animation Frames API; reports long frames with blockingDuration and a scripts[] attribution.

Object lifetime

Oilpan — Blink's garbage collector, built on V8's cppgc. Heaps are per-thread; Node, CSSValue, and LayoutObject get dedicated typed spaces. Marking and sweeping are concurrent.

Unified heap — one collector tracing both the C++ and JavaScript heaps, which is what makes cross-heap cycles collectable. Supersedes "wrapper tracing"; TraceWrapperMember<T> no longer exists (verified 2026-08-11).

Member<T> / Persistent<T> / WeakMember<T> — graph edge / root from non-GC code / weak edge. An object's Trace() method is the authoritative list of what it keeps alive.

ActiveScriptWrappable — keeps an object alive while it has pending activity, because reachability alone would collect a pending XMLHttpRequest.

Wrapper — the JS object for a C++ DOM object. Created lazily, on first observation by script, and must be stable so expandos and === survive.

World (DOMWrapperWorld) — an isolated JS view of the same DOM, used for extension content scripts. Different wrappers, different expandos: a real security boundary.

Framework internals

Reconciliation — computing the minimal DOM operations between two descriptions of a UI.

Key — author-supplied identity for a list child. The runtime cannot infer it: [A,B,C] → [B,C] is ambiguous between "deleted A" and "renamed everything".

Fiber — an explicit, heap-allocated work-loop node (child / sibling / return) replacing the call stack, so render work can be paused, inspected, resumed, and discarded.

Render phase / commit phase — interruptible and side-effect-free / atomic and DOM-touching. Two statements of one requirement: discardable work must have done nothing, and output must be applied all at once.

Tearing — one render observing two different values of external mutable state. The reason useSyncExternalStore exists.

Glitch — a reactive system transiently computing a value from inconsistent inputs, e.g. a diamond a → b → d, a → c → d evaluated in the wrong order.

Invalidation set / dependency set — the same idea in a browser and in a reactive runtime: an index from "what changed" to "what must be recomputed".

Patch flag — a compiler-emitted annotation of which parts of a node can change, so the runtime skips comparisons. Compile-time knowledge substituting for runtime work.

Author-supplied guarantee — a promise the runtime cannot derive, which unlocks an otherwise impossible optimisation: key, {passive: true}, contain, sideEffects, aria-setsize, Origin-Agent-Cluster. This pattern recurs across every layer of the stack.

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)

Phase 1 — Parser, DOM, Bindings

Phase 2 — Style

Phase 3 — Layout & Paint

Phase 4 — Compositor, Scheduling, Debugging

Phase 5 — Compilers, Tooling, Production Source

Phase 6 — Tests, WPT, Contribution

Phase 7 — Capstone

2. Vertical trace ledger (§43)

Record the deepest layer genuinely resolved with evidence, not the deepest you can name.

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)

4. Contribution ladder (§24)

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

Source-code readings go in fe-00-roadmap/docs/learning-log.md §3.

6. Environment

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.

Concepts — The Frontend Principal Journey

1. What is it

A structured progression from platform fundamentals to Principal/Distinguished-level frontend and web-platform engineering, driven by frontend-principal-engineering.md (the specification). The specification lists 46 subject areas plus failure case studies, capstones, and heuristics. This module converts that list into an executable order: which subjects gate which, what can run in parallel, and what "done" means at each stage.

The unit of work is a numbered module directory (fe-NN-topic/) containing concepts, runnable source, step-by-step labs, verification checkpoints, and analysis. A module is complete when its verification checkpoints pass against measured output, not when its prose has been read.

2. Why it matters

Studied in specification order, the 46 areas look like 46 independent subjects. They are not, and treating them as independent produces three specific, expensive failures:

• Optimising symptoms. Performance engineering (§11) attempted before the execution model (§1) and rendering pipeline (§2) produces work that moves numbers without moving experience. The engineer cannot distinguish input delay from processing from presentation, so one fix gets applied to three different problems.
• Cargo-culted architecture. Microfrontends (§30) attempted before build tooling (§28), monorepos (§29), and design systems (§26) yields a distributed system built to solve a problem the organisation does not have. The specification asks the right question — "is this solving an organizational problem or a technical problem?" — and it is unanswerable without the prerequisites.
• Compliant, unusable accessibility. Accessibility (§12) attempted before semantic HTML (§3) produces ARIA-first interfaces that pass automated checks and fail real users.

The ordering is the deliverable. Anyone can enumerate topics; sequencing them against real dependencies is what makes the curriculum executable.

3. How it works

SPECIFICATION (46 areas, flat list)
  |
  v
+------------------------------------------------------------------+
|  CLUSTERING — 46 areas collapse into 8 groups by dependency       |
|                                                                   |
|   A Platform substrate     §1,2,3,4,10      <- root, gates all    |
|   B Framework mechanics    §5,6,40          <- needs A            |
|   C Architecture & data    §7,8,9,19,31     <- needs A+B          |
|   D Quality attributes     §11,12,13,36-39,41                     |
|   E Quality engineering    §14-18,25        <- needs a real system|
|   F AI-assisted eng.       §20-24           <- SPINE, not a phase |
|   G Platform & delivery    §26-30,32-35     <- needs C+D+E        |
|   H Principal judgment     §42-46           <- needs lived A-G    |
+------------------------------------------------------------------+
  |
  v
+------------------------------------------------------------------+
|  FIVE LOAD-BEARING CHAINS (see docs/curriculum-map.md)            |
|                                                                   |
|   1. Scheduling      event loop -> INP -> concurrent -> streaming |
|   2. Async correctness  promises -> races -> optimistic/rollback  |
|   3. Cache coherence    HTTP -> CDN -> ISR -> query invalidation  |
|   4. Semantics       DOM -> a11y tree -> design-system contract   |
|   5. Org topology    boundaries -> monorepo -> MFE -> governance  |
+------------------------------------------------------------------+
  |
  v
+------------------------------------------------------------------+
|  7 PHASES + CONTINUOUS AI SPINE                                   |
|                                                                   |
|   Phase 1  Platform substrate      fe-01 .. fe-08   Foundation    |
|   Phase 2  Framework mechanics     fe-09 .. fe-14   Senior        |
|   Phase 3  Architecture & data     fe-15 .. fe-21   Senior/Staff  |
|   Phase 4  Quality attributes      fe-22 .. fe-30   Staff         |
|   Phase 5  Quality engineering     fe-31 .. fe-37   Staff         |
|   Phase 6  Platform & delivery     fe-38 .. fe-45   Staff/Princ.  |
|   Phase 7  Principal judgment      fe-46 .. fe-51   Principal+    |
|                                                                   |
|   Each phase boundary = a promotion gate, not a checkbox          |
+------------------------------------------------------------------+
  |
  v
PER-MODULE LOOP (non-negotiable)
  Understand -> Predict -> Implement -> Break -> Debug -> Measure -> Compare -> Explain

The loop matters more than the content. A module read without the Predict and Break steps produces recognition, not capability — you will recognise the concept in a code review and be unable to derive its consequences under pressure.

4. Core terminology

5. Mental models

A dependency graph, not a syllabus. A syllabus is ordered by convenience; a dependency graph is ordered by necessity. When tempted to reorder, the test is not "does this interest me now" but "can I make an honest claim in this module without the prerequisite?" Microfrontends before build tooling fails that test; TypeScript alongside almost anything passes it.

Depth is earned per phase, not per topic. Every phase touches performance, accessibility, and testing — at the depth that phase can support. Accessibility in Phase 1 is semantic HTML; accessibility in Phase 4 is an engineering discipline with automation limits; accessibility in Phase 6 is a design-system contract with a CI gate. Same subject, three different competences.

The curriculum is a strangler migration of your own mental model. You already have working models for most of these subjects. The programme's job is incremental replacement — find where the existing model produces a wrong prediction, replace that piece, keep the rest running. This is why every module opens with prediction: a prediction you get right needs no replacement, and a prediction you get wrong localises the defect precisely.

Tutorial density falls as phases rise. The specification requires this explicitly: later phases must "increasingly resemble actual Principal Engineer work." Phase 1 has expected output blocks; Phase 7 has ambiguous situations, competing stakeholders, and no answer key.

6. Common misconceptions

1. "Finishing the modules completes a phase." False. Phases end at promotion gates, which are capabilities demonstrated on unfamiliar input. Completing every Phase-1 module while still unable to predict execution order of code you have not seen means Phase 1 is not complete.

2. "The AI content is a phase to get to." False, and this is the most common structural error. §20–24 are a spine applied from Phase 1. Deferring them means practising the workflows only after your judgment is good enough to not need practice.

3. "Parallel means simultaneous." Parallel-safe modules have no dependency edge between them; it does not follow that studying six at once is effective. Parallelism exists to remove false ordering constraints, not to license context-switching.

4. "The internals track must come first to understand the platform." False. The two tracks are siblings, not stages. Cross into browser-framework-internals.md when a frontend topic stalls without it — the hooks are enumerated in docs/curriculum-map.md §2 — and not on principle.

5. "Measured numbers are the point." False, and dangerous. Numbers are evidence for a claim; the claim is the deliverable. A module that produces a benchmark table without a stated conclusion, an explicit limit of what the numbers prove, and a decision that changed as a result, has produced decoration.

7. Interview talking points

• "I sequence frontend curricula by dependency, not by topic popularity. Performance engineering before the execution model produces engineers who can move a metric but can't tell input delay from presentation delay — that's three different fixes behind one number."
• "The question I ask about microfrontends is the specification's: is this an organisational problem or a technical one? If teams can't deploy independently for organisational reasons, Module Federation won't fix it and will add a distributed system to the list of things that can break."
• "I treat AI-assisted engineering as a cross-cutting practice, not a topic. The rule I hold is that an agent may produce anything whose failure modes I can enumerate myself — otherwise I'm outsourcing judgment, not leverage."
• "Promotion gates in my teams are capability demonstrations on unfamiliar input, not checklists — the difference between recognising a concept and deriving its consequences under pressure is exactly the Senior/Staff boundary."

8. Connections to other modules

• fe-01-execution-model-scheduling — the root of the scheduling chain; gates fe-11 (perf), fe-12 (concurrent rendering), fe-16/17 (server state and races), fe-21 (rendering architectures).
• browser-framework-internals.md — the sibling track. Cross-track hooks are enumerated in docs/curriculum-map.md §2. That track's own tracker is the repository-root PROGRESS.md; the two never claim progress on each other.
• docs/curriculum-map.md — the full map: dependency graph, all seven phases, parallelisation table, hard prerequisites, failure case-study schedule, and promotion gates.
• docs/progress.md — live status across all 51 modules and 12 case studies.
• docs/learning-log.md — continuity: struggles, open questions, source readings, verification log, and the heuristics-under-test table the specification requires.

References — Programme Design

Source specifications (this repository)

• frontend-principal-engineering.md — the authoritative curriculum specification
• browser-framework-internals.md — the sibling depth track
• README.md — track overview and intended agent usage

Engineering ladders and level definitions

• Dropbox Engineering Career Framework
• CircleCI Engineering Competency Matrix
• Rent the Runway Engineering Ladder
• Will Larson, StaffEng — staffeng.com — Staff archetypes and scope
• Tanya Reilly, The Staff Engineer's Path (O'Reilly, 2022)

Technical decision-making and architecture records

• Michael Nygard, Documenting Architecture Decisions
• adr.github.io — ADR templates and tooling
• Jeff Bezos, 1997 & 2015 shareholder letters — one-way vs two-way doors

Learning method

• Ericsson & Pool, Peak — deliberate practice; why prediction-before-verification works
• Bjork & Bjork, Making Things Hard on Yourself, But in a Good Way — desirable difficulties
• Hattie & Timperley, The Power of Feedback (Review of Educational Research, 2007)

Organisational topology (Phase 6–7 grounding)

• Skelton & Pais, Team Topologies (IT Revolution, 2019)
• Conway, How Do Committees Invent? (Datamation, 1968) — the original Conway's Law paper

Curriculum Map, Dependency Graph & Phase Plan

Derived from frontend-principal-engineering.md (source of truth) and browser-framework-internals.md (depth track). This file is navigation, not specification. If it conflicts with the spec files, the spec files win.

1. The map: 46 spec areas → 8 clusters

The spec lists 46 numbered areas plus failure case studies, capstones, heuristics and AI rules. Studied in spec order they look like 46 independent subjects. They are not. They collapse into 8 clusters with very different dependency behaviour.

The three things that are not clusters

• Failure case studies (12 listed incidents) — these are assessments, not content. Each one is scheduled against the phase that gives you the tools to solve it. See §5.
• Capstones (6 levels) — one per phase boundary. They are the promotion gate.
• Heuristics (10 listed) — the spec says "for every heuristic include counterexamples and limitations." That is a running exercise, tracked in learning-log.md, not a module.

2. Dependency graph

The real edges. A → B means "A must be solid before B is honest."

graph TD
  subgraph SUB["A · Platform substrate"]
    JS["§1 JS runtime<br/>event loop · closures · GC · object shapes"]
    BR["§2 Browser architecture<br/>processes · rendering pipeline · scheduling"]
    HTML["§3 HTML platform<br/>semantics · forms · web components"]
    CSS["§4 CSS architecture<br/>cascade · layout · containment"]
    NET["§10 Networking<br/>HTTP/2·3 · caching · CDN"]
    TS["§1b TypeScript<br/>structural typing · contracts"]
  end

  subgraph FW["B · Framework mechanics"]
    REACT["§5 React deep dive<br/>fiber · render/commit · hooks"]
    ALT["§6 Vue/Svelte/Solid/WC"]
    ALGO["§40 UI algorithms<br/>diff · LRU · virtualization"]
  end

  subgraph ARCH["C · Architecture & data"]
    APP["§7 App architecture"]
    STATE["§8 State management"]
    API["§9 API integration"]
    EDGE["§19 Unhappy path"]
    SSR["§31 SSR/SSG/ISR/islands"]
  end

  subgraph QA["D · Quality attributes"]
    PERF["§11 Performance"]
    A11Y["§12 Accessibility"]
    SEC["§13 Security"]
    I18N["§36 i18n"]
    MOB["§37 Mobile web"]
    WORK["§38 Workers"]
    WASM["§39 WASM"]
    BIGUI["§41 Large-scale UI"]
  end

  subgraph TEST["E · Quality engineering"]
    TSTRAT["§14 Test strategy"]
    UIT["§15 UI testing"]
    E2E["§16 E2E"]
    INT["§17 Integration"]
    VIS["§18 Visual regression"]
    QEP["§25 Org quality policy"]
  end

  subgraph PLAT["G · Platform & delivery"]
    DS["§26 Design systems"]
    FPE["§27 Platform engineering"]
    BUILD["§28 Build tooling"]
    MONO["§29 Monorepos"]
    MFE["§30 Microfrontends"]
    OBS["§32 Observability"]
    REL["§33 Reliability"]
    CICD["§34 CI/CD"]
    RELE["§35 Release engineering"]
  end

  subgraph PRIN["H · Principal judgment"]
    ADR["§42 ADRs"]
    DEC["§43 Decision making"]
    DEBT["§44 Technical debt"]
    MIG["§45 Migrations"]
    PSK["§46 Principal skills"]
  end

  JS --> BR
  JS --> REACT
  JS --> ALGO
  JS --> WORK
  BR --> REACT
  BR --> PERF
  BR --> A11Y
  HTML --> A11Y
  HTML --> CSS
  HTML --> REACT
  CSS --> PERF
  CSS --> DS
  NET --> API
  NET --> PERF
  NET --> SSR
  NET --> SEC
  TS --> API
  TS --> APP

  REACT --> APP
  REACT --> STATE
  REACT --> SSR
  ALGO --> BIGUI
  ALT --> APP

  APP --> STATE
  STATE --> API
  API --> EDGE
  STATE --> EDGE
  SSR --> PERF
  REACT --> SSR

  PERF --> OBS
  PERF --> BIGUI
  WORK --> BIGUI
  WORK --> WASM
  A11Y --> DS
  MOB --> PERF

  EDGE --> TSTRAT
  APP --> TSTRAT
  TSTRAT --> UIT
  TSTRAT --> E2E
  TSTRAT --> INT
  TSTRAT --> VIS
  UIT --> QEP
  E2E --> QEP
  INT --> QEP
  VIS --> QEP

  CSS --> BUILD
  BUILD --> MONO
  MONO --> MFE
  DS --> MFE
  DS --> FPE
  MONO --> FPE
  QEP --> CICD
  CICD --> RELE
  OBS --> REL
  RELE --> REL
  FPE --> MFE

  MFE --> ADR
  REL --> ADR
  FPE --> ADR
  ADR --> DEC
  DEC --> MIG
  DEBT --> MIG
  MIG --> PSK
  DEC --> PSK

The five load-bearing chains

Everything else is decoration around these. If you only get five things right:

1. Scheduling chain — event loop → task/microtask semantics → long tasks → INP → concurrent rendering → Suspense/transitions → streaming SSR → hydration cost. Rendering the heuristic "performance problems are often scheduling problems" legible.

2. Async-correctness chain — promises/cancellation → request lifecycle → server-state cache → race conditions → optimistic update + rollback → offline/conflict. This is where "stale response overwrites newer data" lives.

3. Cache-coherence chain — HTTP cache semantics → ETag/Cache-Control → CDN → SSR/ISR revalidation → query-cache invalidation → stale-while-revalidate UX. One concept, four layers, four different invalidation vocabularies.

4. Semantics chain — DOM → semantic HTML → accessibility tree → accessible name computation → focus management → a11y as a design-system contract → a11y CI gate. "Accessibility is architecture, not polish" is only true if you can walk this chain.

5. Org-topology chain — package boundaries → build graph → monorepo → independent deployability → microfrontends → governance → standardisation vs autonomy. "Frontend architecture frequently reflects organizational architecture."

Cross-track hooks into browser-framework-internals.md

Only cross when the frontend topic genuinely stalls without it:

3. Phases

Seven phases plus a continuous spine. Each phase ends in a capstone-shaped deliverable and a promotion gate. Depth target rises per phase; tutorial density falls per phase, per the spec's closing instruction.

Spine (continuous, from Phase 1 onward)

F · AI-assisted engineering (§20–24) + §46 writing practice Not a phase. Every module carries an AI-assisted exercise. The rule from the spec holds throughout: AI increases leverage, never replaces understanding. You may not use an agent to produce an artifact whose failure modes you cannot enumerate yourself.

Phase 1 — Platform Substrate

Spec areas: 1, 2, 3, 4, 10 · Level: Foundation → Senior Thesis: Before any abstraction, know what the abstraction is hiding.

Capstone 1 (Foundation): production-quality accessible responsive application, built with deliberately minimal framework surface. Budget-constrained.

Phase 2 — Framework Mechanics

Spec areas: 5, 6, 40 · Level: Senior Thesis: A framework is a scheduling and diffing policy with ergonomics attached. Prereq: fe-01, fe-02, fe-04, fe-05.

Deliverable: a written architectural comparison of three reactivity models with a measured micro-benchmark and an explicit statement of what the benchmark does not prove.

Phase 3 — Architecture & Data

Spec areas: 7, 8, 9, 19, 31 · Level: Senior → Staff Thesis: A frontend is a distributed system with a rendering engine attached. Prereq: Phase 2 + fe-07.

Capstone 2 (Intermediate): complex application with API integration, state management, full testing — built against an intentionally unreliable API.

Phase 4 — Quality Attributes

Spec areas: 11, 12, 13, 36, 37, 38, 39, 41 · Level: Staff Thesis: These are not features. They are properties of the architecture, and they are measurable. Prereq: Phase 3. fe-22 is the anchor; the rest parallelise heavily.

Capstone 3 (Senior): high-performance application with SSR, caching, observability, defended with numbers against a stated budget.

Phase 5 — Quality Engineering

Spec areas: 14, 15, 16, 17, 18, 25 · Level: Staff Thesis: Quality is an architecture problem. Thousands of tests can still produce low confidence. Prereq: Phase 3 (need a system worth testing) + fe-20 (need to know what to test for).

Deliverable: an organization-wide testing policy document with explicit confidence claims and explicit un-covered risk.

Phase 6 — Platform & Delivery

Spec areas: 26, 27, 28, 29, 30, 32, 33, 34, 35 · Level: Staff → Principal Thesis: You stop building applications and start building the conditions under which others build them. Prereq: Phases 4 and 5.

Capstone 4 (Staff): shared design system + frontend platform used by multiple applications.

Phase 7 — Principal Judgment

Spec areas: 42, 43, 44, 45, 46 + failure case studies + heuristics · Level: Principal → Distinguished Thesis: The work is now decisions, influence, and time horizons — and being right about reversibility. Prereq: Phase 6.

Capstone 5 (Principal): frontend architecture for dozens of teams — RFC, diagrams, budgets, testing strategy, observability, security model, a11y policy, migration strategy, CI/CD, DX, operational model.

Capstone 6 (Distinguished/SME): multi-year frontend platform strategy — standardisation, technology radar, migration roadmap, platform APIs, governance, org topology, adoption, build-vs-buy, measurable outcomes.

4. Parallelisation

Safe to study concurrently

Hard prerequisites — do not parallelise

Explicitly deferred (common temptation to start early)

• Microfrontends (§30) — the most requested, least ready topic. Deferred to Phase 6 on purpose.
• Design systems (§26) — feels like a Phase 1 topic. It isn't; it needs a11y, CSS architecture, versioning and governance to be real.
• State machines / DDD / clean architecture (§7) — Phase 3, and taught with its overengineering critique attached.

5. Failure case-study schedule

The 12 incidents from the spec, assigned to the earliest phase that gives you the tools to solve them honestly. Each runs under the spec's 7-question protocol.

Phase 7 re-runs all twelve, cold, in fe-51.

6. Promotion gates

You do not advance a phase by finishing modules. You advance by clearing the gate.

Learning Log

Continuity file. Append-only in spirit; prune only when something is genuinely resolved. Four sections: struggles, open questions, source readings, architecture decisions & revisits.

1. Concepts struggled with

Record the shape of the confusion, not just the topic. "Didn't get microtasks" is useless in three months. "Believed await yields to the event loop the way setTimeout does" is a diagnosis.

2. Open questions

Questions raised but not yet answered. A question that survives three modules is a signal — either it's genuinely hard, or the mental model underneath it is wrong.

3. Source-code readings

Per the spec's code-reading requirement and browser-framework-internals.md §44 (Source-Code Reading Ladder). Log what you read, what you were looking for, and what surprised you. The surprise column is the valuable one.

Verification log (browsers move; re-check anything older than ~6 months)

4. Architecture decisions & revisit queue

ADRs live in decisions/. This table is the index plus the revisit queue.

Decisions made

Revisit queue

Topics marked revisit in PROGRESS.md, with the reason and the trigger for revisiting.

5. Heuristics under test

The spec lists 10 Principal heuristics and requires counterexamples and limitations for each. Fill these in as you earn them — a heuristic with no counterexample is a slogan you haven't stress-tested.

Frontend Track — Progress

Track: Frontend Principal Engineering (frontend-principal-engineering.md). The PROGRESS.md at the repo root tracks the other track (browser-framework-internals.md). They run independently; this file never claims progress on that one. Cross-track hooks are listed in curriculum-map.md §2.

Current phase: 1 — Platform Substrate Current module: fe-07 — Networking (next). fe-01–fe-06 built and measured. Status: in progress — concept + mechanics verified empirically; lab strategies measured (see measured-results.md). Outstanding: learner-run failure lab (F1–F3) + Principal Review questions.

See curriculum-map.md for the full map, dependency graph and phase plan. See learning-log.md for struggles, open questions, source readings and the revisit queue. See decisions/ for ADRs written during the program.

Status values: todo · in progress · lab done · complete · revisit

Phase 1 — Platform Substrate (Foundation → Senior)

Gate 1→2: predict execution order + rendering timing of unfamiliar async code unaided · find a leak from a heap-snapshot diff · read a waterfall and name the bottleneck class.

Phase 2 — Framework Mechanics (Senior)

Phase 3 — Architecture & Data (Senior → Staff)

Phase 4 — Quality Attributes (Staff)

Phase 5 — Quality Engineering (Staff)

Phase 6 — Platform & Delivery (Staff → Principal)

Phase 7 — Principal Judgment (Principal → Distinguished)

Failure case studies

Concepts — Execution Model, Scheduling & the Rendering Pipeline

Phase 1 · Platform substrate · Specification areas §1 (event loop, microtasks, macrotasks, promises, async/await), §2 (browser scheduling, rendering pipeline). Gates §11 (performance), §5 (concurrent rendering), §8/§9 (server state and races), §31 (rendering architectures).

1. What is it

The execution model is the set of rules determining when JavaScript runs, when the browser is permitted to draw, and in what order queued work is serviced. It has three components:

• The event loop — a cooperative scheduler that services one task at a time, drains a microtask queue between tasks, and renders only at permitted points.
• The rendering pipeline — the fixed sequence (requestAnimationFrame callbacks → observer delivery → style → layout → paint → composite) that converts DOM and CSSOM state into pixels.
• The scheduling policy — how the browser prioritises competing work: input over compositor over default over idle, with dynamic policy changes under load.

These are not three subjects. They are one mechanism, and nearly every "performance problem", "race condition", and "why didn't it re-render" question in frontend engineering is a question about it.

2. Why it matters

Interaction to Next Paint is a scheduling metric. INP decomposes into input delay + processing + presentation. Two of the three terms are pure scheduling, and each has a different fix. A team optimising bundle size to fix an input-delay problem will work for a quarter and move nothing. Redirecting that work in one conversation requires this model.

Async correctness is an ordering claim. "Stale response overwrites newer data" — one of the twelve failure case studies in the specification — is the statement completion order is not issue order. Every fix (cancellation, sequence numbers, render-time guards) is a different answer to "which ordering guarantee do we actually need?" You cannot review that fix without knowing which guarantees the platform provides and which the framework invented.

Modern rendering architecture is applied scheduling. Concurrent rendering, transitions, Suspense, streaming SSR, partial hydration, islands, and Server Components are all strategies for breaking work into more, smaller tasks — or eliminating tasks entirely. Evaluating whether any of them is worth its complexity is impossible without the substrate. Teams routinely adopt concurrent features, observe no INP improvement, and conclude the features do not work; the actual cause is expensive work in an effect, which does not yield.

It is the arbitration a Principal owns. "Is this a network problem, a rendering problem, or a main-thread problem?" Senior engineers own their component. You own that answer across teams, and getting it wrong sends several engineers in the wrong direction for a sprint.

3. How it works

+==================================================================+
|  THE EVENT LOOP  (one main thread, cooperative, no preemption)   |
+==================================================================+

  while (browser is alive) {

    +----------------------------------------------------------+
    | 1. PICK ONE TASK                                          |
    |    from ONE of several prioritised task queues:           |
    |      input > compositor > default > best-effort/idle      |
    |    There is NO single global FIFO.                        |
    +----------------------------------------------------------+
                              |
    +----------------------------------------------------------+
    | 2. RUN IT TO COMPLETION                                   |
    |    No preemption. A 400ms task = 400ms frozen UI.         |
    |    No framework can change this from inside the task.     |
    +----------------------------------------------------------+
                              |
    +----------------------------------------------------------+
    | 3. DRAIN THE MICROTASK QUEUE — EXHAUSTIVELY               |
    |    including microtasks enqueued DURING the drain.        |
    |    Rule: runs whenever the JS execution context stack     |
    |          becomes empty (NOT merely "at end of task").     |
    |    An unbounded microtask chain never exits this step.    |
    +----------------------------------------------------------+
                              |
    +----------------------------------------------------------+
    | 4. IF THIS IS A RENDERING OPPORTUNITY:                    |
    |                                                           |
    |      requestAnimationFrame callbacks   <- BEFORE layout   |
    |               |                                           |
    |      ResizeObserver / IntersectionObserver delivery       |
    |               |            (may loop; deliberately drops  |
    |               |             rather than hanging)          |
    |      style  ->  layout  ->  paint  ->  composite          |
    |                                                           |
    |    ~16.7ms apart at 60Hz, ~8.3ms at 120Hz                 |
    +----------------------------------------------------------+
                              |
    +----------------------------------------------------------+
    | 5. IF TIME REMAINS BEFORE NEXT FRAME:                     |
    |    requestIdleCallback callbacks                          |
    +----------------------------------------------------------+
  }

The asymmetry that does all the work

An infinite setTimeout loop produces a hot CPU and a responsive page. An infinite queueMicrotask loop produces a tab that must be killed. Microtasks are not a queue you yield to; they are a hole you can fall into.

Measured (src/run-starvation.mjs, 400ms of work in 5ms slices, identical structure):

Where INP comes from

INP = input delay        (a task was already running when the user acted)
    + processing time    (your listeners)
    + presentation delay (style/layout/paint/composite to next frame)

4. Core terminology

5. Mental models

The one sentence. Anything between two task boundaries is invisible to the user and blocking their input. Every optimisation here is a variation on: make the gaps between task boundaries smaller.

Three clocks, never conflated.

1. Microtask boundary — consistency, no rendering, ~free.
2. Task boundary — the browser may render and process input; costs scheduling latency.
3. Frame boundary — ~16.7 ms at 60 Hz; the only clock the user perceives. Much confused performance work optimises clock 1 while the user experiences clock 3.

rAF is frame-relative, not fast. requestAnimationFrame is not "quicker than setTimeout". Its latency is your distance to the next rendering opportunity, and that distance is determined by what scheduled you. Measured: from inside a click handler, rAF fires at +2–7 ms and setTimeout(0) at +2.1–7.0 ms (rAF wins); from a plain script, rAF fires at +3–11 ms and setTimeout(0) at +0.0 ms (the timer wins). Input dispatch is scheduled immediately before the rendering steps — that is the entire explanation.

async does not mean "in the background". It is main-thread, cooperative, microtask-scheduled. An async function awaiting 200 already-resolved promises while doing work between them is one long task, and nothing renders during it.

Workers move computation, not data. The boundary is the cost. Structured clone is synchronous main-thread work proportional to payload size. Measured: an identical worker filtering 200k rows cost 1502 ms of clone when the dataset crossed per keystroke, and 4 ms when the dataset lived in the worker and only the query crossed. Same worker, same algorithm, 376× difference from one architectural decision.

6. Common misconceptions

1. "Microtasks yield to the event loop." They do not. The microtask queue must be empty before the browser may reach the rendering steps; a self-enqueueing chain never empties. Measured: microtask "chunking" produced 0 rendered frames, 8 long tasks, 865 ms TBT, 3× the INP of the naive baseline, and 5.5× the wall clock of task-based chunking. It reads like the careful version in code review and is a large regression.

2. "A microtask checkpoint runs at the end of each task." Close enough to be dangerous. The rule is when the JS execution context stack becomes empty. Measured across four dispatch paths — real click interleaves microtasks between listeners (L1 m1 L2 m2 L3 m3); el.click(), dispatchEvent, and el.click() inside a setTimeout all do not (L1 L2 L3 m1 m2 m3). The last case is its own task, which rules out "task vs script" as the discriminator. This is why tests driving UI with .click()/fireEvent have different semantics from real users.

3. "await costs three microtask ticks." Stale — that was pre-2019. Measured on Chrome 149: exactly one tick (sync A1 P1 A2 P2 A3 P3).

4. "setTimeout(fn, 0) fixes layout timing." It works by accident and breaks under load. You did not choose a phase of the frame cycle; you chose a coin flip whose bias depends on scheduling pressure. If you need to run before layout, that is rAF; after layout, ResizeObserver or double-rAF.

5. "Moving work to a worker makes it faster." Only if the data boundary is designed. A naive worker was the worst of seven strategies measured — worse than doing nothing on the main thread — because per-operation structured clone exceeded the computation being offloaded.

6. "Platform primitives are always preferable." A live counterexample to the specification's own heuristic: scheduler.yield() and a hand-rolled MessageChannel yield produced identical INP (32 ms), but the platform primitive took 3.4× the wall clock (1562 ms vs 466 ms), because its continuations are scheduled behind rendering. Correct default, real cost.

7. "Long tasks tell you what was slow." longtask attribution is famously poor (often just the containing frame). LoAF reports blockingDuration, renderStart, and a scripts[] array with per-script invoker and duration. Prefer LoAF where available.

7. Interview talking points

• "INP decomposes into input delay, processing, and presentation, and those are three different bugs with three different fixes. When a team shows me one INP number I ask which term dominates before I let anyone start optimising — in our own benchmark the dominant term moved between proc, pres, and delay across strategies solving the same problem."
• "Chunking work with await Promise.resolve() doesn't chunk anything. The microtask queue has to drain to empty before the browser can render, so a self-enqueueing chain never yields. We measured it: zero frames rendered over 400 ms, versus 48 for the same loop yielding via MessageChannel."
• "Whether to move work to a worker is a data-ownership decision, not a compute decision. Structured clone is synchronous main-thread cost. We measured a 376× difference between posting the dataset per keystroke and keeping it resident in the worker — same worker, same algorithm."
• "React's scheduler yields with MessageChannel rather than microtasks, deliberately: a microtask-based scheduler would have better total throughput and be useless for responsiveness. That design choice is the tasks-versus-microtasks asymmetry."
• "Layout thrashing is invisible in code review because the bug fits on one line — e.style.width = e.offsetWidth + 1 + 'px' is 98× slower across 800 elements than batching the reads and writes, with an identical final DOM."
• "requestAnimationFrame isn't faster than setTimeout; it's frame-relative. Its latency is your distance to the next rendering opportunity, which is set by whatever scheduled you. Input dispatch sits right before the rendering steps, which is why rAF beats a timer inside a click handler and loses to it in a plain script."

8. Connections to other modules

• fe-02-memory-model (next) — the other Phase-1 module gated only by this one. Retention and leaks are about what survives across tasks; this module establishes what a task is.
• fe-11-performance-engineering — hard prerequisite. Core Web Vitals, budgets, and quantitative claims are unreadable without INP decomposition.
• fe-12-concurrent-rendering — Suspense and transitions are scheduling abstractions; this module is the substrate they abstract over.
• fe-16 / fe-17 (server state, races) — "completion order is not issue order" starts here; cancellation, sequence numbers and render-time guards are the architectural answers.
• fe-21-rendering-architectures — hydration is the canonical long task. Partial hydration, islands, and RSC are all task-decomposition strategies.
• fe-28-workers-parallelism — the worker boundary economics measured here (s5 vs s6) generalise to the whole offload decision.
• browser-framework-internals.md §16 (Browser Scheduling), §5 (Rendering Pipeline) — cross only when you need to know why a queue priority exists, not merely that it does.

References — Execution Model, Scheduling & Rendering

Primary sources first. Where a secondary source is listed it is because it is unusually good, not because it is convenient.

Specifications (normative)

• WHATWG HTML Standard — §8.1.7 Event loops — task queues, "perform a microtask checkpoint", "update the rendering". The authoritative source; the update-the-rendering steps are shorter than expected and worth reading once in full.
• WHATWG HTML — Processing model — how a task queue is chosen. This is where "there is no global FIFO" is normative.
• WHATWG HTML — Queuing tasks — task sources.
• W3C Long Animation Frames API — LoAF, blockingDuration, script attribution.
• W3C Event Timing API — PerformanceEventTiming, interactionId, the 16 ms durationThreshold floor.
• WICG Scheduling APIs — scheduler.postTask, scheduler.yield, priority semantics.
• CSSOM View — offsetWidth etc. — why geometric reads force layout.

Explanatory (high quality)

• Jake Archibald, In The Loop (JSConf.Asia 2018) — still the best single explanation of tasks vs microtasks, and the origin of the listener-checkpoint example used in Step 1.
• Jake Archibald, Tasks, microtasks, queues and schedules.
• web.dev — Optimize INP
• web.dev — Optimize long tasks — the source of the "yield every ~5 ms" guidance.
• web.dev — Long animation frames API
• Chrome for Developers — Scheduler API
• Chrome for Developers — Avoid large, complex layouts and layout thrashing
• Paul Irish, What forces layout / reflow — the definitive list of layout-forcing properties.

Implementation / source

• Chromium: docs/ on the renderer main-thread scheduler; blink::scheduler::MainThreadSchedulerImpl — task queue priorities and policy transitions. Guided path in browser-framework-internals.md §16.
• React: packages/scheduler/src/forks/Scheduler.js — schedulePerformWorkUntilDeadline; why MessageChannel over microtasks and setTimeout.
• web-vitals library — src/onINP.ts is the reference implementation of interaction grouping. Read it if you intend to compute INP yourself; the grouping subtlety in docs/analysis.md is handled there.

Security-adjacent (why measurement is constrained)

• MDN — SharedArrayBuffer and cross-origin isolation
• web.dev — Why you need cross-origin isolation — COOP/COEP, Spectre, timer coarsening.

Deliberately excluded

Generic "JavaScript Event Loop Explained" posts. They are overwhelmingly derived from one another and a substantial fraction still assert the pre-2019 three-tick await behaviour, which Checkpoint 3 in docs/verification.md disproves in about four seconds.

Analysis

Deeper treatment of the decisions this module surfaces. Numbers cited are from measured-results.md unless stated.

Yield primitives compared

The setTimeout clamping detail matters: nested timers beyond depth 5 are clamped to 4 ms, so a setTimeout-based chunker silently caps at ~250 slices per second regardless of slice size. That alone makes it unsuitable for time-sliced work, before considering queue position.

Why isInputPending() is a trap

isInputPending() yields only when input is actually waiting, which maximises throughput. But rendering is not input. A loop that yields only for pending input can run for seconds without letting a frame through — responsive to clicks, visually frozen. Prefer a time-slice budget (yield every ~5 ms of work) which is insensitive to whether anyone happens to be clicking.

The throughput cost of responsiveness

Measured, 200k rows at 6× throttle: s3 (MessageChannel) and s4 (scheduler.yield) produce identical INP (32 ms, zero long tasks). Their filter wall-clock differs by 1.5–3.5× across runs, s4 always slower — its continuations are scheduled behind rendering by design.

This produces a predictable and legitimate conflict. An engineer will show a benchmark where yielding is 30 % slower and propose reverting. They are not wrong about their number. The resolution is to establish which number represents the user:

• A human is waiting for incremental feedback → responsiveness wins. Total time is invisible; unresponsiveness is not.
• A human is waiting for the completed result and nothing else → total time is the experience. Yielding makes it worse. Show a determinate progress indicator and do not yield.
• No human is waiting (background sync, prefetch, export) → total time wins outright, and you should be yielding only enough to not block interactions that might arrive.

The failure mode to avoid is deciding this by ideology in either direction. "Always yield" and "never yield" are both wrong; the question is who is waiting for what.

Worker offload economics

The naive worker (s5) was the worst of seven strategies — worse than doing the work synchronously on the main thread. It moved 200k rows across the boundary per keystroke: 1516 ms of structured clone versus 34 ms of actual compute. The resident worker (s6) does the same work with a 4 ms boundary cost and wins every column.

The decision rule that follows:

worker is worth it  ⟺  compute_cost  >  boundary_cost + scheduling_latency

where boundary_cost ≈ structured clone of everything crossing, EACH WAY, EACH CALL

Practical consequences:

• Ownership, not offload. Ask "where does this data live?" before "should this be in a worker?" If the dataset crosses per operation, you have built a slower program with more moving parts and a second failure surface.
• Transferables and SharedArrayBuffer change the arithmetic. ArrayBuffer transfer is O(1) rather than O(size), which is why binary-shaped workloads (image processing, parsing, columnar data) suit workers far better than object graphs do. SharedArrayBuffer requires cross-origin isolation (COOP + COEP) — a deployment constraint, not a code change.
• Structured clone cannot carry functions, DOM nodes, class identity, or cycles-with-identity. Payloads usually need reshaping, and that reshaping is itself main-thread cost.
• Latency floor. Even a trivial round-trip costs a task boundary each way. For sub-millisecond work, a worker is pure loss.

INP decomposition as a routing table

The benchmark produced at least three different dominant terms across seven implementations of one feature. This is the module's most transferable result, because organisations aggregate INP into a single dashboard number and then debate a single fix.

A Principal-level intervention here is usually organisational rather than technical: require the decomposition alongside the number in any performance report, so three teams with the same INP value stop being treated as having the same problem.

Harness failure modes

Both bugs found while building this module produced clean, plausible, entirely fake data. This is the characteristic failure of performance work and is worth internalising more than any individual result.

1. Realm reuse across trials. page.setContent() reuses the JavaScript realm. A top-level const b in trial 2 collides with trial 1's binding, the script throws Identifier 'b' has already been declared, no listeners attach, and the log reads empty — indistinguishable from "the event did not fire." 39 of 40 trials were silently void while the summary table looked orderly. Fixes: IIFE-wrap every page script; assert harness liveness before each trial (loadTrial() throws if window.__log is missing).

2. Per-event instead of per-interaction INP. One keystroke emits keydown, keypress and keyup sharing an interactionId. Taking the longest single event reports processing: 0 even for a fully synchronous handler, because the longest event is keydown, which does no work. Taking the span from first start to last end reports ~250 ms for everything, because it swallows the inter-keystroke gap. Correct: group by interactionId; latency is the longest event's duration; processing is summed across the group.

Both bugs pointed in the right direction while being quantitatively meaningless — the most dangerous kind of wrong, because the conclusion survives review even though the number does not.

Rule: a measurement harness needs its own failing test before you trust a single number from it. Deliberately break the thing being measured and confirm the harness notices.

What breaks at scale

• Third-party scripts you cannot modify. A vendor SDK responsible for the majority of long tasks is a scheduling problem with no code fix available to you. Options, in ascending blast radius: load it lazily after the critical interaction path; move it behind a facade that loads on intent; sandbox it in a worker or iframe; negotiate a contractual performance requirement; remove it. The technical work is the easy part.
• Yielding interacts badly with transactional state. Every yield is a point where the DOM, application state, and the user's intent can all change. A chunked operation that mutates shared state across yields needs the same discipline as a concurrent program: either a consistent snapshot taken before the first yield, or explicit revalidation after each one. This is where naive chunking introduces correctness bugs while fixing performance ones.
• Frameworks yield; your effects do not. React can time-slice rendering. It cannot time-slice 200 ms of parsing inside useEffect. Teams adopt concurrent features, observe no INP change, and conclude the features do not work. The measurement that settles it is the dominant column: framework-level yielding moves pres, and does nothing for proc in an effect.
• Timer coarsening and cross-origin isolation. performance.now() is deliberately coarsened and SharedArrayBuffer requires COOP+COEP — both Spectre mitigations. Your measurement precision and your worker architecture are both constrained by a security decision the application cannot opt out of.
• Background tabs. Timers are throttled aggressively in hidden tabs, rAF stops entirely. Any chunked job that assumes it keeps running when the user switches tabs will silently stall. Use visibilitychange explicitly rather than discovering this from a support ticket.

Execution Guide

Tool versions

playwright-core deliberately ships no browser binaries. src/lib/browser.mjs resolves one in this order:

1. $CHROME environment variable, if set
2. newest chromium-NNNN in ~/Library/Caches/ms-playwright (or ~/.cache/ms-playwright)
3. a system Chrome/Chromium in the usual install locations

If none is found it fails with instructions rather than silently using a different engine.

Version sensitivity. Several findings here are version-dependent — scheduler.yield() availability, LoAF support, and await tick cost have all changed within recent memory. Record the version with any result you keep. docs/measured-results.md states the version used for every number in this module.

Quick start

cd fe-01-execution-model-scheduling/src
npm install                 # playwright-core only, ~1 package
npm run ordering            # experiments A, B, C  (~40s)
npm run starvation          # experiment D          (~5s)
npm run layout              # experiment E          (~5s)
npm run frame-timing        # experiment F          (~10s)
npm run benchmark           # the 7-strategy lab    (~90s)

Or everything in sequence:

npm run all

Manual (browser) labs

Two labs are run by hand in a real browser, because the point is what you observe:

npm run serve               # http://localhost:8080

web/bugs.js holds the failure lab (F1–F3) and is loaded from the console; see steps/05-failure-lab.md.

Tuning the benchmark

All parameters are environment variables:

ROWS=50000    npm run benchmark    # smaller dataset — find the worker crossover
THROTTLE=1    npm run benchmark    # no CPU throttling (see warning below)
THROTTLE=20   npm run benchmark    # low-end device simulation
REPS=5        npm run benchmark    # more repetitions, tighter medians
QUERY=zulu    npm run benchmark    # different selectivity
TRIALS=100    npm run ordering     # more ordering trials
WORK_MS=2000  npm run starvation   # longer starvation window
COUNT=3000    npm run layout       # more elements to thrash

Throttling is not optional for meaningful results. THROTTLE=1 on a modern laptop produces numbers that describe your laptop, not your users. The default of 6× approximates a mid-tier phone. Every table in this module was produced at 6×.

Reproducibility notes

• The dataset uses a seeded PRNG, so row contents are identical across runs and machines.
• Keystrokes are dispatched through CDP as trusted input events, not dispatchEvent — which matters here specifically, because synthetic dispatch changes microtask interleaving (experiment B).
• The benchmark reports medians of REPS runs. Single runs vary by 30–50 % on the wall-clock columns; the ratios between strategies are the durable finding, not the absolute milliseconds.
• Headless frame pacing is not real display pacing. Treat the jank column as directional.

Cleaning up

Nothing is installed globally and no state persists outside src/node_modules.

rm -rf src/node_modules

Observation Guide

How to read the evidence — in the scripts' output, and in DevTools on a real application.

Reading the benchmark output

 strat | strategy             | longTasks |  TBT | jank | INP p75 | INP max | dominant | filter | boundary |  wall
 s0    | sync handler         |         0 |    0 |    5 |      56 |      64 |     pres |    222 |        0 |  2098
 s2    | microtask-chunked    |         8 |  836 |    8 |     184 |     184 |     pres |   1192 |        0 |  3067
 s6    | worker, resident     |         0 |    0 |    0 |      24 |      24 |    delay |     79 |        4 |  1838

Read dominant before anything else. It routes you to a fix class:

• proc → your handler does too much. Split it: acknowledge visually now, defer the rest.
• pres → DOM volume, style recalc, forced layout, or paint. Look at containment and how many elements you invalidate.
• delay → something else was running when the user acted. The fix is often nowhere near the interaction you are measuring.

Healthy vs unhealthy signals

Healthy:

• longTasks: 0, TBT: 0 during interaction
• INP max under 200 ms; under 100 ms if the interaction is a keystroke
• boundary under ~20 ms for any worker strategy
• filter within ~2× of the unchunked baseline — you are paying a little for responsiveness

Unhealthy, and the specific diagnosis:

• longTasks > 0 with a chunked strategy → your yield is not a task boundary (this is s2)
• boundary in the hundreds or thousands → you are cloning your dataset per operation (this is s5)
• filter many times the baseline with no INP improvement → pure overhead; revert
• INP fine but jank high → the interaction is responsive but an animation is not; look at compositor-vs-main-thread properties
• Every strategy shows the same dominant term → your workload is not exercising what you think

DevTools: the six things to look at

Run npm run serve, open /lab.html, DevTools → Performance, CPU: 6× slowdown, record while typing.

1. Main thread flame chart. Find the input event task. Split it into scripting vs rendering (style/layout) vs painting. Most engineers assume scripting dominates; in the 200k-row lab the render half is frequently larger. Check before optimising.

2. Interactions track. Each interaction appears as a bar with its three phases. This is the dominant column, visually. The whisker before the bar is input delay — if it is long, the cause is outside the handler.

3. Forced reflow warnings. DevTools flags forced synchronous layout with a red triangle and gives you the causing stack. Induce one deliberately (run-layout.mjs's thrash path) so you know what the marker looks like before you need to find one under pressure.

4. User Timing track. performance.mark/measure around your filter and render show up as their own lane. Instrument both separately — the point is to find out whether your intuition about the split was right.

5. LoAF vs longtask. In the console:

   new PerformanceObserver(l => l.getEntries().forEach(e =>
     console.log(e.duration, e.blockingDuration, e.scripts?.map(s => [s.invoker, s.duration]))
   )).observe({ type: 'long-animation-frame', buffered: true });
   

   longtask tells you that something blocked. LoAF tells you which script, plus renderStart and blockingDuration. Prefer LoAF whenever it is available.

6. Compositor confirmation. With paint flashing / Layers on, confirm a transform animation keeps running during a long task — then change it to animate left and watch it stop. That contrast is the threading model made visible, and it is the fastest way to explain "animate transform, not position" to a team that thinks it is a style preference.

Reading starvation.html by hand

Open /starvation.html and click each button while watching frames drawn.

• The red square keeps spinning during both runs. This is not a bug. It is a CSS animation on transform, running on the compositor thread, which the blocked main thread cannot stop. It is the single best demonstration in the module that "the page looks alive" and "the page is responsive" are different claims — and why a spinner is a terrible liveness indicator.
• Try selecting text or scrolling during the microtask run. Scrolling may still work (compositor); text selection will not (main thread).
• The frames drawn counter is rAF-driven, therefore main-thread-driven, therefore honest.

What these measurements do not tell you

State this explicitly whenever you present numbers from this module:

• One machine, one browser version. The ratios transfer; the milliseconds do not.
• Headless frame pacing is not display pacing. The jank column is directional.
• Synthetic CPU throttling is not a real slow device. It scales CPU but not memory bandwidth, GPU, storage, or thermal behaviour. A real mid-tier phone will be worse in ways 6× does not model.
• A single filter workload. Selectivity, row size, and render cap all change the balance between filter and render, and therefore which term dominates.
• No network. Everything here is local compute. Real interactions usually have a request in them, which adds a whole failure surface this module does not touch (that is fe-17/fe-18).

M01 — Measured Results

All numbers produced on Chrome for Testing 149.0.7827.55 (arm64 macOS), driven by playwright-core over CDP. Scripts live in ../src/ (run-ordering.mjs, run-starvation.mjs, run-layout.mjs, run-frame-timing.mjs, run-benchmark.mjs) and are reproducible with npm run all. Reproduce before trusting: browsers move, and several of these numbers are version-sensitive.

Ordering results: 40 trials each, 100 % stable. Lab results: median of 3 runs, 6× CPU throttling via Emulation.setCPUThrottlingRate, 200 000-row dataset, 8 trusted keystrokes (november) at 150 ms intervals.

A. Prediction Challenge 1 — ordering

Two things move: the microtasks (B, C, H) and D vs E. Different mechanisms.

B. Microtask checkpoint vs. 3 listeners on one element

The discriminator is not "task vs script" and not "trusted vs synthetic." The setTimeout case is its own task and still shows no interleaving. The rule is the spec's: a microtask checkpoint runs when the JS execution context stack becomes empty. Browser- initiated dispatch has an empty stack between listeners; script-initiated dispatch has your frame still on the stack.

C. await tick cost

sync A1 P1 A2 P2 A3 P3 P4 P5 P6

await null costs exactly one microtask tick — A1 interleaves with P1, A2 with P2. (Pre-2019 this was three ticks; blog posts asserting that are stale.)

D. Microtask "chunking" does not chunk — 400 ms of work, 5 ms slices

Identical structure, identical slice budget, same total time. One renders 48 frames; the other renders nothing. This is the tasks-vs-microtasks asymmetry in one table.

E. Forced synchronous layout — 800 elements

98× . Same work, same elements, same final DOM. Only the ordering changed.

F. Why D and E swap order

Neither primitive changed speed. Input dispatch is scheduled immediately before the rendering steps, so a rAF registered inside a click handler is microseconds from running, while the timer task waits for the frame to finish. A script running at an arbitrary point in the cycle is typically far from the next rendering opportunity, so the timer — already ready — wins easily.

The spec guarantees nothing about D vs E. The observed order is a function of where in the frame cycle the initiating task sits.

Lab — five strategies (+2 controls), 200k rows, 6× CPU throttle

Worst-interaction decomposition (ms):

The four results that matter

1. s2 is worse than doing nothing. Microtask "chunking" produced 8 long tasks, 865 ms of blocking, 3× the INP of the naive baseline, and 5.5× the filter time of s3. It added the full cost of chunking (clock polling, loop restructuring) and bought none of the benefit. A code reviewer who sees "chunked with await" and approves it has shipped a regression that looks like an optimisation.

2. s5 vs s6: the worker is not the win — the boundary is. Same worker, same algorithm, same compute (33 ms vs 80 ms off-thread). s5 posts 200 000 objects per keystroke: 1502 ms of structured clone, on the main thread, which is exactly what a worker was supposed to avoid. s6 keeps the data resident and posts an 8-byte string: 4 ms. 376× difference in boundary cost, from one architectural decision.

3. s3 vs s4: same INP, 3.4× the wall clock. Both hit 32 ms INP with zero long tasks. scheduler.yield() took 1562 ms of elapsed filter time against s3's 466 ms, because its continuations are scheduled behind rendering rather than ahead of it. Whether that is a win depends entirely on whether anything is waiting for the result. This is the trade-off from the module made concrete — and note that s4's jank-frame count (17) is the worst of the non-pathological strategies.

4. The dominant INP term moves between strategies. s0 is proc-bound, s1/s2/s5 are pres-bound, s3 is delay-bound. Three different diagnoses, three different fixes. A team with a single "INP is bad" dashboard cannot tell these apart, and will apply one fix to all of them.

Harness bugs found while building this — keep them

Both produced clean, plausible, entirely fake data. This is the failure mode of performance work.

1. page.setContent reuses the JS realm. A top-level const b in trial 2 collides with trial 1's, the script throws Identifier 'b' has already been declared, no listeners attach, and the harness reports an empty log — indistinguishable from "the event didn't fire." 39/40 trials were silently void. Fix: IIFE-wrap page scripts, and assert the harness is alive before every trial.
2. INP is per interaction, not per event. One keystroke emits keydown+keypress+keyup sharing an interactionId. Taking the longest single event reports processing: 0 for a fully synchronous handler, because the longest event is keydown, whose own processing is empty. Taking the span from first start to last end instead reports ~250 ms for everything, because it swallows the inter-keystroke gap. Correct: group by interactionId, latency = longest event's duration, processing = sum across the group.

Rule this establishes: a measurement harness needs its own failing test before you trust a single number it produces. Both bugs above pointed the right direction while being quantitatively meaningless — the most dangerous kind of wrong.

Verification Checkpoints

A checkpoint passes on observed output, not on having read the explanation. Where a range is given, the range is the pass condition — exact milliseconds are machine-specific.

Reference environment: Chrome for Testing 149.0.7827.55, arm64 macOS, 6× CPU throttle.

Checkpoint 1 — Event ordering is stable and differs by dispatch path

npm run ordering

=== A. EVENT ORDERING (40 trials each) ===
  real click    40/40   A F B C G H D E
  .click()      40/40   A F G B C H E D

Pass: both rows are 40/40 (or ≥ 38/40), and the two orders differ. Fail — both identical: your page script is not IIFE-wrapped, or you are dispatching both cases the same way. Fail — any (empty) row: the harness is broken. loadTrial() should have thrown; if it did not, window.__log is being clobbered. Do not interpret any other number until this is green.

Checkpoint 2 — The microtask checkpoint follows stack emptiness

=== B. MICROTASK CHECKPOINT vs 3 LISTENERS ON ONE ELEMENT ===
  real trusted click       : L1 m1 L2 m2 L3 m3
  el.click() from script   : L1 L2 L3 m1 m2 m3
  dispatchEvent from script: L1 L2 L3 m1 m2 m3
  el.click() in setTimeout : L1 L2 L3 m1 m2 m3

Pass: row 1 interleaves; rows 2–4 do not. The row that matters is the fourth. It is a genuine separate task and still does not interleave — which is what rules out "task boundary" as the explanation and leaves stack emptiness as the only one standing.

Checkpoint 3 — await costs one microtask tick

=== C. `await` TICK COST ===
   sync A1 P1 A2 P2 A3 P3 P4 P5 P6

Pass: A1 appears immediately before P1, A2 before P2 — strict interleaving. Fail — A1 appears after P3: three ticks per await. You are on a pre-2019 engine, or reading a transpiled build where async/await was downleveled to generators. Check what your bundler targets before concluding anything about the platform.

Checkpoint 4 — Microtask chunking renders nothing

npm run starvation

  yield primitive              | frames rendered | slices | wall clock
  -----------------------------|-----------------|--------|-----------
  await Promise.resolve()      |               0 |     80 | 400ms
  MessageChannel postMessage   |              49 |     80 | 404ms

Pass: the microtask row is exactly 0 frames; the task row is > 20. Slice counts and wall clock are within a few percent of each other — that equality is the point, because it proves the two runs did the same amount of work. Fail — microtask row > 0: your yield is not actually a microtask (an await on a real promise that resolves from a timer is a task in disguise).

Checkpoint 5 — Forced synchronous layout is catastrophic and invisible

npm run layout

  interleaved read -> write, per element    | 86.2ms
  batched: read all, then write all         |  0.3ms
  287x difference.

Pass: ratio ≥ 50×. Absolute values vary widely by machine; the ratio does not collapse. Fail — ratio near 1: the compiler eliminated your reads, or the elements are not in the layout tree (display:none ancestors make offsetWidth free). Confirm the elements are rendered.

Checkpoint 6 — rAF latency is frame-relative

npm run frame-timing

Pass: in the el.click() in script rows, setTimeout(0) fires at ~+0.0 ms while rAF fires at +3 to +12 ms — a decisive, repeatable gap. In the real trusted click rows, both fire within a fraction of a millisecond of each other and the winner column flips between runs.

The near-tie is the finding, not noise. It shows that inside a click handler the rAF callback and the frame boundary are effectively the same moment, which is why nothing is guaranteed. If you see a stable winner in the real-click rows, check your margins before claiming a rule.

Checkpoint 7 — The strategy benchmark reproduces its shape

npm run benchmark

Pass — all seven rows present, page errors: none, and these relationships hold (absolute values will differ):

Fail — s4 identical to s3 in every column: scheduler.yield() is unavailable and silently fell back. The header line reports this; check it. Fail — s5.boundary near 0: the dataset is too small for clone cost to register. Raise ROWS. Fail — all INP values 0: no interaction was recorded. Event Timing clamps durationThreshold to a 16 ms floor; on a fast machine with a small dataset every interaction falls below it. Raise ROWS or THROTTLE.

Checkpoint 8 — The decomposition table shows different dominant terms

  strat | input delay | processing | presentation
  s0    |           1 |         27 |           55
  s2    |           0 |        157 |          184
  s6    |           1 |          1 |            0

Pass: the dominant term is not the same for every strategy.

This is the checkpoint with the most transfer to real work. Seven implementations of one feature produce at least three different dominant INP terms. A team looking at a single aggregate INP number cannot distinguish them and will apply one fix to three different problems.

Module completion

All eight checkpoints pass, and:

• steps/05-failure-lab.md F1–F3 diagnosed from evidence before reading the notes
• F2 reproduced deterministically (forced response ordering), not just observed
• Three fixes implemented for F2 and ranked, with the server-side-effect case answered
• Written answers to the Principal Review questions in steps/06-principal-review.md
• ../fe-00-roadmap/docs/learning-log.md updated: any prediction you got wrong, recorded as the shape of the confusion rather than the topic

Broader Ideas

Where this module's mechanism reappears later in the programme, and what it explains.

Hydration is the canonical long task

Server-rendered HTML paints quickly (good LCP), then hydration attaches handlers and rebuilds client state — classically as one uninterruptible task. The result is a page that looks interactive and is not, which is the single most common cause of a good-LCP/bad-INP profile.

Every mitigation is a task-decomposition strategy, and this module lets you evaluate them from first principles rather than by reputation:

The last row is the one teams get wrong: streaming improves time-to-first-byte-of-content and does nothing for hydration cost. If your dominant INP term is proc, streaming will not move it. Picked up properly in fe-21-rendering-architectures.

React's scheduler as a worked example

packages/scheduler/src/forks/Scheduler.js — read schedulePerformWorkUntilDeadline. It prefers MessageChannel over both microtasks and setTimeout, for exactly the reasons measured here: a microtask-based scheduler would have better total throughput and be useless for responsiveness, and setTimeout is clamped and queued behind everything. It is the tasks-versus-microtasks asymmetry, chosen deliberately by people who had to live with the consequences.

Worth reading in source rather than in a blog post, and worth logging in ../fe-00-roadmap/docs/learning-log.md §3. Followed up in fe-09 (Fiber, render vs commit) and fe-12 (concurrent rendering as scheduling).

Debounce is not a race fix

A debounced input reduces the number of in-flight requests. It changes nothing about ordering. If request N returns after request N+1, the user sees results for a query they already replaced — the "stale response overwrites newer data" incident from the specification's case-study list.

The three fixes are not equivalent, and ranking them is the seam into fe-17:

For a read, any of the three works and the ranking is about efficiency. For a request with a server-side effect, only cancellation is safe, and even then only if the server honours it — which is why idempotency keys exist and why this becomes a distributed-systems conversation in fe-18.

Scheduling as an accessibility concern

Long tasks are not neutral across users. Focus movement queues behind the blocked main thread, so a keyboard user pressing Tab gets no response and — unlike a mouse user — has no hover feedback confirming the app is alive. Screen-reader users additionally suffer from aria-live regions updated per chunk, which floods the announcement queue. The correct pattern is announcing start and completion, not progress.

prefers-reduced-motion interacts here too: a rAF-driven busy animation must be suppressible, which means the jank canary from this module's labs is a debugging tool, not a production spinner. Developed in fe-24-accessibility.

The compositor as an architectural boundary

The red square in starvation.html keeps spinning through a completely blocked main thread, because it animates transform on the compositor. This is worth generalising: "the page looks alive" and "the page is responsive" are independent claims, and most loading indicators assert the first while users care about the second.

The corollary is the threading rule behind "animate transform, not left" — it is not a style preference, it is which thread owns the animation. And it is why a single non-passive wheel or touchstart listener hands your scroll performance to your worst long task: the compositor must ask the main thread whether preventDefault() will be called. Picked up in fe-11 and fe-27-mobile-web.

Scheduling shows up in test infrastructure

Experiment B has a direct consequence for testing: .click() and fireEvent do not interleave microtasks between listeners, while real user input does. A test suite driving UI synthetically has different semantics from production. If any listener's correctness depends on another's promise having settled, the suite is structurally incapable of catching it.

The mitigation is knowing which of your tests use real input (Playwright's page.click() goes through CDP and is trusted) versus synthetic dispatch (Testing Library's fireEvent; userEvent is closer but still synthetic). Developed in fe-32 and fe-33.

Scheduling as an SLO

Once you can decompose INP, you can argue about which metric an organisation should commit to. INP is user-centric but lagging and sparse; Total Blocking Time is lab-measurable and leading but does not reflect real interaction patterns. The mature position is to pair them: a field metric for truth and a lab metric for CI gating, with the explicit acknowledgement that the lab metric is a proxy. Developed in fe-43-observability and fe-44-reliability.

Step 1 — Event Ordering and the Microtask Checkpoint

Goal

Predict the execution order of async code without running it, then discover the rule that makes the prediction correct. Establish that the microtask checkpoint follows stack emptiness, not task boundaries.

Prerequisites

• Node 18+; npm install in src/
• Read CONCEPTS.md §3 (How it works) and §5 (Mental models)

Predict first — do not run anything yet

Write your answers down. The value of this step is the diff between prediction and result; if you run it first, there is no diff and no learning.

<button id="b">Go</button>
<script>
const b = document.getElementById('b');

b.addEventListener('click', () => {
  console.log('A');
  Promise.resolve().then(() => console.log('B'));
  queueMicrotask(() => console.log('C'));
  requestAnimationFrame(() => console.log('D'));
  setTimeout(() => console.log('E'), 0);
  b.style.background = 'red';
  console.log('F', b.offsetHeight);
});

b.addEventListener('click', () => {
  console.log('G');
  Promise.resolve().then(() => console.log('H'));
});
</script>

1. Log order when a human clicks the button.
2. Log order when the page runs b.click() from a top-level script. If your answer differs from (1), state the mechanism. If it does not differ, state why not.
3. When does the button actually turn red — relative to which log line?
4. D vs E: which fires first? Separate what the specification guarantees from what Chrome will typically do, and name the condition that flips it.
5. One line in that handler is more expensive than it looks. Which, and what does it cost?

Run

cd src
npm run ordering

Expected output:

=== A. EVENT ORDERING (40 trials each) ===
  real click    40/40   A F B C G H D E
  .click()      40/40   A F G B C H E D

=== B. MICROTASK CHECKPOINT vs 3 LISTENERS ON ONE ELEMENT ===
  real trusted click       : L1 m1 L2 m2 L3 m3
  el.click() from script   : L1 L2 L3 m1 m2 m3
  dispatchEvent from script: L1 L2 L3 m1 m2 m3
  el.click() in setTimeout : L1 L2 L3 m1 m2 m3

=== C. `await` TICK COST ===
   sync A1 P1 A2 P2 A3 P3 P4 P5 P6

What just happened

Two things moved between the two orderings, for unrelated reasons. Most explanations conflate them; keeping them separate is the whole point of this step.

The microtasks (B, C, H) moved because the checkpoint rule is:

A microtask checkpoint runs when the JavaScript execution context stack becomes empty.

"At the end of a task" is a consequence of that rule in the common case, not the rule. Experiment B isolates the real variable across four dispatch paths. The fourth row is decisive: el.click() inside a setTimeout is a genuine separate task and still does not interleave — so "task vs script" cannot be the explanation. When the browser dispatches, nothing of yours is on the stack between listeners, so the stack empties and the checkpoint fires. When you dispatch, your calling frame stays on the stack and every microtask queues behind it.

Consequence for testing (previews fe-32/fe-33): a suite driving UI with .click() or fireEvent runs listeners without microtask interleaving. Real users get interleaving. If any listener's correctness depends on another's promise having settled, the suite is structurally incapable of catching it. That is not flakiness — it is a harness with different semantics from the runtime.

The red background appears after E — after every log line. style.background mutates the CSSOM; it does not paint. Painting happens in the rendering steps, which cannot run until the task ends and the microtask queue drains.

D vs E is not a property of the primitives — see Step 1b below.

b.offsetHeight is the expensive line. You wrote to style.background on the previous line, invalidating style; reading a geometric property demands a correct answer immediately, forcing style recalculation and layout synchronously, inside your handler. One read is cheap; the pattern is not. Quantified in Step 3.

await costs one microtask tick, not three. The three-tick figure is pre-2019 and still widely repeated. This is why the module keeps a verification log — platform facts rot.

Step 1b — why D and E swap

npm run frame-timing

Expected output (abridged):

  dispatch path        | rAF fired at | setTimeout(0) fired at | winner
  real trusted click   |       +5.4ms |                 +5.6ms | tie (<0.5ms)
  real trusted click   |       +6.1ms |                 +6.1ms | tie (<0.5ms)
  el.click() in script |      +10.4ms |                 +0.1ms | timeout
  el.click() in script |       +6.4ms |                 +0.0ms | timeout

Read the margins, not the winner column. Neither primitive changed speed.

• Real click: both fire within a fraction of a millisecond, because input dispatch is scheduled immediately before the rendering steps — the rAF callback and the frame boundary are effectively the same moment. Which one "wins" is decided at sub-millisecond margins. It is reproducible on one machine and guaranteed by nothing.
• Script click: the timer wins decisively (~0.0 ms vs 5–12 ms). A plain script runs at an arbitrary point in the cycle, usually far from the next rendering opportunity, so the already-ready timer task runs immediately.

The generalisation: requestAnimationFrame is not fast or slow. Its latency is your distance to the next frame, and that distance is set by whatever scheduled you. This is why setTimeout(fn, 0) "fixes" a layout-timing bug on your machine and breaks under load — you did not choose a phase of the frame cycle, you chose a coin flip whose bias depends on scheduling pressure.

Checkpoint

docs/verification.md Checkpoints 1, 2, 3, 6.

Record

Any prediction you got wrong goes in ../fe-00-roadmap/docs/learning-log.md §1 — as the shape of the confusion, not the topic. "Didn't get microtasks" is useless in three months. "Believed the checkpoint runs at task boundaries, which predicts interleaving for setTimeout(() => el.click()) — it does not" is a diagnosis.

Step 2 — Does "Chunking" Actually Chunk?

Goal

Establish, by measurement, that microtask-based chunking creates zero rendering opportunities — and feel the difference in a real browser before seeing the number.

Prerequisites

• Step 1 complete
• npm install in src/

Predict first

Two loops. Same 400 ms of work, same 5 ms slices, pausing between every slice. The only difference is how they pause:

const yieldMicro = () => Promise.resolve();                       // A
const yieldTask  = () => new Promise(r => { resume = r;           // B
                          channel.port2.postMessage(0); });

Both pause constantly. Write down: how many frames does each render in 400 ms?

Run it by hand first

cd src
npm run serve       # http://localhost:8080/starvation.html

Click the left button (await Promise.resolve()), watch frames drawn. Then the right button (postMessage).

While the left run is going:

• Try selecting this text. Try scrolling.
• Watch the red square. It keeps spinning. That is not a bug — it is the most useful thing on the page.

Then measure

npm run starvation

Expected output:

=== D. MICROTASK vs TASK CHUNKING (400ms of work, 5ms slices) ===
  yield primitive              | frames rendered | slices | wall clock
  -----------------------------|-----------------|--------|-----------
  await Promise.resolve()      |               0 |     80 | 400ms
  MessageChannel postMessage   |              49 |     80 | 404ms

What just happened

Zero frames. Not "fewer frames" — zero. The specification requires the microtask queue to be empty before the browser may proceed to the rendering steps. A loop that re-enqueues itself is never empty, so the rendering steps are never reached. You did not yield; you built a queue that refills faster than it drains.

The slice counts and wall clocks are nearly identical (80 vs 80, 400 ms vs 404 ms). That equality is what makes this a controlled experiment: both runs did the same work, in the same number of pieces, in the same time. Only the rendering differs.

The red square is the lesson most worth keeping. It animates transform, which runs on the compositor thread, which a blocked main thread cannot stop. So during a total main-thread freeze the page still looks alive.

Two consequences:

1. A spinner is a terrible liveness indicator. "The page looks alive" and "the page is responsive" are independent claims, and most loading UI asserts the first while users care about the second.
2. This is the threading rule behind "animate transform, not left". It is not a style preference — it decides which thread owns the animation. The same mechanism explains why one non-passive wheel listener hands your scroll performance to your worst long task: the compositor must ask the main thread whether preventDefault() will be called.

Scrolling may have worked during the freeze; text selection did not. Scroll is compositor; selection is main thread. You just observed the thread boundary directly.

Checkpoint

docs/verification.md Checkpoint 4.

Going deeper

WORK_MS=3000 npm run starvation     # longer freeze — watch the tab become unkillable-feeling

Then ask: during the microtask run, can you open DevTools? Can you set a breakpoint? What does that tell you about where DevTools' own UI runs?

Step 3 — Forced Synchronous Layout

Goal

Quantify the cost of interleaving layout reads and writes, and learn to recognise the pattern in code that looks entirely ordinary.

Prerequisites

• Step 1 complete (you met b.offsetHeight there)

Predict first

Two loops over 800 elements. Identical work, identical final DOM:

// A
for (const e of els) e.style.width = (e.offsetWidth + 1) + 'px';

// B
const widths = els.map(e => e.offsetWidth);
els.forEach((e, i) => { e.style.width = (widths[i] + 1) + 'px'; });

Write down: how much slower is A than B? Commit to a number, not "somewhat".

Run

cd src
npm run layout

Expected output:

=== E. FORCED SYNCHRONOUS LAYOUT (800 elements, median of 5) ===
  pattern                                  | time
  -----------------------------------------|--------
  interleaved read -> write, per element    | 86.2ms
  batched: read all, then write all         |  0.3ms

  287x difference. Identical work, identical final DOM.

The ratio varies by machine and element count; on the reference machine it ranged from 98× to 287× across runs. Anything above ~50× is the same phenomenon.

What just happened

Each style.width write invalidates layout. Each offsetWidth read demands a geometrically correct answer right now, so the browser must run style recalculation and layout synchronously before returning — inside your loop, outside the rendering steps.

Interleaved, you pay N layouts. Batched, you pay one. You wrote code that looks O(n) and executes O(n) layouts, each of which is itself proportional to the document.

Why this matters more than the number suggests: the bug fits on one line, and the line reads as completely normal code.

e.style.width = e.offsetWidth + 1 + 'px';

There is no await, no loop-in-a-loop, no obviously expensive call. Code review does not catch this by inspection — it is caught by knowing which properties force layout, or by DevTools' forced-reflow warning.

Layout-forcing properties (partial): offsetWidth/Height/Top/Left, clientWidth/Height, scrollWidth/Height/Top, getBoundingClientRect(), getComputedStyle() (for most properties), focus(), scrollIntoView(), innerText. Paul Irish's list in references.md is the complete one and is worth bookmarking rather than memorising.

The general rule: batch reads, then batch writes. If a library forces you to interleave (many measurement-driven layout libraries do), that is a real architectural cost of the library and belongs in the evaluation.

Debugging exercise

npm run serve      # http://localhost:8080/lab.html

DevTools → Performance, CPU 6× slowdown, record while the thrash path runs.

1. Find the red triangle forced-reflow warning. Read the stack it blames.
2. Confirm the total time is dominated by Layout, not Scripting — this is the case where the flame chart contradicts the intuition that "JS is the slow part."
3. Now record the batched version. The Layout blocks collapse to one.

Induce this deliberately now, while you have a working example. You want to recognise the marker before you need to find one under production pressure.

Checkpoint

docs/verification.md Checkpoint 5.

Going deeper

COUNT=3000 npm run layout

Is the ratio stable as N grows, or does it worsen? Explain the answer in terms of what each forced layout costs relative to document size — and what that predicts for a 100k-row table (fe-30).

Step 4 — The Strategy Benchmark

Goal

Compare seven scheduling strategies for one feature under identical conditions, and produce a written recommendation that states what the numbers do not prove.

Prerequisites

• Steps 1–3 complete
• npm install in src/

Predict first

Seven implementations of a filter over 200,000 rows, driven by 8 real keystrokes at 6× CPU throttle:

Rank them for INP before running. Separately, rank them for total wall clock. If your two rankings are identical, you have probably not understood the trade-off yet.

Run

cd src
npm run benchmark          # ~90 seconds

Expected output:

 strat | strategy             | longTasks |  TBT | jank | INP p75 | INP max | dominant | filter | boundary |  wall
 s0    | sync handler         |         0 |    0 |    5 |      56 |      64 |     pres |    222 |        0 |  2098
 s1    | async, unchunked     |         0 |    0 |    4 |      56 |      64 |     pres |    221 |        0 |  2096
 s2    | microtask-chunked    |         8 |  836 |    8 |     184 |     184 |     pres |   1192 |        0 |  3067
 s3    | MessageChannel 5ms   |         0 |    0 |    0 |      32 |      32 |     pres |    957 |        0 |  1920
 s4    | scheduler.yield()    |         0 |    0 |   16 |      32 |      32 |     proc |   1358 |        0 |  1913
 s5    | worker, naive        |         8 |  913 |    8 |     200 |     200 |     pres |     34 |     1516 |  3148
 s6    | worker, resident     |         0 |    0 |    0 |      24 |      24 |    delay |     79 |        4 |  1838

Absolute numbers vary. The relationships in docs/verification.md Checkpoint 7 are the pass condition.

What just happened

s2 is worse than doing nothing. 8 long tasks, 836 ms of blocking, 3× the INP of the naive baseline, and ~5× the filter time. It paid the entire cost of chunking — clock polling, loop restructuring, a lost tight loop — and received none of the benefit, for the reason established in Step 2.

This is the most important row, because s2 passes code review. It reads as await-ing between chunks with a time budget: the careful version. A reviewer without this model approves a large regression labelled as an optimisation.

s5 vs s6: the worker is not the win — the boundary is. Same worker, same algorithm, comparable off-thread compute (34 ms vs 79 ms). s5 posts 200,000 objects per keystroke: 1516 ms of structured clone, synchronously, on the main thread — precisely what the worker was supposed to avoid. s6 keeps the data resident and posts a string: 4 ms.

A ~380× difference in boundary cost from one architectural decision. "Move it to a worker" is not an optimisation; it is a data-ownership decision. And note s5 is worse than s0 — a naive worker is worse than no worker.

s3 vs s4: identical INP, very different throughput. Both reach 32 ms INP with zero long tasks. scheduler.yield() takes 1.5–3.5× the filter wall clock, because its continuations are scheduled behind rendering by design. This is a genuine counterexample to the specification's own heuristic "prefer platform primitives" — correct default, real cost. Record it in the heuristics table in ../fe-00-roadmap/docs/learning-log.md §5.

The dominant column moves. Across seven implementations of one feature you should see at least three different dominant terms. This is the most transferable result in the module: an organisation with a single aggregate INP dashboard cannot distinguish these, and will apply one fix to three different problems.

Answer in writing

Create RESULTS.md in this module directory:

1. Which strategy has the best INP? Which has the best total time? Are they the same? Explain the gap in terms of the event loop — not "it's faster."
2. Find the dataset size at which s5 stops losing to s0. Use ROWS= to search for it. What dominates below the crossover?
3. Change the s3 slice budget from 5 ms to 50 ms, then to 0.5 ms. Both are worse, for different reasons. Name both.
4. What do your numbers not prove? Be specific. This is the section a Principal Engineer is graded on, and docs/observation.md §"What these measurements do not tell you" is the starting point, not the answer.

Optional: implement them yourself

src/web/lab.html has the same seven strategies as TODO stubs with the harness pre-wired (instrument.js). Implementing s2 yourself — after predicting its behaviour — is the single most effective exercise in this module. Serve with npm run serve.

Checkpoint

docs/verification.md Checkpoints 7 and 8.

Step 5 — Failure Lab

Goal

Diagnose three seeded failures from evidence, before reading any explanation. Two of them are realistic production incidents; one is on the specification's failure case-study list.

Prerequisites

• Steps 1–4 complete

Setup

cd src
npm run serve      # http://localhost:8080/lab.html

Open the console and load the bugs:

await import('./bugs.js');

Do not read the notes at the bottom of web/bugs.js until your written diagnosis is done.

F1 — The frozen tab

Bugs.f1()

A "progress-friendly" chunked implementation using recursive queueMicrotask. The tab freezes. No error, no crash dialog, CPU at 100 %.

Predict before running:

• Does the rAF-driven counter stop?
• Can you get a useful Performance recording?
• Can you break in with the debugger?
• Does the tab recover on its own?

Then run it and explain precisely why "chunking" changed nothing. You already have the mechanism from Step 2; this step is about recognising the symptom without knowing the cause in advance.

Corresponds to: specification failure case study "rendering loop freezes browser."

F2 — The stale overwrite

Bugs.f2()

A debounced search against an endpoint with randomised 50–800 ms latency. Typing a query then correcting it intermittently leaves the results showing the old query's results — roughly 1 run in 6.

This is the specification's "stale response overwrites newer data" incident.

Your tasks

1. Reproduce it deterministically. Bugs._f2.fakeFetch.forceOrder([300, 60]) forces the first request slow and the second fast, guaranteeing out-of-order completion.

   If your reproduction is "type fast a few times," you have observed it, not reproduced it. The difference is the difference between a fix and a hope — and it is the difference between a regression test that holds and one that flakes.

2. Name the violated invariant in one sentence.

3. Implement three fixes:

   • AbortController cancellation
   • a request sequence number (last-write-wins on issue order)
   • a render-time guard comparing the response's query against current state

4. Rank them and defend the ranking. All three "work" for a read.

5. Which is correct when the request has a server-side effect? This question is the seam into fe-17 (races, cancellation, idempotency) and fe-18 (API integration as a distributed system). A partial answer is fine here; a stated partial answer is the point.

Note on the debounce

The debounce reduced the number of in-flight requests. Establish for yourself what it did to the ordering guarantee. This is the trap the incident depends on.

F3 — The invisible progress bar

Bugs.f3()

A loop updating progressBar.style.width on every iteration of a 5,000-item job. The bar jumps 0 % → 100 % with nothing in between, and the whole job is slower than the version with no progress bar at all.

Two symptoms. Two different causes. Explain both, then fix it so the bar animates smoothly and the job finishes faster than the original.

You have both mechanisms already — one from Step 2, one from Step 3. This step tests whether you can select the right one from a symptom rather than recognise it from a heading.

Debugging exercise

For each failure, produce written answers to the specification's incident protocol:

1. What do you investigate first?
2. What evidence do you need?
3. What hypotheses exist?
4. What experiments distinguish them?
5. What mitigation is appropriate?
6. What permanent fix is appropriate?
7. What systemic change prevents recurrence?

Question 7 is the Principal-level one, and it is where most incident reviews stop short. For F2, "we added a guard" is a fix; "our data-fetching layer makes unordered responses unrepresentable, and the lint rule catches raw fetch in components" is a systemic change.

Testing considerations

Turn F2 into a regression test that cannot flake:

await page.route('**/search*', async (route) => {
  const q = new URL(route.request().url()).searchParams.get('q');
  await new Promise(r => setTimeout(r, q === 'nov' ? 300 : 60));   // force N after N+1
  await route.fulfill({ json: { query: q, results: [`results for "${q}"`] } });
});

Controlling response ordering explicitly converts a probabilistic bug into a deterministic test. That conversion is the whole game, and it recurs throughout fe-33.

Note also, from Step 1: assert on counted invariants (requests issued per N keystrokes; final rendered state matches the last query), never on wall-clock durations. Shared CI runners have order-of-magnitude variance, and a duration assertion will be deleted within a month — correctly.

Checkpoint

Module completion in docs/verification.md requires F1–F3 diagnosed from evidence, F2 reproduced deterministically, and the three F2 fixes ranked.

Step 6 — Principal Engineer Review

Answer in writing. These are judgment questions: several have defensible answers on more than one side, and "it depends" is only acceptable if you say on what.

Questions 4, 5 and 10 are no longer hypothetical — you generated the data for them in Step 4.

1. A team reports INP regressed from 180 ms to 450 ms after a release that "only changed CSS." Give three mechanisms by which a CSS-only change can regress INP. Which single piece of evidence distinguishes them fastest?

2. An engineer proposes a codebase-wide lint rule banning setTimeout(fn, 0). Make the strongest case for the rule, then the strongest case against. What do you actually do, and what does your answer depend on?

3. Your platform team wants to ship a shared chunkWork() utility to 40 teams. Specify its API. What must it not let callers do? What happens when a caller passes a callback that itself awaits a network request — and does your API make that mistake representable?

4. A senior engineer benchmarks your chunked data transform, finds it 28 % slower in total wall clock, and wants to revert. You measured exactly this in Step 4 (s3 vs s4, s0 vs s3). Walk through how you handle it — the technical argument and the fact that they are right about their number. Under what circumstances should you agree with them?

5. Two proposals for a 100k-row table: (a) virtualize on the main thread with time-sliced rendering; (b) move filtering and sorting to a Web Worker and keep rendering naive. Your s5/s6 result is directly relevant. What does each optimise? What workload makes each the wrong choice? What would you measure before choosing — and what would you do if you could not get that measurement in time?

6. Your organization wants a single frontend performance SLO. Argue for INP over Total Blocking Time as the primary SLI, then argue the reverse. Which do you adopt, and what second metric do you pair it with to cover the first one's blind spot?

7. React's scheduler yields with MessageChannel rather than microtasks or setTimeout. Reconstruct that decision from first principles: what does each of the three options cost, and what breaks if you swap it for the other two?

8. When is the correct engineering decision to have a long task — to deliberately refuse to yield? Give a concrete scenario and state the invariant that yielding would violate.

9. A third-party SDK you cannot modify, and that Legal requires, causes 60 % of your long tasks. Enumerate your options in order of blast radius. Which do you propose, and how do you get agreement?

10. Someone claims: "Concurrent React fixes our INP problem." Under exactly which conditions is that true, and under which is it false? What single question would you ask to find out which situation you are in?

11. Your test suite drives all UI interactions with fireEvent.click(). Given Step 1's finding about microtask interleaving, describe a bug class this suite cannot catch. What would you change, and what would that change cost in suite runtime and maintenance?

12. You have established that the dominant INP term differs across implementations of the same feature. Design the performance report your organization should require. What must it contain beyond a number, and what behaviour are you trying to make impossible?

Record

File your answers as RESULTS.md in the module directory, or as an ADR in ../fe-00-roadmap/docs/decisions/ where the question is genuinely a decision (3, 6, 9, 12 are the natural candidates).

Anything you could not answer goes in ../fe-00-roadmap/docs/learning-log.md §2 as an open question. A question that survives three modules is a signal — either it is genuinely hard, or the model underneath it is still wrong.

Concepts — Memory Model, Retention & Leaks

Phase 1 · Platform substrate · Specification areas §1 (closures, garbage collection, WeakRef, memory leaks, object shapes). Gates §11 (performance), §30 (large-scale UI), §41, and the "memory leak after hours" failure case study.

1. What is it

A JavaScript memory leak is not a failure to free memory. It is unintended reachability: an object you are done with is still reachable from a GC root, so the collector — correctly — keeps it. Every leak in this module is a correctness bug in a reference graph, not a resource-management bug.

Three things make this hard in a browser, and they are why this is a module rather than a footnote:

• You do not control collection. You control reachability. The only lever you have is severing references; when the collector acts is not your decision.
• The heap is not one heap. JavaScript objects live in V8's heap. DOM nodes live in Blink's C++ heap. The instrument most teams reach for reports only the first, so a large DOM leak can look like no leak at all.
• Retention is often created by code you did not write and never called. A sibling closure in the same scope, a framework's subscription registry, a module-level cache.

2. Why it matters

"The app gets slow after a few hours" is a leak until proven otherwise, and it is one of the twelve failure case studies in the specification. It is also the hardest class of bug to reproduce, because it requires time, and time is what test suites do not spend.

Leaks degrade before they crash. Long before an out-of-memory kill, a growing heap causes longer and more frequent GC pauses — which appear as scheduling problems: long tasks, jank, INP regressions with no obvious cause in the interaction path. This is the concrete link back to fe-01: a team can spend a quarter optimising handlers when the actual cause is that major GC now runs every few seconds.

The instrument selects the conclusion. Measured in this module: releasing 5,000 detached DOM nodes freed 508 KB of DOM memory while moving the JS heap by 0.10 MB. A team checking performance.memory, seeing it flat, and concluding "no leak" has been misled by their tool, not by the data.

Single-page applications made this everyone's problem. A page that used to be discarded on every navigation now lives for a working day. Every route change, modal open, subscription and cache entry is an opportunity to retain something forever.

3. How it works

+==================================================================+
|  REACHABILITY — the only thing that decides collection            |
+==================================================================+

  GC ROOTS
   ├── the global object (window)
   ├── the execution stack (locals of running functions)
   ├── the DOM tree reachable from document
   ├── active timers and their callbacks
   ├── registered event listeners (via their targets)
   └── pending promises / microtask queue entries
                    |
                    v
        anything reachable by ANY path is retained
                    |
        +-----------+-----------+
        |                       |
   reachable                unreachable
   -> retained              -> collectable (eventually)


+==================================================================+
|  TWO HEAPS, TWO INSTRUMENTS                                       |
+==================================================================+

  V8 JS heap                        Blink C++ heap (Oilpan)
  ─────────────────                 ────────────────────────
  objects, arrays, closures,        DOM nodes, style data,
  strings, Maps, wrappers           layout objects
        ▲                                   ▲
        │                                   │
  Runtime.getHeapUsage              NOT visible to it
  performance.memory                        │
        │                                   │
        └─── heap snapshot ─────────────────┘
             (includes native nodes +
              a `detachedness` flag per node)

  performance.measureUserAgentSpecificMemory() spans both,
  but requires cross-origin isolation (COOP + COEP).


+==================================================================+
|  THE FIVE RETAINER SHAPES                                         |
+==================================================================+

  1. DETACHED DOM        node removed from document, JS ref survives
  2. LISTENER            long-lived target holds a closure over a dead component
  3. TIMER               setInterval callback closes over a dead scope
  4. SIDE TABLE          Map/Set/registry keyed by objects, never deleted
  5. SHARED CONTEXT      a sibling closure forces context allocation

Closures retain contexts, not variables

V8 allocates one Context per scope. If any closure created in that scope references a variable, the variable is context-allocated — and every sibling closure keeps the whole context alive, including closures that never mention it.

Measured (200 retained closures, each from a scope holding a 50,000-element array):

The returned closure is byte-for-byte identical in all three. What differs is only what else was declared in the same scope. This is why "my callback doesn't reference that variable" is not a defence, and why these leaks survive code review.

4. Core terminology

5. Mental models

You do not free memory; you sever references. Reframing every leak question as "what still points at this?" replaces an unanswerable question ("why isn't this freed?") with a mechanical one you can answer from a retainer path.

The retainer path is the bug report. In a heap snapshot, the object is not the finding — the path from a root to the object is. Fixing a leak means breaking exactly one edge on that path, and the edge you break determines whether the fix is local or architectural.

Ownership must be explicit, and it usually is not. Every subscription, timer, observer and cache entry has an owner responsible for teardown. Leaks happen when ownership is implicit, so the structural fix is to make teardown impossible to forget — an AbortController signal created at registration time rather than a removeEventListener call someone must remember to write.

Growth shape, not growth. A single measurement proves nothing; heaps grow for many innocent reasons. Repeated identical cycles with a forced GC between them produce a slope and a linearity. Measured here: a clean workload had slope 0.001 MB/cycle with R² 0.742 — noise that looks correlated — while the leak had slope 1.836 MB/cycle with R² 1.000. Slope alone would have been ambiguous; slope plus linearity is not.

A cache without an eviction policy is a leak. The most common accidental cache is a module-level Map keyed by objects. Measured: 38.34 MB retained and 2,000 immortal detached nodes versus 0.09 MB and zero for the identical code using a WeakMap.

6. Common misconceptions

1. "performance.memory shows a flat line, so there's no leak." It reports the JS heap only. Measured: 5,000 detached nodes holding 508 KB of DOM memory moved the JS heap by 0.10 MB. Use a heap snapshot's detachedness flag, or performance.measureUserAgentSpecificMemory().

2. "My closure doesn't reference it, so it can't retain it." False, and it is the subtlest result here — a 5,744× difference driven entirely by an unused sibling function.

3. "Setting the variable to null is cargo cult." Usually yes, and occasionally load-bearing — variant C above. The distinguishing question is whether a surviving closure shares the scope.

4. "WeakMap makes memory concerns go away." It weakens the key, not the value. A value that references its own key creates a cycle a WeakMap cannot break. And WeakMap is not enumerable, so the leak you do have becomes harder to see in a dump.

5. "The GC will get to it eventually, so a small leak is fine." Unreachable objects are collected; reachable ones never are, no matter how long you wait. A leak does not shrink.

6. "Removing the element from the DOM frees it." Only if nothing else references it. Detached subtrees retain their entire subtree — one held reference to a leaf can retain thousands of ancestors and their event listeners.

7. "Leaks cause crashes." Eventually. Long before that they cause longer, more frequent GC pauses, which present as fe-01-shaped problems: long tasks, jank, INP regressions with no cause in the interaction path.

7. Interview talking points

• "A leak is unintended reachability, not a failure to free. So the only question worth asking in front of a heap snapshot is 'what is the retainer path?' — the object is never the finding."
• "The first thing I check is whether the team measured the right heap. DOM nodes are in Blink's C++ heap; performance.memory doesn't see them. We measured a case where releasing half a megabyte of detached DOM moved the JS heap by a tenth of that — flat graph, real leak."
• "For leak detection I require repeated identical cycles with forced GC between them, and I report slope and R². We had a clean workload show R² of 0.74 — noise can look correlated, and reporting a slope alone costs someone a week."
• "The listener leak is worth fixing structurally rather than case by case. removeEventListener requires remembering a second call and keeping a reference to the exact function; an AbortController signal created at registration ties teardown to the same line. That's making the invalid state hard to represent."
• "Closures retain contexts, not variables. A sibling function that's never called can pin megabytes, which means the retaining code is often nowhere near the code that looks suspicious."
• "Leaks show up as scheduling problems first. If INP is regressing with no change in the interaction path, I want a heap trace before I let anyone optimise a handler."

8. Connections to other modules

• fe-01-execution-model-scheduling — prerequisite, and the link is causal: GC pauses are long tasks. A leak diagnosed as a scheduling problem is the classic misdirection.
• fe-10 / fe-11 (hooks, memoization) — stale closures and effect cleanup are this module's retention rules wearing framework clothing; useEffect teardown is ownership.
• fe-16 / fe-17 (server state, races) — query caches are side tables keyed by objects. The eviction policy is what separates a cache from a leak.
• fe-30-large-scale-ui — virtualization creates and destroys thousands of nodes per second; a per-row listener or side-table entry becomes catastrophic rather than merely wasteful.
• fe-33-e2e — leaks need time to appear, which is why they escape unit tests. Long-running soak tests with heap assertions are the only automation that catches them.
• browser-framework-internals.md §8 (DOM Internals), §17 (V8 Integration) — cross when you need to know how DOM wrappers are kept alive across the two heaps.

References — Memory, Retention & Leaks

Specifications

• ECMAScript — WeakMap objects, WeakRef, FinalizationRegistry — note how little the spec guarantees about when anything is collected.
• WHATWG DOM — AbortController / AbortSignal and addEventListener options — the signal option is the structural teardown primitive.
• W3C — measureUserAgentSpecificMemory() — the only in-page API spanning JS and DOM memory; requires cross-origin isolation.

Engine internals

• V8 blog — Trash talk: the Orinoco garbage collector — generational GC, scavenger vs mark-compact, why pause times behave as they do.
• V8 blog — Concurrent marking
• V8 — Memory analysis / heap snapshot format — node fields including detachedness.
• Chromium — Oilpan, Blink's GC — why DOM memory is not in the JS heap. Cross-track: browser-framework-internals.md §8, §17.

Tooling

• Chrome DevTools — Memory panel reference — snapshot comparison, retainer paths, the three-snapshot technique.
• Chrome DevTools — Heap snapshot terminology — shallow vs retained size, dominators, distance.
• CDP — HeapProfiler domain — collectGarbage, takeHeapSnapshot.
• memlab (Meta) — automated leak detection in CI; the closest production-grade version of experiment 5.

Analysis and practice

• web.dev — Fix memory problems
• Addy Osmani, JavaScript memory leaks and how to avoid them
• Nolan Lawson — Fixing memory leaks in web applications — unusually good on method rather than symptom lists, and on why the DevTools workflow is ordered the way it is.

Deliberately excluded

Listicles of "10 causes of memory leaks". They enumerate symptoms without the reachability model, which leaves you pattern-matching instead of reading a retainer path — and the retainer path is the only thing that generalises to a leak nobody has blogged about.

Analysis

The five retainer shapes, and where the fix belongs

The altitude column is the Principal-relevant one. Detached-DOM leaks are usually one bad line and one good line. Side-table leaks are a design question — who owns this cache and when does an entry die? — and fixing one instance without answering that question guarantees the next one.

Why AbortController beats removeEventListener

Measured, both fixes work: 0.08 MB vs 0.09 MB retained across 300 cycles. They are not equivalent in the ways that matter at scale.

// requires: a stable reference, a second call, and remembering to make it
this._h = () => this.onResize();
window.addEventListener('resize', this._h);
// ... elsewhere, later, in a different function
window.removeEventListener('resize', this._h);

// teardown handle exists at registration; one abort() covers every registration
this._ac = new AbortController();
window.addEventListener('resize', () => this.onResize(), { signal: this._ac.signal });
// ... teardown
this._ac.abort();

The removeEventListener form has three separate failure modes: forgetting the call, losing the reference (an anonymous listener is unremovable — no amount of later code can fix it), and passing different options than at registration. The signal form has one teardown call regardless of how many listeners were registered, and it composes with fetch, addEventListener, and any API that accepts a signal.

This is the specification's heuristic "make invalid states difficult to represent" applied to lifecycle rather than to data — which is where it usually pays most.

When WeakMap is the wrong answer

WeakMap fixed a 38 MB leak to 0.09 MB in the measurement. It is still not a default:

• It weakens the key, not the value. wm.set(node, { node }) retains everything, because the value's reference to the key is strong. This is a common and hard-to-see mistake.
• Not enumerable. No .size, no iteration, no way to dump it in an incident. You have traded a visible leak for an invisible cache.
• Object keys only. Anything keyed by an id string cannot use it.
• Non-deterministic collection. You cannot write a test that asserts an entry was freed — only that heap growth is bounded, which is a different and weaker claim.
• It hides the real question. If entries should expire on logout, on navigation, or after 30 seconds, WeakMap implements none of that. It only handles "when the key dies", which is frequently not the intended policy.

Decision rule: use WeakMap when the key's lifetime genuinely is the entry's lifetime. When the policy is time, count, or an explicit event, you want a real cache with an eviction policy — LRU, TTL, or clear-on-event — and that is a design decision, not a data-structure swap.

Leak detection as a statistical claim

The clean run in experiment 5 produced R² = 0.742. Correlated-looking noise over a 12-point series is unremarkable, and it is exactly why slope alone is not evidence.

Two further requirements to make the claim honest:

• Magnitude against session length. 0.05 MB/cycle is meaningless until multiplied by how many cycles a real session performs. A leak that costs 4 MB over a working day does not justify a sprint; one that costs 400 MB does.
• A control. Run the same harness against a code path you believe is clean. Without a control you cannot distinguish your application leaking from your harness leaking — and harnesses leak.

What breaks at scale

• Frameworks own the teardown, and their contract is easy to violate. useEffect cleanup, ngOnDestroy, onUnmounted are all ownership declarations. A subscription created outside the lifecycle hook — in a module body, an event handler, a promise chain — is outside the contract and will not be torn down. Most framework-era leaks are ownership placed in the wrong scope.
• Virtualized lists multiply everything. A per-row listener or side-table entry is a rounding error at 20 rows and an incident at 100,000 (fe-30). Anything per-row must be delegated or weak, and the review question for virtualization code is "what is allocated per row and who frees it?"
• Long sessions are the test environment you do not have. Leaks need time. Unit and component tests never spend it, and E2E suites rarely exceed a minute. The only automation that catches these is a soak test asserting bounded growth over N cycles — which belongs in a nightly job, not in PR CI, because it is slow and mildly flaky by nature.
• Third-party scripts leak and you cannot fix them. Analytics and chat widgets that retain DOM across route changes are common. Options in ascending blast radius: lazy-load them, move them to an iframe with its own heap, or drop them. Recognising it is third-party is most of the work — which requires the retainer path, not the growth curve.
• Cross-process invisibility. Workers, iframes and extensions each have their own heap. A renderer that looks healthy may be one of several, and performance.measureUserAgentSpecificMemory() is the only in-page API that even attempts a whole-renderer figure.
• GC pauses present as scheduling problems. A rising heap makes major GC more frequent and longer, which shows up as long tasks and INP regressions with no cause in the interaction path. Teams then optimise handlers for a quarter. The tell is that the regression correlates with session age, not with a code change — and nobody looks at session age unless someone tells them to.

Execution Guide

Tool versions

Browser resolution is identical to fe-01: $CHROME, then the newest Playwright cache build, then a system Chrome. node_modules is symlinked to fe-01's to avoid a second install; if that link is missing, npm install here.

Why CDP rather than in-page APIs. Two capabilities are unavailable to page script and essential here:

• HeapProfiler.collectGarbage — deterministic GC. Without it you measure collection scheduling rather than retention. (--js-flags="--expose-gc" is the alternative and is clumsier.)
• HeapProfiler.takeHeapSnapshot — the only way to see DOM nodes and the detachedness flag.

Quick start

cd fe-02-memory-model-and-leaks/src
npm run closures      # 1. closure context retention      (~10s)
npm run detached      # 2. detached DOM vs the JS heap    (~10s)
npm run listeners     # 3. listener leak + two fixes      (~15s)
npm run weakmap       # 4. Map vs WeakMap                 (~10s)
npm run growth        # 5. leak-detection method          (~30s)
npm run all

Manual lab

npm run serve         # http://localhost:8081

web/leaky-app.html is a small SPA-shaped application with four seeded leaks, for DevTools Memory-panel practice. See steps/05-devtools-hunt.md.

Tuning

N=500 SIZE=100000 npm run closures    # bigger contexts
ROWS=50000        npm run detached    # more detached nodes
CYCLES=1000       npm run listeners   # longer soak
N=10000           npm run weakmap
CYCLES=30 PER_CYCLE=200 npm run growth  # tighter regression, slower run

Reproducibility notes

• Forced GC is two rounds. One round can leave objects reachable only from dying weak references. If your numbers are noisy, raise it before suspecting a real leak.
• Every variant gets a fresh page. Sharing a page lets an earlier variant's leak contaminate later ones — this produced wrong data while building the module; see measured-results.md.
• JS-heap numbers are stable to roughly ±0.1 MB. Anything smaller is noise. Snapshot detached-node counts are exact and are the stronger signal.
• Snapshots are expensive (hundreds of ms to seconds). Do not put one inside a measurement loop.

Observation Guide

Choosing the instrument first

Most failed leak investigations are instrument-selection failures. Decide what you are looking at before you look.

Rule: if a claim about a leak rests on performance.memory, it rests on nothing. Measured in this module: 508 KB of detached DOM freed moved the JS heap by 0.10 MB.

The DevTools Memory panel workflow

The workflow that finds leaks, in the order that works:

1. Establish the repeated action. Open modal → close modal. Navigate → back. It must be idempotent: after one cycle the app should be in the same logical state.
2. Warm up. Run the action 3–5 times first. Caches, lazy compilation and first-run allocation are not leaks, and skipping this step is how false positives are born.
3. Snapshot 1. DevTools forces a GC before each snapshot, so you do not need to.
4. Run the action N times (10–20).
5. Snapshot 2.
6. Comparison view, sort by Delta. You are looking for a class whose count grew by exactly N or a multiple of it. That proportionality is the signal — noise does not come in multiples of your loop count.
7. Select an instance → Retainers panel. This is the finding. Walk the path to a root.
8. Filter by Detached in the class filter to isolate detached DOM directly.

Reading the columns

• Shallow size — the object itself. Usually uninteresting.
• Retained size — what would be freed if it became unreachable. This is the number. A small object with huge retained size is a dominator, and dominators are where fixes go.
• Distance — hops from a GC root. Very short distances on objects that should be transient are suspicious.
• Delta (comparison view) — count and size change between snapshots. Sort here first.

Retainer paths worth recognising instantly

window → myModuleCache (Map) → {…} → HTMLDivElement        side-table leak
window → (event listeners) → onResize() → Widget → data    listener leak
window → (timer) → interval callback → context → Widget    timer leak
Window → context → sibling closure → big array             shared-context leak
document → … (nothing)  +  Detached HTMLDivElement         detached DOM

The last one is diagnostic: an element flagged Detached whose retainer path starts at a JS object rather than the document is the definition of the leak.

Healthy vs unhealthy signals

Healthy:

• Heap returns to roughly its baseline after each cycle, once warmed
• Detached node count returns to 0 after teardown
• Listener count stable across mount/unmount cycles
• Growth slope near zero regardless of R²

Unhealthy, with the diagnosis:

• Class count growing by exactly N per N cycles → deterministic per-iteration retention
• Detached nodes accumulating → something holds a reference to removed DOM
• Listener count rising monotonically → missing teardown, and the target is long-lived
• Heap sawtooths but the troughs rise → real growth hidden under normal GC activity; look at post-GC minima, not peaks
• Major GC frequency rising over a session → the fe-01 link: this presents as jank, not as a memory alert

What these measurements do not tell you

• One browser, one version. Retention behaviour is engine-specific; the closure/context result in particular is a V8 implementation detail, not a language guarantee.
• Synthetic cycles are not user sessions. Real leaks often need a specific navigation order or an error path that a loop never exercises.
• Forced GC is not real GC timing. It removes scheduling noise deliberately — which is what makes retention measurable, and what makes these numbers not a model of production pause behaviour.
• Snapshots perturb what they measure. Taking one forces a GC and pauses the renderer; do not put snapshots inside the loop you are timing.
• Nothing here covers workers, iframes, or other processes. Each has its own heap, and cross-process retention is invisible to all of the above.

Measured Results

Chrome for Testing 149.0.7827.55 (arm64 macOS), driven by playwright-core over CDP. Reproduce with cd ../src && npm run all. GC is forced via HeapProfiler.collectGarbage (two rounds) before every measurement.

1. Closure context retention

200 retained closures, each created in a scope holding a 50,000-element array. Arrays alone would cost ~76 MB if all were retained.

B retains 5,744× what A retains. The returned closure is identical in all three variants. Only the other declarations in the scope differ.

V8 allocates one Context per scope. A variable referenced by any closure in that scope becomes context-allocated, and every sibling closure retains the whole context.

2. Detached DOM, and the wrong instrument

5,000 <div> nodes built, attached, detached, then released.

Releasing 507.8 KB of DOM moved the JS heap by 0.10 MB.

DOM nodes live in Blink's C++ heap. Runtime.getHeapUsage and performance.memory report the JS heap only. A team checking performance.memory, seeing it flat, and concluding "no leak" has been misled by the instrument. Use the snapshot detachedness field or performance.measureUserAgentSpecificMemory().

3. Event listener leak — 300 mount/destroy cycles

Every variant constructs identical widgets and calls destroy(). Only listener lifecycle differs. Each variant runs on a fresh page (see harness note below).

The anonymous-listener variant cannot be repaired later: there is no reference to the function that was registered. The AbortController form creates the teardown handle at registration time, which is why it is the better default — it is not faster, it is harder to get wrong.

4. Map vs WeakMap — 2,000 detached nodes as keys

Identical code except the constructor. A Map holds keys strongly, so every node it has ever seen is immortal, along with its metadata — unreachable from the document and from application code, and still not collectable.

5. Leak-detection method — 12 cycles × 60 views, GC between each

clean  ▁▁▁▁▁▁▁█████  0.68MB -> 0.69MB     slope 0.001 MB/cycle   R² 0.742
leaky  ▁▁▂▃▃▄▅▆▆▇██  2.51MB -> 22.71MB    slope 1.836 MB/cycle   R² 1.000

The clean run has R² = 0.742. Noise can look strongly correlated over a short series — which is exactly why slope alone is not evidence. The discriminator is the pair:

Rules this encodes:

1. Force GC between cycles, or you are measuring GC scheduling, not retention.
2. Use identical repeated cycles, or slope is meaningless.
3. Report slope and linearity. Neither alone supports a conclusion.

A high slope with low R² is usually a cache warming, a lazily-compiled path, or a heap that has not settled. Reporting that as a leak costs someone else a week.

Harness failure mode found while building this

Shared page across variants silently voids the experiment. The first listener-leak run measured all three variants on one page. The leaked widgets from variant 1 remained alive during variants 2 and 3, so the detached column read 300 / 300 / 300 — identical for the fixed variants and the broken one. The JS-heap column was still correct, which made the table look partially plausible and therefore harder to distrust.

Fix: a fresh page (fresh realm, fresh heap) per variant.

This is the same class of bug as the realm-reuse issue in fe-01: the harness produced clean, plausible, wrong data. Deliberately break the thing being measured and confirm the harness notices, before trusting any number it reports.

Verification Checkpoints

Reference environment: Chrome for Testing 149.0.7827.55, arm64 macOS. Ranges are the pass condition; exact bytes are machine-specific.

Checkpoint 1 — Closures retain contexts, not variables

npm run closures

  variant                            | retained heap
  A  no sibling references it        |    0.01MB
  B  unused sibling references it    |   38.17MB
  C  sibling + explicit big = null   |    0.01MB

Pass: B is at least 100× A. A and C are within noise of each other (< 0.5 MB). Fail — all three near zero: SIZE too small, or the engine optimised the arrays away. Raise SIZE/N. Fail — A is also large: you are retaining something else; check that __held is reset between variants.

Checkpoint 2 — The JS heap does not see DOM

npm run detached

  removed from DOM, JS refs held   |           5000 |        507.8KB |  0.84MB
  JS refs released                 |              0 |          0.0KB |  0.74MB

Pass: detached count goes 0 → ROWS → 0, while the JS-heap column changes by a much smaller amount than the detached-bytes column. Fail — detached always 0: the snapshot has no detachedness field (older V8). lib/heap.mjs reports hasDetachednessField; check it. Fall back to name-prefix matching only if false.

This checkpoint is the one to internalise: the instrument selects the conclusion.

Checkpoint 3 — Listener lifecycle, three variants

npm run listeners

  anonymous listener, never removed    |          23.00MB |            300
  removeEventListener in destroy()     |           0.08MB |              0
  AbortController signal + abort()     |           0.09MB |              0

Pass: the anonymous variant retains ≥ 20× the other two and shows CYCLES detached nodes while the other two show 0. Fail — all three show the same detached count: page isolation is broken; each variant must run on a fresh page. This exact bug occurred while building the module.

Checkpoint 4 — WeakMap weakens keys

npm run weakmap

  Map        |          38.34MB |                      2000
  WeakMap    |           0.09MB |                         0

Pass: Map retains ≥ 100× the WeakMap variant, and detached counts differ by ~N.

Checkpoint 5 — Slope and linearity together

npm run growth

clean  ▁▁▁▁▁▁▁█████  slope 0.001 MB/cycle   R² 0.742
leaky  ▁▁▂▃▃▄▅▆▆▇██  slope 1.836 MB/cycle   R² 1.000

Pass: leaky slope ≥ 0.5 MB/cycle with R² ≥ 0.95; clean slope < 0.05 MB/cycle. Note the clean R² is high — around 0.74 here — and that is the point. If your clean R² comes out low, run it again; over a short series it will sometimes be high. The checkpoint is that you can state why a high R² on the clean run is not alarming (the slope is at zero magnitude).

Checkpoint 6 — You can name the retainer path

Not a script. Open web/leaky-app.html, take two snapshots around a repeated action, use the Comparison view, and for each of the four seeded leaks write down:

1. the object class that grew,
2. the retainer path from a GC root,
3. the single edge you would break to fix it,
4. whether breaking that edge is a local fix or an architectural one.

Pass: four retainer paths written down, each naming a specific root. "It's a closure" is not a retainer path. window → appState.cache → Map → {…} → HTMLDivElement is.

Module completion

All six checkpoints, and:

• steps/06-principal-review.md answered in writing
• One leak found in a real codebase you work on, or a documented statement of why none was found and what you checked — the method transfers or it was not learned
• ../fe-00-roadmap/docs/learning-log.md updated with any prediction you got wrong
• A soak-test sketch: what you would assert, at what cadence, in CI (fe-33 picks this up)

Broader Ideas

Leaks are scheduling problems in disguise

The most valuable connection in this module runs back to fe-01. A growing heap makes major GC more frequent and longer. Major GC is a long task. So a leak presents as:

• INP regressions with no change in the interaction path
• jank that worsens the longer a session runs
• "the app gets slow after a few hours", which is the specification's own case study

The diagnostic that separates them: a scheduling problem is reproducible on a fresh page load; a leak is not. If a performance complaint correlates with session age rather than with a release, take a heap trace before anyone touches a handler. Almost nobody checks session age unless it is written into the triage runbook — which is a Principal-level artifact, not a technical fix.

useEffect cleanup is an ownership declaration

Every framework lifecycle teardown hook is this module's ownership rule in framework clothing:

useEffect(() => {
  const ac = new AbortController();
  window.addEventListener('resize', onResize, { signal: ac.signal });
  return () => ac.abort();          // <- the ownership declaration
}, []);

The leaks happen where ownership is placed outside the hook: a subscription in a module body, a listener registered inside a promise chain that resolves after unmount, a cache written from an event handler. The framework cannot tear down what it does not know about.

This is also why the stale-closure bug and the leak bug are the same bug seen from two angles: a closure that outlives its component both reads stale state and retains that state. Developed in fe-10.

Query caches are side tables with a policy

A server-state cache (fe-16) is exactly the side-table shape from experiment 4, and the entire difference between a cache and a leak is the eviction policy:

Libraries default to time-based policies, which is why an unconfigured cache is usually bounded but frequently wrong for the privacy case — cached data surviving a logout is a security finding, not a memory one. That crossover is picked up in fe-25.

Soak testing is the only automation that catches this

Leaks need time, and no normal test spends it. The shape that works:

// nightly, not PR CI: slow, and mildly flaky by nature
const samples = [];
for (let i = 0; i < 30; i++) {
  await doTheRepeatedThing(page);
  await cdp.send('HeapProfiler.collectGarbage');
  samples.push((await cdp.send('Runtime.getHeapUsage')).usedSize);
}
const { slope, r2 } = regression(samples.slice(5));   // discard warm-up
expect(slope).toBeLessThan(BUDGET_BYTES_PER_CYCLE);

Three design decisions carry the value: discard the warm-up samples, assert on slope rather than absolute heap, and pair the slope assertion with an R² sanity check so a noisy run fails loudly rather than silently passing. Assert detached-node counts too where the leak is DOM-shaped — counts are exact where byte counts are not. Picked up properly in fe-33.

Memory as a budget, not an alarm

Performance budgets (fe-11) usually cover bytes over the wire and milliseconds on the main thread, and stop there. A mature budget includes memory, expressed the way this module measures it:

• bytes per repeated operation (slope), not total heap
• detached node count after teardown — should be zero, and zero is testable
• listener count stability across mount/unmount cycles
• a session-length assumption stated explicitly, since slope only becomes a number that matters when multiplied by it

The reason to express it this way is that total heap is not actionable and varies with content, while slope attributes growth to a specific operation someone owns.

WeakRef and FinalizationRegistry

Deliberately not used in this module's experiments, because they are almost always the wrong tool and appear in interviews far more often than in good code. FinalizationRegistry callbacks are not guaranteed to run at all, may run arbitrarily late, and must never be used for correctness — only for opportunistic cleanup of external resources. If a design needs to know when something was collected, the design is wrong; make the lifetime explicit instead.

The legitimate uses are narrow: caches of expensive derived values where recomputation is acceptable, and releasing non-memory resources tied to objects the GC owns.

Step 1 — Reachability, and What Closures Actually Retain

Goal

Replace "the GC frees what you stop using" with "the GC frees what is unreachable", and discover that closures retain contexts, not variables.

Prerequisites

• fe-01 complete
• cd src && npm install (or the symlinked node_modules from fe-01)

Predict first

Three factories. All three return the identical closure () => 42. You keep 200 of the returned closures alive.

// A
const makeClean = () => {
  const big = new Array(50000).fill('x');
  return () => 42;
};

// B
const makeLeaky = () => {
  const big = new Array(50000).fill('x');
  const unusedSibling = () => big.length;   // never called, never returned
  return () => 42;
};

// C
const makeFixed = () => {
  let big = new Array(50000).fill('x');
  const unusedSibling = () => big.length;
  big = null;
  return () => 42;
};

Write down the retained heap for each. Commit to numbers.

Run

npm run closures

Expected output:

  variant                            | retained heap
  -----------------------------------|---------------
  A  no sibling references it        |    0.01MB
  B  unused sibling references it    |   38.17MB
  C  sibling + explicit big = null   |    0.01MB

  B retains 5744x what A retains.

What just happened

V8 allocates one Context per scope. If any closure created in that scope references a variable, that variable is context-allocated — moved from the stack into a heap object shared by every closure from that scope. The returned () => 42 holds the Context, and the Context holds big.

unusedSibling is never called and never escapes. It does not need to run, or even be reachable by name, to have caused big to be context-allocated at compile time.

Three consequences worth carrying:

1. "My callback doesn't reference that variable" is not a defence. The retaining code is a sibling function, often written by someone else, often the innocuous-looking one.
2. x = null is sometimes load-bearing, not cargo cult — variant C. The distinguishing question is whether a surviving closure shares the scope. If none does, nulling is noise.
3. This is a V8 implementation detail, not a language guarantee. Other engines may allocate contexts differently. Record it as engine behaviour, with the version, in the verification log.

The general rule this establishes and the rest of the module builds on:

Nothing is freed because you stopped using it. Things are freed because nothing can reach them.

Every remaining experiment is an instance of that sentence.

Checkpoint

docs/verification.md Checkpoint 1.

Going deeper

N=1000 SIZE=100000 npm run closures

Does B scale linearly with N? With SIZE? What does that tell you about whether the Context is shared per call or per scope?

Step 2 — Detached DOM, and Why Your Instrument Lied

Goal

Find a detached-DOM leak, and learn that the tool most teams reach for cannot see it.

Prerequisites

• Step 1 complete

Predict first

5,000 <div> elements are created, appended to the document, then removed with host.replaceChildren() — while an array holds a JS reference to every one.

1. After removal, are the nodes collectable?
2. How much will the JS heap change when the array is finally cleared?
3. Would performance.memory reveal this leak?

Run

npm run detached

Expected output:

  stage                            | detached nodes | detached bytes | JS heap
  ---------------------------------|----------------|----------------|--------
  built + attached                 |              0 |          0.0KB |  0.84MB
  removed from DOM, JS refs held   |           5000 |        507.8KB |  0.84MB
  JS refs released                 |              0 |          0.0KB |  0.74MB

What just happened

Removing a node from the document does not free it. It only removes one reference path — the one from document. The array still reaches every node, so every node is retained, along with its attributes, text nodes, and any listeners attached to it.

And the JS heap barely moved. Freeing 507.8 KB of DOM changed the JS heap by 0.10 MB, because DOM nodes live in Blink's C++ heap (Oilpan), not V8's. Runtime.getHeapUsage, performance.memory, and every "check the heap size" reflex report the JS heap only.

This is the module's central methodological point:

A team checks performance.memory, sees a flat line, concludes "no leak", and stops looking. The instrument selected the conclusion.

What actually sees it:

Detached subtrees retain their whole subtree. One held reference to a leaf can retain thousands of ancestors. This is why virtualized lists (fe-30) turn a small mistake into an incident.

Checkpoint

docs/verification.md Checkpoint 2.

Going deeper

ROWS=50000 npm run detached

Then ask: how large would this leak need to be before performance.memory moved enough to notice — and would the page still be usable at that point?

Step 3 — Listeners, Timers, and Who Owns Teardown

Goal

Measure the classic component leak and establish why one of the two working fixes is structurally better than the other.

Prerequisites

• Steps 1–2 complete

Predict first

A Widget appends an element, holds a 20,000-element payload, registers a resize listener on window, and is then destroyed 300 times. Three listener strategies:

// leak   — anonymous listener on a long-lived target
window.addEventListener('resize', () => this.onResize());

// manual — keep the reference, remove it in destroy()
this._h = () => this.onResize();
window.addEventListener('resize', this._h);
// destroy: window.removeEventListener('resize', this._h)

// abort  — signal created at registration
this._ac = new AbortController();
window.addEventListener('resize', () => this.onResize(), { signal: this._ac.signal });
// destroy: this._ac.abort()

All three call destroy(), and destroy() always calls this.el.remove(). Predict retained heap and detached-node count for each.

Run

npm run listeners

Expected output:

  variant                              | retained JS heap | detached nodes
  -------------------------------------|------------------|---------------
  anonymous listener, never removed    |          23.00MB |            300
  removeEventListener in destroy()     |           0.08MB |              0
  AbortController signal + abort()     |           0.09MB |              0

What just happened

The retainer path is:

window → (event listeners) → the arrow function → its context → the Widget → this.data + this.el

window is a GC root and lives forever. The listener closes over this. So the Widget, its 20,000-element payload, and its detached DOM element are all immortal — even though destroy() ran and removed the element from the document.

Both fixes work. They are not equivalent.

The anonymous form is unrepairable after the fact: there is no reference to the registered function, so no later code can remove it. That is not a bug you fix in a follow-up commit; it is a bug you fix by rewriting the registration.

removeEventListener has three independent failure modes: forgetting the call, losing the reference, and passing different options than at registration. AbortController has one teardown call regardless of how many listeners were registered, the handle exists at registration time, and it composes with fetch() and every other signal-aware API.

This is "make invalid states difficult to represent" applied to lifecycle rather than to data — which is where the heuristic usually pays most.

Timers are the same shape. setInterval(() => this.refresh(), 1000) is a registration on a long-lived registry that closes over this. Same retainer path, same fix altitude.

Framework connection (previews fe-10): useEffect cleanup, ngOnDestroy and onUnmounted are ownership declarations. Leaks happen when the subscription is created outside the lifecycle hook — in a module body, inside a promise chain that resolves after unmount, in an event handler. The framework cannot tear down what it was never told about.

Checkpoint

docs/verification.md Checkpoint 3.

Note on the harness

Each variant runs on a fresh page. The first version of this experiment shared one page, so leaked widgets from variant 1 stayed alive through variants 2 and 3 and every row reported 300 detached nodes. The JS-heap column was still right, which made the table look partly plausible. See docs/measured-results.md.

Step 4 — Side Tables, Caches, and the Limits of WeakMap

Goal

Measure the most common accidental cache leak, and establish when WeakMap is not the answer.

Prerequisites

• Steps 1–3 complete

Predict first

2,000 DOM nodes are created, used as keys in a module-level side table with per-node metadata, then detached and dereferenced. Two variants, identical except:

const store = new Map();       // vs
const store = new WeakMap();

Predict retained heap and surviving detached-node count for each.

Run

npm run weakmap

Expected output:

  side table | retained JS heap | detached nodes still alive
  -----------|------------------|---------------------------
  Map        |          38.34MB |                      2000
  WeakMap    |           0.09MB |                         0

What just happened

A Map holds its keys strongly. Every node the map has ever seen is immortal, along with the metadata hanging off it. The nodes are unreachable from the document and from application code, and still not collectable — the map is the only thing keeping 38 MB alive.

This is the shape of most accidental caches: a module-level Map, Set, registry, or id → object index that nothing ever deletes from.

A cache without an eviction policy is a leak with better branding.

But WeakMap is not a default. Five limits worth knowing before reaching for it:

1. It weakens the key, not the value. wm.set(node, { node }) retains everything, because the value's reference to the key is strong. Easy to write, hard to see.
2. Not enumerable. No .size, no iteration, no dump during an incident. You have traded a visible leak for an invisible cache.
3. Object keys only. Anything keyed by an id string cannot use it.
4. Non-deterministic collection. You cannot write a test asserting an entry was freed — only that growth is bounded, which is a weaker claim.
5. It implements one policy: "when the key dies". If entries should expire on logout, on navigation, or after 30 seconds, WeakMap implements none of that.

The decision rule:

Point 5 crosses into security: cached user data surviving a logout is a privacy finding, not a memory one, and WeakMap would not have fixed it. Picked up in fe-25.

Checkpoint

docs/verification.md Checkpoint 4.

Step 5 — The DevTools Hunt

Goal

Find four seeded leaks in an unfamiliar application using only the Memory panel, and write a retainer path for each. This is the step that transfers to real work.

Prerequisites

• Steps 1–4 complete

Setup

cd src
npm run serve      # http://localhost:8081/leaky-app.html

An SPA-shaped app with three routes. web/leaky-app.html contains four distinct leaks. Do not read the source until you have found them from evidence — reading it spends the exercise, and the exercise is the deliverable.

The workflow, in the order that works

1. Establish the repeated action. Navigating between routes. It is idempotent: after one navigation the app is in the same logical state.
2. Warm up. Click Navigate ×10 once and discard it. Caches and lazy compilation are not leaks, and skipping this is how false positives are born.
3. Snapshot 1. DevTools → Memory → Heap snapshot. It forces a GC first, so you do not need to.
4. Click Navigate ×50.
5. Snapshot 2.
6. Comparison view, sorted by Delta. Look for classes whose count grew by exactly 50 or a multiple of it. That proportionality is the signal — noise does not arrive in multiples of your loop count.
7. Select an instance → Retainers panel. Walk the path to a root. This is the finding.
8. Filter the class list by Detached to isolate detached DOM directly.

Deliverable

For each of the four leaks, write down:

"It's a closure" is not a retainer path. A retainer path names the root and every hop: window → appState.cache (Map) → {…} → HTMLDivElement.

Hints, in increasing order of spoiler

Then fix them

Fix each leak, re-run the comparison, and confirm the deltas are gone. For each fix, state whether it is local (one line moved) or architectural (someone now owns a policy). Two of these four are architectural — being able to say which is the Principal-level part of the exercise.

Debugging exercise

Run the app under the specification's incident protocol as though it were a production report of "the dashboard gets slow after a few hours":

1. What do you investigate first?
2. What evidence do you need?
3. What hypotheses exist? — include at least one that is not a leak
4. What experiments distinguish them?
5. What mitigation is appropriate? — before the fix ships
6. What permanent fix is appropriate?
7. What systemic change prevents recurrence?

Question 3 is the one that separates levels. "GC pauses from a leak" and "a genuine long task" present identically to a user, and the discriminator is cheap: a leak correlates with session age, a scheduling problem reproduces on a fresh page load. If that check is not in the triage runbook, nobody performs it — which makes question 7's answer a document, not a code change.

Checkpoint

docs/verification.md Checkpoint 6.

Step 6 — Growth Detection: Telling a Leak From Noise

Goal

Turn "the heap went up" into a defensible claim, and design the only automation that catches leaks.

Prerequisites

• Steps 1–5 complete

Predict first

Two workloads, 12 cycles each, 60 components created and destroyed per cycle, GC forced between every cycle. One registers each component in a module-level array; one does not.

1. What slope (MB/cycle) do you expect for each?
2. What R² do you expect for the clean run?

Most people answer the second question "near zero". Commit to a number before running.

Run

npm run growth

Expected output:

  clean  ▁▁▁▁▁▁▁█████  0.68MB -> 0.69MB
         slope 0.001 MB/cycle   R² 0.742

  leaky  ▁▁▂▃▃▄▅▆▆▇██  2.51MB -> 22.71MB
         slope 1.836 MB/cycle   R² 1.000

What just happened

The clean run has R² = 0.742. Over a short series, noise routinely looks strongly correlated. If R² alone were your test, you would have just reported a leak that does not exist.

Slope alone is equally insufficient — caches warming, lazy compilation, and an unsettled heap all produce real positive slopes for a while.

The claim requires both, read together:

Two further requirements before the claim is honest:

• Magnitude against session length. 0.05 MB/cycle means nothing until multiplied by how many cycles a real session performs. 4 MB over a working day does not justify a sprint; 400 MB does.
• A control. Run the same harness against a path you believe is clean. Without one you cannot distinguish your application leaking from your harness leaking. Harnesses leak.

Three rules the experiment encodes:

1. Force GC between cycles, or you are measuring GC scheduling, not retention.
2. Use identical repeated cycles, or slope is meaningless.
3. Report slope and linearity. Neither alone supports a conclusion.

Design the soak test

Leaks need time, and no normal test spends it. Unit tests do not. Component tests do not. E2E suites rarely exceed a minute. Sketch the automation:

// nightly, NOT PR CI: slow by nature, and mildly flaky by nature
const samples = [];
for (let i = 0; i < 30; i++) {
  await doTheRepeatedThing(page);
  await cdp.send('HeapProfiler.collectGarbage');
  samples.push((await cdp.send('Runtime.getHeapUsage')).usedSize);
}
const { slope, r2 } = regression(samples.slice(5));      // discard warm-up
expect(slope).toBeLessThan(BUDGET_BYTES_PER_CYCLE);
expect(detachedNodeCount).toBe(0);                        // exact where bytes are not

Write down, for an application you actually work on:

1. Which repeated action would you soak? Why that one?
2. What is your budget in bytes per cycle, and how did you derive it from an assumed session length rather than from taste?
3. Where does it run — and why not in PR CI?
4. What does it assert besides slope? (Detached counts are exact; byte counts are not.)
5. How do you stop it becoming a flaky test everyone disables within a month?

Question 5 is the one that decides whether this exists in twelve months. A soak test that fails noisily gets muted; one that reports a trend and only fails on a sustained regression survives. Picked up properly in fe-33.

Checkpoint

docs/verification.md Checkpoint 5.

Step 7 — Principal Engineer Review

Answer in writing. Several have defensible answers on more than one side; "it depends" is acceptable only if you say on what.

1. Users report the dashboard "gets slow after a few hours". Nothing reproduces on a fresh load. Give three hypotheses — at least one that is not a memory leak — and the cheapest experiment that distinguishes them. What single field would you add to your triage runbook so the next person does not have to be clever?

2. An engineer reports a leak: "heap grew 40 MB over ten minutes of use." What do you ask before accepting it? Your measurement in Step 6 produced R² = 0.742 on a clean workload — use it.

3. A teammate proposes a lint rule requiring every addEventListener to have a matching removeEventListener. Make the strongest case for, then against. What would you actually ship, and what would it fail to catch?

4. Your design system ships a useResizeObserver hook used by 40 teams. Specify its teardown contract. What must it not let callers do? What happens if a caller stores the observed element in a module-level Map — is that your problem, and how would you know it happened?

5. A team fixes a detached-DOM leak by adding element = null in 30 places. It works. What is your review comment? Under what circumstances is the diff actually correct?

6. You must choose between WeakMap and an LRU cache for a query cache keyed by request objects. What information decides it? Give a scenario where WeakMap is dangerous rather than merely insufficient.

7. Memory is not in your organisation's performance budget. Propose an addition. What is measured, what is the threshold, where is it enforced, and what makes it resistant to being disabled after the third false positive?

8. A third-party analytics script retains DOM across route changes: ~2 MB per navigation. Legal requires the script. Enumerate your options in ascending blast radius, say which you propose, and say how you would get agreement from the team that owns the relationship.

9. Your soak test has failed intermittently for three weeks. Nobody has investigated. What went wrong — technically and organisationally — and what do you change first?

10. Explain to a senior engineer why a memory leak can present as an INP regression, and why optimising the interaction handler will not help. What one measurement settles it?

11. WeakRef and FinalizationRegistry are proposed to fix a cache. Explain why this is almost certainly wrong, and name the narrow cases where it is right.

12. You have one week to reduce leak risk across a 200-engineer frontend organisation. You cannot review every codebase. What do you do, and what do you deliberately not do?

Record

File answers as RESULTS.md in the module directory. Questions 4, 7 and 12 are natural ADRs — write at least one in ../fe-00-roadmap/docs/decisions/ using the seven-field template, and make the reversibility and migration sections real rather than perfunctory.

Anything unanswerable goes in ../fe-00-roadmap/docs/learning-log.md §2 as an open question.

Concepts — Object Shapes, Hidden Classes, Inline Caches & JIT

Phase 1 · Platform substrate · Specification area §1 (object shapes, hidden classes, inline caches, JIT compilation). Parallel-safe with fe-04–fe-07.

This module's thesis is unusual: its main deliverable is knowing when to ignore it. The effects are real and reproducible. In frontend code they are almost always the wrong thing to work on, and being able to say so with numbers is the Principal-level skill here.

1. What is it

V8 does not store JavaScript objects as hash maps. It infers structure and specialises:

• Hidden classes (Maps/Shapes) describe an object's layout — which properties exist, in what order, at which offsets. Objects built identically share one hidden class.
• Inline caches (ICs) memoise, at each property-access site, which shapes have been seen there and where the property lives. One shape means a direct offset load.
• Element kinds specialise array storage by content: small integers, doubles, or general elements; packed or holey. Transitions are one-way.
• Tiered JIT — an interpreter (Ignition) plus optimising compilers (Sparkplug/Maglev/TurboFan) that speculate on observed types and deoptimise when the speculation breaks.

All of it is speculation on consistency. Consistent code runs fast; inconsistent code falls back.

2. Why it matters

Three legitimate reasons, and one illegitimate one worth naming.

Legitimate — you own a hot data path. Virtualized tables, canvas/WebGL render loops, parsers, diffing algorithms, worker-side transforms over 10⁵–10⁷ items. Here per-element costs multiply by enough to matter (fe-30).

Legitimate — you are choosing a data representation. Array-of-objects vs object-of-arrays, Map vs plain object as a dictionary, whether to delete. These are decisions made once and hard to reverse, so making them from knowledge rather than folklore is cheap.

Legitimate — you must arbitrate. An engineer proposes a refactor for shape stability. You need to price it against alternatives in the same units, and say no with evidence rather than taste.

Illegitimate — it feels like real performance work. It is measurable, satisfying, and tractable, which makes it a magnet for effort that belongs elsewhere. Measured here: removing one forced layout from a render path is worth more than de-megamorphising 1,448 property accesses. That number is the module.

3. How it works

+==================================================================+
|  HIDDEN CLASSES — structure inferred from construction order      |
+==================================================================+

   {}          --add x-->   {x}        --add y-->   {x,y}
   Shape0                   Shape1                  Shape2

   const a = { x: 1, y: 2 };     ->  Shape0 -> Shape1 -> Shape2
   const b = { y: 2, x: 1 };     ->  Shape0 -> Shape1'-> Shape2'
                                        DIFFERENT final shape

   delete o.tmp                  ->  DICTIONARY MODE (no shape at all)


+==================================================================+
|  INLINE CACHES — per-access-site memory of shapes seen            |
+==================================================================+

   function read(o) { return o.v; }
                        ^ this site has its own IC

   1 shape seen    MONOMORPHIC   direct offset load          fastest
   2-4 shapes      POLYMORPHIC   short linear shape check    ~equal
   5+ shapes       MEGAMORPHIC   global stub-cache hash      ~2x slower


+==================================================================+
|  TIERED EXECUTION                                                 |
+==================================================================+

   Ignition (interpreter)
        | hot
   Sparkplug (baseline)  ->  Maglev  ->  TurboFan (optimising)
        ^                                     |
        +------------- DEOPTIMISE ------------+
              speculation violated: a shape, type, or
              element kind the compiler assumed away

The measured effects

4. Core terminology

5. Mental models

The engine bets on consistency. Every optimisation is a wager that the future resembles the past: same shapes, same types, same element kinds. You do not make code fast by adding cleverness; you avoid making it slow by not surprising the engine.

Ratios seduce; absolutes decide. "2× slower" is the most misleading phrase in performance work. The megamorphic penalty is 1.9× — and 2.9 nanoseconds. Always convert to absolute cost per operation, then multiply by the real operation count, then compare against what else is on the critical path. Doing this once will kill most micro-optimisation proposals, including your own.

Micro-benchmarks lie by default. Three of the four experiments here produced confidently wrong results before they produced right ones — a shared function accumulating IC state across cases, a DOM case leaving 5,000 children for the next case, and an accumulator overflowing SMI range. Each looked plausible. Assume your first benchmark is wrong and try to break it.

Optimise the tree, then the leaf. Frontend cost lives in the network, the DOM, layout, and scheduling — in that order, by orders of magnitude. Shape optimisation is a leaf-level concern and belongs after the tree is right, which it rarely is.

6. Common misconceptions

1. "Property order matters a lot." It measured 1.14×. It is real, cheap to get right, and almost never the reason anything is slow. Treat it as hygiene, not optimisation.

2. "delete is fine, it's just a keyword." The one folklore item that holds: 11.9×, from dictionary mode. o.tmp = undefined measured 0.98×. If you must remove keys from hot objects, rebuild the object or use a Map.

3. "Megamorphic call sites are a crisis." 2.9 ns per read. You need ~1,448 of them to equal one forced layout. Fix it when it is free; never schedule work for it without a profile.

4. "Map is always slower than a plain object." Map is designed for dynamic keys, never enters dictionary mode, and supports deletion without shape damage. For a genuine dictionary it is usually the better choice — the plain-object habit is a shape hazard.

5. "The JIT will optimise my code." It will specialise consistent code. It cannot fix an algorithm, a request waterfall, or layout thrashing, and those dominate frontend cost.

6. "Benchmark ratios transfer between engines and versions." These are V8 implementation details on one version. JavaScriptCore and SpiderMonkey differ. Record the version with any number you keep — this module's verification log does.

7. Interview talking points

• "I convert every micro-optimisation claim to absolute nanoseconds and multiply by the real operation count before discussing it. Megamorphic access is 1.9× slower, which sounds urgent, and 2.9 ns, which usually isn't — one forced layout costs about 1,448 of them."
• "The one piece of shape folklore that survives measurement is delete: 11.9× from dictionary mode, versus 0.98× for assigning undefined. Property order was 1.14×, which is hygiene, not a refactor."
• "Shape stability matters where per-element cost multiplies — virtualized lists, canvas loops, worker transforms over millions of rows. In component code it's noise, and I'd rather the team spend that attention on request waterfalls."
• "I assume my first micro-benchmark is wrong. Building this module, three of four produced confident, plausible, backwards results from shared IC state, DOM contamination, and an accumulator type transition. Isolation per case is not optional."
• "Map versus plain object is a shape question, not a style question. If keys are dynamic and get deleted, a plain object drops into dictionary mode and a Map doesn't."

8. Connections to other modules

• fe-01 — the perspective table is priced in the same units as scheduling work; forced layout appears in both modules as the dominant avoidable cost.
• fe-02 — dictionary mode and shape transitions change retained size as well as speed; both are consequences of object representation.
• fe-14 (UI algorithms) and fe-30 (large-scale UI) — where per-element cost genuinely multiplies, and therefore the only places this module's findings should change a design.
• fe-28 (workers) — structured clone cost depends on object representation; shape-stable, transferable-friendly data is the real optimisation at a worker boundary.
• browser-framework-internals.md §17 (V8 Integration) — cross if you want to read the IC implementation rather than measure its behaviour.

References — Object Shapes, ICs & JIT

Primary / engine

• V8 — Hidden classes and inline caches (blog) — the canonical explanation of shapes and transition chains.
• Mathias Bynens, JavaScript engine fundamentals: Shapes and Inline Caches — the best single article on this topic.
• Mathias Bynens, Elements kinds in V8 — element-kind lattice and one-way transitions.
• V8 — Sparkplug, Maglev, TurboFan — the tiering story.
• V8 — Ignition interpreter

Measurement method

• Chrome for Developers — Performance panel reference
• tachometer — statistically rigorous browser microbenchmarking, if you need real confidence intervals rather than medians.
• Aleksey Shipilëv, JMH and the anatomy of a microbenchmark — JVM-focused and the best writing anywhere on why microbenchmarks lie. Every failure mode in docs/measured-results.md appears here first.

Counterweight — read these alongside

• Donald Knuth, Structured Programming with go to Statements (1974) — the actual "premature optimisation" passage, including the 3% it is usually stripped from.
• web.dev — Optimize long tasks — where frontend time really goes.
• Paul Irish, What forces layout / reflow — the 4,200 ns line item in the perspective table.

Deliberately excluded

"JavaScript performance tips" listicles. They propagate property-order folklore (measured: 1.14×) while omitting delete (measured: 11.9×), and none of them price their advice against a forced layout. The perspective experiment exists specifically to inoculate against this genre.

Analysis

When this actually matters

The honest list. If your situation is not on it, the perspective table applies and you should be working on something else.

Everywhere else — component code, event handlers, data fetching, form logic, business rules — the effects are real and swamped by DOM, layout, network and scheduling.

The test to apply before starting: what is the operation count, what is the absolute per-op saving, and what else is on the same critical path? If you cannot answer all three, you are not ready to spend anyone's time.

Ratio vs absolute: the arithmetic that ends most debates

A proposal to "fix megamorphic access in the render path" sounds serious. Price it:

penalty            2.9 ns per read
reads per render   50,000            (generous for a component tree)
saving             0.145 ms per render

0.145 ms against a 16.7 ms frame budget: 0.9%. Now price the alternative:

one forced layout removed   4,200 ns = 0.0042 ms

...which sounds worse, until you count how many forced layouts a thrashing render path performs. At 800 elements interleaving reads and writes, fe-01 measured 86 ms. The shape refactor buys 0.145 ms; removing the thrash buys 86 ms. Same engineer, same week, 590× the return.

This arithmetic is reusable. Convert to absolutes, multiply by real counts, compare against alternatives on the same path. Most micro-optimisation proposals do not survive it — including ones you will be tempted by.

delete is the exception worth acting on

11.9×, and the fix is free. It is worth a lint rule where objects are hot, because it is the rare case where the folklore, the measurement, and the cost of compliance all align.

// dictionary mode: 11.93x
const o = { x, y, z, tmp: 0 }; delete o.tmp;

// shape preserved: 0.98x
const o = { x, y, z, tmp: 0 }; o.tmp = undefined;

// no phantom key at all — usually the right answer
const { tmp, ...rest } = o;

// dynamic keys that get deleted: this is what Map is for
const m = new Map(); m.set(k, v); m.delete(k);

The third form allocates a new object, which is the correct trade in almost all frontend code and the wrong one in a hot loop. The fourth is the structural answer: if keys are dynamic and deleted, a plain object is being used as a dictionary and Map is the type that was designed for it.

The polymorphic→megamorphic cliff

The IC curve is not linear, and the shape of it changes what you do:

1 shape   1.00x
2 shapes  1.00x   <- free
4 shapes  1.23x
8 shapes  1.96x   <- cliff crossed
16 shapes 1.94x   <- flat; already in the stub cache

Two consequences:

• Going from 1 to 4 shapes is nearly free. Refactoring to make a site strictly monomorphic is usually not worth it.
• Going from 8 to 80 shapes costs nothing further. Once a site is megamorphic, "reducing" shape variety buys nothing unless you get back under the threshold — which is rarely achievable in code that legitimately handles heterogeneous data.

So the only actionable version is: avoid crossing the cliff in code that is genuinely hot. Once crossed, stop optimising and go read the perspective table.

Why Map deserves rehabilitation

The folklore ("objects are faster than Maps") comes from benchmarks with static string keys, where an object's shape is stable and its IC monomorphic. That is the case Map was never for.

A plain object accumulating user IDs as keys is a shape hazard and a dictionary-mode candidate and a leak candidate. Three separate modules point at the same refactor.

What breaks at scale

• Deoptimisation loops. A function repeatedly optimised then deoptimised by an unexpected type is far worse than never optimising. These are invisible without --trace-deopt, which means a frontend engineer will essentially never find one — which is itself the argument for not speculating about JIT behaviour in code review.
• Benchmarks that stop resembling the application. A micro-benchmark runs one shape through one site. Production runs your component with props from twelve call sites. Shape-stability results from a benchmark routinely fail to reproduce in the app, and the benchmark is the thing that is wrong.
• Framework internals move the ground. Which objects a framework allocates per render, and whether they are shape-stable, is a framework implementation detail that changes between minor versions. Building application-level optimisations on assumptions about it creates work that silently expires.
• Engine divergence. These are V8 behaviours. Safari (JavaScriptCore) and Firefox (SpiderMonkey) differ in IC design, element-kind handling, and tiering. Any optimisation justified by numbers from one engine needs a statement about the other two before it becomes a standard.
• The opportunity cost is the real risk. The failure mode of this module is not writing slow code; it is a senior engineer spending a sprint on shapes while a request waterfall, an unindexed list render, and a 200 KB JSON parse sit untouched on the same critical path.

Execution Guide

Tool versions

Browser resolution as in fe-01: $CHROME, newest Playwright cache build, then system Chrome.

Quick start

cd fe-03-object-shapes-and-jit/src
npm install
npm run ic            # 1. inline caches: mono/poly/megamorphic    (~15s)
npm run shapes        # 2. hidden classes, delete, dictionary mode (~20s)
npm run arrays        # 3. array element kinds                     (~25s)
npm run perspective   # 4. what any of it is worth                 (~40s)
npm run all

Run perspective even if you skip the others. It is the module.

Tuning

ITER=10000000 npm run ic
N=1000000     npm run shapes
N=20000000    npm run arrays

Why every case gets a fresh page

Micro-benchmarks contaminate each other in ways that are silent and directional:

• Inline caches are per-site and persist. A shared helper function accumulates feedback across cases, so case 1 pays warm-up and case 4 inherits a warm-but-polymorphic function. This produced a backwards result while building the module.
• JIT tier is per-function and persists. By case 3, a function may be in TurboFan; case 1 ran in Sparkplug.
• The DOM persists. A case that appends 5,000 elements makes every later layout measurement enormous.

Fresh page per case costs ~150 ms of setup and removes all three. It is not optional.

Reading the harness

lib/bench.mjs addresses three standard micro-benchmark failures:

It does not address: timer coarsening (performance.now() is quantised to ~0.1 ms in non-isolated contexts, so keep per-rep work above ~5 ms), thermal throttling on long runs, or other processes on the machine.

A warning about editing the page templates

Page scripts are embedded in JS template literals. A backtick anywhere inside them — including inside a comment — terminates the template and produces a syntax error reported at a confusing line. This happened twice while building this module. Write the (a[i] || 0) form, never `a[i] || 0`, inside a page template.

Observation Guide

Seeing shapes and ICs directly

The measurements in this module are black-box. To see the mechanism, use V8 flags via node (same engine, no browser needed):

node --allow-natives-syntax -e '
  const a = { x: 1, y: 2 };
  const b = { y: 2, x: 1 };
  console.log(%HaveSameMap(a, b));        // false — different transition chains
  const c = { x: 1, y: 2, tmp: 0 };
  delete c.tmp;
  console.log(%HasFastProperties(c));     // false — dictionary mode
'

%DebugPrint(obj) prints the hidden class and property layout. This is the fastest way to confirm a shape hypothesis, and far more reliable than inferring it from timings.

These are debugging tools, not decision tools. Nothing here tells you whether an optimisation is worth doing — only what the engine is doing. The perspective table answers "worth it".

Chrome DevTools

The Performance panel's bottom-up view attributes time to functions, not to shapes. There is no "megamorphic access" marker, and this is deliberate: at 2.9 ns, it would be noise in any real profile.

What you can see, and what actually matters:

The ordering of that table is the observation skill. Engineers reach for JIT explanations when the flame chart shows a big scripting block, and the cause is nearly always an algorithm, a waterfall, or layout thrashing.

Healthy vs unhealthy

Healthy:

• Objects for one logical entity constructed with the same properties in the same order
• No delete on objects in hot paths
• Numeric arrays that stay numeric
• Map used where keys are dynamic
• Nobody on the team can tell you the IC state of anything, because nobody needed to look

Unhealthy — but check the magnitude before acting:

• Object literals built conditionally so property sets vary per branch
• delete in a per-item loop
• Arrays initialised as new Array(n) then filled sparsely
• A "fast path" object mutated into a different shape by an error handler

Unhealthy — act immediately, unrelated to this module:

• Forced reflow warnings in a render path
• Parsing large JSON on the main thread
• A request waterfall

What these measurements do not tell you

• One engine, one version. V8 149. JavaScriptCore and SpiderMonkey differ in IC design and element-kind handling; no result here transfers without re-measurement.
• Micro-benchmarks are not applications. One shape through one site, versus your component receiving props from twelve call sites. Shape results routinely fail to reproduce in the app.
• Timer resolution is ~0.1 ms. Anything below ~5 ms per rep is quantisation, not measurement.
• No allocation or GC pressure is measured here. Shape churn also affects memory (fe-02), and this module measures only speed.
• The PACKED_DOUBLE result is unexplained. It reproduced, one hypothesis was tested and rejected, and it was not pursued because it is ~0.6 ns/element. That is a documented limit, not a finding.

Measured Results

Chrome for Testing 149.0.7827.55 (arm64 macOS) via playwright-core/CDP. Reproduce: cd ../src && npm run all. Medians of 7 reps after 3 warm-up runs.

These are V8 implementation details on one version, not language guarantees.

1. Inline caches — 3,000,000 property reads per rep

The access site is character-identical in every row; only shape variety differs.

Note the shape of the curve. Nothing happens from 1→2. The cliff is between 4 and 8 — the polymorphic→megamorphic boundary — and past 8 it flattens: 16 shapes is no worse than 8, because the site has already fallen back to the stub cache.

Absolute penalty: 1.7 ns per read here, 2.9 ns in the perspective run (different iteration count and JIT tier).

2. Hidden classes — 400,000 objects created + read per rep

The folklore is mostly wrong and one part is right. Property order (the part everyone repeats) is 1.14×. delete (the part people wave away) is 11.9×, and the fix is free.

3. Array element kinds — 5,000,000 elements summed per rep, fresh page per case

Spread: 1.70×.

Doubles measured faster than small integers, and I did not fully isolate why. The first hypothesis — the accumulator overflowing SMI range and transitioning to double mid-loop — was tested and rejected: constraining values to i % 100 keeps the sum near 2.5e8, well inside SMI range, and the ordering did not change. The most plausible remaining explanation is that SMI addition carries an overflow check per accumulate which double addition does not.

Recorded as unexplained. It is ~0.6 ns/element either way, which is why it did not justify further investigation — a judgement this module explicitly endorses, and an open question in the learning log rather than a claim.

4. Perspective — what these optimisations are worth

Megamorphic penalty: 2.9 ns per read.

Property reads you must de-megamorphise to save the cost of one:

Removing one forced layout from a render path is worth more than de-megamorphising 1,448 property accesses. One avoided 200 KB JSON parse is worth more than 136,000.

This table is the module's deliverable. Bring it to the next discussion about object shapes.

Harness failure modes — three, all producing plausible wrong answers

1. Shared IC state across cases. One page for all four element kinds meant the shared sum accumulated feedback across kinds: the first case measured paid JIT warm-up, later cases inherited a warm-but-polymorphic function. Reported doubles as 4× faster than SMIs. Fix: fresh page per case.

2. DOM contamination between cases. createAppend left 5,000–20,000 children in the host element, so every subsequent getBoundingClientRect measured layout over a huge subtree. The script did not produce a wrong number — it timed out, which was luckier than the alternative. Fix: fresh page per case, and reset the DOM inside the case.

3. Accumulator type transition. Summing raw i over 5M elements reaches ~1.25e13, overflowing SMI range and transitioning the accumulator to a double partway through the loop — attributing a cost to the array that belonged to the sum variable. Fix: constrain values so the accumulator stays in range. (This fix did not change the ordering, which is how it was ruled out as the cause of finding 3.)

Plus one mechanical trap worth recording: backticks inside comments in a page template literal terminate the template, twice producing syntax errors far from the real line.

Rule: every micro-benchmark needs a case whose answer you already know. If the harness cannot reproduce a result you are certain of, it cannot be trusted on one you are not.

Verification Checkpoints

Reference: Chrome for Testing 149.0.7827.55, arm64 macOS. Ratios are the pass condition; absolute nanoseconds are machine-specific.