react-render-detective 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,7 +1,130 @@
-import { b as RenderEvent, R as RenderReason, j as Confidence, a as DetectiveOptions, D as DetectiveConfig, A as AppStats, d as ComponentStats } from './types-gl13xwmN.js';
+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 { 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?"
+ *
+ * Render counts answer the wrong question — a component rendering 2 000 times
+ * for 0.01ms is not the problem, and one rendering 40 times for 12ms might be.
+ * This ranks by **estimated recoverable time**, so the top of the list is the
+ * biggest win rather than the noisiest component.
+ */
+interface Opportunity {
+    component: string;
+    source?: string;
+    /** Milliseconds plausibly recovered by fixing this. The ranking key. */
+    estimatedSavingMs: number;
+    /** Renders where no observable input changed. */
+    avoidableRenders: number;
+    /** Times the component was rebuilt rather than re-rendered. */
+    remounts: number;
+    averageSelfDuration: number;
+    /** One line: what to look at. Comes from the diagnostic engine, not from here. */
+    summary: string;
+    nextStep: string;
+    confidence: Confidence;
+}
+interface OpportunityInput {
+    events: RenderEvent[];
+    lifecycles: Map<string, {
+        remounts: number;
+    }>;
+    /** Ignore anything below this. Noise is worse than silence in a ranked list. */
+    minSavingMs?: number;
+}
+declare function rankOpportunities({ events, lifecycles, minSavingMs }: OpportunityInput): Opportunity[];
+declare function formatOpportunities(opportunities: Opportunity[]): string;
+
 interface TrackOptions {
     /** Overrides the inferred component name. Required for anonymous components. */
     name?: string;
@@ -155,6 +278,33 @@ declare function reset(): void;
 declare function explain(componentName: string): string | undefined;
 /** Structured form of `explain`, for building UIs on top. */
 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?".
+ */
+declare function getOpportunities(limit?: number): Opportunity[];
+declare function printOpportunities(limit?: number): void;
 /** Prints the application-level dashboard (§53). */
 declare function printStats(): void;
 /** Namespaced form, matching the documented `ReactRenderDetective.init()` usage. */
@@ -171,7 +321,15 @@ declare const ReactRenderDetective: {
     reset: typeof reset;
     explain: typeof explain;
     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, ReactRenderDetective, RenderDetective, type RenderDetectiveProps, RenderEvent, RenderReason, type TrackOptions, clear, configure, explain, explainEvents, explainStructured, formatExplanation, getComponentStats, getConfig, getEvents, getStats, init, isEnabled, printStats, reset, subscribe, useRenderDiagnostics, useTrackedContextValue, useTrackedEffect, useTrackedState, withRenderDetective };
+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 };