Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
/**
* Turn perf-artifacts/switch-events.json into a human-readable
* perf-artifacts/switch-report.md.
*
* The correlation core (`analyzeSwitch`, `renderReport`) is pure and exported
* for unit testing — no filesystem, no browser.
*/
import { readFileSync, rmSync, writeFileSync } from "node:fs"
import { resolve } from "node:path"
import type {
CaptureFile,
CapturedSwitch,
CapturedResource,
} from "../src/test/e2e-ui/perf/perf-capture-types"
const ARTIFACTS_DIR = resolve(import.meta.dirname, "..", "perf-artifacts")
const CAPTURE_IN = resolve(ARTIFACTS_DIR, "switch-events.json")
const REPORT_OUT = resolve(ARTIFACTS_DIR, "switch-report.md")
export function clearPerfArtifacts(capturePath = CAPTURE_IN, reportPath = REPORT_OUT): void {
rmSync(capturePath, { force: true })
rmSync(reportPath, { force: true })
}
export interface SwitchAnalysis {
kind: string
targetId: string
cacheState: string
contentChannelId: string | null
contentKind: "messages" | "empty" | null
/** click → content-stable (or painted if no resize settle). The headline. */
perceivedMs: number | null
clickToSkeletonMs: number | null
skeletonToPaintedMs: number | null
paintedToStableMs: number | null
/** sum of gaps where exactly one /api/community request was in flight. */
networkMs: number
/** wall time from first request start to last response end. */
networkSpanMs: number
/** true if read-state's response-end precedes messages' request-start. */
readStateBlocksMessages: boolean | null
/** Total mount events reported by react-scan across all commits — INFLATED:
* the ring buffer re-reports every still-mounted fiber on each subsequent
* commit, so a single first-mount shows up once per later commit. */
mountCountRaw: number
/** Distinct fiber ids that mounted — the real "how many components first
* mounted this switch". This is the trustworthy render-cost number. */
mountCountUnique: number
/** Total re-render events. Unlike mounts these are NOT inflated: each
* (fiberId, commit, duration) triple is unique, so a fiber re-rendering N
* times across N commits is N genuine renders. */
rerenderCountRaw: number
/** Distinct fiber ids that re-rendered at least once. */
rerenderCountUnique: number
unmounts: string[]
topRenders: Array<{ name: string; count: number; reason?: string }>
/** attribution of the perceived total. */
verdict: string
}
function findResource(resources: CapturedResource[], needle: string): CapturedResource | undefined {
return resources.find((r) => r.name.includes(needle))
}
/**
* Count mount events two ways. react-scan's ring buffer re-reports every
* still-mounted fiber on each subsequent commit, so `mountRaw` (the naive
* total) is inflated 6-13× by that echo — an earlier heuristic tried to undo
* it by "halving fibers seen an even number of times", but the real repeat
* rate isn't 2× and that produced numbers ~3-4× too high. A first mount is
* unique per fiber by definition, so deduping by fiberId is lossless and
* yields the true count. Fibers without an id (rare) each count as their own
* mount — they can't be deduped and dropping them would under-count.
*/
function countMounts(sw: CapturedSwitch): { mountRaw: number; mountUnique: number } {
let mountRaw = 0
const ids = new Set<number>()
let idless = 0
for (const commit of sw.commits) {
for (const m of commit.mounts) {
mountRaw++
if (typeof m.fiberId === "number") ids.add(m.fiberId)
else idless++
}
}
return { mountRaw, mountUnique: ids.size + idless }
}
export function analyzeSwitch(sw: CapturedSwitch): SwitchAnalysis {
const clickToSkeletonMs = sw.skeletonTs != null ? sw.skeletonTs - sw.clickTs : null
const skeletonToPaintedMs =
sw.skeletonTs != null && sw.paintedTs != null ? sw.paintedTs - sw.skeletonTs : null
const paintedToStableMs =
sw.paintedTs != null && sw.contentStableTs != null ? sw.contentStableTs - sw.paintedTs : null
const validAnchors = Number.isFinite(sw.clickTs) && sw.paintedTs != null && Number.isFinite(sw.paintedTs) && sw.paintedTs >= sw.clickTs
&& (sw.contentStableTs == null || Number.isFinite(sw.contentStableTs) && sw.contentStableTs >= sw.paintedTs)
const stableTs = validAnchors ? sw.contentStableTs ?? sw.paintedTs : null
const perceivedMs = stableTs != null ? stableTs - sw.clickTs : null
const sorted = [...sw.resources].sort((a, b) => a.startTime - b.startTime)
const networkSpanMs = sorted.length
? Math.max(...sorted.map((r) => r.responseEnd)) - Math.min(...sorted.map((r) => r.startTime))
: 0
// Union of busy intervals = actual time at least one request was in flight.
let networkMs = 0
let curStart = -1
let curEnd = -1
for (const r of sorted) {
const start = Math.max(sw.clickTs, r.startTime), end = Math.min(stableTs ?? Infinity, r.responseEnd)
if (end <= start) continue
if (curEnd < start) {
if (curStart >= 0) networkMs += curEnd - curStart
curStart = start
curEnd = end
} else {
curEnd = Math.max(curEnd, end)
}
}
if (curStart >= 0) networkMs += curEnd - curStart
const readState = findResource(sw.resources, "/read-state")
const messages = findResource(sw.resources, "/messages")
const readStateBlocksMessages =
readState && messages ? readState.responseEnd <= messages.startTime + 1 : null
const { mountRaw, mountUnique } = countMounts(sw)
let rerenderCountRaw = 0
const rerenderIds = new Set<number>()
let rerenderIdless = 0
const renderTally = new Map<string, { count: number; reason?: string }>()
for (const commit of sw.commits) {
for (const r of commit.rerenders) {
rerenderCountRaw++
if (typeof r.fiberId === "number") rerenderIds.add(r.fiberId)
else rerenderIdless++
const cur = renderTally.get(r.name) ?? { count: 0, reason: r.reason }
cur.count++
if (!cur.reason && r.reason) cur.reason = r.reason
renderTally.set(r.name, cur)
}
}
const rerenderCountUnique = rerenderIds.size + rerenderIdless
const topRenders = [...renderTally.entries()]
.map(([name, v]) => ({ name, count: v.count, reason: v.reason }))
.sort((a, b) => b.count - a.count)
.slice(0, 8)
// Attribution verdict.
let verdict: string
if (perceivedMs == null) {
verdict = "incomplete capture — no content-stable anchor"
} else if (networkMs >= perceivedMs * 0.6) {
verdict =
readStateBlocksMessages === true
? `network-bound, and read-state→messages is SERIALIZED (${networkMs.toFixed(0)}ms of ${perceivedMs.toFixed(0)}ms)`
: `network-bound (${networkMs.toFixed(0)}ms of ${perceivedMs.toFixed(0)}ms)`
} else {
const nonNetwork = perceivedMs - networkMs
verdict = `NOT network-bound — ${nonNetwork.toFixed(0)}ms of ${perceivedMs.toFixed(0)}ms is outside measured request intervals (network only ${networkMs.toFixed(0)}ms); mounts=${mountUnique} fibers, unmounts=${sw.unmounts.length}`
}
return {
kind: sw.kind,
targetId: sw.targetId,
cacheState: sw.cacheState,
contentChannelId: sw.contentChannelId ?? null,
contentKind: sw.contentKind ?? null, perceivedMs,
clickToSkeletonMs,
skeletonToPaintedMs,
paintedToStableMs,
networkMs,
networkSpanMs,
readStateBlocksMessages,
mountCountRaw: mountRaw,
mountCountUnique: mountUnique,
rerenderCountRaw,
rerenderCountUnique,
unmounts: sw.unmounts,
topRenders,
verdict,
}
}
function ms(n: number | null): string {
return n == null ? "—" : `${n.toFixed(0)}ms`
}
export function renderReport(file: CaptureFile): string {
const lines: string[] = []
lines.push("# Community Switch — Perceived-Latency Report")
lines.push("")
lines.push(`Owner: \`${file.owner.email}\` (userId \`${file.owner.userId}\`)`)
lines.push(`Captured: ${file.createdAt}`)
lines.push("")
lines.push(
"> Local development diagnostic: compare matched runs; these are not production latency measurements. " +
"The headline requires a valid target-content anchor. Counts are dev-mode. " +
"Mounts are reported as `unique` (distinct fiber ids — the trustworthy number) and " +
"`raw` (react-scan re-reports every still-mounted fiber on each later commit, inflating " +
"the raw total 6-13×). Re-renders are NOT inflated (each is a genuine distinct render), " +
"so `raw` is real; `unique` counts how many distinct components re-rendered.",
)
lines.push("")
for (const sw of file.switches) {
const a = analyzeSwitch(sw)
lines.push(`## ${a.kind} switch → \`${a.targetId}\` _(cache: ${a.cacheState})_`)
lines.push("")
if (a.contentKind) lines.push(`- target content: **${a.contentKind === "empty" ? "empty channel (0 messages)" : "message content"}** · channel \`${a.contentChannelId ?? "unknown"}\`${a.contentKind === "empty" ? " · not a populated-message sample" : ""}`)
lines.push(`- PERCEIVED (click → content stable): **${ms(a.perceivedMs)}**`)
lines.push(` - click → skeleton: ${ms(a.clickToSkeletonMs)}`)
lines.push(` - skeleton → painted: ${ms(a.skeletonToPaintedMs)}`)
lines.push(` - painted → stable: ${ms(a.paintedToStableMs)}`)
lines.push(
`- network: ${ms(a.networkMs)} busy before stability / ${ms(a.networkSpanMs)} full span` +
(a.readStateBlocksMessages == null
? ""
: a.readStateBlocksMessages
? " · read-state→messages **SERIALIZED**"
: " · read-state/messages overlap (parallel)"),
)
lines.push(
`- renders: mounts ${a.mountCountUnique} unique (${a.mountCountRaw} raw w/ ring-buffer echo) · ` +
`re-renders ${a.rerenderCountRaw} (${a.rerenderCountUnique} distinct components) · ` +
`unmounts ${a.unmounts.length}`,
)
if (a.topRenders.length) {
lines.push("- top re-renders:")
for (const r of a.topRenders) {
lines.push(` - ${r.name} ×${r.count}${r.reason ? ` (${r.reason})` : ""}`)
}
}
// network waterfall
const sorted = [...sw.resources].sort((x, y) => x.startTime - y.startTime)
if (sorted.length) {
lines.push("- waterfall:")
const base = sorted[0].startTime
for (const r of sorted) {
const short = r.name.replace(/^https?:\/\/[^/]+/, "").split("?")[0]
lines.push(
` - ${short} [t+${(r.startTime - base).toFixed(0)} → t+${(r.responseEnd - base).toFixed(0)}ms]`,
)
}
}
lines.push(`- **VERDICT:** ${a.verdict}`)
lines.push("")
}
return lines.join("\n")
}
function main(): void {
if (process.argv.includes("--clear")) {
clearPerfArtifacts()
return
}
let file: CaptureFile
try {
file = JSON.parse(readFileSync(CAPTURE_IN, "utf8")) as CaptureFile
} catch {
console.error(`Missing ${CAPTURE_IN}. Run the perf spec first (pnpm perf:switch).`)
process.exit(1)
}
const report = renderReport(file)
writeFileSync(REPORT_OUT, report)
console.log(`Wrote ${REPORT_OUT} (${file.switches.length} switches)`)
}
if (import.meta.url === `file://${process.argv[1]}`) {
main()
}