rerender-lens 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,136 +1,9 @@
-/** Why a single prop/state/hook value differs between two renders. */
-type ChangeKind = 
-/** New reference, but deep-equal to the previous value. Avoidable. */
-'deep-equal'
-/** A new function with the same name/body shape. Almost always avoidable. */
- | 'function'
-/** A new React element that renders the same type with deep-equal props. Avoidable. */
- | 'element'
-/** The value genuinely changed. */
- | 'different'
-/** Key was added. */
- | 'added'
-/** Key was removed. */
- | 'removed';
-interface Change {
-    /** Dot path from the root, e.g. `style.color` or `items[2]`. */
-    path: string;
-    kind: ChangeKind;
-    prev: unknown;
-    next: unknown;
-}
-/** What caused a re-render. */
-type RenderTrigger = 
-/** At least one prop genuinely changed. */
-'props'
-/** Props are equal by value, but the parent re-rendered. Wrap in React.memo. */
- | 'parent'
-/** Own state (useState/useReducer/this.setState) changed. */
- | 'state'
-/** A non-state hook value (useContext, useSyncExternalStore) changed. */
- | 'hooks'
-/** More than one of the above. */
- | 'mixed';
-interface HookChange extends Change {
-    /** `useState`, `useReducer`, `useContext`, `useSyncExternalStore`, or `state` when the exact hook is unknown. */
-    hook: string;
-    /** Position of the hook in call order (0-based). */
-    index: number;
-    /** `useContext` only: the component that renders the nearest matching Provider, and its ancestry. */
-    provider?: {
-        component: string | null;
-        path: string[];
-    };
-    /** `useContext` only, object values: top-level keys whose value changed (shallow), and how many keys the value has. */
-    changedKeys?: string[];
-    totalKeys?: number;
-}
-/** Scheduler priority of the commit, as React reports it to the DevTools hook (transitions run at `normal`). */
-type CommitPriority = 'immediate' | 'user-blocking' | 'normal' | 'low' | 'idle';
-interface ParentInfo {
-    /** Display name of the nearest ancestor component that also rendered in this commit. */
-    name: string;
-    /** Why that ancestor rendered. */
-    trigger: RenderTrigger;
-}
-/** Where a component's element was created (React <= 18: `_debugSource`; React 19: parsed from `_debugStack`). */
-interface SourceLocation {
-    fileName: string;
-    lineNumber?: number;
-    columnNumber?: number;
-}
-interface RenderReport {
-    /** Display name of the tracked component. */
-    component: string;
-    /** Stable id of this component instance (fiber) across its lifetime. */
-    instanceId: number;
-    /** Monotonic id of the React commit that produced this report. Reports from one commit share it. 0 for `useWhyRerender`. */
-    commitId: number;
-    /** Priority React assigned to the commit: `immediate` for discrete input (clicks, keys), `user-blocking` for continuous input, `normal` for transitions and async updates. */
-    commitPriority?: CommitPriority;
-    /** Monotonic per-instance update count (1 = first update; mount is never reported). */
-    renderCount: number;
-    trigger: RenderTrigger;
-    /** True when the re-render produced no genuine change in props, state, or hooks. */
-    avoidable: boolean;
-    props: {
-        prev: Record<string, unknown>;
-        next: Record<string, unknown>;
-    };
-    propChanges: Change[];
-    /** Class components only. */
-    stateChanges: Change[];
-    /** Function components: state hooks and contexts that changed. */
-    hookChanges: HookChange[];
-    /** Nearest ancestor that rendered in the same commit, or null when the update started here. */
-    parent: ParentInfo | null;
-    /** Component that created this element (dev builds only). */
-    owner: string | null;
-    /** Component ancestry from the root down to this component, display names only. */
-    path: string[];
-    /** True for `React.memo` components and `PureComponent` classes: props alone decide whether they re-render. */
-    memoized: boolean;
-    /** Time spent in this component's own render (children excluded), in ms, when React exposes it (dev/profiling builds). */
-    selfDuration?: number;
-    /** Time spent rendering this component and everything below it that rendered in the same commit, in ms. */
-    treeDuration?: number;
-    /** Source location of the element that rendered this component, when React exposes it (dev builds). */
-    source?: SourceLocation;
-    /** Human-readable explanations and suggested fixes. */
-    reasons: string[];
-    /** `performance.now()` (or `Date.now()`) when the report was produced. */
-    time: number;
-}
-type Notifier = (report: RenderReport) => void;
-type ComponentMatcher = string | RegExp | ((displayName: string) => boolean);
-interface Options {
-    /** Track every `React.memo`-wrapped component and every `PureComponent`. Default false. */
-    trackAllMemoized?: boolean;
-    /** Track every component, memoized or not. Noisy. Default false. */
-    trackAllComponents?: boolean;
-    /** Components to track by display name (string = exact match). */
-    include?: ComponentMatcher[];
-    /** Components never to track, even when marked. */
-    exclude?: ComponentMatcher[];
-    /** Diff hook state and contexts of function components. Default true. */
-    trackHooks?: boolean;
-    /** Report re-renders caused by genuine changes too, not only avoidable ones. Default false. */
-    logAll?: boolean;
-    /** Do not print to the console. Reports still reach `notifier`. Default false. */
-    silent?: boolean;
-    /** Receive every report. Combine several with `combineNotifiers`. */
-    notifier?: Notifier;
-    /** Use `console.groupCollapsed` instead of `console.group`. Default true. */
-    collapse?: boolean;
-    /** Console-like sink used for printing. Default `console`. */
-    console?: Pick<Console, 'log' | 'group' | 'groupCollapsed' | 'groupEnd' | 'warn'>;
-    /** Skip commits caused by Fast Refresh / hot module replacement. Default true. */
-    ignoreHotReload?: boolean;
-    /** Stop printing a component after this many reports (0 = unlimited). The notifier still receives them. Default 0. */
-    maxReportsPerComponent?: number;
-}
-/** Marker static: `MyComponent.rerenderLens = true` opts a component in. */
-declare const MARKER: "rerenderLens";
+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-BHGUUo-p.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-BHGUUo-p.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';
 
 declare function getDisplayName(type: unknown): string;
 /** Decide whether a component type is tracked under the given options. */
@@ -153,84 +26,25 @@ declare function isEnabled(): boolean;
 declare function track<T>(component: T, name?: string): T;
 
 /**
- * Fiber-tree inspection. Runs after every React commit via the DevTools global
- * hook, exactly like React DevTools itself. Element types are never touched, so
- * Fast Refresh, memo comparators and component identity all stay intact.
+ * Custom hook names, opt-in (`resolveHookNames`). React keeps no record of which custom hook
+ * called a primitive, so, like React DevTools, we re-run the component once with a stand-in
+ * dispatcher: every primitive records the call stack, and the frames between the primitive and the
+ * component are the custom hooks. Values come from the fiber's real hook nodes so the component
+ * takes the same code path. Results are cached per component type; a throwing render yields no names.
  */
 
-interface ContextDependency {
-    context: {
-        displayName?: string;
-        _currentValue?: unknown;
-    };
-    memoizedValue: unknown;
-    next: ContextDependency | null;
-}
-interface Fiber {
-    tag: number;
-    key: unknown;
-    type: unknown;
-    elementType: unknown;
-    stateNode: unknown;
-    memoizedProps: Record<string, unknown> | null;
-    memoizedState: unknown;
-    alternate: Fiber | null;
-    child: Fiber | null;
-    sibling: Fiber | null;
-    return: Fiber | null;
-    flags?: number;
-    /** React 16 name for `flags`. */
-    effectTag?: number;
-    dependencies?: {
-        firstContext: ContextDependency | null;
-    } | null;
-    _debugOwner?: {
-        type?: unknown;
-        name?: string;
-    } | null;
-    _debugHookTypes?: string[] | null;
-    /** React <= 18 with the JSX dev transform. */
-    _debugSource?: {
-        fileName?: string;
-        lineNumber?: number;
-        columnNumber?: number;
-    } | null;
-    /** React 19: an Error captured where the element was created. */
-    _debugStack?: {
-        stack?: string;
-    } | string | null;
-    actualDuration?: number;
-}
-interface FiberRoot {
-    current: Fiber;
-}
-/** What `react-dom` passes to `hook.inject`. */
-interface RendererInfo {
-    version?: string;
-    /** 1 = development build, 0 = production build. */
-    bundleType?: number;
-    rendererPackageName?: string;
-}
-interface DevtoolsHook {
-    renderers: Map<number, unknown>;
-    supportsFiber: boolean;
-    inject(renderer: unknown): number;
-    onCommitFiberRoot?: (id: number, root: FiberRoot, priority?: unknown, didError?: boolean) => void;
-    onCommitFiberUnmount?: (id: number, fiber: Fiber) => void;
-    onScheduleFiberRoot?: (id: number, root: FiberRoot, children: unknown) => void;
-    onPostCommitFiberRoot?: (id: number, root: FiberRoot) => void;
-    isDisabled?: boolean;
-}
+/** `currentDispatcherRef` as react-dom injects it: `{ current }` (React 16-18) or the shared internals `{ H }` (React 19). */
+type DispatcherRef = {
+    current?: unknown;
+    H?: unknown;
+};
+/** Function names in the frames between our dispatcher and the component (innermost first). */
+declare function customHooksFromStack(stack: string, componentName: string, marker: string): string[];
 /**
- * Make sure `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` exists. React DOM only looks
- * for it once, when the `react-dom` module is evaluated, so this must run before
- * that unless the React DevTools extension or Fast Refresh already created it.
+ * Custom hook chain per hook node index for a rendered function-component fiber. Empty map when the
+ * replay fails, when the dispatcher ref is missing, or when the node count does not match.
  */
-declare function ensureDevtoolsHook(): DevtoolsHook;
-/** The renderers React registered on the hook (version and dev/prod bundle type). */
-declare function getRenderers(): RendererInfo[];
-/** True when every registered React renderer is a production build (names minified, no hook labels). */
-declare function isProductionReact(): boolean;
+declare function resolveHookNames(fiber: Fiber, ref: DispatcherRef | null | undefined): Map<number, string[]>;
 
 type HookOptions = Pick<Options, 'notifier' | 'silent' | 'console' | 'collapse' | 'logAll'>;
 /**
@@ -273,6 +87,12 @@ interface BuildInput {
     propChanges: Change[];
     stateChanges?: Change[];
     hookChanges?: HookChange[];
+    hookState?: HookSnapshot[];
+    contexts?: {
+        name: string;
+        value: unknown;
+    }[];
+    state?: Record<string, unknown>;
     parent?: ParentInfo | null;
     owner?: string | null;
     path?: string[];
@@ -283,141 +103,25 @@ interface BuildInput {
     commitId?: number;
     commitPriority?: CommitPriority;
     source?: SourceLocation;
+    updaters?: string[];
+    commitCause?: CommitCause;
+    afterCommit?: number;
+    key?: string | null;
 }
+/** `useCart › useState#0` when custom hook names are known, else `useState #0`. */
+declare const hookLabel: (c: {
+    hook: string;
+    index: number;
+    custom?: string[];
+}) => string;
+/** 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;
 /** Default notifier: prints a console group per report. */
 declare function printReport(report: RenderReport, options: Options): void;
 
-interface Collector {
-    /** Every report received, in order. */
-    readonly reports: RenderReport[];
-    /** Reports where `avoidable` is true. */
-    readonly avoidable: RenderReport[];
-    /** Pass this to `init({ notifier })`. */
-    readonly notifier: Notifier;
-    clear(): void;
-    /** Throws with a readable message if any avoidable re-render was recorded. */
-    assertNoAvoidable(): void;
-}
-/** Collect reports in memory. Meant for tests. */
-declare function createCollector(): Collector;
-declare function combineNotifiers(...notifiers: Array<Notifier | undefined | null | false>): Notifier;
-
-declare const DEVTOOLS_MARKER: "__rerenderLens";
-/** Bumped when the message shape or bridge API changes in a way the panel must know about. */
-declare const PROTOCOL_VERSION = 2;
-interface DevtoolsMessage {
-    [DEVTOOLS_MARKER]: true;
-    version: number;
-    type: 'report' | 'clear' | 'hello';
-    payload?: unknown;
-}
-/** Payload of a `hello` message. */
-interface HelloPayload {
-    /** Buffered reports available for `replay()` / `pull()`. */
-    count: number;
-    /** Library version. */
-    library: string;
-    protocol: number;
-    react: RendererInfo[];
-    /** True when every React renderer on the page is a production build. */
-    production: boolean;
-    enabled: boolean;
-    options: SerializableOptions;
-    /** Who created this bridge: the page's own `init` call, or the extension's injected copy. */
-    source: 'page' | 'extension';
-    /** True when the extension injected a copy of the library into this page (whether or not it is the active one). */
-    injected: boolean;
-    /** Roots React scheduled (dev builds) and commits observed since `init`; the gap is work that never committed. */
-    scheduled: number;
-    commits: number;
-}
-declare global {
-    interface Window {
-        /** Set by the extension's inject script: version of the injected library. */
-        __RERENDER_LENS_INJECTED__?: string;
-    }
-}
-/** `Options` with matchers as strings (`"Name"` or `"/regex/flags"`) and no functions. */
-interface SerializableOptions {
-    trackAllMemoized?: boolean;
-    trackAllComponents?: boolean;
-    include?: string[];
-    exclude?: string[];
-    trackHooks?: boolean;
-    logAll?: boolean;
-    silent?: boolean;
-    collapse?: boolean;
-    ignoreHotReload?: boolean;
-    maxReportsPerComponent?: number;
-}
-interface DevtoolsNotifierOptions {
-    /** How many reports to keep for `replay()`. Default 300. */
-    bufferSize?: number;
-    /** Where to post. Default `window`. */
-    target?: Pick<Window, 'postMessage'>;
-    /** Max serialization depth. Default 6. */
-    maxDepth?: number;
-    /** Flash the DOM of components that re-rendered avoidably. Default false; toggle later with `flashAvoidable`. */
-    flashAvoidable?: boolean;
-    /** Reported in `info()`. The extension's inject script passes `'extension'`. Default `'page'`. */
-    source?: 'page' | 'extension';
-}
-interface InspectResult {
-    component: string;
-    instanceId: number | null;
-    tracked: boolean;
-    path: string[];
-    /** Serialized reports for this instance, oldest first. */
-    reports: unknown[];
-}
-interface PullResult {
-    /** Sequence number of the newest report included; pass it back as `since`. */
-    seq: number;
-    reports: unknown[];
-    /** True when the caller missed reports that fell out of the buffer. */
-    dropped: boolean;
-}
-interface DevtoolsBridge {
-    /** Re-post every buffered report (a panel that opened late calls this). */
-    replay(): void;
-    clear(): void;
-    readonly size: number;
-    readonly version: number;
-    /** Library version. */
-    readonly library: string;
-    /** Everything the panel shows in its status line. */
-    info(): HelloPayload;
-    /** Reports newer than `since`. Lets a panel poll without any content script. */
-    pull(since?: number): PullResult;
-    /** Merge options at runtime; matchers are strings (`"/^Grid/"` becomes a RegExp). */
-    configure(options: SerializableOptions): SerializableOptions;
-    getOptions(): SerializableOptions;
-    /** Outline the DOM of an instance in the page; `null` clears. */
-    highlight(instanceId: number | null): boolean;
-    /** Turn the avoidable-render flash on or off. */
-    flashAvoidable(on: boolean): void;
-    /** Re-render details for a DOM node (DevTools' `$0`). */
-    inspect(node: unknown): InspectResult | null;
-}
-declare global {
-    interface Window {
-        __RERENDER_LENS_DEVTOOLS__?: DevtoolsBridge;
-    }
-}
-/** Convert a report into a structured-clone-safe value (functions, elements, cycles removed). */
-declare function serialize(value: unknown, maxDepth?: number, seen?: WeakSet<object>, depth?: number): unknown;
-/** The current options in a JSON-safe form (function matchers and custom consoles are dropped). */
-declare function serializeOptions(o: Options): SerializableOptions;
-declare function deserializeOptions(o: SerializableOptions): Options;
-/**
- * A notifier that posts every report on `window` for a DevTools extension to pick up.
- * Also installs `window.__RERENDER_LENS_DEVTOOLS__` with `replay()` / `clear()` / `pull()` and friends.
- */
-declare function createDevtoolsNotifier(options?: DevtoolsNotifierOptions): Notifier;
-
 /** Library version, injected by the build; "dev" when running from source. */
 declare const VERSION: string;
 
-export { type Change, type ChangeKind, type Collector, type ComponentMatcher, DEVTOOLS_MARKER, type DevtoolsBridge, type DevtoolsMessage, type DevtoolsNotifierOptions, type HelloPayload, type HookChange, type InspectResult, MARKER, type Notifier, type Options, PROTOCOL_VERSION, type ParentInfo, type PullResult, type RenderReport, type RenderTrigger, type RendererInfo, type SerializableOptions, type SourceLocation, VERSION, buildReport, classify, combineNotifiers, configure, createCollector, createDevtoolsNotifier, deepEqual, deserializeOptions, diffRecords, disable, ensureDevtoolsHook, getDisplayName, getRenderers, init, isEnabled, isProductionReact, printReport, serialize, serializeOptions, shouldTrack, summarize, track, useWhyRerender };
+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 };