Performance Audit

Skill: Octane performance audit

Use this to investigate performance regressions, benchmark results, scheduler/reconciler overhead, compiler output quality, or ecosystem binding perf.

Read first

• Benchmark README in the affected benchmarks/* directory
• packages/octane/src/runtime.ts comments for runtime-level changes
• Existing benchmark scripts in benchmarks/*/package.json and run.mjs
• The discipline reference for each dimension the change touches: V8 shapes and allocation, DOM work, and scheduling

Hot-path discipline

These rules apply to code that runs per render, node, item, event, signal notification, or server request. Each reference cites the runtime code that already follows the rule.

• Shapes: allocate hot records from one constructor or one literal site with every field present, in a fixed order, as BlockImpl and the bagN factories do. No delete, conditional keys, runtime class fields on hot classes, or per-instance freezing. Keep call sites and return shapes monomorphic, numeric fields integral, and arrays packed. Do not allocate closures, literals, rest arrays, or iterators per item.
• Reachability: never name a heavy function from a hot compiled path. Put feature-only code behind the capability or driver that owns it.
• Member reads: look for repeated property reads and member-chain prefixes in hot code and emitted JS. Prefer a local const for a stable value used more than once; follow Reuse stable member reads.
• DOM: read geometry before writing, never in the render walk, and never interleaved with writes in a loop. Insert built subtrees once. Keep events native and delegated. Write from resize callbacks only through createResizeObserver.
• Scheduling: a microtask, await of a settled value, or requestAnimationFrame is not a yield. Do not add a render or commit per microtask hop. Coalesce first, then yield by posting a task through an existing poster. Leave the documented scheduler contract to issue #1864.

Run the perf-review skill on the diff before handoff. It applies these rules to the change and lists the evidence each finding needs.

Workflow

1. Define target

   • Scenario: mount, update, keyed reorder, context, effects, Suspense, hydration, SSR, binding package.
   • Metric: runtime duration, allocations, DOM operations, bundle size, compiler output size, benchmark score.
   • Baseline: current main, previous commit, React, Solid/Ripple comparison, or documented expectation.
   • Semantic control: the output, identity, ordering, or lifecycle result that proves both candidates perform the same work.

2. Choose harness

   • Existing benchmarks: node benchmarks/bench.mjs --list names every suite. Common ones are js-framework, dbmon, news, recursive-context, signal-favoring, and todomvc.
   • Object shapes: benchmarks/runtime-object-shapes gates one map per record family with %HaveSameMap. Tier and deopt traces: benchmarks/client-hot-paths/functions.mjs.
   • Scheduling: scheduler-responsiveness, passive-scheduling, effect-scheduling, and the marker-task commit count in scheduling.
   • Micro regression: focused Vitest with counters/logging.
   • Compiler output: inspect emitted JS from compile.js/Vite transform.
   • Browser-only perf: use Playwright or benchmark harness if available.

3. Run baseline and candidate

   • Warm up.
   • Run multiple iterations.
   • Record environment and command.
   • Avoid mixing dependency install/build changes with code changes.
   • Use the same commit inputs, runner options, and machine state. Do not compare a quick smoke result with a full result.
   • Treat a delta inside observed variance as inconclusive. Prefer ratio guards and deterministic counters when wall-clock noise is larger than the claim.
   • The pull request benchmark gates js-framework production calls and DOM mutations per operation against the merge commit's first parent: any increase fails it. Wall time there is a paired report, called slower or faster only when its 95% interval lies beyond ±3%.

4. Diagnose

   • Runtime hot paths: scheduler queues, effect flushing, keyed reconciliation, event delegation, context propagation, refs.
   • Compiler hot paths: unnecessary deopts, over-broad dynamic regions, missed folding, slot churn, repeated closures.
   • Binding hot paths: excessive subscriptions, selector equality failures, layout-effect loops.

5. Patch or report

   • Prefer measurable changes with a regression test/benchmark note.
   • Preserve correctness over micro-optimizations.
   • Document tradeoffs and residual risk.

6. Challenge the conclusion

   • Inspect whether work was shifted to startup, compilation, hydration, garbage collection, or a less visible branch rather than removed.
   • Check allocation lifetime and invalidation for new caches or memoization.
   • Attempt a workload that should make the proposed improvement disappear; if it does not, look for a harness or measurement error.
   • Re-run the final candidate after self-review changes. Never report a stale intermediate measurement as the final result.