@react-perfscope/core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -171,6 +171,19 @@ type FrameStats = {
     /** Approximate frames dropped across the recording (vs a 60fps budget). */
     droppedFrames: number;
 };
+/** A component whose instances were unmounted but stayed retained (not
+ * garbage-collected) with a count that climbed across the recording — i.e. a
+ * suspected leak. Identifies WHICH component leaks and HOW MANY instances; the
+ * retainer chain (who holds them) is not observable from in-page JS. */
+type LeakSuspect = {
+    component: string;
+    /** Total instances of this component unmounted during the recording. */
+    unmounted: number;
+    /** Unmounted instances still alive at the end (unmounted − collected). */
+    retained: number;
+    /** Growth rate of the retained-instance floor, in instances per minute. */
+    retainedSlopePerMin: number;
+};
 interface RecordingResult {
     signals: Signal[];
     startedAt: number;
@@ -181,12 +194,15 @@ interface RecordingResult {
     /** requestAnimationFrame timestamps captured during the recording, for
      * frame-rate / jank analysis. Attached at finalize. */
     frames?: number[];
+    /** Components with a sustained rise in retained-after-unmount instances —
+     * suspected leaks. Attached at finalize; absent when none or unsupported. */
+    leakSuspects?: LeakSuspect[];
 }
 /** Collectors are usually keyed by the SignalKind they emit. A few (heap,
  * self-profiling) drive a side-channel instead of emitting signals; `'heap'`
  * widens the kind for the heap sampler, which attaches a time series via
  * finalize rather than pushing signals. */
-type CollectorKind = SignalKind | 'heap' | 'frame';
+type CollectorKind = SignalKind | 'heap' | 'frame' | 'leak';
 interface Collector {
     readonly kind: CollectorKind;
     activate(emit: (signal: Signal) => void): void;
@@ -200,6 +216,9 @@ interface Recorder {
     use(collector: Collector): void;
 }
 
+/** Hard cap on retained signals; the oldest are dropped past this. Exported so
+ * downstream tests can assert the buffer never grows beyond it. */
+declare const BUFFER_CAP = 10000;
 declare function createRecorder(): Recorder;
 
 /** A parsed source map (the JSON object), as returned by a FetchMap. */
@@ -241,6 +260,44 @@ declare function markSelfRequest(url: string): void;
 /** True when `url` was fetched by react-perfscope itself. */
 declare function isSelfRequest(url: string): boolean;
 
+type Capabilities = Record<SignalKind, boolean>;
+/** Which signal kinds the current browser can actually measure. The render and
+ * forced-reflow collectors are pure JS (React fibers / DOM-API instrumentation)
+ * so they work everywhere; the rest depend on PerformanceObserver entry types
+ * that Firefox and Safari do not implement (long tasks, layout shift, INP). */
+declare function detectCapabilities(): Capabilities;
+/** Signal kinds the current browser cannot measure — for telling the user a
+ * tab is empty because of the platform, not because nothing happened. */
+declare function unsupportedKinds(): SignalKind[];
+
+/** One reading of how many unmounted instances of a component are still
+ * retained (alive, not yet garbage-collected) at a point in time. */
+type LeakSample = {
+    at: number;
+    retained: number;
+};
+/**
+ * Decide whether a component's retained-instance series indicates a leak.
+ *
+ * Mirrors {@link analyzeHeapTrend}: GC makes the raw retained count a sawtooth
+ * (instances pile up, then a sweep collects a batch), so the reliable signal is
+ * the *floor* — the post-GC troughs. We segment the series, take each segment's
+ * minimum, and regress those minima against time.
+ *
+ * A rising slope alone is not enough: a one-time step (a screen mounts N
+ * long-lived instances once, then plateaus) regresses positive but is not a
+ * leak. So we additionally require the recent half of the floor to still be
+ * rising, and gate on a minimum net growth in instances. This is what makes the
+ * detector robust to React StrictMode's intentional mount→unmount→remount
+ * churn, whose discarded fibers get collected and keep the floor flat.
+ *
+ * Returns null when there are too few samples to say anything.
+ */
+declare function analyzeLeakTrend(samples: LeakSample[]): {
+    leaking: boolean;
+    slopePerMin: number;
+} | null;
+
 type AnchorSignal = InteractionSignal | LongTaskSignal;
 /** How strongly a member is linked to its episode anchor. `caused` means a
  * member's source location matches one of the anchor's hot frames — a real
@@ -421,4 +478,4 @@ interface SelfProfilingCollector extends Collector {
  */
 declare function createSelfProfilingCollector(): SelfProfilingCollector;
 
-export { type AnchorSignal, type Collector, type CollectorKind, type CommitCause, type CreateSourceMapResolverOptions, type Episode, type EpisodeMember, type FetchMap, type ForcedReflowSignal, type FpsSample, type FrameCollector, type FrameStats, type HeapCollector, type HeapSample, type HeapTrend, type HeapTrendClass, type InpPhase, type InteractionCollector, type InteractionSignal, type LayoutShiftSignal, type LinkConfidence, type LongTaskAttribution, type LongTaskScript, type LongTaskSignal, type NetworkSignal, type ProfilerFrame, type ProfilerSample, type ProfilerStack, type ProfilerTrace, type Recorder, type RecordingResult, type RenderReason, type RenderSignal, type Signal, type SignalKind, type SourceMapResolver, type StackFrame, type WebVitalSignal, analyzeFrames, analyzeHeapTrend, attachLazyStack, attributeLongTaskSignals, attributeWindow, correlate, createForcedReflowCollector, createFrameCollector, createHeapCollector, createInteractionCollector, createLayoutShiftCollector, createLongTasksCollector, createNetworkCollector, createRecorder, createSelfProfilingCollector, createSourceMapResolver, createWebVitalsCollector, isSelfRequest, isUserResource, markSelfRequest, parseStack, resolveFrame };
+export { type AnchorSignal, BUFFER_CAP, type Capabilities, type Collector, type CollectorKind, type CommitCause, type CreateSourceMapResolverOptions, type Episode, type EpisodeMember, type FetchMap, type ForcedReflowSignal, type FpsSample, type FrameCollector, type FrameStats, type HeapCollector, type HeapSample, type HeapTrend, type HeapTrendClass, type InpPhase, type InteractionCollector, type InteractionSignal, type LayoutShiftSignal, type LeakSample, type LeakSuspect, type LinkConfidence, type LongTaskAttribution, type LongTaskScript, type LongTaskSignal, type NetworkSignal, type ProfilerFrame, type ProfilerSample, type ProfilerStack, type ProfilerTrace, type Recorder, type RecordingResult, type RenderReason, type RenderSignal, type Signal, type SignalKind, type SourceMapResolver, type StackFrame, type WebVitalSignal, analyzeFrames, analyzeHeapTrend, analyzeLeakTrend, attachLazyStack, attributeLongTaskSignals, attributeWindow, correlate, createForcedReflowCollector, createFrameCollector, createHeapCollector, createInteractionCollector, createLayoutShiftCollector, createLongTasksCollector, createNetworkCollector, createRecorder, createSelfProfilingCollector, createSourceMapResolver, createWebVitalsCollector, detectCapabilities, isSelfRequest, isUserResource, markSelfRequest, parseStack, resolveFrame, unsupportedKinds };

package/dist/index.d.ts

@@ -171,6 +171,19 @@ type FrameStats = {
     /** Approximate frames dropped across the recording (vs a 60fps budget). */
     droppedFrames: number;
 };
+/** A component whose instances were unmounted but stayed retained (not
+ * garbage-collected) with a count that climbed across the recording — i.e. a
+ * suspected leak. Identifies WHICH component leaks and HOW MANY instances; the
+ * retainer chain (who holds them) is not observable from in-page JS. */
+type LeakSuspect = {
+    component: string;
+    /** Total instances of this component unmounted during the recording. */
+    unmounted: number;
+    /** Unmounted instances still alive at the end (unmounted − collected). */
+    retained: number;
+    /** Growth rate of the retained-instance floor, in instances per minute. */
+    retainedSlopePerMin: number;
+};
 interface RecordingResult {
     signals: Signal[];
     startedAt: number;
@@ -181,12 +194,15 @@ interface RecordingResult {
     /** requestAnimationFrame timestamps captured during the recording, for
      * frame-rate / jank analysis. Attached at finalize. */
     frames?: number[];
+    /** Components with a sustained rise in retained-after-unmount instances —
+     * suspected leaks. Attached at finalize; absent when none or unsupported. */
+    leakSuspects?: LeakSuspect[];
 }
 /** Collectors are usually keyed by the SignalKind they emit. A few (heap,
  * self-profiling) drive a side-channel instead of emitting signals; `'heap'`
  * widens the kind for the heap sampler, which attaches a time series via
  * finalize rather than pushing signals. */
-type CollectorKind = SignalKind | 'heap' | 'frame';
+type CollectorKind = SignalKind | 'heap' | 'frame' | 'leak';
 interface Collector {
     readonly kind: CollectorKind;
     activate(emit: (signal: Signal) => void): void;
@@ -200,6 +216,9 @@ interface Recorder {
     use(collector: Collector): void;
 }
 
+/** Hard cap on retained signals; the oldest are dropped past this. Exported so
+ * downstream tests can assert the buffer never grows beyond it. */
+declare const BUFFER_CAP = 10000;
 declare function createRecorder(): Recorder;
 
 /** A parsed source map (the JSON object), as returned by a FetchMap. */
@@ -241,6 +260,44 @@ declare function markSelfRequest(url: string): void;
 /** True when `url` was fetched by react-perfscope itself. */
 declare function isSelfRequest(url: string): boolean;
 
+type Capabilities = Record<SignalKind, boolean>;
+/** Which signal kinds the current browser can actually measure. The render and
+ * forced-reflow collectors are pure JS (React fibers / DOM-API instrumentation)
+ * so they work everywhere; the rest depend on PerformanceObserver entry types
+ * that Firefox and Safari do not implement (long tasks, layout shift, INP). */
+declare function detectCapabilities(): Capabilities;
+/** Signal kinds the current browser cannot measure — for telling the user a
+ * tab is empty because of the platform, not because nothing happened. */
+declare function unsupportedKinds(): SignalKind[];
+
+/** One reading of how many unmounted instances of a component are still
+ * retained (alive, not yet garbage-collected) at a point in time. */
+type LeakSample = {
+    at: number;
+    retained: number;
+};
+/**
+ * Decide whether a component's retained-instance series indicates a leak.
+ *
+ * Mirrors {@link analyzeHeapTrend}: GC makes the raw retained count a sawtooth
+ * (instances pile up, then a sweep collects a batch), so the reliable signal is
+ * the *floor* — the post-GC troughs. We segment the series, take each segment's
+ * minimum, and regress those minima against time.
+ *
+ * A rising slope alone is not enough: a one-time step (a screen mounts N
+ * long-lived instances once, then plateaus) regresses positive but is not a
+ * leak. So we additionally require the recent half of the floor to still be
+ * rising, and gate on a minimum net growth in instances. This is what makes the
+ * detector robust to React StrictMode's intentional mount→unmount→remount
+ * churn, whose discarded fibers get collected and keep the floor flat.
+ *
+ * Returns null when there are too few samples to say anything.
+ */
+declare function analyzeLeakTrend(samples: LeakSample[]): {
+    leaking: boolean;
+    slopePerMin: number;
+} | null;
+
 type AnchorSignal = InteractionSignal | LongTaskSignal;
 /** How strongly a member is linked to its episode anchor. `caused` means a
  * member's source location matches one of the anchor's hot frames — a real
@@ -421,4 +478,4 @@ interface SelfProfilingCollector extends Collector {
  */
 declare function createSelfProfilingCollector(): SelfProfilingCollector;
 
-export { type AnchorSignal, type Collector, type CollectorKind, type CommitCause, type CreateSourceMapResolverOptions, type Episode, type EpisodeMember, type FetchMap, type ForcedReflowSignal, type FpsSample, type FrameCollector, type FrameStats, type HeapCollector, type HeapSample, type HeapTrend, type HeapTrendClass, type InpPhase, type InteractionCollector, type InteractionSignal, type LayoutShiftSignal, type LinkConfidence, type LongTaskAttribution, type LongTaskScript, type LongTaskSignal, type NetworkSignal, type ProfilerFrame, type ProfilerSample, type ProfilerStack, type ProfilerTrace, type Recorder, type RecordingResult, type RenderReason, type RenderSignal, type Signal, type SignalKind, type SourceMapResolver, type StackFrame, type WebVitalSignal, analyzeFrames, analyzeHeapTrend, attachLazyStack, attributeLongTaskSignals, attributeWindow, correlate, createForcedReflowCollector, createFrameCollector, createHeapCollector, createInteractionCollector, createLayoutShiftCollector, createLongTasksCollector, createNetworkCollector, createRecorder, createSelfProfilingCollector, createSourceMapResolver, createWebVitalsCollector, isSelfRequest, isUserResource, markSelfRequest, parseStack, resolveFrame };
+export { type AnchorSignal, BUFFER_CAP, type Capabilities, type Collector, type CollectorKind, type CommitCause, type CreateSourceMapResolverOptions, type Episode, type EpisodeMember, type FetchMap, type ForcedReflowSignal, type FpsSample, type FrameCollector, type FrameStats, type HeapCollector, type HeapSample, type HeapTrend, type HeapTrendClass, type InpPhase, type InteractionCollector, type InteractionSignal, type LayoutShiftSignal, type LeakSample, type LeakSuspect, type LinkConfidence, type LongTaskAttribution, type LongTaskScript, type LongTaskSignal, type NetworkSignal, type ProfilerFrame, type ProfilerSample, type ProfilerStack, type ProfilerTrace, type Recorder, type RecordingResult, type RenderReason, type RenderSignal, type Signal, type SignalKind, type SourceMapResolver, type StackFrame, type WebVitalSignal, analyzeFrames, analyzeHeapTrend, analyzeLeakTrend, attachLazyStack, attributeLongTaskSignals, attributeWindow, correlate, createForcedReflowCollector, createFrameCollector, createHeapCollector, createInteractionCollector, createLayoutShiftCollector, createLongTasksCollector, createNetworkCollector, createRecorder, createSelfProfilingCollector, createSourceMapResolver, createWebVitalsCollector, detectCapabilities, isSelfRequest, isUserResource, markSelfRequest, parseStack, resolveFrame, unsupportedKinds };

package/dist/index.js

@@ -201,6 +201,74 @@ function parseStack(raw) {
   return frames;
 }
 
+// src/capabilities.ts
+function supportedEntryTypes() {
+  const PO = globalThis.PerformanceObserver;
+  return PO?.supportedEntryTypes;
+}
+function observerSupported(needed) {
+  const types = supportedEntryTypes();
+  if (!Array.isArray(types)) return true;
+  return needed.some((t) => types.includes(t));
+}
+function detectCapabilities() {
+  return {
+    "forced-reflow": true,
+    render: true,
+    "web-vital": true,
+    "layout-shift": observerSupported(["layout-shift"]),
+    "long-task": observerSupported(["long-animation-frame", "longtask"]),
+    interaction: observerSupported(["event"]),
+    network: observerSupported(["resource"])
+  };
+}
+function unsupportedKinds() {
+  const caps = detectCapabilities();
+  return Object.keys(caps).filter((k) => !caps[k]);
+}
+
+// src/leak-trend.ts
+var MIN_SAMPLES = 4;
+var FLOOR_SEGMENTS = 8;
+var MIN_NET_GROWTH = 3;
+function slope(points) {
+  const n = points.length;
+  if (n < 2) return 0;
+  let sx = 0;
+  let sy = 0;
+  let sxy = 0;
+  let sxx = 0;
+  for (const { x, y } of points) {
+    sx += x;
+    sy += y;
+    sxy += x * y;
+    sxx += x * x;
+  }
+  const denom = n * sxx - sx * sx;
+  if (denom === 0) return 0;
+  return (n * sxy - sx * sy) / denom;
+}
+function analyzeLeakTrend(samples) {
+  if (samples.length < MIN_SAMPLES) return null;
+  const t0 = samples[0].at;
+  const segSize = Math.max(1, Math.ceil(samples.length / FLOOR_SEGMENTS));
+  const floorPoints = [];
+  for (let i = 0; i < samples.length; i += segSize) {
+    const seg = samples.slice(i, i + segSize);
+    let min = Infinity;
+    for (const s of seg) min = Math.min(min, s.retained);
+    const mid = seg[Math.floor(seg.length / 2)];
+    floorPoints.push({ x: (mid.at - t0) / 6e4, y: min });
+  }
+  const slopePerMin = slope(floorPoints);
+  const spanMin = (samples[samples.length - 1].at - t0) / 6e4;
+  const projectedGrowth = slopePerMin * spanMin;
+  const recent = floorPoints.slice(Math.floor(floorPoints.length / 2));
+  const recentSlope = recent.length >= 2 ? slope(recent) : slopePerMin;
+  const leaking = projectedGrowth >= MIN_NET_GROWTH && recentSlope > 0;
+  return { leaking, slopePerMin };
+}
+
 // src/correlate.ts
 var FRAME_MS = 16;
 function isAnchor(signal) {
@@ -690,19 +758,19 @@ function createWebVitalsCollector() {
 // src/collectors/heap.ts
 var SAMPLE_INTERVAL_MS = 250;
 var MAX_SAMPLES = 2e4;
-var MIN_SAMPLES = 4;
-var FLOOR_SEGMENTS = 8;
+var MIN_SAMPLES2 = 4;
+var FLOOR_SEGMENTS2 = 8;
 var MB = 1024 * 1024;
 var GROWING_SLOPE = 1 * MB;
 var LEAK_SLOPE = 5 * MB;
-var MIN_NET_GROWTH = 2 * MB;
+var MIN_NET_GROWTH2 = 2 * MB;
 function readMemory() {
   const perf = globalThis.performance;
   const mem = perf?.memory;
   if (!mem || typeof mem.usedJSHeapSize !== "number") return null;
   return mem;
 }
-function slope(points) {
+function slope2(points) {
   const n = points.length;
   if (n < 2) return 0;
   let sx = 0;
@@ -720,9 +788,9 @@ function slope(points) {
   return (n * sxy - sx * sy) / denom;
 }
 function analyzeHeapTrend(samples) {
-  if (samples.length < MIN_SAMPLES) return null;
+  if (samples.length < MIN_SAMPLES2) return null;
   const t0 = samples[0].at;
-  const segSize = Math.max(1, Math.ceil(samples.length / FLOOR_SEGMENTS));
+  const segSize = Math.max(1, Math.ceil(samples.length / FLOOR_SEGMENTS2));
   const floorPoints = [];
   for (let i = 0; i < samples.length; i += segSize) {
     const seg = samples.slice(i, i + segSize);
@@ -731,13 +799,13 @@ function analyzeHeapTrend(samples) {
     const mid = seg[Math.floor(seg.length / 2)];
     floorPoints.push({ x: (mid.at - t0) / 6e4, y: min });
   }
-  const slopeBytesPerMin = slope(floorPoints);
+  const slopeBytesPerMin = slope2(floorPoints);
   const spanMin = (samples[samples.length - 1].at - t0) / 6e4;
   const projectedGrowth = slopeBytesPerMin * spanMin;
   const recent = floorPoints.slice(Math.floor(floorPoints.length / 2));
-  const recentSlope = recent.length >= 2 ? slope(recent) : slopeBytesPerMin;
+  const recentSlope = recent.length >= 2 ? slope2(recent) : slopeBytesPerMin;
   let classification = "stable";
-  const sustained = projectedGrowth >= MIN_NET_GROWTH && recentSlope >= GROWING_SLOPE;
+  const sustained = projectedGrowth >= MIN_NET_GROWTH2 && recentSlope >= GROWING_SLOPE;
   if (sustained) {
     classification = slopeBytesPerMin >= LEAK_SLOPE && recentSlope >= LEAK_SLOPE ? "leak-suspected" : "growing";
   }
@@ -1066,8 +1134,10 @@ function createSelfProfilingCollector() {
   };
 }
 export {
+  BUFFER_CAP,
   analyzeFrames,
   analyzeHeapTrend,
+  analyzeLeakTrend,
   attachLazyStack,
   attributeLongTaskSignals,
   attributeWindow,
@@ -1083,10 +1153,12 @@ export {
   createSelfProfilingCollector,
   createSourceMapResolver,
   createWebVitalsCollector,
+  detectCapabilities,
   isSelfRequest,
   isUserResource,
   markSelfRequest,
   parseStack,
-  resolveFrame
+  resolveFrame,
+  unsupportedKinds
 };
 //# sourceMappingURL=index.js.map