*/
+export function shallowWide() {
+ const children = Array.from({ length: 1000 }, (_, i) =>
+ React.createElement("span", { key: i }, `item ${i}`)
+ );
+ return React.createElement("div", null, ...children);
+}
+
+/** 100-level deep nesting: div > div > ... > span */
+export function deepNested(depth = 100) {
+ let el = React.createElement("span", null, "leaf");
+ for (let i = 0; i < depth; i++) {
+ el = React.createElement("div", { key: i }, el);
+ }
+ return el;
+}
+
+/** Realistic product list with structured children */
+export function productList(count = 50) {
+ const items = Array.from({ length: count }, (_, i) =>
+ React.createElement(
+ "li",
+ { key: i, className: "product" },
+ React.createElement("h3", null, `Product ${i}`),
+ React.createElement(
+ "p",
+ null,
+ `Description for product ${i} with some details about features and specifications.`
+ ),
+ React.createElement(
+ "span",
+ { className: "price" },
+ `$${(i * 9.99).toFixed(2)}`
+ ),
+ React.createElement(
+ "span",
+ { className: "rating" },
+ `${(3 + Math.random() * 2).toFixed(1)} stars`
+ )
+ )
+ );
+ return React.createElement("ul", { className: "product-list" }, ...items);
+}
+
+/** 500-row x 10-column table */
+export function largeTable(rows = 500, cols = 10) {
+ const headerCells = Array.from({ length: cols }, (_, c) =>
+ React.createElement("th", { key: c }, `Col ${c}`)
+ );
+ const header = React.createElement(
+ "thead",
+ null,
+ React.createElement("tr", null, ...headerCells)
+ );
+
+ const bodyRows = Array.from({ length: rows }, (_, r) => {
+ const cells = Array.from({ length: cols }, (_, c) =>
+ React.createElement("td", { key: c }, `r${r}c${c}`)
+ );
+ return React.createElement("tr", { key: r }, ...cells);
+ });
+ const body = React.createElement("tbody", null, ...bodyRows);
+
+ return React.createElement("table", null, header, body);
+}
+
+// ── Data Type Fixtures ──────────────────────────────────────────
+
+/** Primitive values: string, number, boolean, null */
+export function primitives() {
+ return {
+ str: "hello world",
+ num: 42,
+ float: Math.PI,
+ bool: true,
+ nil: null,
+ negZero: -0,
+ inf: Infinity,
+ negInf: -Infinity,
+ nan: NaN,
+ };
+}
+
+/** 100KB string payload */
+export function largeString() {
+ return "x".repeat(100_000);
+}
+
+/** 20-level deep nested object */
+export function nestedObjects() {
+ const build = (depth) =>
+ depth === 0
+ ? { leaf: true, value: "terminal" }
+ : { child: build(depth - 1), value: depth, label: `level-${depth}` };
+ return build(20);
+}
+
+/** 10,000-element array of objects */
+export function largeArray() {
+ return Array.from({ length: 10_000 }, (_, i) => ({
+ id: i,
+ name: `item-${i}`,
+ active: i % 2 === 0,
+ }));
+}
+
+/** Map with 100 entries, Set with 100 entries */
+export function mapAndSet() {
+ return {
+ map: new Map(
+ Array.from({ length: 100 }, (_, i) => [
+ `key-${i}`,
+ { index: i, data: `val-${i}` },
+ ])
+ ),
+ set: new Set(Array.from({ length: 100 }, (_, i) => i * 7)),
+ };
+}
+
+/** Date, BigInt, Infinity, NaN, Symbol.for, RegExp */
+export function specialTypes() {
+ return {
+ date: new Date("2024-06-15T12:00:00Z"),
+ bigint: BigInt("12345678901234567890"),
+ sym: Symbol.for("bench.symbol"),
+ };
+}
+
+/** Typed arrays: Uint8Array (10KB), Int32Array (20KB), Float64Array (20KB) */
+export function typedArrays() {
+ const uint8 = new Uint8Array(10_000);
+ const int32 = new Int32Array(5_000);
+ const float64 = new Float64Array(2_500);
+ // Fill with non-zero data to avoid compression shortcuts
+ for (let i = 0; i < uint8.length; i++) uint8[i] = i & 0xff;
+ for (let i = 0; i < int32.length; i++) int32[i] = i * 17;
+ for (let i = 0; i < float64.length; i++) float64[i] = i * 0.123;
+ return { uint8, int32, float64 };
+}
+
+/** Mixed payload combining React elements, collections, and binary data */
+export function mixedPayload() {
+ return {
+ tree: productList(10),
+ data: Array.from({ length: 100 }, (_, i) => ({ id: i, name: `item-${i}` })),
+ map: new Map([
+ ["alpha", 1],
+ ["beta", 2],
+ ["gamma", 3],
+ ]),
+ date: new Date("2025-01-01T00:00:00Z"),
+ bigint: BigInt(999),
+ buffer: new Uint8Array(1000).fill(42),
+ };
+}
+
+// ── Scenario registry ───────────────────────────────────────────
+
+/**
+ * All scenarios keyed by name.
+ * Each bench file iterates this to generate benchmarks programmatically.
+ */
+export const scenarios = {
+ // React trees
+ "react: minimal element": minimalElement,
+ "react: shallow wide (1000)": shallowWide,
+ "react: deep nested (100)": deepNested,
+ "react: product list (50)": productList,
+ "react: large table (500x10)": largeTable,
+ // Data types
+ "data: primitives": primitives,
+ "data: large string (100KB)": largeString,
+ "data: nested objects (20)": nestedObjects,
+ "data: large array (10K)": largeArray,
+ "data: Map & Set": mapAndSet,
+ "data: Date/BigInt/Symbol": specialTypes,
+ "data: typed arrays": typedArrays,
+ "data: mixed payload": mixedPayload,
+};
diff --git a/packages/rsc/__bench__/report.mjs b/packages/rsc/__bench__/report.mjs
new file mode 100644
index 00000000..42f57414
--- /dev/null
+++ b/packages/rsc/__bench__/report.mjs
@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+/**
+ * Flight Protocol Benchmark Report Generator
+ *
+ * Reads vitest bench JSON output (--outputJson), normalizes it, optionally
+ * compares against a baseline, and produces a markdown report suitable for
+ * GitHub PR comments.
+ *
+ * Usage:
+ * node __bench__/report.mjs --current bench-raw.json [options]
+ *
+ * Options:
+ * --current
Vitest bench JSON output (required)
+ * --baseline Previous results JSON for comparison
+ * --output Write normalized JSON results (default: bench-results.json)
+ * --markdown Write markdown report (default: comment.md)
+ * --commit Git commit SHA (auto-detected if omitted)
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+// ── CLI args ────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+function getArg(name, defaultValue = null) {
+ const idx = args.indexOf(`--${name}`);
+ return idx !== -1 && args[idx + 1] ? args[idx + 1] : defaultValue;
+}
+
+const currentFile = getArg("current");
+const baselineFile = getArg("baseline");
+const outputFile = getArg("output", "bench-results.json");
+const markdownFile = getArg("markdown", "comment.md");
+let commitSha = getArg("commit");
+
+if (!currentFile) {
+ console.error("Usage: node report.mjs --current ");
+ process.exit(1);
+}
+
+if (!commitSha) {
+ try {
+ commitSha = execSync("git rev-parse HEAD", { encoding: "utf8" }).trim();
+ } catch {
+ commitSha = "unknown";
+ }
+}
+
+const shortSha = commitSha.slice(0, 7);
+
+// ── Parse vitest bench output ───────────────────────────────────
+
+const raw = JSON.parse(readFileSync(currentFile, "utf8"));
+
+/**
+ * Vitest bench --outputJson format (v4.x):
+ * {
+ * files: [
+ * {
+ * filepath: "...",
+ * groups: [
+ * {
+ * fullName: "file > group name",
+ * benchmarks: [
+ * {
+ * name: "bench name",
+ * hz: number,
+ * mean: number,
+ * p75: number,
+ * p99: number,
+ * min: number,
+ * max: number,
+ * rme: number,
+ * sampleCount: number,
+ * ...
+ * }
+ * ]
+ * }
+ * ]
+ * }
+ * ]
+ * }
+ */
+
+function parseVitestBench(data) {
+ const results = {};
+
+ const files = data.files || [];
+ for (const file of files) {
+ for (const group of file.groups || []) {
+ // fullName is "file > group name" — extract just the group name
+ const fullName = group.fullName || "";
+ const groupName = fullName.includes(" > ")
+ ? fullName.split(" > ").slice(1).join(" > ")
+ : fullName;
+
+ if (!results[groupName]) results[groupName] = {};
+
+ for (const bench of group.benchmarks || []) {
+ results[groupName][bench.name] = {
+ hz: bench.hz,
+ mean: bench.mean,
+ p75: bench.p75,
+ p99: bench.p99,
+ min: bench.min,
+ max: bench.max,
+ sampleCount: bench.sampleCount,
+ rme: bench.rme,
+ };
+ }
+ }
+ }
+
+ return results;
+}
+
+const results = parseVitestBench(raw);
+
+// ── Write normalized JSON ───────────────────────────────────────
+
+const normalized = {
+ commit: commitSha,
+ shortCommit: shortSha,
+ date: new Date().toISOString(),
+ results,
+};
+
+writeFileSync(outputFile, JSON.stringify(normalized, null, 2) + "\n");
+console.log(`Normalized results written to ${outputFile}`);
+
+// ── Load baseline ───────────────────────────────────────────────
+
+let baseline = null;
+if (baselineFile) {
+ try {
+ baseline = JSON.parse(readFileSync(baselineFile, "utf8"));
+ console.log(
+ `Loaded baseline from ${baselineFile} (${baseline.shortCommit || "unknown"})`
+ );
+ } catch (e) {
+ console.warn(`Warning: could not load baseline: ${e.message}`);
+ }
+}
+
+// ── Group mapping ───────────────────────────────────────────────
+
+/**
+ * Maps bench group names to library identifiers and operation types.
+ * Group names come from the describe() blocks in bench files.
+ */
+const GROUP_MAP = {
+ "@lazarv/rsc serialize": { lib: "lazarv", op: "serialize" },
+ "@lazarv/rsc prerender": { lib: "lazarv", op: "prerender" },
+ "@lazarv/rsc deserialize": { lib: "lazarv", op: "deserialize" },
+ "@lazarv/rsc roundtrip": { lib: "lazarv", op: "roundtrip" },
+ "webpack serialize": { lib: "webpack", op: "serialize" },
+ "webpack deserialize": { lib: "webpack", op: "deserialize" },
+ "webpack roundtrip": { lib: "webpack", op: "roundtrip" },
+};
+
+/**
+ * Build a lookup: { [op]: { [scenarioName]: { lazarv: benchData, webpack: benchData } } }
+ */
+function buildComparison(data) {
+ const comparison = {};
+ for (const [group, benches] of Object.entries(data)) {
+ const mapped = GROUP_MAP[group];
+ if (!mapped) continue;
+ const { lib, op } = mapped;
+ if (!comparison[op]) comparison[op] = {};
+ for (const [name, bench] of Object.entries(benches)) {
+ if (!comparison[op][name]) comparison[op][name] = {};
+ comparison[op][name][lib] = bench;
+ }
+ }
+ return comparison;
+}
+
+const current = buildComparison(results);
+const base = baseline ? buildComparison(baseline.results) : null;
+
+// ── Markdown generation ─────────────────────────────────────────
+
+function fmtHz(hz) {
+ if (hz >= 1_000_000) return `${(hz / 1_000_000).toFixed(1)}M`;
+ if (hz >= 1_000) return `${(hz / 1_000).toFixed(1)}K`;
+ return hz.toFixed(0);
+}
+
+function fmtTime(ms) {
+ if (ms < 0.001) return `${(ms * 1_000_000).toFixed(0)} ns`;
+ if (ms < 1) return `${(ms * 1_000).toFixed(1)} \u00b5s`;
+ return `${ms.toFixed(2)} ms`;
+}
+
+function fmtDelta(current, base, lowerIsBetter = false) {
+ if (base == null || base === 0) return "";
+ const pct = ((current - base) / base) * 100;
+ const sign = pct > 0 ? "+" : "";
+ const good = lowerIsBetter ? pct < -1 : pct > 1;
+ const bad = lowerIsBetter ? pct > 1 : pct < -1;
+ const icon = good ? "\u{1f7e2}" : bad ? "\u{1f534}" : "\u{26aa}";
+ return `${icon} ${sign}${pct.toFixed(1)}%`;
+}
+
+function fmtLibDelta(lazarvHz, webpackHz) {
+ if (!webpackHz || webpackHz === 0) return "";
+ const pct = ((lazarvHz - webpackHz) / webpackHz) * 100;
+ const sign = pct > 0 ? "+" : "";
+ const icon = pct > 1 ? "\u{1f7e2}" : pct < -1 ? "\u{1f534}" : "\u{26aa}";
+ return `${icon} ${sign}${pct.toFixed(1)}%`;
+}
+
+const lines = [];
+lines.push("");
+lines.push("## \u26a1 Flight Protocol Benchmark");
+lines.push("");
+
+if (baseline) {
+ lines.push(
+ `Comparing \`${shortSha}\` against baseline \`${baseline.shortCommit || "?"}\``
+ );
+} else {
+ lines.push(`Commit: \`${shortSha}\``);
+}
+lines.push("");
+
+// Operation order for the report
+const OP_ORDER = ["serialize", "prerender", "deserialize", "roundtrip"];
+const OP_LABELS = {
+ serialize: "Serialization (`renderToReadableStream`)",
+ prerender: "Prerender (`prerender`)",
+ deserialize: "Deserialization (`createFromReadableStream`)",
+ roundtrip: "Roundtrip (serialize + deserialize)",
+};
+
+for (const op of OP_ORDER) {
+ const scenarios = current[op];
+ if (!scenarios) continue;
+
+ lines.push(`### ${OP_LABELS[op]}`);
+ lines.push("");
+
+ if (baseline) {
+ if (op === "prerender") {
+ lines.push("| Scenario | @lazarv/rsc ops/s | mean | vs baseline |");
+ lines.push("|:---------|------------------:|-----:|------------:|");
+ } else {
+ lines.push(
+ "| Scenario | @lazarv/rsc | webpack | vs webpack | vs baseline |"
+ );
+ lines.push(
+ "|:---------|------------:|--------:|-----------:|------------:|"
+ );
+ }
+ } else {
+ if (op === "prerender") {
+ lines.push("| Scenario | @lazarv/rsc ops/s | mean |");
+ lines.push("|:---------|------------------:|-----:|");
+ } else {
+ lines.push("| Scenario | @lazarv/rsc | webpack | vs webpack |");
+ lines.push("|:---------|------------:|--------:|-----------:|");
+ }
+ }
+
+ for (const [name, libs] of Object.entries(scenarios)) {
+ const lazarv = libs.lazarv;
+ const webpack = libs.webpack;
+
+ if (op === "prerender") {
+ if (lazarv) {
+ if (baseline) {
+ const baseRsc = base?.[op]?.[name]?.lazarv;
+ const baselineDelta = baseRsc ? fmtDelta(lazarv.hz, baseRsc.hz) : "-";
+ lines.push(
+ `| **${name}** | ${fmtHz(lazarv.hz)} | ${fmtTime(lazarv.mean)} | ${baselineDelta} |`
+ );
+ } else {
+ lines.push(
+ `| **${name}** | ${fmtHz(lazarv.hz)} | ${fmtTime(lazarv.mean)} |`
+ );
+ }
+ }
+ continue;
+ }
+
+ const lazarvHz = lazarv ? fmtHz(lazarv.hz) : "-";
+ const webpackHz = webpack ? fmtHz(webpack.hz) : "-";
+ const delta = lazarv && webpack ? fmtLibDelta(lazarv.hz, webpack.hz) : "-";
+
+ if (baseline) {
+ const baseRsc = base?.[op]?.[name]?.lazarv;
+ const baselineDelta = baseRsc
+ ? fmtDelta(lazarv?.hz || 0, baseRsc.hz)
+ : "-";
+ lines.push(
+ `| **${name}** | ${lazarvHz} | ${webpackHz} | ${delta} | ${baselineDelta} |`
+ );
+ } else {
+ lines.push(`| **${name}** | ${lazarvHz} | ${webpackHz} | ${delta} |`);
+ }
+ }
+
+ lines.push("");
+}
+
+// ── Legend ───────────────────────────────────────────────────────
+
+lines.push("Legend & methodology
");
+lines.push("");
+lines.push(
+ "**Indicators:** \u{1f7e2} > 1% faster | \u{1f534} > 1% slower | \u{26aa} within noise margin"
+);
+lines.push("");
+lines.push(
+ "**vs webpack**: compares @lazarv/rsc against react-server-dom-webpack within the same run."
+);
+lines.push(
+ "**vs baseline**: compares @lazarv/rsc against the previous main branch run."
+);
+lines.push("");
+lines.push(
+ "Values shown are operations/second (higher is better). Each scenario runs for at least 100 iterations with warmup."
+);
+lines.push("");
+lines.push(
+ "Benchmarks run on GitHub Actions runners (shared infrastructure) \u2014 expect ~5% variance between runs. Consistent directional changes across multiple scenarios are more meaningful than any single number."
+);
+lines.push("");
+lines.push("