improve bundle size benchmarks and add initial skill

AGENTS.md

@@ -21,6 +21,7 @@ TanStack Router is a type-safe router with built-in caching and URL state manage
 - Framework-agnostic core logic separated from React/Solid bindings
 - Type-safe routing with search params and path params
 - Use workspace protocol for internal dependencies (`workspace:*`)
+- Always use curly braces for `if`, `else`, loops, and similar control statements. Never write one-line bodies like `if (foo) x = 1`.
 
 ## Dev environment tips
 

benchmarks/bundle-size/README.md

@@ -32,11 +32,41 @@ Each package has `minimal` and `full` scenarios:
 pnpm nx run @benchmarks/bundle-size:build
 ```
 
+Run one or more scenarios during local optimization:
+
+```bash
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal,react-router.full
+```
+
+Filtered runs build only the package projects needed by selected scenarios. Full runs build all package projects needed by all scenarios. If the required packages are already built and unchanged, skip that step:
+
+```bash
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal --skip-package-builds
+```
+
 This writes:
 
 - `benchmarks/bundle-size/results/current.json`
 - `benchmarks/bundle-size/results/benchmark-action.json`
 
+`current.json` includes run status, selected package build projects, per-scenario totals, per-file sizes, and the emitted JS files used for measurement. Dist paths use `scenarioDir`/`outDir`, e.g. `react-router.minimal` maps to `benchmarks/bundle-size/dist/react-router-minimal/`.
+
+## Local Query Tools
+
+```bash
+pnpm benchmark:bundle-size:query --id react-router.minimal
+pnpm benchmark:bundle-size:diff --baseline /tmp/base-current.json --id react-router.minimal
+pnpm benchmark:bundle-size:history --id react-router.minimal --top-deltas 20
+```
+
+For source attribution, run an analysis build. This uses hidden source maps and writes source estimates into `current.json`; those estimates are for investigation only, not tracking.
+
+```bash
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal --analysis
+pnpm benchmark:bundle-size:analyze --id react-router.minimal --top-sources 30
+```
+
 ## CI Reporting
 
 - PR workflow generates a sticky comment with:
@@ -56,6 +86,10 @@ The measurement script supports optional interfaces for historical backfilling:
 - `--sha`
 - `--measured-at`
 - `--append-history`
+- `--scenario`
+- `--analysis`
+- `--sourcemap`
+- `--skip-package-builds`
 
 These are intended for one-off scripts that replay historical commits and append results to the same history dataset shape used for chart generation.
 If `--append-history` points at a `data.js` file, output is written as `window.BENCHMARK_DATA = ...` for direct GitHub Pages compatibility.

benchmarks/bundle-size/package.json

@@ -5,6 +5,14 @@
   "scripts": {
     "build": "node ../../scripts/benchmarks/bundle-size/measure.mjs"
   },
+  "nx": {
+    "targets": {
+      "build": {
+        "cache": false,
+        "dependsOn": []
+      }
+    }
+  },
   "dependencies": {
     "@tanstack/react-router": "workspace:^",
     "@tanstack/solid-router": "workspace:^",

package.json

@@ -20,6 +20,10 @@
     "test:types": "nx affected --target=test:types --exclude=examples/**",
     "test:e2e": "nx run-many --target=test:e2e",
     "benchmark:bundle-size": "pnpm nx run @benchmarks/bundle-size:build",
+    "benchmark:bundle-size:query": "node scripts/benchmarks/bundle-size/query.mjs",
+    "benchmark:bundle-size:diff": "node scripts/benchmarks/bundle-size/diff.mjs",
+    "benchmark:bundle-size:history": "node scripts/benchmarks/bundle-size/history.mjs",
+    "benchmark:bundle-size:analyze": "node scripts/benchmarks/bundle-size/analyze.mjs",
     "benchmark:client-nav": "pnpm nx run @benchmarks/client-nav:test:perf",
     "benchmark:ssr": "pnpm nx run @benchmarks/ssr:test:perf",
     "build": "nx affected --target=build --exclude=e2e/** --exclude=examples/**",
@@ -35,6 +39,7 @@
     "labeler-generate": "node scripts/generate-labeler-config.ts",
     "cleanup-empty-packages": "node scripts/cleanup-empty-packages.mjs",
     "test:docs": "node scripts/verify-links.ts",
+    "ts:symbol-references": "node scripts/ts-symbol-references.mjs",
     "vite-ecosystem-ci:build": "nx run-many --targets=build --projects=@tanstack/router-plugin,@tanstack/start-plugin-core,@tanstack/react-start,@tanstack/react-start-client,@tanstack/react-start-server --skipRemoteCache",
     "vite-ecosystem-ci:before-test": "pnpm exec playwright install chromium",
     "vite-ecosystem-ci:test": "nx run-many --targets=test:unit --projects=@tanstack/router-plugin,@tanstack/start-plugin-core,@tanstack/react-start-client --skipRemoteCache && nx run-many --target=test:e2e --projects=tanstack-router-e2e-react-basic-file-based,tanstack-router-e2e-react-basic-file-based-code-splitting,tanstack-react-start-e2e-basic,tanstack-vue-start-e2e-basic,tanstack-solid-start-e2e-basic --skipRemoteCache"

scripts/benchmarks/bundle-size/analyze.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+
+const { values } = parseArgs({
+  allowPositionals: false,
+  options: {
+    current: {
+      type: 'string',
+      default: 'benchmarks/bundle-size/results/current.json',
+    },
+    id: { type: 'string' },
+    'top-sources': { type: 'string', default: '30' },
+    json: { type: 'boolean' },
+  },
+})
+
+if (!values.id) {
+  throw new Error('Missing required argument: --id')
+}
+
+const current = JSON.parse(
+  fs.readFileSync(path.resolve(values.current), 'utf8'),
+)
+const metric = (current.metrics || []).find((item) => item.id === values.id)
+
+if (!metric) {
+  throw new Error(`Unknown bundle-size metric: ${values.id}`)
+}
+
+if (!metric.sources) {
+  throw new Error(
+    `No source attribution found for ${values.id}. Re-run measure with --analysis.`,
+  )
+}
+
+const sourceBytes = new Map()
+for (const chunk of metric.sources) {
+  for (const source of chunk.sources || []) {
+    sourceBytes.set(
+      source.source,
+      (sourceBytes.get(source.source) || 0) + source.estimatedBytes,
+    )
+  }
+}
+
+const rows = [...sourceBytes]
+  .map(([source, estimatedBytes]) => ({ source, estimatedBytes }))
+  .sort((a, b) => b.estimatedBytes - a.estimatedBytes)
+  .slice(0, Number.parseInt(values['top-sources'], 10))
+
+if (values.json) {
+  process.stdout.write(JSON.stringify(rows, null, 2) + '\n')
+} else {
+  for (const row of rows) {
+    process.stdout.write(`${row.estimatedBytes} ${row.source}\n`)
+  }
+}

scripts/benchmarks/bundle-size/diff.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+
+const { values } = parseArgs({
+  allowPositionals: false,
+  options: {
+    baseline: { type: 'string' },
+    current: {
+      type: 'string',
+      default: 'benchmarks/bundle-size/results/current.json',
+    },
+    id: { type: 'string' },
+    json: { type: 'boolean' },
+  },
+})
+
+if (!values.baseline) {
+  throw new Error('Missing required argument: --baseline')
+}
+
+function readCurrent(filePath) {
+  return JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8'))
+}
+
+function byId(current) {
+  return new Map((current.metrics || []).map((metric) => [metric.id, metric]))
+}
+
+const baselineById = byId(readCurrent(values.baseline))
+const currentById = byId(readCurrent(values.current))
+const ids = values.id
+  ? [values.id]
+  : [...new Set([...baselineById.keys(), ...currentById.keys()])].sort()
+
+const rows = ids.map((id) => {
+  const baseline = baselineById.get(id)
+  const current = currentById.get(id)
+  return {
+    id,
+    baseline: baseline?.gzipBytes,
+    current: current?.gzipBytes,
+    delta:
+      Number.isFinite(baseline?.gzipBytes) &&
+      Number.isFinite(current?.gzipBytes)
+        ? current.gzipBytes - baseline.gzipBytes
+        : undefined,
+    initialDelta:
+      Number.isFinite(baseline?.initialGzipBytes) &&
+      Number.isFinite(current?.initialGzipBytes)
+        ? current.initialGzipBytes - baseline.initialGzipBytes
+        : undefined,
+    rawDelta:
+      Number.isFinite(baseline?.rawBytes) && Number.isFinite(current?.rawBytes)
+        ? current.rawBytes - baseline.rawBytes
+        : undefined,
+    brotliDelta:
+      Number.isFinite(baseline?.brotliBytes) &&
+      Number.isFinite(current?.brotliBytes)
+        ? current.brotliBytes - baseline.brotliBytes
+        : undefined,
+  }
+})
+
+if (values.json) {
+  process.stdout.write(JSON.stringify(rows, null, 2) + '\n')
+} else {
+  for (const row of rows) {
+    const delta = Number.isFinite(row.delta)
+      ? `${row.delta >= 0 ? '+' : ''}${row.delta}`
+      : 'n/a'
+    process.stdout.write(
+      `${row.id} ${row.baseline ?? 'n/a'} -> ${row.current ?? 'n/a'} (${delta}) initial=${row.initialDelta ?? 'n/a'} raw=${row.rawDelta ?? 'n/a'} brotli=${row.brotliDelta ?? 'n/a'}\n`,
+    )
+  }
+}

scripts/benchmarks/bundle-size/history.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import vm from 'node:vm'
+import { parseArgs } from 'node:util'
+
+const HISTORY_PATH = 'benchmarks/bundle-size/data.js'
+
+const { values } = parseArgs({
+  allowPositionals: false,
+  options: {
+    history: { type: 'string' },
+    id: { type: 'string' },
+    'top-deltas': { type: 'string', default: '20' },
+    json: { type: 'boolean' },
+  },
+})
+
+function parseHistory(raw) {
+  const trimmed = raw.trim()
+  if (trimmed.startsWith('window.BENCHMARK_DATA')) {
+    const sandbox = { window: {} }
+    vm.runInNewContext(trimmed, sandbox, { timeout: 1000 })
+    return sandbox.window.BENCHMARK_DATA
+  }
+  return JSON.parse(trimmed)
+}
+
+function readHistoryFromGit() {
+  for (const ref of ['origin/gh-pages', 'gh-pages']) {
+    try {
+      return execFileSync('git', ['show', `${ref}:${HISTORY_PATH}`], {
+        encoding: 'utf8',
+      })
+    } catch {}
+  }
+
+  throw new Error(
+    `Could not read ${HISTORY_PATH} from origin/gh-pages or gh-pages. Run: git fetch origin gh-pages`,
+  )
+}
+
+const raw = values.history
+  ? fs.readFileSync(values.history, 'utf8')
+  : readHistoryFromGit()
+const history = parseHistory(raw)
+const entries = history.entries?.['Bundle Size (gzip)'] || []
+const previous = new Map()
+const deltas = []
+
+for (const entry of entries) {
+  for (const bench of entry.benches || []) {
+    if (values.id && bench.name !== values.id) {
+      continue
+    }
+
+    const prior = previous.get(bench.name)
+    if (prior !== undefined && prior !== bench.value) {
+      deltas.push({
+        id: bench.name,
+        delta: bench.value - prior,
+        value: bench.value,
+        sha: entry.commit?.id,
+        message: String(entry.commit?.message || '').split('\n')[0],
+        timestamp: entry.commit?.timestamp,
+      })
+    }
+
+    previous.set(bench.name, bench.value)
+  }
+}
+
+deltas.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta))
+const rows = deltas.slice(0, Number.parseInt(values['top-deltas'], 10))
+
+if (values.json) {
+  process.stdout.write(JSON.stringify(rows, null, 2) + '\n')
+} else {
+  for (const row of rows) {
+    process.stdout.write(
+      `${row.id} ${row.delta >= 0 ? '+' : ''}${row.delta} => ${row.value} ${row.sha?.slice(0, 12)} ${row.message}\n`,
+    )
+  }
+}