react-perf-recorder 0.1.0

package/dist/browser/index-BlkKhwHe.d.ts

@@ -0,0 +1,585 @@
+declare const RECORDING_SCHEMA = "react-perf-recorder/recording";
+declare const GLOBAL_KEY = "__REACT_PERF_RECORDER__";
+type Primitive = string | number | boolean | null;
+type JsonValue = Primitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type Conditions = Record<string, Primitive>;
+interface PluginInfo {
+    name: string;
+    sectionVersion: number;
+    error?: string;
+}
+interface PluginSection<Data = unknown> {
+    version: number;
+    /** false: the plugin's library is not on the page, and the report leaves the plugin out. */
+    active?: boolean;
+    highlights?: string[];
+    metrics?: Record<string, {
+        value: number;
+        kind: 'count' | 'gauge';
+    }>;
+    data?: Data;
+}
+/**
+ * One render on the way down: the root first (`root` indexes the recording's roots, inside then outside), the
+ * component itself last. `reason` indexes `RecordingV2.reasons`; `skipped` stands for links left out of a long chain.
+ */
+/** A link of the commits' cascade trees: the link above it (-1 for a root), who rendered, and why. */
+interface ChainNodeInfo {
+    up: number;
+    name: string;
+    reason?: number;
+    /** For a root's link: the root, as `ChainLink.root`. */
+    root?: number;
+}
+interface ChainLink {
+    name: string;
+    reason?: number;
+    root?: number;
+    skipped?: number;
+}
+/** A useMemo or useCallback that recomputed on at least half of its component's renders. */
+interface MemoHookStat {
+    component: string;
+    source?: string;
+    /** Cell index in the component's hook list: the same `#N` the reasons use. */
+    hook: number;
+    kind: 'useMemo' | 'useCallback';
+    /** Renders in which the hook had a value to keep; `recomputed` of them made a new one. */
+    renders: number;
+    recomputed: number;
+    /** No dependency array: it recomputes on every render by definition. */
+    noDeps?: true;
+    /** Per dependency position: how often it changed, and how often into a value with the same content. */
+    deps: Array<{
+        index: number;
+        changed: number;
+        sameContent: number;
+    }>;
+    info?: HookInfo;
+}
+interface HookInfo {
+    /** Primitive hook type from `_debugHookTypes`, e.g. `useSyncExternalStore`. */
+    type?: string;
+    /** Custom hooks from the component down to the primitive, e.g. `['useActivePositionsList', 'useSelector', 'SyncExternalStore']`. */
+    path?: string[];
+    /** npm package the chain enters, e.g. `zustand`; absent when every custom hook is app code. */
+    library?: string;
+    /** Index in `path` of the first hook of `library`: the package API the app called, e.g. `useStore`. */
+    libraryAt?: number;
+    /** Call site in the generated code; the dev server maps it to `site` and `code`. */
+    generated?: {
+        url: string;
+        line: number;
+        column: number;
+    };
+    site?: string;
+    code?: string;
+    /** For a useMemo or useCallback: its dependency list as the code writes it, `['items', 'filter']`. */
+    deps?: string[];
+}
+/** What made a component render, as fields rather than a sentence; `text` is the sentence, built from them. */
+type ReasonKind = 'state' | 'store' | 'context' | 'props' | 'parent' | 'bailout' | 'unknown';
+interface ReasonInfo {
+    i: number;
+    kind: ReasonKind;
+    /** Index in the hook list, for `state` and `store`; the key into `RootStat.hooks`. */
+    hook?: number;
+    /** The store behind an external-store hook, and the selector it was read with. */
+    store?: string;
+    selector?: string;
+    /** The context that changed, for `context`. */
+    context?: string;
+    /** Props that really changed, and props that are a new reference with the same content. */
+    changed?: string[];
+    sameRef?: string[];
+    /** The children element changed by reference. */
+    children?: true;
+    /** The parent rendered and handed over equal props: `memo` would have skipped this render. */
+    equal?: true;
+    /** A new value with the same content: a subscription bug rather than new data. */
+    sameContent?: true;
+    /** Older recordings carry the sentence; it is built from the fields above by `reasonText` when it is not there. */
+    text?: string;
+}
+interface RootStat {
+    key: string;
+    name: string;
+    source: string;
+    /** Call site in the generated code, when the source alone has no line; the dev server maps it into `source`. */
+    generatedSource?: {
+        url: string;
+        line: number;
+        column: number;
+    };
+    path: string;
+    hits: number;
+    instances: number;
+    cascade: number;
+    perHit: number;
+    medianGapMs: number | null;
+    firstAtMs: number;
+    lastAtMs: number;
+    /** `[reason id, how many hits]`; the ids index `RecordingV2.reasons`. */
+    reasons: Array<[number, number]>;
+    causes: Array<[string, number]>;
+    lanes: Array<[string, number]>;
+    /** Hits in which nothing in the root's DOM changed: the render was wasted. */
+    noDomChange: number;
+    renderMs?: number;
+    /** Components mounted under the root in its hits: a component declared in render or an unstable key remounts. */
+    mounts?: number;
+    hooks?: Record<string, HookInfo>;
+    /** Only for outside roots: renders inside the scope this root caused. */
+    scopeRenders?: number;
+}
+interface ScopeInfo {
+    name: string;
+    source: string;
+    path: string[];
+    state: 'attached' | 'lost';
+    remounts: number;
+    lostAtMs: number[];
+}
+interface Totals {
+    commits: number;
+    commitsInScope: number;
+    renders: number;
+    mounts: number;
+    rendersPerCommit: number;
+    rendersPerScopeCommit: number;
+    rendersFromOutside: number;
+    rendersWithoutDom: number;
+    domTextChanges: number;
+    causesDropped: number;
+    lanes: Record<string, number>;
+}
+interface CauseStat {
+    /** Id: what a commit references instead of repeating the key. */
+    i: number;
+    key: string;
+    plugin: string;
+    type: string;
+    events: number;
+    commits: number;
+    keys?: Record<string, {
+        changed: number;
+        sameContent: number;
+        unknown: number;
+    }>;
+}
+type ActionKind = 'click' | 'typing' | 'change' | 'key' | 'submit' | 'scroll' | 'navigation';
+interface ActionTarget {
+    testId?: string;
+    name?: string;
+    label?: string;
+    tag: string;
+    role?: string;
+    text?: string;
+    /** The component that rendered the element, where it was written, and the app's components above it. */
+    component?: string;
+    source?: string;
+    /** React 19: the built position of the component, which the dev server maps into `source` when saving. */
+    generatedSource?: {
+        url: string;
+        line: number;
+        column: number;
+    };
+    path?: string[];
+    /** Enough to find the element again: a selector, and which one it is among its like-named siblings. */
+    selector?: string;
+    nth?: number;
+    /** Where the click landed, and the box of the element at that moment. */
+    point?: {
+        x: number;
+        y: number;
+    };
+    box?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** The element's own state when it was acted on. */
+    id?: string;
+    href?: string;
+    disabled?: true;
+    checked?: boolean;
+    inScope?: boolean;
+}
+interface ActionRecord {
+    id: number;
+    kind: ActionKind;
+    atMs: number;
+    endMs: number;
+    target?: ActionTarget;
+    key?: string;
+    /** Characters typed, for `typing`. */
+    chars?: number;
+    /** Value length after the action; the value itself only with `actions.values`. */
+    length?: number;
+    value?: string;
+    secret?: boolean;
+    scroll?: {
+        from: number;
+        to: number;
+        pixels: number;
+    };
+    url?: string;
+    /** The commits that followed it, by id; empty when the action changed nothing. */
+    commitIds?: number[];
+}
+interface LatencyEntry {
+    atMs: number;
+    type: string;
+    duration: number;
+    inputDelay: number;
+    processing: number;
+    presentation: number;
+    interactionId: number;
+}
+interface LongFrame {
+    atMs: number;
+    duration: number;
+    blocking: number;
+    commits: number;
+    scripts: Array<{
+        invoker: string;
+        source: string;
+        duration: number;
+        layout: number;
+        own?: boolean;
+    }>;
+}
+interface Segment {
+    action: number;
+    /** Internal wiring while a recording is built; the saved recording keeps these on the action itself. */
+    commitIds?: number[];
+    atMs: number;
+    durationMs: number;
+    commits: number;
+    renders: number;
+    reaction: {
+        commits: number;
+        renders: number;
+    };
+    background: {
+        commits: number;
+        renders: number;
+    };
+    perChar?: {
+        commits: number;
+        renders: number;
+        maxRenders: number;
+    };
+    topRoots: Array<[number, number]>;
+    latency?: LatencyEntry;
+    longFrames: number;
+    maxFrameMs: number;
+}
+/**
+ * One commit, with everything that points at it: the action and the causes that led to it, the roots that rendered
+ * in it and why. This is what a timeline is drawn from — a bar per commit, a marker per action.
+ */
+interface CommitRecord {
+    i: number;
+    atMs: number;
+    /** Milliseconds since the previous commit. */
+    sinceMs?: number;
+    /** React render time of the commit's cascade roots, when the build has profile timings. */
+    ms?: number;
+    lane?: string;
+    /** The DOM event being dispatched when React was told, e.g. `click`. */
+    event?: string;
+    /** The action this commit answered, and the causes that claimed it. */
+    actionId?: number;
+    causeIds?: number[];
+    /** Renders in scope (or everywhere without a scope), and how many changed nothing in the DOM. */
+    renders: number;
+    noDom?: number;
+    outside?: number;
+    mounts?: number;
+    /** Cascade roots of this commit: which root, how many of its instances, and why each rendered. */
+    roots?: Array<{
+        i: number;
+        hits: number;
+        reasonIds: number[];
+    }>;
+    /**
+     * The commit's cascade as a tree: `[link, renders]` into `RecordingV2.chainNodes`, the busiest links and every link
+     * above them. Absent in fast recordings.
+     */
+    ways?: Array<[number, number]>;
+}
+interface Navigation {
+    type: 'push' | 'replace' | 'pop';
+    atMs: number;
+    url: string;
+    sameUrl?: true;
+}
+interface RecordingV2 {
+    schema: typeof RECORDING_SCHEMA;
+    version: 2;
+    id?: string;
+    createdAt: string;
+    label?: string;
+    partial?: boolean;
+    tool: {
+        version: string;
+        source: string;
+        plugins: PluginInfo[];
+    };
+    page: {
+        url: string;
+        title: string;
+        viewport: string;
+        dpr: number;
+        userAgent: string;
+    };
+    react: {
+        version: string | null;
+        roots: number;
+        profileTimings: boolean;
+    };
+    meta?: Record<string, Primitive>;
+    options: Record<string, JsonValue>;
+    startedAt: string;
+    durationMs: number;
+    scope: ScopeInfo | null;
+    totals: Totals;
+    roots: RootStat[];
+    outsideRoots: RootStat[];
+    /** Every rendered component; `reasons` covers renders caused by a parent too (`parent: props …`). */
+    components: Array<{
+        name: string;
+        renders: number;
+        mounts?: number;
+        /** A component of a package: the app's own come first in the list. */
+        library?: true;
+        /** An unnamed wrapper of the app or a component that only hands a context down: listed after the app's own. */
+        wrapper?: true;
+        withoutDom: number;
+        byParent: number;
+        memo?: true;
+        reasons: Array<[number, number]>;
+        /** Its most frequent ways down from a root, with how many renders came each way; only for renders a parent caused. */
+        chains?: Array<{
+            n: number;
+            links: ChainLink[];
+        }>;
+        /** Its parent-caused renders had their reasons worked out for a sample of the instances in a commit, not all. */
+        sampled?: true;
+    }>;
+    watch?: Record<string, {
+        mounted: number;
+        renders: number;
+        byRoot: Array<[number | null, number]>;
+    }>;
+    zones?: Record<string, {
+        renders: number;
+        mounted: number;
+        found: boolean;
+    }>;
+    causes: CauseStat[];
+    actions: ActionRecord[];
+    segments: Segment[];
+    /** Memo hooks that keep recomputing, worst first; absent when none do. */
+    memos?: MemoHookStat[];
+    latency: LatencyEntry[];
+    /** Every reason any root or component gave, once; everything else points here by id. */
+    reasons: ReasonInfo[];
+    commits: {
+        list: CommitRecord[];
+        truncated: boolean;
+    };
+    /** The links the commits' `ways` point at; only in the final recording. */
+    chainNodes?: ChainNodeInfo[];
+    bigCommits: number[];
+    frames: {
+        longTasks: {
+            count: number;
+            maxMs: number;
+            totalMs: number;
+        };
+        loaf: LongFrame[];
+        fps?: number;
+    };
+    dom: {
+        text: number;
+        attr?: number;
+        child?: number;
+    };
+    navigations: Navigation[];
+    hmr: Array<{
+        atMs: number;
+        type: string;
+        paths: string[];
+    }>;
+    conditions: Conditions;
+    conditionsChanged?: Record<string, [Primitive, Primitive]>;
+    plugins: Record<string, PluginSection>;
+    /** `highlight`: outlines were drawn during the recording, which adds to frame and long-task times. */
+    overhead: {
+        commitMs: number;
+        maxCommitMs: number;
+        overlayMs: number;
+        highlight?: boolean;
+    };
+    warnings: string[];
+    errors: string[];
+}
+
+interface ContextDependency {
+    context: {
+        displayName?: string;
+    };
+    memoizedValue: unknown;
+    next: ContextDependency | null;
+}
+interface Fiber {
+    tag: number;
+    key: string | null;
+    type: any;
+    elementType: any;
+    stateNode: any;
+    return: Fiber | null;
+    child: Fiber | null;
+    sibling: Fiber | null;
+    index: number;
+    alternate: Fiber | null;
+    memoizedProps: any;
+    memoizedState: any;
+    dependencies: {
+        firstContext: ContextDependency | null;
+    } | null;
+    mode: number;
+    flags: number;
+    lanes?: number;
+    childLanes?: number;
+    actualDuration?: number;
+    /** React 18 only: where the element was written. React 19.1 replaced it with `_debugStack`. */
+    _debugSource?: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    } | null;
+    /** React 19.1+: an owner stack whose second frame is where the element was written. */
+    _debugStack?: unknown;
+    _debugOwner?: Fiber | null;
+    _debugHookTypes?: string[] | null;
+}
+interface FiberRoot {
+    current: Fiber;
+    containerInfo: Element;
+    finishedLanes?: number;
+    pendingLanes?: number;
+}
+
+interface MemoStat {
+    name: string;
+    file: string;
+    kind: string;
+    size: number;
+    calls: number;
+    recomputes: number;
+    hitRate: number;
+    nestedCalls: number;
+    recomputesOnArgSwitch: number;
+    distinctArgs: number;
+    /**
+     * Recomputes for arguments whose answer was already pushed out: `size` other answers were stored since theirs.
+     * The cache is a ring, so this happens even with more slots than argument sets.
+     */
+    evictions: number;
+    /** A size-limited cache that keeps pushing out answers still in use: rows, cells or two forms sharing one selector. */
+    evicting: boolean;
+}
+interface MemoInstrumentation {
+    /** Wraps a memoizer factory (`memoize`, `memoizeWithArgs`, `createSelector`) so every memoized function it creates is counted. */
+    instrument<F extends (...args: any[]) => any>(factory: F, kind: string, fnArg: number | 'lastFunction'): F;
+    /** Names a memoized function; the build transform calls it after `const selectX = memoize(...)`. */
+    name(fn: unknown, name: string, file: string): void;
+    label(fn: Function): string | null;
+    /** Whether any memoized function made through `instrument` is still alive: the library is in use on the page. */
+    readonly used: boolean;
+    start(): void;
+    stop(): MemoStat[];
+    readonly recording: boolean;
+}
+/**
+ * Counting must not change memoization: arguments inside nested selector calls are proxy-compare proxies, and any
+ * property read would be recorded as a dependency. Only `typeof`, WeakMap lookups and `String()` of primitives touch them.
+ */
+declare function createMemoInstrumentation(): MemoInstrumentation;
+
+/**
+ * Called by the proxy of `react-dom/client` right after a root is created, before the app renders into it, with the
+ * root itself: it is found wherever the app mounted it, not only where a search of the page would look.
+ */
+declare function noteRoot(root?: {
+    _internalRoot?: FiberRoot | null;
+}): void;
+
+interface CauseInput {
+    /** Shown as `<plugin>:<type>`, e.g. `markets/updateMarketsAmmState`. */
+    type: string;
+    /** Top-level keys the event changed; the core marks the ones with the same content and drops the values. */
+    changes?: Array<{
+        key: string;
+        prev: unknown;
+        next: unknown;
+    }>;
+    data?: Record<string, Primitive>;
+    /**
+     * Emitted after React was told of the update, so the recorder can see which components it woke.
+     * Leave it out when the event runs ahead of React, as a query cache or a navigation does.
+     */
+    aim?: true;
+    /**
+     * The library tells React later, from a timer of its own (react-query's notify batch): the event waits for that
+     * timer and goes to the components it updated. Needs the plugin's `packages`.
+     */
+    waitForTimer?: true;
+    /** Events with the same key still waiting are one: the later one's type replaces the earlier's. */
+    merge?: string;
+}
+interface PluginContext {
+    readonly recording: boolean;
+    /** Queues a cause for the next commit and returns it, so a later hook can refine `type`; null outside a recording. */
+    emitCause(event: CauseInput): {
+        type: string;
+    } | null;
+    /** Milliseconds since the recording started. */
+    now(): number;
+    warn(message: string): void;
+}
+interface SessionContext extends PluginContext {
+    scope: {
+        name: string;
+        source: string;
+    } | null;
+    /** One full walk of the committed tree; use for discovery at start, not per commit. */
+    findFibers(predicate: (fiber: Fiber) => boolean, limit?: number): Fiber[];
+}
+type DescribeKind = 'selector' | 'store';
+interface RuntimePlugin<Data = unknown> {
+    name: string;
+    sectionVersion?: number;
+    /** npm packages whose timers deliver this plugin's `waitForTimer` events. */
+    packages?: string[];
+    /** Runs at page boot, before the app's modules. */
+    setup?(ctx: PluginContext): void;
+    /** Label for a store selector or a store (by its getSnapshot); `null` when the function is not the plugin's. */
+    describe?(fn: Function, kind: DescribeKind, next: (fn: Function) => string): string | null;
+    start?(session: SessionContext): void;
+    /** After each commit of a recording, for what mounts late (a lazy provider); keep it cheap. */
+    commit?(session: SessionContext): void;
+    stop?(session: SessionContext): PluginSection<Data> | void;
+    conditions?(): Conditions;
+}
+type RuntimePluginFactory<Options = any> = (options: Options) => RuntimePlugin;
+/** Identity helper for typing; the module's default export is the factory. */
+declare const definePlugin: <Options = void>(factory: (options: Options) => RuntimePlugin) => RuntimePluginFactory<Options>;
+
+export { type ActionRecord as A, type CauseInput as C, type DescribeKind as D, type Fiber as F, GLOBAL_KEY as G, type HookInfo as H, type JsonValue as J, type MemoInstrumentation as M, type PluginInfo as P, type RuntimePlugin as R, type SessionContext as S, type RuntimePluginFactory as a, type PluginContext as b, type Primitive as c, type PluginSection as d, type Conditions as e, type RecordingV2 as f, type ReasonInfo as g, type RootStat as h, type MemoStat as i, createMemoInstrumentation as j, definePlugin as k, noteRoot as n };

package/dist/browser/plugins/proxy-memoize.d.ts

@@ -0,0 +1,7 @@
+import { a as RuntimePluginFactory } from '../index-BlkKhwHe.js';
+
+declare const instrument: <F extends (...args: any[]) => any>(factory: F, kind: string, fnArg: number | "lastFunction") => F;
+declare const nameMemoized: (fn: unknown, name: string, file: string) => void;
+declare const _default: RuntimePluginFactory<void>;
+
+export { _default as default, instrument, nameMemoized };

package/dist/browser/plugins/proxy-memoize.js

@@ -0,0 +1,41 @@
+import {
+  createMemoInstrumentation,
+  definePlugin
+} from "../chunk-NTY2W4HE.js";
+import "../chunk-7DJUCCWG.js";
+
+// src/plugins/proxy-memoize/runtime.ts
+var memo = createMemoInstrumentation();
+var instrument = memo.instrument;
+var nameMemoized = memo.name;
+var runtime_default = definePlugin(() => ({
+  name: "proxy-memoize",
+  describe: (fn, kind) => kind === "selector" ? memo.label(fn) : null,
+  start: () => memo.start(),
+  stop() {
+    const selectors = memo.stop();
+    const evicting = selectors.filter((s) => s.evicting);
+    return {
+      version: 1,
+      active: memo.used,
+      highlights: selectors.length ? [
+        ...evicting.slice(0, 5).map(
+          (s) => s.distinctArgs > s.size ? `${s.name}: ${s.recomputes}/${s.calls} recomputes, ${s.distinctArgs} argument sets > cache size ${s.size}` : `${s.name}: ${s.recomputes}/${s.calls} recomputes, ${s.evictions} after the answer was pushed out of cache size ${s.size} (${s.distinctArgs} argument sets)`
+        ),
+        ...selectors.filter((s) => !s.evicting).slice(0, 3).map((s) => `${s.name}: ${s.recomputes}/${s.calls} recomputes`)
+      ] : ["no selector calls during the recording"],
+      metrics: Object.fromEntries(
+        selectors.slice(0, 30).flatMap((s) => [
+          [`${s.name}.calls`, { value: s.calls, kind: "count" }],
+          [`${s.name}.recomputes`, { value: s.recomputes, kind: "count" }]
+        ])
+      ),
+      data: { selectors }
+    };
+  }
+}));
+export {
+  runtime_default as default,
+  instrument,
+  nameMemoized
+};

package/dist/browser/plugins/react-query.d.ts

@@ -0,0 +1,5 @@
+import { a as RuntimePluginFactory } from '../index-BlkKhwHe.js';
+
+declare const _default: RuntimePluginFactory<void>;
+
+export { _default as default };