react-render-detective 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,96 +1,8 @@
-import { b as RenderEvent, j as Confidence, R as RenderReason, a as DetectiveOptions, D as DetectiveConfig, A as AppStats, d as ComponentStats } from './types-gl13xwmN.js';
-export { i as ComponentInfo, C as ContextChange, f as Diagnosis, I as Inspected, g as InspectionLimits, M as Mode, P as PropChange, k as PropChangeKind, h as PropValueType, c as RenderPhase, l as RenderTimings, e as Thresholds, T as TrackedStateChange } from './types-gl13xwmN.js';
+import { j as Confidence, b as RenderEvent, R as RenderReason, a as DetectiveOptions, D as DetectiveConfig, A as AppStats, d as ComponentStats } from './types-CRET8EhB.js';
+export { i as ComponentInfo, C as ContextChange, f as Diagnosis, I as Inspected, g as InspectionLimits, M as Mode, P as PropChange, k as PropChangeKind, h as PropValueType, c as RenderPhase, l as RenderTimings, S as SelectorChange, e as Thresholds, T as TrackedStateChange } from './types-CRET8EhB.js';
 import { RenderProfile } from './testing.js';
 import { ComponentType, ReactNode, Dispatch, SetStateAction } from 'react';
 
-/**
- * Interaction-scoped attribution.
- *
- * Performance is felt per interaction, not in aggregate — and INP is the metric
- * teams are actually judged on. This joins the two halves: the browser says a
- * keystroke took 240ms, and the render events say which components spent it and
- * why.
- *
- * Uses `PerformanceObserver` with `event` timing, a public browser API. Where it
- * is unsupported (older Safari, jsdom) interaction tracking simply stays empty
- * rather than guessing.
- */
-interface InteractionRecord {
-    id: string;
-    /** `click`, `keydown`, `pointerup`… */
-    type: string;
-    /** Best-effort description of what was interacted with. */
-    target?: string;
-    startTime: number;
-    /** Browser-reported event duration — the number INP is computed from. */
-    durationMs: number;
-    /**
-     * For a manually measured interaction: how long the synchronous action took.
-     * Immune to throttling, unlike the full window, which waits on a frame.
-     */
-    handlerMs?: number;
-    /** Renders committed inside this interaction's window. */
-    renders: RenderEvent[];
-    /** Sum of self durations for those renders. */
-    renderTimeMs: number;
-    /** Render time that no observable input change explains. */
-    avoidableRenderTimeMs: number;
-}
-interface InteractionSummary {
-    interaction: InteractionRecord;
-    /** Components ordered by cost within this interaction. */
-    contributors: Array<{
-        component: string;
-        source?: string;
-        renders: number;
-        totalMs: number;
-        cause: string;
-    }>;
-    headline: string;
-    nextStep: string;
-    confidence: Confidence;
-}
-interface RawEventTiming {
-    name: string;
-    startTime: number;
-    duration: number;
-    target?: string;
-    handlerMs?: number;
-}
-declare class InteractionTracker {
-    private capacity;
-    private records;
-    private observer;
-    private nextId;
-    constructor(capacity?: number);
-    /** Returns false when the browser cannot report event timing. */
-    start(): boolean;
-    stop(): void;
-    /** Is the automatic path available in this browser? */
-    get automatic(): boolean;
-    /**
-     * Time an interaction by hand.
-     *
-     * The automatic path depends on the Event Timing API, which Safari only
-     * gained in 16.4 and which does not fire for synthetic input at all — so
-     * anything driven by a test harness records nothing. This measures a specific
-     * action instead, up to the paint that follows it, and needs no browser
-     * support beyond `performance.now`.
-     */
-    measure<T>(label: string, action: () => T): T;
-    /** Exposed for tests and for `measure`. */
-    record(timing: RawEventTiming): InteractionRecord;
-    clear(): void;
-    /**
-     * Joins render events to interactions by commit time. A render belongs to an
-     * interaction when it committed between the event starting and shortly after
-     * it finished — React commits just after the event handler returns.
-     */
-    attribute(events: RenderEvent[]): InteractionRecord[];
-}
-declare function summarise(record: InteractionRecord): InteractionSummary;
-declare function formatInteraction(summary: InteractionSummary): string;
-
 /**
  * "Where should I spend my next hour?"
  *
@@ -171,6 +83,31 @@ interface RenderDetectiveProps {
  */
 declare function RenderDetective({ name, children }: RenderDetectiveProps): ReactNode;
 
+interface TrackSelectorOptions {
+    /** Readable label — a property path where one could be derived, else the call site. */
+    name?: string;
+    /** `File.tsx:12:3` of the call, supplied by the build plugin. */
+    source?: string;
+}
+/**
+ * Records a store value and returns it untouched.
+ *
+ * Pass-through by construction: the value is returned as given, and nothing
+ * here can change what the component receives.
+ */
+declare function trackSelector<T>(value: T, options?: TrackSelectorOptions): T;
+/**
+ * Wraps a store hook so its results are attributed. Signature-preserving: extra
+ * arguments (react-redux's equality function, for instance) pass straight
+ * through, because changing them would change the app's behaviour.
+ *
+ *   const useSelector = createTrackedSelectorHook(useReduxSelector);
+ *
+ * The build plugin rewrites `useSelector` imports for you; use this directly for
+ * a custom store hook, or where the plugin cannot run.
+ */
+declare function createTrackedSelectorHook<A extends unknown[], R>(hook: (...args: A) => R, options?: TrackSelectorOptions): (...args: A) => R;
+
 /**
  * In-component diagnostics without wrapping.
  *
@@ -231,6 +168,13 @@ interface Explanation {
         share: number;
         valueType: string;
     }>;
+    /** Store selectors that returned a new reference with identical contents. */
+    unstableSelectors: Array<{
+        name: string;
+        source?: string;
+        count: number;
+        share: number;
+    }>;
     averageSelfDuration: number;
     totalSelfDuration: number;
     potentiallyAvoidableRenders: number;
@@ -280,25 +224,6 @@ declare function explain(componentName: string): string | undefined;
 declare function explainStructured(componentName: string): Explanation | undefined;
 /** Snapshot render behaviour for regression testing. See `react-render-detective/testing`. */
 declare function getRenderProfile(scenario: string): RenderProfile;
-/**
- * Interactions, slowest first, with the renders that happened inside each.
- *
- * This is the bridge from render causality to what a user actually feels: the
- * browser reports how long the interaction took, and the render events say
- * which components spent that time and why.
- */
-declare function getInteractions(): InteractionRecord[];
-/** Structured analysis of one interaction. Defaults to the slowest recorded. */
-declare function explainInteractionStructured(id?: string): InteractionSummary | undefined;
-declare function explainInteraction(id?: string): string | undefined;
-declare function printInteractions(limit?: number): void;
-/**
- * Time one interaction explicitly, up to the paint that follows it.
- *
- * Needed wherever the automatic path cannot see: Safari before 16.4, and any
- * synthetic input, which never produces Event Timing entries.
- */
-declare function measureInteraction<T>(label: string, action: () => T): T;
 /**
  * Components ranked by estimated recoverable time — the triage view. Render
  * counts answer the wrong question; this answers "what should I fix first?".
@@ -323,13 +248,8 @@ declare const ReactRenderDetective: {
     explainStructured: typeof explainStructured;
     getOpportunities: typeof getOpportunities;
     printOpportunities: typeof printOpportunities;
-    getInteractions: typeof getInteractions;
-    explainInteraction: typeof explainInteraction;
-    explainInteractionStructured: typeof explainInteractionStructured;
-    printInteractions: typeof printInteractions;
-    measureInteraction: typeof measureInteraction;
     getRenderProfile: typeof getRenderProfile;
     printStats: typeof printStats;
 };
 
-export { AppStats, ComponentStats, Confidence, DetectiveConfig, DetectiveOptions, type Explanation, type InteractionRecord, type InteractionSummary, InteractionTracker, type Opportunity, ReactRenderDetective, RenderDetective, type RenderDetectiveProps, RenderEvent, RenderReason, type TrackOptions, clear, configure, explain, explainEvents, explainInteraction, explainInteractionStructured, explainStructured, formatExplanation, formatInteraction, formatOpportunities, getComponentStats, getConfig, getEvents, getInteractions, getOpportunities, getRenderProfile, getStats, init, isEnabled, measureInteraction, printInteractions, printOpportunities, printStats, rankOpportunities, reset, subscribe, summarise as summariseInteraction, useRenderDiagnostics, useTrackedContextValue, useTrackedEffect, useTrackedState, withRenderDetective };
+export { AppStats, ComponentStats, Confidence, DetectiveConfig, DetectiveOptions, type Explanation, type Opportunity, ReactRenderDetective, RenderDetective, type RenderDetectiveProps, RenderEvent, RenderReason, type TrackOptions, type TrackSelectorOptions, clear, configure, createTrackedSelectorHook, explain, explainEvents, explainStructured, formatExplanation, formatOpportunities, getComponentStats, getConfig, getEvents, getOpportunities, getRenderProfile, getStats, init, isEnabled, printOpportunities, printStats, rankOpportunities, reset, subscribe, trackSelector, useRenderDiagnostics, useTrackedContextValue, useTrackedEffect, useTrackedState, withRenderDetective };