rerender-lens 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { O as Options, C as ChangeKind, a as Change, H as HookChange, b as HookSnapshot, P as ParentInfo, c as CommitPriority, S as SourceLocation, d as CommitCause, R as RenderReport } from './types-BzUEVkxJ.cjs';
-export { e as ComponentMatcher, M as MARKER, N as Notifier, f as RenderTrigger } from './types-BzUEVkxJ.cjs';
-import { F as Fiber } from './devtools-BkCct3cJ.cjs';
-export { C as ChannelCommand, a as ChannelReply, D as DEFAULT_CHANNEL, b as DEVTOOLS_MARKER, c as DevtoolsBridge, d as DevtoolsMessage, e as DevtoolsNotifierOptions, H as HelloPayload, I as InspectResult, P as PROTOCOL_VERSION, f as PullResult, R as RendererInfo, S as SerializableOptions, g as createDevtoolsNotifier, h as deserializeOptions, i as ensureDevtoolsHook, j as getRenderers, k as isProductionReact, s as serialize, l as serializeOptions } from './devtools-BkCct3cJ.cjs';
-export { B as Budget, a as BudgetResult, b as BudgetViolation, F as Fix, d as FixKind, R as RankedFix, e as assertWithinBudget, g as avoidableCounts, c as checkBudget, h as fixKey, i as fixesFor, f as formatFixes, r as rankFixes, t as toBudget } from './budget-COBu7jBU.cjs';
-export { C as Collector, a as CompareRow, b as Comparison, S as SessionSummary, c as combineNotifiers, d as compareSummaries, e as createCollector, f as formatComparison, p as parseExport, s as summarizeReports } from './notifiers-BGQtWKfX.cjs';
+import { O as Options, C as ChangeKind, b as Change, H as HookChange, c as HookSnapshot, P as ParentInfo, d as CommitPriority, S as SourceLocation, e as CommitCause, R as RenderReport, a as ReportLike } from './types-DW5-N2XH.cjs';
+export { f as ChangeLike, g as ComponentMatcher, M as MARKER, N as Notifier, h as RenderTrigger } from './types-DW5-N2XH.cjs';
+import { F as Fiber } from './devtools-DJi_6AfJ.cjs';
+export { C as ChannelCommand, a as ChannelReply, D as DEFAULT_CHANNEL, b as DEVTOOLS_MARKER, c as DevtoolsBridge, d as DevtoolsMessage, e as DevtoolsNotifierOptions, H as HelloPayload, I as InspectResult, P as PROTOCOL_VERSION, f as PullResult, R as RendererInfo, S as SerializableOptions, g as createDevtoolsNotifier, h as deserializeOptions, i as ensureDevtoolsHook, j as getRenderers, k as isProductionReact, s as serialize, l as serializeOptions } from './devtools-DJi_6AfJ.cjs';
+export { B as Budget, a as BudgetResult, b as BudgetViolation, F as Fix, d as FixKind, R as RankedFix, e as assertWithinBudget, g as avoidableCounts, c as checkBudget, h as fixKey, i as fixesFor, f as formatFixes, r as rankFixes, s as shortValue, t as toBudget } from './budget-CRswn-nC.cjs';
+export { C as Collector, a as CompareRow, b as Comparison, S as SessionSummary, c as combineNotifiers, d as compareSessions, e as compareSummaries, f as createCollector, g as formatComparison, p as parseExport, s as summarizeReports, h as summarizeSession } from './notifiers-DwKlvv4H.cjs';
 
 declare function getDisplayName(type: unknown): string;
 /** Decide whether a component type is tracked under the given options. */
@@ -69,6 +69,8 @@ type Seen = Map<object, Set<object>>;
  * React elements and cyclic references. Functions are equal only by reference.
  */
 declare function deepEqual(a: unknown, b: unknown, seen?: Seen): boolean;
+/** Change kinds that mean "new reference, same contents": the ones a fix removes. */
+declare const AVOIDABLE_KINDS: ReadonlySet<string>;
 /** Classify why two values differ. Assumes `!Object.is(prev, next)`. */
 declare function classify(prev: unknown, next: unknown): ChangeKind;
 /**
@@ -77,6 +79,19 @@ declare function classify(prev: unknown, next: unknown): ChangeKind;
  * actually differs is reported in `path` to make the console output actionable.
  */
 declare function diffRecords(prev: Record<string, unknown> | undefined | null, next: Record<string, unknown> | undefined | null, basePath?: string): Change[];
+/**
+ * Walk plain objects/arrays to find the deepest path where the values first differ, e.g. `style.color`
+ * or `items[2].id`; null when they are deep-equal. Two different values with no path to descend into
+ * (primitives at the root) give `(value)`. Works on live values and on the panel's serialized ones.
+ */
+declare function firstDifferentPath(a: unknown, b: unknown, path?: string, depth?: number): string | null;
+interface Leaf {
+    path: string;
+    prev: unknown;
+    next: unknown;
+}
+/** Every leaf at which two values differ, at most `limit` of them (the panel's diff view of `different` changes). */
+declare function diffLeaves(a: unknown, b: unknown, limit?: number, path?: string, out?: Leaf[]): Leaf[];
 
 interface BuildInput {
     component: string;
@@ -98,6 +113,12 @@ interface BuildInput {
     path?: string[];
     /** Default true: `useWhyRerender` and the console output assume the component decides on props alone. */
     memoized?: boolean;
+    /** The component was compiled by React Compiler (its output is memoized per input). */
+    compiled?: boolean;
+    /** A class component: the memoization advice names PureComponent / shouldComponentUpdate instead of React.memo. */
+    classComponent?: boolean;
+    /** The component sits under a Suspense boundary that switched from its fallback to content in this commit. */
+    revealed?: boolean;
     selfDuration?: number;
     treeDuration?: number;
     commitId?: number;
@@ -117,11 +138,113 @@ declare const hookLabel: (c: {
 /** Store-specific advice for a `useSyncExternalStore` snapshot that is a new reference with equal contents. */
 declare function storeAdvice(custom: string[] | undefined): string;
 declare function buildReport(input: BuildInput): RenderReport;
-declare function summarize(report: RenderReport): string;
+/** Short label per change kind, as printed by the console output and the panel. */
+declare const KIND_LABEL: Record<Change['kind'], string>;
+/** `1 equal by value, 2 new function`, or `no changes`. Shared with the panel (serialized reports). */
+declare function summarize(report: Pick<ReportLike, 'propChanges' | 'stateChanges' | 'hookChanges'>): string;
 /** Default notifier: prints a console group per report. */
 declare function printReport(report: RenderReport, options: Options): void;
 
+interface RootCause {
+    name: string;
+    trigger: string;
+    /** Avoidable re-renders in the commit that trace back to this component. */
+    count: number;
+    components: Map<string, number>;
+}
+interface ContextStat {
+    name: string;
+    consumers: number;
+    avoidable: number;
+    components: Map<string, number>;
+    commits: Set<number>;
+    /** Components rendering the Provider (usually one). */
+    providers: Map<string, number>;
+    /** Keys that changed in object values, and the largest key count seen. */
+    changedKeys: Set<string>;
+    totalKeys: number;
+}
+interface CommitAnalysis<R extends ReportLike = RenderReport> {
+    /** The commit id (`commitId` of its reports), 0 when the reports carry none. */
+    id: number;
+    total: number;
+    avoidable: number;
+    /** Sum of `selfDuration` over the avoidable reports, in ms. */
+    wasted: number;
+    roots: RootCause[];
+    /** Root cause name of every avoidable report (what `roots` was aggregated from). */
+    rootByReport: Map<R, string>;
+    contexts: ContextStat[];
+    reports: R[];
+}
+interface CascadeNode<R extends ReportLike = RenderReport> {
+    name: string;
+    children: Map<string, CascadeNode<R>>;
+    report: R | null;
+    count?: number;
+    avoidable?: number;
+}
+interface RootSummary<R extends ReportLike = RenderReport, A extends CommitAnalysis<R> = CommitAnalysis<R>> {
+    name: string;
+    trigger: string;
+    /** Newest first. */
+    commits: {
+        key: number;
+        analysis: A;
+        count: number;
+        components: Map<string, number>;
+    }[];
+    /** Avoidable re-renders across every commit. */
+    total: number;
+    components: Map<string, number>;
+    /** The avoidable reports that trace back to this root cause. */
+    affected: R[];
+}
+/** One root cause across a whole run: how many commits it started and what those cost. */
+interface RankedRootCause {
+    name: string;
+    trigger: string;
+    commits: number;
+    /** Avoidable re-renders it caused. */
+    count: number;
+    components: Map<string, number>;
+}
+/** One commit's reports grouped by component name, so a parent lookup is O(same-named reports) instead of O(commit). */
+declare function indexByComponent<R extends ReportLike>(reports: readonly R[]): Map<string, R[]>;
+/**
+ * Walk `parent` links inside one commit up to the component whose own change started the cascade.
+ * Null when `r` started it itself; `report` is null when the root is an ancestor that is not in the
+ * commit (untracked), in which case `name`/`trigger` come from the last `parent` link.
+ */
+declare function rootCauseOf<R extends ReportLike>(r: R, commitReports: readonly R[], index?: Map<string, R[]>): {
+    name: string;
+    trigger: string;
+    report: R | null;
+} | null;
+/** Analyze the reports of one commit: what started the cascade, which contexts changed, what it cost. */
+declare function analyzeCommit<R extends ReportLike>(reports: R[]): CommitAnalysis<R>;
+/** Which contexts changed and how many consumers re-rendered because of them. */
+declare function contextAttribution(reports: readonly ReportLike[]): ContextStat[];
+/** Nested cascade for one commit: every report placed under its ancestors (untracked ancestors appear as plain names). */
+declare function cascadeTree<R extends ReportLike>(reports: readonly R[]): CascadeNode<R>;
+/**
+ * Every commit a component started (as the root cause), across the whole session.
+ * `analyze` lets a caller (the panel) pass its per-commit memoized analysis.
+ */
+declare function rootCauseSummary<R extends ReportLike>(name: string, commits: Iterable<[number, R[]]>): RootSummary<R>;
+declare function rootCauseSummary<R extends ReportLike, A extends CommitAnalysis<R>>(name: string, commits: Iterable<[number, R[]]>, analyze: (key: number, reports: R[]) => A): RootSummary<R, A>;
+/** Reports grouped by `commitId` in first-seen order. Reports without one (`useWhyRerender`, protocol 1) are left out. */
+declare function groupByCommit<R extends ReportLike>(reports: readonly R[]): Map<number, R[]>;
+/** Root causes across every commit in `reports`, most avoidable re-renders caused first. */
+declare function rankRootCauses(reports: readonly ReportLike[]): RankedRootCause[];
+/**
+ * Multi-line root-cause table for a test failure or a CI log, one line per root cause:
+ * `<Page> (state) started 3 commits, 12 avoidable re-renders  (<Row> x10, <Toolbar> x2)`.
+ * Empty when nothing is avoidable or the reports carry no `commitId`.
+ */
+declare function formatRootCauses(reports: readonly ReportLike[], limit?: number): string;
+
 /** Library version, injected by the build; "dev" when running from source. */
 declare const VERSION: string;
 
-export { Change, ChangeKind, CommitCause, CommitPriority, type DispatcherRef, HookChange, HookSnapshot, Options, ParentInfo, RenderReport, SourceLocation, VERSION, buildReport, classify, configure, customHooksFromStack, deepEqual, diffRecords, disable, getDisplayName, hookLabel, init, isEnabled, printReport, resolveHookNames, shouldTrack, storeAdvice, summarize, track, useWhyRerender };
+export { AVOIDABLE_KINDS, type CascadeNode, Change, ChangeKind, type CommitAnalysis, CommitCause, CommitPriority, type ContextStat, type DispatcherRef, HookChange, HookSnapshot, KIND_LABEL, type Leaf, Options, ParentInfo, type RankedRootCause, RenderReport, ReportLike, type RootCause, type RootSummary, SourceLocation, VERSION, analyzeCommit, buildReport, cascadeTree, classify, configure, contextAttribution, customHooksFromStack, deepEqual, diffLeaves, diffRecords, disable, firstDifferentPath, formatRootCauses, getDisplayName, groupByCommit, hookLabel, indexByComponent, init, isEnabled, printReport, rankRootCauses, resolveHookNames, rootCauseOf, rootCauseSummary, shouldTrack, storeAdvice, summarize, track, useWhyRerender };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { O as Options, C as ChangeKind, a as Change, H as HookChange, b as HookSnapshot, P as ParentInfo, c as CommitPriority, S as SourceLocation, d as CommitCause, R as RenderReport } from './types-BzUEVkxJ.js';
-export { e as ComponentMatcher, M as MARKER, N as Notifier, f as RenderTrigger } from './types-BzUEVkxJ.js';
-import { F as Fiber } from './devtools-CZebzpF6.js';
-export { C as ChannelCommand, a as ChannelReply, D as DEFAULT_CHANNEL, b as DEVTOOLS_MARKER, c as DevtoolsBridge, d as DevtoolsMessage, e as DevtoolsNotifierOptions, H as HelloPayload, I as InspectResult, P as PROTOCOL_VERSION, f as PullResult, R as RendererInfo, S as SerializableOptions, g as createDevtoolsNotifier, h as deserializeOptions, i as ensureDevtoolsHook, j as getRenderers, k as isProductionReact, s as serialize, l as serializeOptions } from './devtools-CZebzpF6.js';
-export { B as Budget, a as BudgetResult, b as BudgetViolation, F as Fix, d as FixKind, R as RankedFix, e as assertWithinBudget, g as avoidableCounts, c as checkBudget, h as fixKey, i as fixesFor, f as formatFixes, r as rankFixes, t as toBudget } from './budget-LkNjGtRc.js';
-export { C as Collector, a as CompareRow, b as Comparison, S as SessionSummary, c as combineNotifiers, d as compareSummaries, e as createCollector, f as formatComparison, p as parseExport, s as summarizeReports } from './notifiers-BjjGSHpp.js';
+import { O as Options, C as ChangeKind, b as Change, H as HookChange, c as HookSnapshot, P as ParentInfo, d as CommitPriority, S as SourceLocation, e as CommitCause, R as RenderReport, a as ReportLike } from './types-DW5-N2XH.js';
+export { f as ChangeLike, g as ComponentMatcher, M as MARKER, N as Notifier, h as RenderTrigger } from './types-DW5-N2XH.js';
+import { F as Fiber } from './devtools-BYWat7nQ.js';
+export { C as ChannelCommand, a as ChannelReply, D as DEFAULT_CHANNEL, b as DEVTOOLS_MARKER, c as DevtoolsBridge, d as DevtoolsMessage, e as DevtoolsNotifierOptions, H as HelloPayload, I as InspectResult, P as PROTOCOL_VERSION, f as PullResult, R as RendererInfo, S as SerializableOptions, g as createDevtoolsNotifier, h as deserializeOptions, i as ensureDevtoolsHook, j as getRenderers, k as isProductionReact, s as serialize, l as serializeOptions } from './devtools-BYWat7nQ.js';
+export { B as Budget, a as BudgetResult, b as BudgetViolation, F as Fix, d as FixKind, R as RankedFix, e as assertWithinBudget, g as avoidableCounts, c as checkBudget, h as fixKey, i as fixesFor, f as formatFixes, r as rankFixes, s as shortValue, t as toBudget } from './budget-BnJlYwrV.js';
+export { C as Collector, a as CompareRow, b as Comparison, S as SessionSummary, c as combineNotifiers, d as compareSessions, e as compareSummaries, f as createCollector, g as formatComparison, p as parseExport, s as summarizeReports, h as summarizeSession } from './notifiers-FNzKHs0a.js';
 
 declare function getDisplayName(type: unknown): string;
 /** Decide whether a component type is tracked under the given options. */
@@ -69,6 +69,8 @@ type Seen = Map<object, Set<object>>;
  * React elements and cyclic references. Functions are equal only by reference.
  */
 declare function deepEqual(a: unknown, b: unknown, seen?: Seen): boolean;
+/** Change kinds that mean "new reference, same contents": the ones a fix removes. */
+declare const AVOIDABLE_KINDS: ReadonlySet<string>;
 /** Classify why two values differ. Assumes `!Object.is(prev, next)`. */
 declare function classify(prev: unknown, next: unknown): ChangeKind;
 /**
@@ -77,6 +79,19 @@ declare function classify(prev: unknown, next: unknown): ChangeKind;
  * actually differs is reported in `path` to make the console output actionable.
  */
 declare function diffRecords(prev: Record<string, unknown> | undefined | null, next: Record<string, unknown> | undefined | null, basePath?: string): Change[];
+/**
+ * Walk plain objects/arrays to find the deepest path where the values first differ, e.g. `style.color`
+ * or `items[2].id`; null when they are deep-equal. Two different values with no path to descend into
+ * (primitives at the root) give `(value)`. Works on live values and on the panel's serialized ones.
+ */
+declare function firstDifferentPath(a: unknown, b: unknown, path?: string, depth?: number): string | null;
+interface Leaf {
+    path: string;
+    prev: unknown;
+    next: unknown;
+}
+/** Every leaf at which two values differ, at most `limit` of them (the panel's diff view of `different` changes). */
+declare function diffLeaves(a: unknown, b: unknown, limit?: number, path?: string, out?: Leaf[]): Leaf[];
 
 interface BuildInput {
     component: string;
@@ -98,6 +113,12 @@ interface BuildInput {
     path?: string[];
     /** Default true: `useWhyRerender` and the console output assume the component decides on props alone. */
     memoized?: boolean;
+    /** The component was compiled by React Compiler (its output is memoized per input). */
+    compiled?: boolean;
+    /** A class component: the memoization advice names PureComponent / shouldComponentUpdate instead of React.memo. */
+    classComponent?: boolean;
+    /** The component sits under a Suspense boundary that switched from its fallback to content in this commit. */
+    revealed?: boolean;
     selfDuration?: number;
     treeDuration?: number;
     commitId?: number;
@@ -117,11 +138,113 @@ declare const hookLabel: (c: {
 /** Store-specific advice for a `useSyncExternalStore` snapshot that is a new reference with equal contents. */
 declare function storeAdvice(custom: string[] | undefined): string;
 declare function buildReport(input: BuildInput): RenderReport;
-declare function summarize(report: RenderReport): string;
+/** Short label per change kind, as printed by the console output and the panel. */
+declare const KIND_LABEL: Record<Change['kind'], string>;
+/** `1 equal by value, 2 new function`, or `no changes`. Shared with the panel (serialized reports). */
+declare function summarize(report: Pick<ReportLike, 'propChanges' | 'stateChanges' | 'hookChanges'>): string;
 /** Default notifier: prints a console group per report. */
 declare function printReport(report: RenderReport, options: Options): void;
 
+interface RootCause {
+    name: string;
+    trigger: string;
+    /** Avoidable re-renders in the commit that trace back to this component. */
+    count: number;
+    components: Map<string, number>;
+}
+interface ContextStat {
+    name: string;
+    consumers: number;
+    avoidable: number;
+    components: Map<string, number>;
+    commits: Set<number>;
+    /** Components rendering the Provider (usually one). */
+    providers: Map<string, number>;
+    /** Keys that changed in object values, and the largest key count seen. */
+    changedKeys: Set<string>;
+    totalKeys: number;
+}
+interface CommitAnalysis<R extends ReportLike = RenderReport> {
+    /** The commit id (`commitId` of its reports), 0 when the reports carry none. */
+    id: number;
+    total: number;
+    avoidable: number;
+    /** Sum of `selfDuration` over the avoidable reports, in ms. */
+    wasted: number;
+    roots: RootCause[];
+    /** Root cause name of every avoidable report (what `roots` was aggregated from). */
+    rootByReport: Map<R, string>;
+    contexts: ContextStat[];
+    reports: R[];
+}
+interface CascadeNode<R extends ReportLike = RenderReport> {
+    name: string;
+    children: Map<string, CascadeNode<R>>;
+    report: R | null;
+    count?: number;
+    avoidable?: number;
+}
+interface RootSummary<R extends ReportLike = RenderReport, A extends CommitAnalysis<R> = CommitAnalysis<R>> {
+    name: string;
+    trigger: string;
+    /** Newest first. */
+    commits: {
+        key: number;
+        analysis: A;
+        count: number;
+        components: Map<string, number>;
+    }[];
+    /** Avoidable re-renders across every commit. */
+    total: number;
+    components: Map<string, number>;
+    /** The avoidable reports that trace back to this root cause. */
+    affected: R[];
+}
+/** One root cause across a whole run: how many commits it started and what those cost. */
+interface RankedRootCause {
+    name: string;
+    trigger: string;
+    commits: number;
+    /** Avoidable re-renders it caused. */
+    count: number;
+    components: Map<string, number>;
+}
+/** One commit's reports grouped by component name, so a parent lookup is O(same-named reports) instead of O(commit). */
+declare function indexByComponent<R extends ReportLike>(reports: readonly R[]): Map<string, R[]>;
+/**
+ * Walk `parent` links inside one commit up to the component whose own change started the cascade.
+ * Null when `r` started it itself; `report` is null when the root is an ancestor that is not in the
+ * commit (untracked), in which case `name`/`trigger` come from the last `parent` link.
+ */
+declare function rootCauseOf<R extends ReportLike>(r: R, commitReports: readonly R[], index?: Map<string, R[]>): {
+    name: string;
+    trigger: string;
+    report: R | null;
+} | null;
+/** Analyze the reports of one commit: what started the cascade, which contexts changed, what it cost. */
+declare function analyzeCommit<R extends ReportLike>(reports: R[]): CommitAnalysis<R>;
+/** Which contexts changed and how many consumers re-rendered because of them. */
+declare function contextAttribution(reports: readonly ReportLike[]): ContextStat[];
+/** Nested cascade for one commit: every report placed under its ancestors (untracked ancestors appear as plain names). */
+declare function cascadeTree<R extends ReportLike>(reports: readonly R[]): CascadeNode<R>;
+/**
+ * Every commit a component started (as the root cause), across the whole session.
+ * `analyze` lets a caller (the panel) pass its per-commit memoized analysis.
+ */
+declare function rootCauseSummary<R extends ReportLike>(name: string, commits: Iterable<[number, R[]]>): RootSummary<R>;
+declare function rootCauseSummary<R extends ReportLike, A extends CommitAnalysis<R>>(name: string, commits: Iterable<[number, R[]]>, analyze: (key: number, reports: R[]) => A): RootSummary<R, A>;
+/** Reports grouped by `commitId` in first-seen order. Reports without one (`useWhyRerender`, protocol 1) are left out. */
+declare function groupByCommit<R extends ReportLike>(reports: readonly R[]): Map<number, R[]>;
+/** Root causes across every commit in `reports`, most avoidable re-renders caused first. */
+declare function rankRootCauses(reports: readonly ReportLike[]): RankedRootCause[];
+/**
+ * Multi-line root-cause table for a test failure or a CI log, one line per root cause:
+ * `<Page> (state) started 3 commits, 12 avoidable re-renders  (<Row> x10, <Toolbar> x2)`.
+ * Empty when nothing is avoidable or the reports carry no `commitId`.
+ */
+declare function formatRootCauses(reports: readonly ReportLike[], limit?: number): string;
+
 /** Library version, injected by the build; "dev" when running from source. */
 declare const VERSION: string;
 
-export { Change, ChangeKind, CommitCause, CommitPriority, type DispatcherRef, HookChange, HookSnapshot, Options, ParentInfo, RenderReport, SourceLocation, VERSION, buildReport, classify, configure, customHooksFromStack, deepEqual, diffRecords, disable, getDisplayName, hookLabel, init, isEnabled, printReport, resolveHookNames, shouldTrack, storeAdvice, summarize, track, useWhyRerender };
+export { AVOIDABLE_KINDS, type CascadeNode, Change, ChangeKind, type CommitAnalysis, CommitCause, CommitPriority, type ContextStat, type DispatcherRef, HookChange, HookSnapshot, KIND_LABEL, type Leaf, Options, ParentInfo, type RankedRootCause, RenderReport, ReportLike, type RootCause, type RootSummary, SourceLocation, VERSION, analyzeCommit, buildReport, cascadeTree, classify, configure, contextAttribution, customHooksFromStack, deepEqual, diffLeaves, diffRecords, disable, firstDifferentPath, formatRootCauses, getDisplayName, groupByCommit, hookLabel, indexByComponent, init, isEnabled, printReport, rankRootCauses, resolveHookNames, rootCauseOf, rootCauseSummary, shouldTrack, storeAdvice, summarize, track, useWhyRerender };