react-render-detective 0.2.0 → 0.4.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-BWVaQPHb.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-BWVaQPHb.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;
@@ -10,6 +133,12 @@ interface TrackOptions {
      * is no runtime way to obtain it.
      */
     source?: string;
+    /**
+     * Set by the build plugin when the component is declared inside another
+     * function. React sees a new component type on every parent render and
+     * rebuilds the whole subtree, so this turns a guess into a fact.
+     */
+    declaredInRender?: boolean;
 }
 
 /**
@@ -107,6 +236,8 @@ interface Explanation {
     potentiallyAvoidableRenders: number;
     estimatedAvoidableTime: number;
     devReplays: number;
+    /** Times the component was rebuilt rather than re-rendered. */
+    remounts: number;
     headline: string;
     nextStep: string;
     confidence: Confidence;
@@ -115,7 +246,9 @@ interface Explanation {
  * The flagship "explain this render" answer, aggregated across the recorded
  * history of one component. Pure — no React, no console.
  */
-declare function explainEvents(component: string, events: RenderEvent[]): Explanation | undefined;
+declare function explainEvents(component: string, events: RenderEvent[], lifecycle?: {
+    remounts: number;
+}): Explanation | undefined;
 declare function formatExplanation(e: Explanation): string;
 
 /**
@@ -145,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. */
@@ -161,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 };

package/dist/index.js

@@ -1,6 +1,7 @@
-import { explainEvents, formatExplanation } from './chunk-LSIXHWQD.js';
-export { explainEvents, formatExplanation } from './chunk-LSIXHWQD.js';
-import { getDetective, inspect, shallowEqual, diffProps, formatInspected } from './chunk-MSISKPST.js';
+import { explainEvents, formatExplanation } from './chunk-HOTY7J3X.js';
+export { explainEvents, formatExplanation } from './chunk-HOTY7J3X.js';
+import { getDetective, inspect, shallowEqual, diffProps, formatInspected } from './chunk-QOGTEVBP.js';
+import { profileFromEvents } from './chunk-LILK23YH.js';
 import * as React from 'react';
 import { createContext, useContext, useState, useRef, useEffect, useLayoutEffect, useCallback, Profiler } from 'react';
 import { jsx } from 'react/jsx-runtime';
@@ -118,6 +119,245 @@ function label(event) {
       return "undetermined";
   }
 }
+
+// src/core/interactions.ts
+var COMMIT_SLACK_MS = 100;
+var FALLBACK_CLOSE_MS = 50;
+var InteractionTracker = class {
+  constructor(capacity = 50) {
+    this.capacity = capacity;
+    this.records = [];
+    this.nextId = 0;
+  }
+  /** Returns false when the browser cannot report event timing. */
+  start() {
+    if (this.observer) return true;
+    const PO = globalThis.PerformanceObserver;
+    const supported = PO?.supportedEntryTypes?.includes("event");
+    if (!PO || !supported) return false;
+    try {
+      const observer = new PO((list) => {
+        for (const entry of list.getEntries()) {
+          const timing = entry;
+          this.record({
+            name: timing.name,
+            startTime: timing.startTime,
+            duration: timing.duration,
+            target: describeTarget(timing.target)
+          });
+        }
+      });
+      observer.observe({ type: "event", buffered: true, durationThreshold: 16 });
+      this.observer = observer;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  stop() {
+    this.observer?.disconnect();
+    this.observer = void 0;
+  }
+  /** Is the automatic path available in this browser? */
+  get automatic() {
+    return this.observer !== void 0;
+  }
+  /**
+   * 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(label2, action) {
+    const startTime = now();
+    let handlerMs = 0;
+    let finished = false;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      this.record({ name: label2, startTime, duration: now() - startTime, handlerMs });
+    };
+    let result;
+    try {
+      result = action();
+      handlerMs = now() - startTime;
+    } catch (error) {
+      handlerMs = now() - startTime;
+      finish();
+      throw error;
+    }
+    const raf = globalThis.requestAnimationFrame;
+    if (raf) raf(() => raf(finish));
+    setTimeout(finish, FALLBACK_CLOSE_MS);
+    return result;
+  }
+  /** Exposed for tests and for `measure`. */
+  record(timing) {
+    const record = {
+      id: `interaction_${++this.nextId}`,
+      type: timing.name,
+      target: timing.target,
+      startTime: timing.startTime,
+      durationMs: timing.duration,
+      handlerMs: timing.handlerMs,
+      renders: [],
+      renderTimeMs: 0,
+      avoidableRenderTimeMs: 0
+    };
+    this.records.push(record);
+    if (this.records.length > this.capacity) this.records.shift();
+    return record;
+  }
+  clear() {
+    this.records.length = 0;
+  }
+  /**
+   * 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) {
+    for (const record of this.records) {
+      const from = record.startTime;
+      const to = record.startTime + record.durationMs + COMMIT_SLACK_MS;
+      record.renders = events.filter((e) => e.timings.commitTime >= from && e.timings.commitTime <= to);
+      record.renderTimeMs = record.renders.reduce((a, e) => a + e.timings.selfDuration, 0);
+      record.avoidableRenderTimeMs = record.renders.filter((e) => e.diagnosis.potentiallyAvoidable).reduce((a, e) => a + e.timings.selfDuration, 0);
+    }
+    return [...this.records].sort((a, b) => b.durationMs - a.durationMs);
+  }
+};
+function summarise(record) {
+  const byComponent = /* @__PURE__ */ new Map();
+  for (const event of record.renders) {
+    const entry = byComponent.get(event.component.name) ?? {
+      renders: 0,
+      totalMs: 0,
+      source: event.component.source,
+      cause: event.diagnosis.reason
+    };
+    entry.renders++;
+    entry.totalMs += event.timings.selfDuration;
+    byComponent.set(event.component.name, entry);
+  }
+  const contributors = [...byComponent.entries()].map(([component, v]) => ({ component, source: v.source, renders: v.renders, totalMs: v.totalMs, cause: v.cause })).sort((a, b) => b.totalMs - a.totalMs);
+  const top = contributors[0];
+  const accounted = (record.handlerMs ?? record.durationMs) + record.renderTimeMs;
+  const idleWindow = record.handlerMs !== void 0 && record.durationMs > accounted * 3 && record.durationMs - accounted > 100;
+  const effectiveMs = idleWindow ? accounted : record.durationMs;
+  const share = effectiveMs > 0 ? record.renderTimeMs / effectiveMs : 0;
+  let headline;
+  let nextStep;
+  let confidence = "medium";
+  if (idleWindow) {
+    headline = `${record.type}: ${fmt(record.handlerMs ?? 0)} in the handler and ${fmt(record.renderTimeMs)} rendering. The measured window was ${fmt(record.durationMs)}, but most of that was the page waiting for a frame \u2014 ignore it.`;
+    nextStep = record.renderTimeMs > (record.handlerMs ?? 0) ? `Rendering dominates the real work${top ? `; start with ${top.component}` : ""}.` : "The handler itself costs more than rendering. Profile the handler, not React.";
+    return { interaction: record, contributors, headline, nextStep, confidence: "medium" };
+  }
+  if (record.renders.length === 0) {
+    headline = `${record.type} took ${fmt(record.durationMs)}, and no instrumented component rendered inside it.`;
+    nextStep = "The cost is somewhere other than React rendering \u2014 an event handler, a layout, or an uninstrumented component. Instrument more of the tree to narrow it down.";
+    confidence = "low";
+  } else if (share >= 0.4 && record.avoidableRenderTimeMs > 0) {
+    headline = `${record.type} took ${fmt(record.durationMs)}; ${fmt(record.renderTimeMs)} of it was rendering, and ${fmt(record.avoidableRenderTimeMs)} of that had no input change to explain it.`;
+    nextStep = top ? `Start with ${top.component}${top.source ? ` (${top.source})` : ""} \u2014 ${fmt(top.totalMs)} across ${top.renders} render${top.renders === 1 ? "" : "s"}.` : "Look at the top contributor below.";
+    confidence = "high";
+  } else if (share >= 0.4) {
+    headline = `${record.type} took ${fmt(record.durationMs)}; ${fmt(record.renderTimeMs)} of it was rendering, all of it explained by real input changes.`;
+    nextStep = "This is genuine work. Make the renders cheaper rather than fewer \u2014 or do less of it per interaction.";
+    confidence = "high";
+  } else {
+    headline = `${record.type} took ${fmt(record.durationMs)}, but only ${fmt(record.renderTimeMs)} was React rendering.`;
+    nextStep = "Most of the cost is outside rendering \u2014 event handlers, layout or paint. A browser profile will show more than this tool can.";
+    confidence = "medium";
+  }
+  return { interaction: record, contributors, headline, nextStep, confidence };
+}
+function formatInteraction(summary) {
+  const { interaction: i } = summary;
+  const lines = [
+    `${i.type}${i.target ? ` on ${i.target}` : ""}   ${fmt(i.durationMs)}`,
+    "",
+    summary.headline
+  ];
+  if (summary.contributors.length > 0) {
+    lines.push("", "Rendering inside this interaction");
+    for (const c of summary.contributors.slice(0, 8)) {
+      lines.push(
+        `  ${c.component.padEnd(22)} ${String(c.renders).padStart(4)} render(s)  ${fmt(c.totalMs).padStart(8)}  ${c.cause}`
+      );
+    }
+  }
+  lines.push("", `Next step`, `  ${summary.nextStep}`, "", `Confidence: ${summary.confidence}`);
+  return lines.join("\n");
+}
+function describeTarget(target) {
+  if (!target || typeof target !== "object") return void 0;
+  const el = target;
+  if (!el.tagName) return void 0;
+  const tag = el.tagName.toLowerCase();
+  if (el.id) return `${tag}#${el.id}`;
+  const className = typeof el.className === "string" ? el.className.trim().split(/\s+/)[0] : void 0;
+  if (className) return `${tag}.${className}`;
+  const text = el.textContent?.trim().slice(0, 20);
+  return text ? `${tag} "${text}"` : tag;
+}
+var fmt = (ms) => `${ms.toFixed(1)}ms`;
+var now = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+
+// src/core/opportunities.ts
+var DEFAULT_MIN_SAVING_MS = 1;
+function rankOpportunities({ events, lifecycles, minSavingMs = DEFAULT_MIN_SAVING_MS }) {
+  const names = new Set(events.map((e) => e.component.name));
+  const out = [];
+  for (const name of names) {
+    const lifecycle = lifecycles.get(name);
+    const explanation = explainEvents(name, events, lifecycle);
+    if (!explanation) continue;
+    const mounts = events.filter((e) => e.component.name === name && e.phase === "mount");
+    const averageMountCost = mounts.length ? mounts.reduce((a, e) => a + e.timings.selfDuration, 0) / mounts.length : 0;
+    const remountSaving = explanation.remounts * averageMountCost;
+    const estimatedSavingMs = explanation.estimatedAvoidableTime + remountSaving;
+    if (estimatedSavingMs < minSavingMs) continue;
+    out.push({
+      component: name,
+      source: explanation.source,
+      estimatedSavingMs,
+      avoidableRenders: explanation.potentiallyAvoidableRenders,
+      remounts: explanation.remounts,
+      averageSelfDuration: explanation.averageSelfDuration,
+      summary: explanation.headline,
+      nextStep: explanation.nextStep,
+      confidence: explanation.confidence
+    });
+  }
+  return out.sort((a, b) => b.estimatedSavingMs - a.estimatedSavingMs);
+}
+function formatOpportunities(opportunities) {
+  if (opportunities.length === 0) {
+    return "React Render Detective\n\nNo measurable render waste found yet. Interact with the app and try again.";
+  }
+  const lines = [
+    "React Render Detective \u2014 where to spend your next hour",
+    "",
+    "Ranked by estimated recoverable time. These are estimates, not promises:",
+    "measure each fix.",
+    ""
+  ];
+  for (const [index, o] of opportunities.entries()) {
+    lines.push(
+      `${String(index + 1).padStart(2)}. ${o.component}${o.source ? `   ${o.source}` : ""}`,
+      `    ~${o.estimatedSavingMs.toFixed(0)}ms recoverable   ${o.avoidableRenders} avoidable render${o.avoidableRenders === 1 ? "" : "s"}${o.remounts > 0 ? `, ${o.remounts}\xD7 rebuilt` : ""}   (confidence: ${o.confidence})`,
+      `    ${o.summary}`,
+      `    \u2192 ${o.nextStep}`,
+      ""
+    );
+  }
+  return lines.join("\n");
+}
 var AncestryContext = createContext(void 0);
 AncestryContext.displayName = "RenderDetectiveAncestry";
 function useInstrumentedNode(name, props, source) {
@@ -171,6 +411,7 @@ var IS_WRAPPER = /* @__PURE__ */ Symbol.for("react-render-detective.wrapper");
 function withRenderDetective(Component, options = {}) {
   if (Component[IS_WRAPPER]) return Component;
   const name = options.name ?? componentName(Component);
+  getDetective().noteDefinition(name, options.source, options.declaredInRender === true);
   function RenderDetected(props) {
     const { node, onRender } = useInstrumentedNode(name, props, options.source);
     return renderInstrumented(node, onRender, /* @__PURE__ */ jsx(Component, { ...props }));
@@ -284,12 +525,21 @@ function isRecord(v) {
 
 // src/index.ts
 var REPORTER = /* @__PURE__ */ Symbol.for("react-render-detective.reporter");
+var INTERACTIONS = /* @__PURE__ */ Symbol.for("react-render-detective.interactions");
+function tracker() {
+  const g = globalThis;
+  if (!g[INTERACTIONS]) g[INTERACTIONS] = new InteractionTracker();
+  return g[INTERACTIONS];
+}
 function init(options = {}) {
   const detective = getDetective();
   detective.init(options);
   const g = globalThis;
   g[REPORTER]?.();
   g[REPORTER] = void 0;
+  if (detective.enabled) {
+    tracker().start();
+  }
   if (detective.enabled && detective.config.mode !== "silent") {
     g[REPORTER] = attachConsoleReporter(detective);
   } else if (!detective.enabled) {
@@ -321,19 +571,63 @@ function subscribe(listener) {
 }
 function clear() {
   getDetective().clear();
+  tracker().clear();
 }
 function reset() {
   const g = globalThis;
   g[REPORTER]?.();
   g[REPORTER] = void 0;
+  g[INTERACTIONS]?.stop();
+  g[INTERACTIONS] = void 0;
   getDetective().reset();
 }
 function explain(componentName2) {
-  const explanation = explainEvents(componentName2, getEvents());
+  const explanation = explainStructured(componentName2);
   return explanation ? formatExplanation(explanation) : void 0;
 }
 function explainStructured(componentName2) {
-  return explainEvents(componentName2, getEvents());
+  return explainEvents(componentName2, getEvents(), getDetective().lifecycleOf(componentName2));
+}
+function getRenderProfile(scenario) {
+  const remounts = {};
+  for (const stats of getDetective().getComponentStats()) remounts[stats.name] = stats.remountCount;
+  return profileFromEvents(scenario, getEvents(), remounts);
+}
+function getInteractions() {
+  return tracker().attribute(getEvents());
+}
+function explainInteractionStructured(id) {
+  const records = getInteractions();
+  const record = id ? records.find((r) => r.id === id) : records[0];
+  return record ? summarise(record) : void 0;
+}
+function explainInteraction(id) {
+  const summary = explainInteractionStructured(id);
+  return summary ? formatInteraction(summary) : void 0;
+}
+function printInteractions(limit = 5) {
+  const records = getInteractions().slice(0, limit);
+  if (records.length === 0) {
+    console.log(
+      tracker().automatic ? "No interactions recorded yet. Event timing is working \u2014 nothing has taken longer than 16ms.\nSynthetic clicks from a test harness never produce these entries; use measureInteraction() there." : "This browser does not report event timing (Safari before 16.4, jsdom).\nUse measureInteraction(label, fn) to time interactions by hand."
+    );
+    return;
+  }
+  console.log(records.map((r) => formatInteraction(summarise(r))).join("\n\n"));
+}
+function measureInteraction(label2, action) {
+  return tracker().measure(label2, action);
+}
+function getOpportunities(limit = 10) {
+  const detective = getDetective();
+  const lifecycles = /* @__PURE__ */ new Map();
+  for (const stats of detective.getComponentStats()) {
+    lifecycles.set(stats.name, { remounts: stats.remountCount });
+  }
+  return rankOpportunities({ events: detective.getEvents(), lifecycles }).slice(0, limit);
+}
+function printOpportunities(limit = 10) {
+  console.log(formatOpportunities(getOpportunities(limit)));
 }
 function printStats() {
   const s = getStats();
@@ -346,6 +640,14 @@ function printStats() {
     `Slow renders             ${s.slowRenders}`,
     `Potentially avoidable    ${s.potentiallyAvoidableRenders}`
   ];
+  const rebuilt = s.mostRendered.filter((c) => c.remountCount >= 2);
+  if (rebuilt.length > 0) {
+    lines.push(
+      "",
+      "Rebuilt rather than re-rendered (state and DOM discarded each time)",
+      ...rebuilt.slice(0, 5).map((c) => `  ${c.name.padEnd(22)} ${String(c.remountCount).padStart(5)}\xD7 remounted`)
+    );
+  }
   if (s.devReplays > 0) {
     lines.push(`Development replays      ${s.devReplays} (StrictMode / discarded \u2014 not counted above)`);
   }
@@ -372,9 +674,17 @@ var ReactRenderDetective = {
   reset,
   explain,
   explainStructured,
+  getOpportunities,
+  printOpportunities,
+  getInteractions,
+  explainInteraction,
+  explainInteractionStructured,
+  printInteractions,
+  measureInteraction,
+  getRenderProfile,
   printStats
 };
 
-export { ReactRenderDetective, RenderDetective, clear, configure, explain, explainStructured, getComponentStats, getConfig, getEvents, getStats, init, isEnabled, printStats, reset, subscribe, useRenderDiagnostics, useTrackedContextValue, useTrackedEffect, useTrackedState, withRenderDetective };
+export { InteractionTracker, ReactRenderDetective, RenderDetective, clear, configure, explain, explainInteraction, explainInteractionStructured, explainStructured, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map