rerender-lens 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,3 @@
-import * as ReactNS from 'react';
-
 /** Why a single prop/state/hook value differs between two renders. */
 type ChangeKind = 
 /** New reference, but deep-equal to the previous value. Avoidable. */
@@ -34,15 +32,43 @@ type RenderTrigger =
 /** More than one of the above. */
  | 'mixed';
 interface HookChange extends Change {
-    /** `useState`, `useReducer`, `useContext`, ... */
+    /** `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;
-    /** Monotonic per-component render count (1 = first update, mount is never reported). */
+    /** 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. */
@@ -54,8 +80,22 @@ interface RenderReport {
     propChanges: Change[];
     /** Class components only. */
     stateChanges: Change[];
-    /** Function components only, when `trackHooks` is on. */
+    /** 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. */
@@ -72,7 +112,7 @@ interface Options {
     include?: ComponentMatcher[];
     /** Components never to track, even when marked. */
     exclude?: ComponentMatcher[];
-    /** Capture `useState`/`useReducer`/`useContext` values and diff them. Default true. */
+    /** 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;
@@ -84,27 +124,26 @@ interface Options {
     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;
 }
-/**
- * The React object to patch. Structural so that both `import React from 'react'`
- * and `import * as React from 'react'` type-check.
- */
-type ReactLike = Pick<typeof ReactNS, 'createElement' | 'memo' | 'forwardRef' | 'useRef'> & Partial<Pick<typeof ReactNS, 'useState' | 'useReducer' | 'useContext' | 'useSyncExternalStore'>>;
 /** Marker static: `MyComponent.rerenderLens = true` opts a component in. */
 declare const MARKER: "rerenderLens";
 
-type AnyType = any;
 declare function getDisplayName(type: unknown): string;
-/** Map an element type to its tracked wrapper (or return it unchanged). */
-declare function resolveType(type: AnyType): AnyType;
+/** Decide whether a component type is tracked under the given options. */
+declare function shouldTrack(type: unknown, o: Options): boolean;
 /**
- * Patch `React.createElement` (and the state hooks) so tracked components report
- * their re-renders. Returns a function that undoes the patch.
+ * Start reporting re-renders of tracked components. Observes React commits
+ * through the DevTools global hook; nothing in React is patched or wrapped.
+ * Returns a function that stops reporting.
  */
-declare function init(R: ReactLike, options?: Options): () => void;
-/** Update options at runtime. Include/exclude changes apply to elements created afterwards. */
+declare function init(options?: Options): () => void;
+/** Merge options at runtime. Takes effect on the next commit. */
 declare function configure(options: Options): void;
-/** Restore the original React functions. Already-created wrappers keep working but stop reporting. */
+/** Stop reporting and restore the DevTools hook callback. */
 declare function disable(): void;
 declare function isEnabled(): boolean;
 /**
@@ -113,6 +152,86 @@ 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.
+ */
+
+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;
+}
+/**
+ * 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.
+ */
+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;
+
 type HookOptions = Pick<Options, 'notifier' | 'silent' | 'console' | 'collapse' | 'logAll'>;
 /**
  * Track one component from the inside, without patching React:
@@ -147,12 +266,23 @@ declare function diffRecords(prev: Record<string, unknown> | undefined | null, n
 
 interface BuildInput {
     component: string;
+    instanceId?: number;
     renderCount: number;
     prevProps: Record<string, unknown>;
     nextProps: Record<string, unknown>;
     propChanges: Change[];
     stateChanges?: Change[];
     hookChanges?: HookChange[];
+    parent?: ParentInfo | null;
+    owner?: string | null;
+    path?: string[];
+    /** Default true: `useWhyRerender` and the console output assume the component decides on props alone. */
+    memoized?: boolean;
+    selfDuration?: number;
+    treeDuration?: number;
+    commitId?: number;
+    commitPriority?: CommitPriority;
+    source?: SourceLocation;
 }
 declare function buildReport(input: BuildInput): RenderReport;
 declare function summarize(report: RenderReport): string;
@@ -175,13 +305,53 @@ declare function createCollector(): Collector;
 declare function combineNotifiers(...notifiers: Array<Notifier | undefined | null | false>): Notifier;
 
 declare const DEVTOOLS_MARKER: "__rerenderLens";
-declare const PROTOCOL_VERSION = 1;
+/** 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;
@@ -189,6 +359,25 @@ interface DevtoolsNotifierOptions {
     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). */
@@ -196,6 +385,21 @@ interface DevtoolsBridge {
     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 {
@@ -204,10 +408,16 @@ declare global {
 }
 /** 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()`.
+ * Also installs `window.__RERENDER_LENS_DEVTOOLS__` with `replay()` / `clear()` / `pull()` and friends.
  */
 declare function createDevtoolsNotifier(options?: DevtoolsNotifierOptions): Notifier;
 
-export { type Change, type ChangeKind, type Collector, type ComponentMatcher, DEVTOOLS_MARKER, type DevtoolsBridge, type DevtoolsMessage, type DevtoolsNotifierOptions, type HookChange, MARKER, type Notifier, type Options, PROTOCOL_VERSION, type RenderReport, type RenderTrigger, buildReport, classify, combineNotifiers, configure, createCollector, createDevtoolsNotifier, deepEqual, diffRecords, disable, getDisplayName, init, isEnabled, printReport, resolveType, serialize, summarize, track, useWhyRerender };
+/** 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 };