Performance Engineering

Performance Engineering

Overview

Optimize the amount and frequency of work before optimizing individual operations.

Core principle: Make expensive work structurally unnecessary. A fast inner function still freezes the app when called millions of times on the main thread.

Load sync-state-invariants when an optimization changes state authority, reconciliation, optimistic data, event ordering, cache lifecycle, or destructive cleanup. This skill owns measured cost; sync-state-invariants owns state correctness.

Start With A Performance Contract

Define before editing:

Do not optimize against a toy fixture when the report provides production scale.

Workflow

Complete the numbered workflow in order. An optimization is complete only when the exact measured scenario meets its budget and separate correctness checks preserve every applicable state, identity, layout, and lifecycle transition.

0. Trust The Measurement Before Trusting The Number

A measurement setup that is wrong produces clean, confident, wrong numbers, and a clean number ends an investigation. Establish validity first.

Prove the environment is not throttled. Chrome stops producing frames and throttles timers for windows it considers backgrounded or occluded, headless or not. A capture taken that way reports near-zero rendering work no matter what the page does. Disable background/occlusion throttling at launch and measure frame liveness inside the capture. The same applies to any environment that idles when unobserved.

Prove zero is a measurement. A metric reading zero, absent, or perfectly quiet is a claim that requires evidence, because a disabled instrument reports exactly the same thing. RunTask only appears under the disabled-by-default timeline category; a scenario opened for the wrong directory renders nothing at all. Before believing a quiet result, confirm the instrument fired and the workload actually ran: assert on an independent signal, such as DOM growth alongside the application's own render counters.

Prove the workload is comparable. When the stimulus varies in size between runs, per-second and total figures are not comparable. Normalise by units of work delivered, and check run-to-run spread on an unchanged build before attributing any difference to a change.

Do not report a number whose validity you have not established. State which validity checks ran.

1. Reproduce And Measure

• Reproduce the exact interaction, not a nearby helper in isolation.
• Separate scripting, rendering, painting, network, disk, and waiting time.
• Use a profiler to identify total time and self time.
• Add operation counters when timings are noisy: selector calls, normalizations, scans, allocations, sorts, notifications.
• Capture a baseline before changing code.

Do not infer a bottleneck from code appearance when a trace or counter can identify it.

Treat every proposed optimization as a hypothesis. Memoization, caches, indexes, workers, scheduling, retries, and lifecycle machinery must address an observed cost or failure in the measured path; “could be slow” or “might race” is not evidence. Keep only the smallest mechanism that meets the contract, except where an inherent security, data-loss, destructive-operation, or concurrency invariant requires proactive protection.

Never accept an "after" without a "before" on the identical scenario and build. Measuring a fixed build against a remembered number, a different scenario, or a nearby baseline proves nothing: the mechanism you changed may not even execute in the path you measured. Re-run the unchanged build through the same scenario, however inconvenient the rebuild. Expect to discover that a plausible fix changes nothing.

A sampling profiler cannot explain native work. Self time attributed to (program) says only that the time was not in interpreted JavaScript. Use the timeline trace, which names parsing, style recalculation, layout, layerization, paint, and raster, and reserve the sampler for attributing application code.

Reproduction may require production scale you do not have. A threshold effect is invisible below its threshold, and a development workspace is usually below it. When a report will not reproduce, compare the reporter's scale against yours on the specific dimension the code keys on before concluding the bug is absent.

Profiling identifies where time is spent; it does not prove behavioral equivalence. Separately verify the applicable state, identity, layout, and lifecycle transitions for every structural optimization.

2. Write The Cost Equation

Name every multiplying dimension:

consumers × events × projects × sessions × candidate paths

For each factor, record:

• cardinality at production scale;
• update frequency;
• whether work happens on the main thread;
• whether multiple consumers independently derive the same result.

Treat hidden fanout as real work. Equality checks may prevent renders while selectors, aggregation, sorting, and allocation still execute.

3. Map Sources, Derived State, And Lifetimes

Classify each input:

• authoritative or partial;
• live or historical;
• stable or high-frequency;
• successful empty result or fetch failure;
• globally complete or complete only for one entity.

Define invalidation before adding a cache. Prefer a stronger source of truth over inference.

For destructive consumers, represent completeness explicitly. An incomplete empty bucket means "unknown", not "delete everything".

Track completeness at the smallest destructive scope. One failed project/entity blocks cleanup for itself, not for unrelated complete scopes.

4. Remove Work In This Order

1. Skip: gate disabled paths and return on no-op updates.
2. Narrow: subscribe to the exact entity/field that can affect the result.
3. Share: compute identical derived data once for all consumers.
4. Index: represent the lookup direction the UI actually needs.
5. Increment: update only affected buckets/entities and preserve other references.
6. Cache: reuse pure results with explicit keys, invalidation, and memory bounds.
7. Schedule: defer, chunk, or move genuinely unavoidable CPU work off the interaction path.
8. Micro-optimize: tune regexes, loops, and allocations only after structural multipliers are gone.

Do not jump to a worker to hide avoidable work. Do not add a global store when a local shared index has the correct lifetime.

Structural Pattern

Replace repeated questions with maintained answers:

// Bad: every consumer asks every item about every owner.
for (const project of projects) {
  const items = sessions.filter((session) => belongsTo(project, session, topology));
}

// Good: resolve ownership once, then read direct buckets.
const sessionsByProject = new Map<string, Session[]>();
for (const session of sessions) {
  const projectId = ownership.resolve(session.directory);
  if (projectId) append(sessionsByProject, projectId, session);
}

Prefer indexes keyed by stable IDs. Keep high-frequency runtime state out of metadata indexes unless it changes membership.

React And Store Hot Paths

• Subscribe to leaf values, not broad collections.
• Preserve references for unaffected entities and buckets.
• Keep streaming state out of broadly consumed stores.
• Never rely on React.memo, useMemo, or Zustand equality to prevent selector execution upstream.
• Treat every custom memo/equality comparator as a correctness boundary. Inventory every render-relevant value that comparator gates and observe its canonical identity or an explicit semantic version covering the same semantics.
• Do not compare a proxy, aggregate, fallback, or differently resolved identity when the gated render path uses another source. Stable entity IDs do not imply stable rendered content; changes to comparator-gated semantics under the same ID must invalidate affected consumers, while semantically equivalent replacements may remain stable.
• Prefer leaf subscriptions for isolated high-frequency state over threading broad state through custom comparators. Keep comparator work bounded so render fanout is not merely replaced by recursive comparison fanout.
• Do not sort structural lists from token/delta-frequency fields.
• Coalesce repeated same-entity events and skip no-op reducer updates.
• Ensure hidden or disabled surfaces perform no ongoing work.
• Preserve scroll position synchronously with useLayoutEffect; do not wait visible frames before compensation.
• Distinguish viewport resize from content growth and avoid fighting browser scroll anchoring.
• Avoid textarea auto-size shrink/expand cycles when content only grows.
• Freeze structural ordering during high-frequency updates and reorder at an explicit lifecycle edge.

Virtualization Contracts

Virtualization changes layout, mounting, measurement, focus, and scroll semantics. It is not behaviorally equivalent merely because steady-state visible rows look the same.

Before virtualizing a collection, define:

• the actual scrolling element and whether it directly contains the virtualizer or is an ancestor;
• how total virtual height and the final item remain reachable from that scroller;
• estimated versus measured sizes, including expanded, nested, and dynamically resized items;
• initialization, remount, and activation-threshold behavior;
• interactions that depend on mounted DOM, including incremental reveal, focus, selection, drag-and-drop, menus, and accessibility traversal.

Lists here use @tanstack/react-virtual; the chat transcript uses LegendList (components/chat/lib/scroll/DOCUMENTATION.md). Known traps: a virtualizer enabled before its scroll element exists caches offset 0 and scrolls the scroller to the top on attach, so enable it only once the element is known; row margins collapse in plain flow but not across virtual wrappers, so spacing doubles when virtualization kicks in; getVirtualItems()[0] is the overscan boundary, not the first visible row; a scroller hosting a virtualizer sets overflow-anchor: none. bun-patches/@tanstack+virtual-core+*.patch clamps the render range to real scroll bounds inside a shared scroller: carry it over when bumping the dependency.

When activation is threshold-based, test threshold minus one, threshold, and threshold plus one. Also test applicable collapsed/expanded, hidden/visible, filtered/unfiltered, and short/long transitions. If the current DOM or scroll topology cannot expose the virtual tail reliably, correct that topology or retain normal rendering rather than virtualizing solely by item count.

Caching Rules

Add a cache only when all are explicit:

• exact key and source identity;
• invalidation events;
• stale-result behavior;
• memory count and byte bounds where values can grow;
• runtime/project/user isolation where identities can collide;
• proof that caching removes enough work to meet the budget.

Do not introduce a cache merely to make an abstraction reusable or prepare for future consumers. First prove repeated work in the real path; then place the cache with the narrowest owner and lifetime that can invalidate it correctly.

A cache inside an O(consumers × entities × candidates) loop is a mitigation, not automatically a complete fix.