refactor: improve v6 stability and re-organize core logic

Author: danielbarion

benchmarks/README.md

@@ -0,0 +1,55 @@
+# React Tooltip Scaling Benchmark
+
+Automated benchmark harness comparing V5 and V6 mount/unmount performance across tooltip counts.
+
+## Quick start
+
+```bash
+# Single benchmark pass (5 repeats per count)
+node benchmarks/run-benchmark.mjs
+
+# Full statistical run (100 passes across 5 workers, then aggregate)
+yarn benchmark:scaling:full -r 100 -w 5
+
+# Aggregate the latest N results
+node benchmarks/aggregate-benchmarks.mjs --latest 100
+```
+
+## Options
+
+| Flag               | Default                      | Description                                                    |
+| ------------------ | ---------------------------- | -------------------------------------------------------------- |
+| `--counts`         | `50,100,500,2000,5000,10000` | Comma-separated tooltip counts to benchmark                    |
+| `--repeats`        | `5`                          | Measurement repeats per count                                  |
+| `--warmups`        | `1`                          | Warmup rounds per count (auto-scales to 2 for counts ≥ 10,000) |
+| `--timeoutMs`      | `1200`                       | Max time (ms) to wait for render completion                    |
+| `--executablePath` | Playwright Chromium          | Path to a Chrome/Chromium binary                               |
+| `-r` / `--runs`    | `3`                          | Total benchmark passes (scaling series)                        |
+| `-w` / `--workers` | `1`                          | Parallel worker count (scaling series)                         |
+
+## How it works
+
+1. **Build** — Bundles the fixture app with esbuild, embedding both V5 and V6 tooltip builds
+2. **Launch** — Opens a headless Chromium instance with `--enable-precise-memory-info` and `--expose-gc`
+3. **Isolate** — Each version gets its own browser page to prevent GC/memory cross-contamination
+4. **Randomize** — V5/V6 execution order is randomized per run to eliminate ordering bias
+5. **Measure** — For each count: warmup rounds, then timed mount/unmount with GC-settled memory snapshots
+6. **Trim** — IQR-based outlier removal filters OS scheduling noise from aggregated results
+
+## Latest results (100 runs, April 2026)
+
+| Count  | V5 mount  | V6 mount  | Delta     | Spread | V5 unmount | V6 unmount | Delta    | V5 update | V6 update | Delta    | V6 mount mem | Mem savings |
+| ------ | --------- | --------- | --------- | ------ | ---------- | ---------- | -------- | --------- | --------- | -------- | ------------ | ----------- |
+| 50     | 0.70 ms   | 0.60 ms   | -0.10 ms  | 0.0%   | 0.20 ms    | 0.20 ms    | 0.00 ms  | 8.30 ms   | 8.40 ms   | +0.10 ms | 41.5 KiB     | -18.5 KiB   |
+| 100    | 0.90 ms   | 0.70 ms   | -0.20 ms  | 14.3%  | 0.20 ms    | 0.20 ms    | 0.00 ms  | 8.30 ms   | 8.30 ms   | 0.00 ms  | 72.3 KiB     | -15.0 KiB   |
+| 500    | 3.00 ms   | 2.60 ms   | -0.40 ms  | 6.7%   | 0.50 ms    | 0.40 ms    | -0.10 ms | 8.30 ms   | 8.30 ms   | 0.00 ms  | 358.3 KiB    | -33.2 KiB   |
+| 2,000  | 15.60 ms  | 14.90 ms  | -0.70 ms  | 6.0%   | 1.60 ms    | 1.00 ms    | -0.60 ms | 7.60 ms   | 8.30 ms   | +0.70 ms | 1,430 KiB    | -34.7 KiB   |
+| 5,000  | 91.55 ms  | 87.25 ms  | -4.30 ms  | 21.9%  | 4.10 ms    | 2.40 ms    | -1.70 ms | 16.80 ms  | 13.30 ms  | -3.50 ms | 3,568 KiB    | -719.6 KiB  |
+| 10,000 | 381.20 ms | 364.75 ms | -16.45 ms | 13.0%  | 8.40 ms    | 4.90 ms    | -3.50 ms | 33.50 ms  | 26.20 ms  | -7.30 ms | 7,123 KiB    | -1,330 KiB  |
+
+**Key takeaways:**
+
+- V6 is faster on mount and unmount at all tested counts (up to 10k)
+- V6 uses less mount memory at every count (2k outlier resolved)
+- V6 prop updates are 21% faster at 10k (26.2 ms vs 33.5 ms)
+- Zero timeouts at all counts

benchmarks/aggregate-benchmarks.mjs

@@ -28,29 +28,44 @@ function aggregateNumbers(values) {
       standardDeviation: null,
       spreadPercent: null,
       sampleCount: 0,
+      trimmedCount: 0,
     }
   }
 
-  const middle = Math.floor(sorted.length / 2)
+  // IQR-based outlier trimming (only when enough samples)
+  let trimmed = sorted
+  if (sorted.length >= 8) {
+    const q1Index = Math.floor(sorted.length * 0.25)
+    const q3Index = Math.floor(sorted.length * 0.75)
+    const q1 = sorted[q1Index]
+    const q3 = sorted[q3Index]
+    const iqr = q3 - q1
+    const lowerFence = q1 - 1.5 * iqr
+    const upperFence = q3 + 1.5 * iqr
+    trimmed = sorted.filter((value) => value >= lowerFence && value <= upperFence)
+    if (trimmed.length < sorted.length * 0.5) {
+      trimmed = sorted
+    }
+  }
+
+  const middle = Math.floor(trimmed.length / 2)
   const median =
-    sorted.length % 2 === 0
-      ? (sorted[middle - 1] + sorted[middle]) / 2
-      : sorted[middle]
-  const mean = sorted.reduce((total, value) => total + value, 0) / sorted.length
-  const variance =
-    sorted.reduce((total, value) => total + (value - mean) ** 2, 0) / sorted.length
+    trimmed.length % 2 === 0 ? (trimmed[middle - 1] + trimmed[middle]) / 2 : trimmed[middle]
+  const mean = trimmed.reduce((total, value) => total + value, 0) / trimmed.length
+  const variance = trimmed.reduce((total, value) => total + (value - mean) ** 2, 0) / trimmed.length
   const standardDeviation = Math.sqrt(variance)
-  const p95 = sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)]
+  const p95 = trimmed[Math.min(trimmed.length - 1, Math.ceil(trimmed.length * 0.95) - 1)]
 
   return {
     median,
     p95,
-    min: sorted[0],
-    max: sorted[sorted.length - 1],
+    min: trimmed[0],
+    max: trimmed[trimmed.length - 1],
     mean,
     standardDeviation,
     spreadPercent: median === 0 ? null : ((p95 - median) / Math.abs(median)) * 100,
     sampleCount: sorted.length,
+    trimmedCount: trimmed.length,
   }
 }
 
@@ -134,13 +149,13 @@ function buildMarkdownReport(result) {
     `- Generation filter: ${result.generationFilter}`,
     `- Counts: ${result.counts.join(', ')}`,
     '',
-    '| Count | V5 mount | V6 mount | Mount delta | Mount spread | V5 unmount | V6 unmount | Unmount delta | Unmount spread | V5 mount mem | V6 mount mem | Mount mem delta | Mount mem spread | V5 unmount mem | V6 unmount mem | Unmount mem delta | Unmount mem spread | Samples | V5 timeouts | V6 timeouts |',
-    '| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |',
+    '| Count | V5 mount | V6 mount | Mount delta | Mount spread | V5 unmount | V6 unmount | Unmount delta | Unmount spread | V5 update | V6 update | Update delta | Update spread | V5 mount mem | V6 mount mem | Mount mem delta | Mount mem spread | V5 unmount mem | V6 unmount mem | Unmount mem delta | Unmount mem spread | Samples | V5 timeouts | V6 timeouts |',
+    '| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |',
   ]
 
   result.summary.forEach((row) => {
     lines.push(
-      `| ${row.count} | ${formatMs(row.v5.mount.median)} | ${formatMs(row.v6.mount.median)} | ${formatMs(row.mountDeltaMs)} | ${formatPercent(row.mountDeltaSpreadPercent)} | ${formatMs(row.v5.unmount.median)} | ${formatMs(row.v6.unmount.median)} | ${formatMs(row.unmountDeltaMs)} | ${formatPercent(row.unmountDeltaSpreadPercent)} | ${formatBytes(row.v5.mountMemory.median)} | ${formatBytes(row.v6.mountMemory.median)} | ${formatBytes(row.mountMemoryDeltaBytes)} | ${formatPercent(row.mountMemoryDeltaSpreadPercent)} | ${formatBytes(row.v5.unmountMemory.median)} | ${formatBytes(row.v6.unmountMemory.median)} | ${formatBytes(row.unmountMemoryDeltaBytes)} | ${formatPercent(row.unmountMemoryDeltaSpreadPercent)} | ${row.sampleCount} | ${row.v5.timeoutCount} | ${row.v6.timeoutCount} |`,
+      `| ${row.count} | ${formatMs(row.v5.mount.median)} | ${formatMs(row.v6.mount.median)} | ${formatMs(row.mountDeltaMs)} | ${formatPercent(row.mountDeltaSpreadPercent)} | ${formatMs(row.v5.unmount.median)} | ${formatMs(row.v6.unmount.median)} | ${formatMs(row.unmountDeltaMs)} | ${formatPercent(row.unmountDeltaSpreadPercent)} | ${formatMs(row.v5.update.median)} | ${formatMs(row.v6.update.median)} | ${formatMs(row.updateDeltaMs)} | ${formatPercent(row.updateDeltaSpreadPercent)} | ${formatBytes(row.v5.mountMemory.median)} | ${formatBytes(row.v6.mountMemory.median)} | ${formatBytes(row.mountMemoryDeltaBytes)} | ${formatPercent(row.mountMemoryDeltaSpreadPercent)} | ${formatBytes(row.v5.unmountMemory.median)} | ${formatBytes(row.v6.unmountMemory.median)} | ${formatBytes(row.unmountMemoryDeltaBytes)} | ${formatPercent(row.unmountMemoryDeltaSpreadPercent)} | ${row.sampleCount} | ${row.v5.timeoutCount} | ${row.v6.timeoutCount} |`,
     )
   })
 
@@ -163,9 +178,9 @@ async function main() {
     throw new Error('No benchmark result files matched the requested generation filter.')
   }
 
-  const counts = Array.from(
-    new Set(runs.flatMap((run) => run.counts ?? [])),
-  ).sort((left, right) => left - right)
+  const counts = Array.from(new Set(runs.flatMap((run) => run.counts ?? []))).sort(
+    (left, right) => left - right,
+  )
 
   const summary = counts.map((count) => {
     const rows = runs
@@ -175,12 +190,10 @@ async function main() {
     const aggregateVersion = (version) => ({
       mount: aggregateNumbers(rows.map((row) => row[version]?.mount?.median)),
       unmount: aggregateNumbers(rows.map((row) => row[version]?.unmount?.median)),
+      update: aggregateNumbers(rows.map((row) => row[version]?.update?.median)),
       mountMemory: aggregateNumbers(rows.map((row) => row[version]?.mountMemory?.median)),
       unmountMemory: aggregateNumbers(rows.map((row) => row[version]?.unmountMemory?.median)),
-      timeoutCount: rows.reduce(
-        (total, row) => total + (row[version]?.timeoutCount ?? 0),
-        0,
-      ),
+      timeoutCount: rows.reduce((total, row) => total + (row[version]?.timeoutCount ?? 0), 0),
     })
 
     const v5 = aggregateVersion('v5')
@@ -203,6 +216,10 @@ async function main() {
       typeof v5.unmountMemory.median === 'number' && typeof v6.unmountMemory.median === 'number'
         ? v6.unmountMemory.median - v5.unmountMemory.median
         : null
+    const updateDeltaMs =
+      typeof v5.update.median === 'number' && typeof v6.update.median === 'number'
+        ? v6.update.median - v5.update.median
+        : null
 
     return {
       count,
@@ -211,6 +228,7 @@ async function main() {
       v6,
       mountDeltaMs,
       unmountDeltaMs,
+      updateDeltaMs,
       mountMemoryDeltaBytes,
       unmountMemoryDeltaBytes,
       mountDeltaSpreadPercent:
@@ -222,13 +240,19 @@ async function main() {
           ? Math.max(v5.unmount.spreadPercent, v6.unmount.spreadPercent)
           : null,
       mountMemoryDeltaSpreadPercent:
-        typeof v5.mountMemory.spreadPercent === 'number' && typeof v6.mountMemory.spreadPercent === 'number'
+        typeof v5.mountMemory.spreadPercent === 'number' &&
+        typeof v6.mountMemory.spreadPercent === 'number'
           ? Math.max(v5.mountMemory.spreadPercent, v6.mountMemory.spreadPercent)
           : null,
       unmountMemoryDeltaSpreadPercent:
-        typeof v5.unmountMemory.spreadPercent === 'number' && typeof v6.unmountMemory.spreadPercent === 'number'
+        typeof v5.unmountMemory.spreadPercent === 'number' &&
+        typeof v6.unmountMemory.spreadPercent === 'number'
           ? Math.max(v5.unmountMemory.spreadPercent, v6.unmountMemory.spreadPercent)
           : null,
+      updateDeltaSpreadPercent:
+        typeof v5.update.spreadPercent === 'number' && typeof v6.update.spreadPercent === 'number'
+          ? Math.max(v5.update.spreadPercent, v6.update.spreadPercent)
+          : null,
     }
   })
 

benchmarks/fixture/app.tsx

@@ -12,12 +12,14 @@ type FixtureState = {
   version: BenchmarkVersion
   count: number
   renderMode: RenderMode
+  place?: string
 }
 
 type ScenarioSample = {
   count: number
   mountDurationMs: number | null
   unmountDurationMs: number | null
+  updateDurationMs: number | null
   mountMemoryDeltaBytes: number | null
   unmountMemoryDeltaBytes: number | null
   timedOut: boolean
@@ -98,7 +100,7 @@ async function waitUntil(predicate: () => boolean, timeoutMs: number) {
   return false
 }
 
-function BenchmarkFixture({ version, count }: FixtureState) {
+function BenchmarkFixture({ version, count, place }: FixtureState) {
   const TooltipComponent = version === 'v5' ? TooltipV5 : TooltipV6
   const tooltipId = `benchmark-tooltip-${version}`
 
@@ -128,7 +130,7 @@ function BenchmarkFixture({ version, count }: FixtureState) {
           </button>
         ))}
       </div>
-      <TooltipComponent id={tooltipId} />
+      <TooltipComponent id={tooltipId} place={place} />
     </div>
   )
 }
@@ -179,8 +181,11 @@ async function runScalingBenchmark({
   const samplesByCount: ScenarioSample[] = []
 
   for (const count of counts) {
-    for (let warmupIndex = 0; warmupIndex < warmups; warmupIndex += 1) {
-      onProgress?.(`count=${count} warmup ${warmupIndex + 1}/${warmups}`)
+    // Scale warmups for large counts to ensure JIT is fully warm
+    const effectiveWarmups = count >= 10000 ? Math.max(warmups, 2) : warmups
+
+    for (let warmupIndex = 0; warmupIndex < effectiveWarmups; warmupIndex += 1) {
+      onProgress?.(`count=${count} warmup ${warmupIndex + 1}/${effectiveWarmups}`)
       await renderFixture({
         version,
         count: 0,
@@ -210,7 +215,9 @@ async function runScalingBenchmark({
       })
       await nextFrame()
 
-      const mountMemoryBefore = await readStableHeapBytes()
+      // Settle memory before mount measurement
+      await collectGarbage()
+      const mountMemoryBefore = readUsedHeapBytes()
       const mountStartedAt = window.performance.now()
 
       await renderFixture({
@@ -223,11 +230,34 @@ async function runScalingBenchmark({
         return document.querySelectorAll('[data-tooltip-id]').length === count
       }, timeoutMs)
 
+      const mountEndedAt = window.performance.now()
+
+      // Settle memory after mount, outside timing window
       await nextFrame()
+      await collectGarbage()
+      const mountMemoryAfter = readUsedHeapBytes()
 
-      const mountEndedAt = window.performance.now()
+      // --- Update measurement: change `place` prop to trigger a re-render cycle ---
+      const updateStartedAt = window.performance.now()
+
+      await renderFixture({
+        version,
+        count,
+        renderMode,
+        place: 'bottom',
+      })
+      await nextFrame()
+
+      const updateEndedAt = window.performance.now()
+
+      // Restore original place for a clean unmount
+      await renderFixture({
+        version,
+        count,
+        renderMode,
+      })
+      await nextFrame()
 
-      const mountMemoryAfter = await readStableHeapBytes()
       const unmountMemoryBefore = mountMemoryAfter
       const unmountStartedAt = window.performance.now()
 
@@ -237,16 +267,17 @@ async function runScalingBenchmark({
         return document.querySelectorAll('[data-tooltip-id]').length === 0
       }, timeoutMs)
 
-      await nextFrame()
-
       const unmountEndedAt = window.performance.now()
 
-      const unmountMemoryAfter = await readStableHeapBytes()
+      await nextFrame()
+      await collectGarbage()
+      const unmountMemoryAfter = readUsedHeapBytes()
 
       samplesByCount.push({
         count,
         mountDurationMs: mountReady ? mountEndedAt - mountStartedAt : null,
         unmountDurationMs: unmountReady ? unmountEndedAt - unmountStartedAt : null,
+        updateDurationMs: mountReady ? updateEndedAt - updateStartedAt : null,
         mountMemoryDeltaBytes:
           mountReady && mountMemoryBefore !== null && mountMemoryAfter !== null
             ? mountMemoryAfter - mountMemoryBefore