rolldown-perf-kit 0.0.0-stage → 0.1.0

package/lib/worker/launch.mjs

@@ -0,0 +1,337 @@
+// Cloudflare Worker startup driver: run a Vite-built Worker under the app's OWN workerd
+// (through its miniflare and wrangler), with the Worker's startup moved inside a request
+// so it can be timed, profiled and covered.
+//
+// workerd evaluates a Worker's main module when it loads the worker, before any request
+// or inspector can observe it. So the worker the lab runs is a generated wrapper entry
+// whose fetch handler does `await import('./<main>')`: the import compiles and evaluates
+// the main module and its whole static closure, which is exactly the work Cloudflare's
+// startup limit counts. `wrangler check startup` uses the same trick.
+//
+// Two instance shapes, deliberately separate:
+//   wrapper  - startup happens inside the lab route. Durable Object and Workflow classes
+//              live in the main module, not in the wrapper, so their namespaces are
+//              dropped here and DO-backed routes cannot be served through it.
+//   plain    - the app's real entry is the worker: startup happens at boot, every export
+//              is in place. The shape for first-request numbers and response parity.
+
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+export const WRAPPER_NAME = '__lab_wrapper.js';
+export const EMPTY_NAME = '__lab_empty.js';
+export const LAB_IMPORT_PATH = '/__lab/import';
+export const LAB_COVERAGE_PATH = '/__lab/coverage';
+export const COVERAGE_FLAGS = ['nodejs_compat', 'enable_nodejs_inspector_local_dev'];
+/** First Wrangler whose workerd (1.20260706.1) carries the in-process inspector session. */
+export const COVERAGE_MIN_WRANGLER = '4.108.0';
+
+/**
+ * Resolve miniflare, wrangler and the workerd version from the app directory. The lab
+ * never ships a runtime of its own: the number must come from the workerd the app pins.
+ */
+export function resolveWorkerTools(appDir) {
+  const require = createRequire(path.join(appDir, 'package.json'));
+  const resolveOrNull = (id) => {
+    try {
+      return require.resolve(id);
+    } catch {
+      return null;
+    }
+  };
+  const miniflarePath = resolveOrNull('miniflare');
+  const wranglerPath = resolveOrNull('wrangler');
+  if (!miniflarePath || !wranglerPath) {
+    throw new Error(
+      `${appDir} has no ${!miniflarePath ? 'miniflare' : 'wrangler'} - add wrangler as a dev dependency ` +
+        "(it brings miniflare and workerd). The lab runs the app's own workerd, never one of its own.",
+    );
+  }
+  const version = (id) => {
+    try {
+      return require(`${id}/package.json`).version;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    appDir,
+    miniflarePath,
+    wranglerPath,
+    versions: {
+      wrangler: version('wrangler'),
+      miniflare: version('miniflare'),
+      workerd: version('workerd'),
+    },
+    miniflare: null,
+    wrangler: null,
+    async load() {
+      this.miniflare ??= await import(this.miniflarePath);
+      this.wrangler ??= await import(this.wranglerPath);
+      return this;
+    },
+    /** Miniflare 5 takes `workers: [...]`; v4 takes the flat shape wrangler's helper returns. */
+    toOptions(flat) {
+      const convert = this.miniflare?.convertV4MiniflareOptions;
+      return typeof convert === 'function' ? convert(flat) : flat;
+    },
+  };
+}
+
+/** `a.b.c` >= `x.y.z` */
+export function versionAtLeast(version, minimum) {
+  if (!version) return false;
+  const a = String(version).split(/[.-]/).map(Number);
+  const b = String(minimum).split(/[.-]/).map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return true;
+}
+
+/**
+ * The output `wrangler.json` the Cloudflare Vite plugin writes next to the worker's
+ * `index.js`, read through wrangler's own helper so bindings, flags and the compatibility
+ * date mean what `wrangler dev` makes them mean. When the helper cannot express a binding,
+ * startup is still measurable: module evaluation rarely touches `env`.
+ */
+export function loadWorkerOptions(tools, configPath) {
+  const helper = tools.wrangler?.unstable_getMiniflareWorkerOptions;
+  if (typeof helper !== 'function') {
+    throw new Error(
+      'this wrangler does not export unstable_getMiniflareWorkerOptions - update wrangler',
+    );
+  }
+  try {
+    const { workerOptions, main } = helper(configPath, undefined, {
+      overrides: { enableContainers: false },
+    });
+    return { workerOptions, main, fallback: null };
+  } catch (error) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return {
+      workerOptions: {
+        compatibilityDate: config.compatibility_date,
+        compatibilityFlags: config.compatibility_flags ?? [],
+        modulesRules: (config.rules ?? []).map((r) => ({ type: r.type, include: r.globs })),
+      },
+      main: config.main,
+      fallback: String(error.message).split('\n')[0],
+    };
+  }
+}
+
+export const DEFAULT_RULES = [
+  { type: 'ESModule', include: ['**/*.js', '**/*.mjs'] },
+  { type: 'CompiledWasm', include: ['**/*.wasm'] },
+  { type: 'Text', include: ['**/*.txt', '**/*.html', '**/*.sql'] },
+  { type: 'Data', include: ['**/*.bin'] },
+];
+
+/** A wrangler module-rule glob (`**` and `*`, `?`) to a RegExp over a `/`-joined path. */
+export function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        i++;
+        if (glob[i + 1] === '/') {
+          i++;
+          re += '(?:.*/)?';
+        } else re += '.*';
+      } else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else re += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Every file under the output dir that a module rule classifies, as miniflare module
+ * descriptors. The app's own rules come first, the defaults close the gaps (`.wasm` is a
+ * CompiledWasm module even when the app lists only ESModule rules, as wrangler does).
+ */
+export function classifyModules(outDir, rules = []) {
+  const all = [...rules, ...DEFAULT_RULES].map((rule) => ({
+    type: rule.type,
+    patterns: (rule.include ?? rule.globs ?? []).map(globToRegExp),
+  }));
+  const typeOf = (rel) => all.find((rule) => rule.patterns.some((p) => p.test(rel)))?.type ?? null;
+  const modules = [];
+  const skipped = [];
+  const walk = (dir, rel) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const r = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(path.join(dir, entry.name), r);
+        continue;
+      }
+      if (r.endsWith('.map') || r === 'wrangler.json' || r.startsWith('wrangler.')) continue;
+      const type = typeOf(r);
+      if (type) modules.push({ type, path: path.join(outDir, r), rel: r });
+      else skipped.push(r);
+    }
+  };
+  walk(outDir, '');
+  return { modules, skipped };
+}
+
+/** The wrapper entry. `coverage: true` is the variant that collects precise coverage. */
+export function wrapperModule(outDir, target, { coverage = false } = {}) {
+  const spec = JSON.stringify(`./${target}`);
+  const contents = coverage
+    ? `import { Session } from 'node:inspector/promises';
+export default {
+  async fetch() {
+    let s;
+    try { s = new Session(); s.connect(); } catch (e) { return Response.json({ unsupported: String((e && e.code) || e) }); }
+    await s.post('Profiler.enable');
+    await s.post('Profiler.startPreciseCoverage', { callCount: true, detailed: true });
+    let error = null;
+    try { await import(${spec}); } catch (e) { error = String((e && e.stack) || e); }
+    const { result } = await s.post('Profiler.takePreciseCoverage');
+    await s.post('Profiler.stopPreciseCoverage');
+    s.disconnect();
+    return Response.json({ error, result });
+  }
+};
+`
+    : `let mod = null;
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    if (url.pathname === ${JSON.stringify(LAB_IMPORT_PATH)}) {
+      let error = null;
+      try { mod = await import(${spec}); } catch (e) { error = String((e && e.stack) || e); }
+      return new Response(error ? 'startup threw: ' + error : 'ok', { status: error ? 500 : 200 });
+    }
+    mod ??= await import(${spec});
+    const handler = mod.default && mod.default.fetch ? mod.default : null;
+    if (!handler) return new Response('no default export with fetch', { status: 501 });
+    return handler.fetch(request, env, ctx);
+  }
+};
+`;
+  return { type: 'ESModule', path: path.join(outDir, WRAPPER_NAME), contents };
+}
+
+export const emptyModule = (outDir) => ({
+  type: 'ESModule',
+  path: path.join(outDir, EMPTY_NAME),
+  contents: 'export {};\n',
+});
+
+/**
+ * Static assets answer before the worker unless a route is listed as worker-first; with
+ * SPA fallback every unknown path becomes `index.html`, lab routes included - and that
+ * answer is a 200, so the import silently never runs. Lab routes go worker-first.
+ */
+export function labAssetsRouting(assets) {
+  if (!assets) return assets;
+  const router = { ...assets.routerConfig, has_user_worker: true };
+  const routing = { ...router.static_routing };
+  routing.user_worker = ['/__lab/*', ...(routing.user_worker ?? [])];
+  router.static_routing = routing;
+  return { ...assets, routerConfig: router };
+}
+
+/** Deduplicated workerd stderr, printed once at the end instead of once per run. */
+export function createStderrCollector() {
+  const lines = new Map();
+  return {
+    lines,
+    handleRuntimeStdio(stdout, stderr) {
+      stdout.on('data', () => {});
+      stderr.on('data', (chunk) => {
+        for (const line of String(chunk).split('\n')) {
+          const key = line.replace(/\s+/g, ' ').trim().slice(0, 220);
+          if (key) lines.set(key, (lines.get(key) ?? 0) + 1);
+        }
+      });
+    },
+  };
+}
+
+/**
+ * One miniflare instance. `ctx` is the resolved worker context (tools, workerOptions,
+ * outDir, mainName, modules). Options: `target` (module the wrapper imports), `coverage`
+ * (coverage wrapper), `extraFlags` (compatibility flags added for this instance only),
+ * `shared` (top-level miniflare options such as `inspectorPort`), `plain` (real entry).
+ */
+export async function createInstance(
+  ctx,
+  { target, coverage = false, extraFlags = [], shared = {}, plain = false, tools = null } = {},
+) {
+  const mod = tools ?? ctx.tools;
+  await mod.load();
+  const { Log, LogLevel } = mod.miniflare;
+  const appFlags = ctx.workerOptions.compatibilityFlags ?? [];
+  const flat = {
+    ...ctx.workerOptions,
+    name: 'lab',
+    compatibilityFlags: [...new Set([...appFlags, ...extraFlags])],
+    modulesRoot: ctx.outDir,
+    handleRuntimeStdio: ctx.stderr.handleRuntimeStdio,
+    log: new Log(LogLevel.WARN),
+    ...shared,
+  };
+  if (plain) {
+    const mainModule = ctx.modules.find((m) => m.rel === ctx.mainName);
+    if (!mainModule) throw new Error(`main module ${ctx.mainName} is not among the output modules`);
+    flat.modules = [mainModule, ...ctx.modules.filter((m) => m !== mainModule)];
+  } else {
+    flat.modules = [
+      wrapperModule(ctx.outDir, target ?? ctx.mainName, { coverage }),
+      emptyModule(ctx.outDir),
+      ...ctx.modules,
+    ];
+    delete flat.durableObjects;
+    delete flat.workflows;
+    if (flat.assets) flat.assets = labAssetsRouting(flat.assets);
+  }
+  const mf = new mod.miniflare.Miniflare(mod.toOptions(flat));
+  await mf.ready;
+  return mf;
+}
+
+export async function fetchText(mf, p, { timeoutMs = 120_000 } = {}) {
+  const res = await mf.dispatchFetch(`http://lab${p}`, { signal: AbortSignal.timeout(timeoutMs) });
+  return { status: res.status, text: await res.text() };
+}
+
+export async function disposeQuietly(mf) {
+  try {
+    await mf.dispose();
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * One cold run: a fresh instance, then the time of the lab import request as seen from
+ * the host. Timers inside workerd advance only on I/O, so the Worker cannot time itself.
+ * `bootMs` (instance creation to ready) is reported but never counted: it is workerd
+ * process start, config load and wasm compile, not the Worker's global scope.
+ */
+export async function timedImport(ctx, { target } = {}) {
+  const b0 = performance.now();
+  const mf = await createInstance(ctx, { target });
+  const bootMs = performance.now() - b0;
+  try {
+    const t0 = performance.now();
+    const { status, text } = await fetchText(mf, LAB_IMPORT_PATH);
+    const ms = performance.now() - t0;
+    if (status !== 200 || text !== 'ok') {
+      throw new Error(`the lab import route did not run (${status}): ${text.slice(0, 600)}`);
+    }
+    return { ms, bootMs };
+  } finally {
+    await disposeQuietly(mf);
+  }
+}

package/lib/worker/measure.mjs

@@ -0,0 +1,296 @@
+// Startup measurement for Cloudflare Workers: timed cold runs, first requests on the real
+// entry, a CPU profile over the external inspector, and precise coverage from inside the
+// isolate. Nothing here re-implements analysis the other modes have: the profile and
+// coverage transforms are the shared ones, only the acquisition differs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { pathToFileURL } from 'node:url';
+
+import { connect } from '../cdp.mjs';
+import { median, quantile } from '../measure.mjs';
+import { attributeStartupCoverage, profileStartup } from '../node/measure.mjs';
+import {
+  COVERAGE_FLAGS,
+  COVERAGE_MIN_WRANGLER,
+  EMPTY_NAME,
+  LAB_COVERAGE_PATH,
+  LAB_IMPORT_PATH,
+  WRAPPER_NAME,
+  createInstance,
+  disposeQuietly,
+  fetchText,
+  timedImport,
+  versionAtLeast,
+} from './launch.mjs';
+
+// The measured window excludes process boot, so the jitter is the host round trip to
+// workerd: 1-2 ms on the floor runs seen so far. The floor is set above that, never below.
+export const NOISE_FLOOR_MS = 3;
+export const NOISE_FLOOR_PCT = 2;
+export const COLD_MIN_BYTES = 4 * 1024;
+
+const round1 = (v) => (v == null ? null : Math.round(v * 10) / 10);
+
+/** N cold runs of one target (the main module, or the empty module for the floor). */
+export async function gatherSeries(ctx, { target, runs, warmup = 1, onSample = null }) {
+  for (let i = 0; i < warmup; i++) await timedImport(ctx, { target });
+  const samples = [];
+  for (let i = 0; i < runs; i++) {
+    const run = await timedImport(ctx, { target });
+    samples.push(run);
+    onSample?.(i, run);
+  }
+  return samples;
+}
+
+/**
+ * Fold the two series into the flat metric map. The floor is what the wrapper costs
+ * when it imports an empty module: the host round trip, the proxy hop and the dynamic
+ * import machinery. App startup is what is left, the part a bundle change can move.
+ */
+export function summarizeWorkerStartup({ floor, main }) {
+  const floorMs = floor.map((s) => s.ms);
+  const mainMs = main.map((s) => s.ms);
+  const floorMedian = median(floorMs);
+  const mainMedian = median(mainMs);
+  const spread =
+    mainMs.length > 1 && mainMedian > 0
+      ? ((Math.max(...mainMs) - Math.min(...mainMs)) / mainMedian) * 100
+      : 0;
+  return {
+    runs: main.length,
+    metrics: {
+      'worker.startup_ms': round1(mainMedian),
+      'worker.startup_p75_ms': round1(quantile(mainMs, 0.75)),
+      'worker.boot_floor_ms': round1(floorMedian),
+      'worker.app_startup_ms': round1(Math.max(0, mainMedian - floorMedian)),
+      'worker.instance_boot_ms': round1(median(main.map((s) => s.bootMs))),
+    },
+    guard: {
+      allRunsCompleted: main.length > 0 && main.every((s) => typeof s.ms === 'number'),
+      spreadPct: Math.round(spread * 10) / 10,
+    },
+    samples: { floor: floorMs.map(round1), main: mainMs.map(round1) },
+  };
+}
+
+/**
+ * First requests on a plain instance: the real entry, every export in place, startup
+ * already done at boot. The first hit of a route that imports a deferred module pays
+ * that load, which is the cost a deferral moved out of startup.
+ */
+export async function firstRequests(ctx, paths) {
+  const mf = await createInstance(ctx, { plain: true });
+  const rows = [];
+  try {
+    for (const p of paths) {
+      const t0 = performance.now();
+      const { status, text } = await fetchText(mf, p);
+      rows.push({
+        path: p,
+        status,
+        bytes: text.length,
+        ms: round1(performance.now() - t0),
+        error: status >= 500 ? text.slice(0, 200).replace(/\s+/g, ' ') : null,
+      });
+    }
+  } finally {
+    await disposeQuietly(mf);
+  }
+  return rows;
+}
+
+/**
+ * CPU profile of the import, over the external inspector. workerd serves `Profiler.start`
+ * and `stop` itself with its own CpuProfiler, so this route works on every workerd.
+ */
+export async function cpuProfileRun(ctx, { intervalUs = 100 } = {}) {
+  const mf = await createInstance(ctx, { shared: { inspectorPort: 0 } });
+  let cdp = null;
+  try {
+    const inspectorUrl = await mf.getInspectorURL();
+    cdp = await connect(new URL('/core:user:lab', inspectorUrl).href);
+    await cdp.send('Profiler.enable');
+    await cdp.send('Profiler.setSamplingInterval', { interval: intervalUs });
+    await cdp.send('Profiler.start');
+    const imported = await fetchText(mf, LAB_IMPORT_PATH);
+    const { profile } = await cdp.send('Profiler.stop');
+    return {
+      profile,
+      importRan: imported.status === 200 && imported.text === 'ok',
+      importText: imported.text,
+    };
+  } finally {
+    try {
+      cdp?.close();
+    } catch {
+      /* closed */
+    }
+    await disposeQuietly(mf);
+  }
+}
+
+/** The summary `wrangler check startup` prints, so the two tools agree on their terms. */
+export function summarizeProfile(profile) {
+  const nodes = new Map(profile.nodes.map((n) => [n.id, n]));
+  let sampled = 0;
+  let idle = 0;
+  let gc = 0;
+  let program = 0;
+  (profile.timeDeltas ?? []).forEach((d, i) => {
+    sampled += d;
+    const fn = nodes.get(profile.samples[i])?.callFrame.functionName;
+    if (fn === '(idle)') idle += d;
+    else if (fn === '(garbage collector)') gc += d;
+    else if (fn === '(program)') program += d;
+  });
+  return {
+    windowMs: round1((profile.endTime - profile.startTime) / 1000),
+    sampledMs: round1(sampled / 1000),
+    activeMs: round1((sampled - idle) / 1000),
+    gcMs: round1(gc / 1000),
+    programMs: round1(program / 1000),
+    idleMs: round1(idle / 1000),
+    samples: profile.samples.length,
+  };
+}
+
+/**
+ * Map a script URL onto the output dir. Miniflare reports `file://` paths on one version
+ * and bare module names on another, and a profile recorded elsewhere carries another
+ * directory: the longest path suffix that exists under the output dir wins.
+ */
+export function localFile(url, outDir) {
+  if (!url || /^[a-z-]+:(?!\/\/)/.test(url)) return null;
+  const parts = (url.startsWith('file://') ? new URL(url).pathname : url)
+    .split('/')
+    .filter(Boolean);
+  for (let i = 0; i < parts.length; i++) {
+    const candidate = path.join(outDir, parts.slice(i).join('/'));
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** `readChunk` for `profileStartup`: every chunk under the output dir that has a sourcemap. */
+export function chunkResolver(outDir) {
+  return (frameFile) => {
+    const file = localFile(frameFile, outDir);
+    if (!file || !fs.existsSync(`${file}.map`)) return null;
+    return {
+      code: fs.readFileSync(file, 'utf8'),
+      map: JSON.parse(fs.readFileSync(`${file}.map`, 'utf8')),
+    };
+  };
+}
+
+/** Self time by source module through every chunk's sourcemap, plus the wrangler-style summary. */
+export function attributeProfile(profile, { outDir, mainName }) {
+  const summary = summarizeProfile(profile);
+  const mapFile = path.join(outDir, `${mainName}.map`);
+  if (!fs.existsSync(mapFile))
+    return { summary, rows: null, totalMs: null, ownership: null, missingSourcemap: true };
+  const code = fs.readFileSync(path.join(outDir, mainName), 'utf8');
+  const map = JSON.parse(fs.readFileSync(mapFile, 'utf8'));
+  const { rows, totalMs, ownership } = profileStartup(profile, {
+    code,
+    map,
+    entryPath: path.join(outDir, mainName),
+    readChunk: chunkResolver(outDir),
+    baseUrl: pathToFileURL(`${outDir}/`),
+  });
+  return { summary, rows, totalMs, ownership, missingSourcemap: false };
+}
+
+/**
+ * Precise coverage of the import, taken from INSIDE the isolate. The external inspector
+ * cannot do it: workerd answers `Profiler.enable` itself and never forwards it to V8, so
+ * `Profiler.startPreciseCoverage` fails with "Profiler is not enabled". The in-process
+ * `node:inspector` session needs two compatibility flags, added for this run only, and a
+ * workerd from 1.20260706.1 on. `tools` may point at a newer wrangler than the app's; the
+ * timing and the profile keep the app's own workerd regardless.
+ */
+export async function coverageRun(ctx, { tools = null } = {}) {
+  const used = tools ?? ctx.tools;
+  const appFlags = ctx.workerOptions.compatibilityFlags ?? [];
+  const addedFlags = COVERAGE_FLAGS.filter((f) => !appFlags.includes(f));
+  const base = {
+    source: null,
+    result: null,
+    addedFlags,
+    workerd: used.versions.workerd,
+    borrowed: Boolean(tools),
+  };
+  if (!versionAtLeast(used.versions.wrangler, COVERAGE_MIN_WRANGLER)) {
+    return {
+      ...base,
+      unsupported: `wrangler ${used.versions.wrangler ?? '?'} (workerd ${used.versions.workerd ?? '?'}) predates the in-process inspector session; needs wrangler ${COVERAGE_MIN_WRANGLER} or later. Update wrangler, or pass --tools <dir> with a newer one for this run.`,
+    };
+  }
+  const mf = await createInstance(ctx, { coverage: true, extraFlags: COVERAGE_FLAGS, tools: used });
+  try {
+    const { status, text } = await fetchText(mf, LAB_COVERAGE_PATH);
+    if (status !== 200)
+      return { ...base, unsupported: `coverage route answered ${status}: ${text.slice(0, 200)}` };
+    const body = JSON.parse(text);
+    if (body.unsupported)
+      return {
+        ...base,
+        unsupported: `node:inspector session unavailable (${body.unsupported}) on workerd ${used.versions.workerd}`,
+      };
+    return { ...base, result: body.result, importError: body.error ?? null, unsupported: null };
+  } finally {
+    await disposeQuietly(mf);
+  }
+}
+
+/** The package a sourcemap source belongs to, or `(app)`. */
+export function packageOf(source) {
+  const m = String(source).match(/node_modules\/((?:@[^/]+\/)?[^/]+)/g);
+  return m ? m[m.length - 1].replace('node_modules/', '') : '(app)';
+}
+
+/**
+ * Coverage attribution plus the views a real app needs: the 2% cold filter finds almost
+ * nothing on real libraries, which run 5-30% of themselves at startup, so rank by bytes
+ * parsed but not executed, and group by package.
+ */
+export function attributeCoverage(result, { outDir }) {
+  const runtimeScripts = result
+    .filter((s) =>
+      /^(node|node-internal|cloudflare|cloudflare-internal|workerd):/.test(s.url ?? ''),
+    )
+    .map((s) => s.url);
+  const local = [];
+  for (const script of result) {
+    const file = localFile(script.url, outDir);
+    if (!file || file.endsWith(WRAPPER_NAME) || file.endsWith(EMPTY_NAME)) continue;
+    local.push({ ...script, url: `file://${file}` });
+  }
+  const attributed = attributeStartupCoverage(local, { root: outDir });
+  const modules = attributed.modules.map((m) => ({ ...m, idleBytes: m.totalBytes - m.readyBytes }));
+  const totalBytes = modules.reduce((a, m) => a + m.totalBytes, 0);
+  const readyBytes = modules.reduce((a, m) => a + m.readyBytes, 0);
+  const byPackage = new Map();
+  for (const m of modules) {
+    const key = packageOf(m.source);
+    const row = byPackage.get(key) ?? { pkg: key, totalBytes: 0, readyBytes: 0, modules: 0 };
+    row.totalBytes += m.totalBytes;
+    row.readyBytes += m.readyBytes;
+    row.modules += 1;
+    byPackage.set(key, row);
+  }
+  return {
+    scripts: attributed.scripts,
+    runtimeScripts,
+    modules,
+    totals: { totalBytes, readyBytes, moduleCount: modules.length },
+    cold: modules
+      .filter((m) => m.totalBytes >= COLD_MIN_BYTES && m.readyRatio <= 0.02)
+      .sort((a, b) => b.totalBytes - a.totalBytes),
+    idle: [...modules].sort((a, b) => b.idleBytes - a.idleBytes),
+    packages: [...byPackage.values()].sort((a, b) => b.totalBytes - a.totalBytes),
+  };
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "rolldown-perf-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Experimental build of rolldown's perf-kit (feat/metrics-lab-field-replay @ 6e578fb57 (with uncommitted changes)). Performance harness for agent loops: throttled browser runs with first-paint coverage and boot profile, node/deno startup runs, static deferral planning on the module graph.",
+  "bin": {
+    "rolldown-perf-kit": "./harness.mjs",
+    "perf-kit": "./harness.mjs",
+    "perf-kit-replay": "./replay.mjs"
+  },
+  "files": [
+    "harness.mjs",
+    "replay.mjs",
+    "lib",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rolldown/rolldown.git",
+    "directory": "packages/perf-kit"
+  },
+  "homepage": "https://github.com/rolldown/rolldown/tree/main/packages/perf-kit",
+  "keywords": [
+    "rolldown",
+    "vite",
+    "performance",
+    "startup",
+    "lcp",
+    "cloudflare-workers",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}