@react-perfscope/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+/// <reference lib="es2015" />
+/// <reference lib="dom" />
+
+import { SourceMapInput } from '@jridgewell/trace-mapping';
+
+type StackFrame = {
+    file: string;
+    line: number;
+    col: number;
+    fnName?: string;
+};
+type ForcedReflowSignal = {
+    kind: 'forced-reflow';
+    at: number;
+    duration: number;
+    stack: StackFrame[];
+};
+type LayoutShiftSignal = {
+    kind: 'layout-shift';
+    at: number;
+    value: number;
+    sources: DOMRect[];
+    /**
+     * Parallel array to `sources`. Each entry is the rect of the source node
+     * BEFORE the shift, in document coords. `null` when the source had no
+     * previous rect (newly inserted element). Lets consumers draw a "moved
+     * from → to" arrow during overlay rendering.
+     */
+    previousSources?: (DOMRect | null)[];
+};
+type LongTaskScript = {
+    /** What kind of entry point ran this script: 'event-listener',
+     * 'user-callback', 'resolve-promise', 'reject-promise', 'classic-script',
+     * 'module-script', etc. (from the LoAF spec). */
+    invokerType: string;
+    /** Human-readable invoker, e.g. "BUTTON#go.onclick" or a callback name. */
+    invoker: string;
+    sourceURL: string;
+    sourceFunctionName: string;
+    /** Character offset of the function in its source, or -1 when unknown. */
+    charPosition: number;
+    /** Wall-clock ms this script occupied. */
+    duration: number;
+};
+/**
+ * One hot user-source location inside a long task, derived from JS
+ * Self-Profiling samples. Answers "which of MY functions burned the time",
+ * which LoAF cannot do for React-delegated events (it only sees React's
+ * single root dispatcher). `frame` is the raw served-file position; resolve
+ * it through source maps for the original location.
+ */
+type LongTaskAttribution = {
+    frame: StackFrame;
+    /** Fraction (0..1) of this task's in-window samples whose leaf user frame
+     * was this one. */
+    selfRatio: number;
+    /** Number of in-window samples attributed to this frame. */
+    sampleCount: number;
+};
+type LongTaskSignal = {
+    kind: 'long-task';
+    at: number;
+    duration: number;
+    stack: StackFrame[];
+    /** Per-script attribution from the Long Animation Frame API. Absent when
+     * LoAF is unsupported (falls back to the legacy `longtask` entry, which
+     * gives duration only). */
+    scripts?: LongTaskScript[];
+    /** Main-thread blocking time reported by LoAF, when available. */
+    blockingDuration?: number;
+    /** Hottest user-source frames inside this task, from JS Self-Profiling.
+     * Sorted by sampleCount desc. Absent when self-profiling is unavailable
+     * (no Profiler API or missing Document-Policy header). */
+    attribution?: LongTaskAttribution[];
+};
+type WebVitalSignal = {
+    kind: 'web-vital';
+    name: 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB';
+    value: number;
+};
+type NetworkSignal = {
+    kind: 'network';
+    url: string;
+    startedAt: number;
+    duration: number;
+    size: number;
+    blocking: boolean;
+};
+type InteractionSignal = {
+    kind: 'interaction';
+    /** Event startTime — when the user input arrived. */
+    at: number;
+    /** Event type that defined the interaction latency (click, pointerup, keydown…). */
+    eventType: string;
+    /** Best-effort CSS-ish selector of the event target. */
+    target?: string;
+    /** Total interaction latency: input → handlers → next paint (ms). */
+    duration: number;
+    /** startTime → processingStart: main thread was busy before handlers ran. */
+    inputDelay: number;
+    /** processingStart → processingEnd: the event handlers themselves. */
+    processing: number;
+    /** processingEnd → next paint: re-render + paint after handlers. */
+    presentation: number;
+    /** Hottest user-source frames during the processing window, from JS
+     * Self-Profiling. Absent when self-profiling is unavailable or found none. */
+    attribution?: LongTaskAttribution[];
+};
+type RenderReason = 'mount' | 'state' | 'props' | 'parent';
+type RenderSignal = {
+    kind: 'render';
+    at: number;
+    component: string;
+    reason: RenderReason;
+    duration: number;
+    /** Prop keys that changed since the previous render (reason === 'props'). */
+    changedProps?: string[];
+    /** Groups every render emitted from the same commit so the UI can show
+     * one cascade (root + the components it re-rendered) as a unit. */
+    commitId: number;
+    /** Fiber depth from the committed root — used to indent the cascade. */
+    depth: number;
+};
+type Signal = ForcedReflowSignal | LayoutShiftSignal | LongTaskSignal | WebVitalSignal | NetworkSignal | RenderSignal | InteractionSignal;
+type SignalKind = Signal['kind'];
+/** One heap-usage reading. `at` shares the performance.now() clock used by
+ * signal timestamps, so it lines up with the timeline x-axis. */
+type HeapSample = {
+    at: number;
+    /** usedJSHeapSize — live JS objects, in bytes. */
+    used: number;
+    /** totalJSHeapSize — allocated heap, in bytes. */
+    total: number;
+};
+type HeapTrendClass = 'stable' | 'growing' | 'leak-suspected';
+type HeapTrend = {
+    classification: HeapTrendClass;
+    /** Slope of the heap "floor" (post-GC troughs), in bytes per minute. A
+     * steadily rising floor is the signal that memory is being retained. */
+    slopeBytesPerMin: number;
+};
+/** One windowed frame-rate reading. */
+type FpsSample = {
+    at: number;
+    fps: number;
+};
+type FrameStats = {
+    /** Windowed FPS series across the recording. */
+    series: FpsSample[];
+    /** Lowest windowed FPS — the worst sustained dip. */
+    minFps: number;
+    /** Longest single inter-frame gap (worst hitch), in ms. */
+    longestFrameMs: number;
+    /** Approximate frames dropped across the recording (vs a 60fps budget). */
+    droppedFrames: number;
+};
+interface RecordingResult {
+    signals: Signal[];
+    startedAt: number;
+    duration: number;
+    /** Heap-usage time series, present only when performance.memory is
+     * available (Chromium). Attached at finalize, not part of the signal buffer. */
+    heapSamples?: HeapSample[];
+    /** requestAnimationFrame timestamps captured during the recording, for
+     * frame-rate / jank analysis. Attached at finalize. */
+    frames?: number[];
+}
+/** 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';
+interface Collector {
+    readonly kind: CollectorKind;
+    activate(emit: (signal: Signal) => void): void;
+    deactivate(): void;
+}
+interface Recorder {
+    start(): void;
+    stop(): RecordingResult;
+    isRecording(): boolean;
+    onSignal(cb: (signal: Signal) => void): () => void;
+    use(collector: Collector): void;
+}
+
+declare function createRecorder(): Recorder;
+
+/** A parsed source map (the JSON object), as returned by a FetchMap. */
+type RawSourceMap = SourceMapInput;
+type FetchMap = (file: string) => Promise<RawSourceMap | null>;
+declare function resolveFrame(frame: StackFrame, fetchMap: FetchMap): Promise<StackFrame>;
+/**
+ * Attach a lazy `stack` getter to `target` that parses `raw` on first access
+ * and memoizes the result. Use this from collectors to defer parseStack cost
+ * until a consumer actually reads `signal.stack`.
+ *
+ * `skipTopFrames` drops the leading N parsed frames — useful for collectors
+ * that wrap a patched function (the wrapper itself shows up as the topmost
+ * frame, but it's noise from the user's perspective).
+ */
+declare function attachLazyStack(target: object, raw: string | undefined, skipTopFrames?: number): void;
+interface SourceMapResolver {
+    /** Resolve a parsed StackFrame to its original source position. Falls back to the input frame on any failure. */
+    resolve(frame: StackFrame): Promise<StackFrame>;
+}
+interface CreateSourceMapResolverOptions {
+    /** Override the global fetch. Useful for tests and non-browser environments. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Create a SourceMap resolver that fetches `.map` files from the live URL
+ * referenced in each source file's `//# sourceMappingURL=` directive.
+ * Caches the parsed source map per source URL so repeated resolves against
+ * the same file are O(1) after the first.
+ *
+ * Returns the input frame on any failure (network error, missing map, etc.).
+ */
+declare function createSourceMapResolver(opts?: CreateSourceMapResolverOptions): SourceMapResolver;
+declare function parseStack(raw: string | undefined): StackFrame[];
+
+declare function createLongTasksCollector(): Collector;
+
+declare function createForcedReflowCollector(): Collector;
+
+declare function createLayoutShiftCollector(): Collector;
+
+declare function createNetworkCollector(): Collector;
+
+declare function createWebVitalsCollector(): Collector;
+
+/**
+ * Estimate whether memory is being retained across the recording.
+ *
+ * GC makes raw heap usage a sawtooth, so the peak is noisy. The reliable
+ * signal is the *floor* — the post-GC troughs. We split the series into
+ * contiguous segments, take the minimum of each (its trough), and regress
+ * those minima against time.
+ *
+ * A rising overall slope is necessary but NOT sufficient: a one-time step
+ * (heap warms up early, then plateaus) also regresses to a positive slope, and
+ * flagging that as a leak is a false positive — the classic "idle recording
+ * reads abnormal" bug. A real leak keeps climbing, so we additionally require
+ * the *recent* half of the floor to still be rising. We also gate on a minimum
+ * net growth, since over a short window a sub-MB wobble extrapolates to a steep
+ * per-minute slope.
+ *
+ * Returns null when there are too few samples to say anything.
+ */
+declare function analyzeHeapTrend(samples: HeapSample[]): HeapTrend | null;
+interface HeapCollector extends Collector {
+    /** Attach the sampled heap series to the recording result. Returns the
+     * input untouched when nothing was sampled (unsupported browser). */
+    finalize(result: RecordingResult): RecordingResult;
+}
+/**
+ * Samples `performance.memory` on an interval for the duration of a recording
+ * and attaches the series via `finalize`. It is a Collector so the recorder
+ * drives its start/stop, but it emits no signals — the series is a separate
+ * track (see RecordingResult.heapSamples), so a busy session's signal buffer
+ * can't evict it. No-ops entirely when performance.memory is unavailable
+ * (non-Chromium), leaving `heapSamples` absent so the UI can show a fallback.
+ */
+declare function createHeapCollector(): HeapCollector;
+
+interface InteractionCollector extends Collector {
+    /** Group buffered Event Timing entries into one interaction each and append
+     * them to the result. Returns the input untouched when none qualified. */
+    finalize(result: RecordingResult): RecordingResult;
+}
+/**
+ * Records Event Timing entries during a recording and, on finalize, turns each
+ * user interaction (grouped by interactionId) into one signal carrying the INP
+ * latency breakdown: input delay → processing → presentation. The longest
+ * event in a group defines the interaction's latency (matching how INP is
+ * attributed). Emits no live signals — interactions are assembled at finalize,
+ * then the self-profiling collector attributes the processing window to the
+ * developer's hot functions.
+ */
+declare function createInteractionCollector(): InteractionCollector;
+
+/**
+ * Turn raw requestAnimationFrame timestamps into a frame-rate picture:
+ * a windowed FPS series, the lowest sustained FPS, the worst single hitch,
+ * and an approximate dropped-frame count. Long tasks (>50ms) show up here as
+ * big gaps, but so does sustained scroll jank (30–50ms frames) that the
+ * long-task collector's threshold misses.
+ *
+ * Returns null when there are too few frames to analyze.
+ */
+declare function analyzeFrames(frames: number[]): FrameStats | null;
+interface FrameCollector extends Collector {
+    /** Attach the captured frame timestamps to the result. Returns the input
+     * untouched when too few frames were seen (or rAF was unavailable). */
+    finalize(result: RecordingResult): RecordingResult;
+}
+/**
+ * Records requestAnimationFrame timestamps for the duration of a recording so
+ * the UI can chart frame rate and surface jank. Emits no signals — the
+ * timestamps are a side track attached at finalize. No-ops when
+ * requestAnimationFrame is unavailable (non-DOM environments).
+ */
+declare function createFrameCollector(): FrameCollector;
+
+/**
+ * JS Self-Profiling API trace shape (the subset we consume).
+ * @see https://wicg.github.io/js-self-profiling/
+ */
+interface ProfilerFrame {
+    name?: string;
+    resourceId?: number;
+    line?: number;
+    column?: number;
+}
+interface ProfilerStack {
+    frameId: number;
+    parentId?: number;
+}
+interface ProfilerSample {
+    /** DOMHighResTimeStamp, same clock as performance.now() / entry.startTime. */
+    timestamp: number;
+    stackId?: number;
+}
+interface ProfilerTrace {
+    resources: string[];
+    frames: ProfilerFrame[];
+    stacks: ProfilerStack[];
+    samples: ProfilerSample[];
+}
+/**
+ * Whether a resource URL belongs to the developer's own source (vs. a
+ * dependency or tooling shim). Dependency frames are noise when the question
+ * is "which of MY functions is slow".
+ */
+declare function isUserResource(url: string | undefined): boolean;
+/**
+ * Aggregate the hottest user-source frames among samples whose timestamp
+ * falls in [start, end]. `selfRatio` is relative to ALL in-window samples
+ * (including vendor-only ones), so it reflects the share of the task's
+ * blocking time spent in that user function.
+ */
+declare function attributeWindow(trace: ProfilerTrace, start: number, end: number): LongTaskAttribution[];
+/**
+ * Return a copy of `signals` with each long-task signal enriched with the
+ * hottest user frames sampled during its window. Long tasks with no in-window
+ * user samples are left without `attribution`. Non-long-task signals pass
+ * through by reference.
+ */
+declare function attributeLongTaskSignals(trace: ProfilerTrace, signals: Signal[]): Signal[];
+interface SelfProfilingCollector extends Collector {
+    /** Stop the profiler (if running), await its trace, and return a result
+     * with long-task signals enriched. Falls back to the input on any failure
+     * or when the Profiler API / Document-Policy header is unavailable. */
+    finalize(result: RecordingResult): Promise<RecordingResult>;
+}
+/**
+ * Collector that runs the JS Self-Profiling API across a recording and, on
+ * finalize, attributes each long task to the developer's own hot functions —
+ * something LoAF can't do for React-delegated events (it only sees React's
+ * single root dispatcher).
+ *
+ * It reports `kind: 'long-task'` because it enriches that signal rather than
+ * emitting its own. Requires Chromium + a `Document-Policy: js-profiling`
+ * response header (the dev plugins inject it); degrades to a no-op otherwise.
+ */
+declare function createSelfProfilingCollector(): SelfProfilingCollector;
+
+export { type Collector, type CollectorKind, type CreateSourceMapResolverOptions, type FetchMap, type ForcedReflowSignal, type FpsSample, type FrameCollector, type FrameStats, type HeapCollector, type HeapSample, type HeapTrend, type HeapTrendClass, type InteractionCollector, type InteractionSignal, type LayoutShiftSignal, 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, createForcedReflowCollector, createFrameCollector, createHeapCollector, createInteractionCollector, createLayoutShiftCollector, createLongTasksCollector, createNetworkCollector, createRecorder, createSelfProfilingCollector, createSourceMapResolver, createWebVitalsCollector, isUserResource, parseStack, resolveFrame };