react-perf-recorder 0.1.0

package/dist/browser/client.d.ts

@@ -0,0 +1,589 @@
+import { R as RuntimePlugin, F as Fiber, a as RuntimePluginFactory, P as PluginInfo, b as PluginContext, C as CauseInput, c as Primitive, S as SessionContext, d as PluginSection, e as Conditions, f as RecordingV2, g as ReasonInfo, h as RootStat, H as HookInfo, A as ActionRecord, G as GLOBAL_KEY } from './index-BlkKhwHe.js';
+
+interface Describer {
+    selector(fn: Function): string;
+    store(getSnapshot: Function): string | null;
+}
+
+interface CauseEvent {
+    plugin: string;
+    type: string;
+    atMs: number;
+    changes?: Array<{
+        key: string;
+        prev: unknown;
+        next: unknown;
+    }>;
+    data?: Record<string, Primitive>;
+    /** Components the event scheduled updates on, when the core knows them: the cause goes to those roots only. */
+    fibers?: Set<Fiber>;
+    /** The event knows which components it woke — even if that turned out to be none of them. */
+    aimed?: true;
+}
+type PluginEntry = [RuntimePluginFactory | RuntimePlugin, unknown];
+interface Loaded {
+    plugin: RuntimePlugin;
+    error?: string;
+}
+/** Runtime halves of the plugins: labels, cause events and their sections of the recording. */
+declare class PluginHost implements Describer {
+    readonly loaded: Loaded[];
+    recording: boolean;
+    /** Set by the recorder: components that got updates since the last commit, to aim a cause at their roots. */
+    targets: (() => Set<Fiber>) | null;
+    private buffer;
+    /** `waitForTimer` events, until a timer of their plugin's packages runs. */
+    private waiting;
+    private readonly owners;
+    /** Plugins whose events a timer of theirs has delivered in this recording. */
+    private readonly delivering;
+    private t0;
+    readonly warnings: string[];
+    constructor(entries: PluginEntry[]);
+    setupAll(): void;
+    info(): PluginInfo[];
+    context(name: string): PluginContext;
+    /** Aimed only when the caller says it can be: an event that runs before React cannot say whom it woke. */
+    emit(plugin: string, event: CauseInput, fibers?: Set<Fiber>): CauseEvent | null;
+    get hasWaiting(): boolean;
+    /**
+     * A timer of `library` updated components: the events its plugin had waiting since before it started go to them,
+     * or to the commit as it is when `fibers` is null (the commit ran inside the timer). Returns whether it was a
+     * plugin's delivery, which then needs no cause of its own. A timer that updated no one is not called: a library
+     * runs other timers too (garbage collection, the next poll), and one of those must not take the events.
+     */
+    deliver(library: string | null, fibers: () => Set<Fiber> | null, startedAt?: number): boolean;
+    drain(): CauseEvent[];
+    now(): number;
+    selector(fn: Function, depth?: number): string;
+    store(getSnapshot: Function): string | null;
+    private describe;
+    start(session: Omit<SessionContext, keyof PluginContext>, t0: number): void;
+    commit(session: Omit<SessionContext, keyof PluginContext>): void;
+    stop(session: Omit<SessionContext, keyof PluginContext>): Record<string, PluginSection>;
+    conditions(): Conditions;
+    private guard;
+}
+
+interface ScopeHandle {
+    kind: 'scope';
+    /** Every fiber from the HostRoot down to the scope component; either object of an alternate pair. */
+    chain: Fiber[];
+    name: string;
+    source: string;
+}
+
+interface EngineConfig {
+    version: string;
+    projectRoot: string;
+    wrapperPattern: string;
+    actions: {
+        values: boolean;
+        secretSelector: string;
+    };
+    maxDurationMs: number;
+    bigCommit: number;
+    timelineLimit: number;
+    /** Timers are wrapped at boot; off leaves the page's timers alone and timer causes out. */
+    timers?: boolean;
+}
+interface RecordOptions {
+    source?: string;
+    label?: string;
+    scope?: ScopeHandle | null;
+    watch?: string[];
+    zones?: Record<string, string | {
+        selector: string;
+        viaAriaControls?: boolean;
+    }>;
+    highlight?: boolean;
+    actions?: boolean;
+    hookNames?: boolean;
+    prune?: boolean;
+    /** Count animation frames for a rough fps; the commit scan itself costs frame time, so trust long frames more. */
+    frames?: boolean;
+    bigCommit?: number;
+    timeline?: number;
+    meta?: Record<string, Primitive>;
+    /** Work out parent-caused reasons for the first instances of a component per commit only; render counts stay exact. */
+    sampleReasons?: boolean;
+}
+interface HighlightSink {
+    /** The panel's toggle; a recording draws and counts as highlighted only while it is on. */
+    enabled?: boolean;
+    /** `mounted`: the tops of subtrees mounted into the tree, outlined apart from renders. */
+    flash(pairs: Array<[Element, string, Fiber]>, withoutDom: Set<Fiber>, mounted?: Set<Fiber>): void;
+    /** Time spent measuring and drawing outside commits since the last call. */
+    takeCostMs?(): number;
+}
+
+interface BootConfig extends EngineConfig {
+    /** `{base}__react-perf-recorder`; null when no dev server stores sessions. */
+    endpoint: string | null;
+}
+type ScopeSpec = ScopeHandle | {
+    selector: string;
+    component?: string;
+    level?: number;
+} | {
+    names: string[];
+} | null;
+interface StartOptions extends Omit<RecordOptions, 'scope'> {
+    scope?: ScopeSpec;
+    /** Stream the session to the dev server; on by default when there is one. */
+    save?: boolean;
+}
+/** What the tree may hide: components of packages, providers, and the app's own unnamed wrappers. */
+interface Shown {
+    library: boolean;
+    providers: boolean;
+}
+interface Owner {
+    name: string;
+    source: string;
+    /** An unnamed component the app left for the pattern to name: `Anonymous`, `Memo`, `ForwardRef`. */
+    wrapper: boolean;
+    /** Hands a context down and nothing else. */
+    provider: boolean;
+    /** A component of a package, not of the app: no site of its own, or a file under node_modules. */
+    library: boolean;
+    fiber: Fiber;
+}
+interface Saved extends RecordingV2 {
+    id?: string;
+    dir?: string;
+    saveError?: string;
+}
+/** The page-side API: `window.__REACT_PERF_RECORDER__.engine`. */
+declare class Engine {
+    readonly config: BootConfig;
+    readonly plugins: PluginHost;
+    private highlight;
+    private ownHost;
+    last: Saved | null;
+    private recorder;
+    /** The area the running recording was started with, as it was found: a load recording finds it before the panel does. */
+    private recordingScope;
+    private writer;
+    private timer;
+    /** `saved`: a recording that stopped on its own at the length limit, once it is saved — no one else asked for it. */
+    private listeners;
+    /** The stop the length limit made, for whoever was waiting to stop it themselves. */
+    private autoStop;
+    private readonly wrapperRe;
+    private idle;
+    private idleHighlight;
+    private idleRetry;
+    constructor(config: BootConfig, plugins: PluginHost, highlight?: HighlightSink | null, ownHost?: Element | null);
+    /** The panel and its highlight canvas: events inside the panel are not user actions. */
+    attachUi(highlight: HighlightSink | null, ownHost: Element | null): void;
+    get version(): string;
+    get recording(): boolean;
+    get scopeOfRecording(): ScopeHandle | null;
+    onChange(listener: (state: 'started' | 'stopped' | 'saved', saved?: Saved) => void): () => boolean;
+    status(): {
+        version: string;
+        recording: boolean;
+        busyOwner: string | null;
+        react: {
+            found: boolean;
+            version: string | null;
+            roots: number;
+        };
+        scope: {
+            name: string;
+            source: string;
+        } | null;
+        sessionId: string | null;
+        plugins: PluginInfo[];
+    };
+    /**
+     * Outlines renders in the area while nothing is recorded. A recording takes the commit hook over and, with
+     * `highlight` on, keeps drawing; this resumes after it stops.
+     */
+    highlightWhenIdle(on: boolean, scope?: ScopeSpec): void;
+    get idleHighlighting(): boolean;
+    private syncIdleHighlight;
+    start(options?: StartOptions): {
+        scope: {
+            name: string;
+            source: string;
+        } | null;
+    };
+    /** Stops, builds the recording and, with a dev server, saves it; resolves with the id of the saved session. */
+    stop(): Promise<Saved>;
+    record(durationMs: number, options?: StartOptions): Promise<Saved>;
+    live(): {
+        commits: number;
+        commitsInScope: number;
+        renders: number;
+        rendersPerSec: number;
+        elapsedMs: number;
+        scopeState: "attached" | "lost" | null;
+        topRoots: ({
+            reason: string;
+            info: ReasonInfo;
+            name: string;
+            hits: number;
+            perHit: number;
+        } | {
+            reason: string;
+            info?: undefined;
+            name: string;
+            hits: number;
+            perHit: number;
+        })[];
+    } | null;
+    noteHmr(type: string, paths: string[]): void;
+    /** The page unloads mid-recording: flush what is left; the server marks the session interrupted. */
+    interrupt(): void;
+    /**
+     * The app's own components on the page right now, by name. A script that was told to record inside one and did
+     * not find it can say what there is instead of failing into nothing.
+     */
+    componentNames(limit?: number): string[];
+    /**
+     * Every instance of a component on the page now, found by its name and file. A line that moved since the
+     * recording (the code was edited) still finds it by the file; failing that, by the name alone.
+     */
+    findComponents(name: string, source?: string, limit?: number): Fiber[];
+    /**
+     * The topmost of the app's own components, as the tree shows them with these filters: where a tree of the whole
+     * app opens when no area has been picked yet.
+     */
+    topComponent(shown: Shown): Fiber | null;
+    /** Composite ancestors of an element, nearest first. */
+    owners(el: Element): Owner[];
+    /** The fiber itself when it is a component, then its composite ancestors, nearest first. */
+    ownersOfFiber(fiber: Fiber): Owner[];
+    ownerOf(fiber: Fiber): Owner;
+    /** Nearest components below one; what is hidden is walked through, not stopped at. */
+    childOwners(fiber: Fiber, shown: Shown): Owner[];
+    /** A component the tree leaves out: the checkboxes decide, and an unnamed wrapper follows the library one. */
+    hidden(owner: Owner, shown: Shown): boolean;
+    scopeFromFiber(fiber: Fiber): ScopeHandle;
+    scopeFromElement(el: Element, level?: number): ScopeHandle;
+    /** Finds the component again after a reload by its composite path, e.g. ['OrdersPanel', 'PositionTable']. */
+    scopeFromNames(names: string[]): ScopeHandle;
+    private resolveScope;
+}
+
+interface RootLine {
+    root: string;
+    source: string;
+    path: string;
+    hits: number;
+    hitsPerSec: number;
+    instances: number;
+    perHit: number;
+    noDomChange: number;
+    /** Components mounted under the root: remounts on every hit point at a component declared in render or a new key. */
+    mounts?: number;
+    renderMsPerHit?: number;
+    reasons: string[];
+    causes: string[];
+    lanes?: string;
+}
+interface ActionLine {
+    id: number;
+    what: string;
+    atSec: number;
+    commits: number;
+    renders: number;
+    reaction: number;
+    perChar?: string;
+    latencyMs?: number;
+    longFrames?: number;
+    topRoot?: string;
+}
+interface Summary {
+    id?: string;
+    status?: string;
+    partial?: boolean;
+    createdAt: string;
+    label?: string;
+    source: string;
+    url: string;
+    viewport: string;
+    durationSec: number;
+    scope: {
+        name: string;
+        source: string;
+        state: string;
+        remounts: number;
+    } | null;
+    totals: {
+        commits: number;
+        commitsPerSec: number;
+        commitsInScope: number;
+        renders: number;
+        rendersPerScopeCommit: number;
+        rendersFromOutside: number;
+        rendersWithoutDom: number;
+        domTextChanges: number;
+        rendersPerTextChange: number | null;
+    };
+    topRoots: RootLine[];
+    outsideRoots: RootLine[];
+    topCauses: Array<{
+        key: string;
+        events: number;
+        commits: number;
+        keys?: string;
+    }>;
+    actions: ActionLine[];
+    plugins: Record<string, {
+        version: number;
+        highlights: string[];
+    }>;
+    /** useMemo and useCallback that recompute on most renders, worst first. */
+    memos?: string[];
+    frames: {
+        longTasks: number;
+        maxLongTaskMs: number;
+        longFrames: number;
+        worstFrameMs: number;
+    };
+    overhead: RecordingV2['overhead'];
+    warnings: string[];
+}
+/** `full` keeps the whole chain; `short` stops at the package API the app called: `useSelector › zustand.useStore`. */
+type HookMode = 'full' | 'short';
+declare function hookText(hook: HookInfo | undefined, mode?: HookMode): string;
+/** `12× state #2 SAME-CONTENT · useController › useFormState › State @ src/Field.tsx:48 const { fieldState } = …` */
+declare function reasonLine(root: RootStat, reason: ReasonInfo | undefined, n: number, mode?: HookMode): string;
+declare function actionText(action: ActionRecord): string;
+declare function summarize(rec: RecordingV2 & {
+    id?: string;
+    status?: string;
+}, top?: number, hooks?: HookMode): Summary;
+
+/**
+ * Outlines of rendered components on one canvas, `Name ×N` for the render count; grey when the DOM did not change.
+ * Rects come through IntersectionObserver, so drawing forces no layout.
+ */
+declare class Highlighter implements HighlightSink {
+    enabled: boolean;
+    private readonly canvas;
+    private readonly ctx;
+    private pending;
+    /** Renders in a row with less than a fade between them: a steady ticker keeps counting up and turns red. */
+    private counts;
+    /** One box per element, so a component rendering again refreshes its outline instead of stacking another. */
+    private flashes;
+    private frameRequested;
+    private drawing;
+    private costMs;
+    private colours;
+    /** Components picked on the report's timeline: outlined until the pick changes, whatever the highlight toggle says. */
+    private pinned;
+    constructor(parent: ShadowRoot | Element);
+    /** Outlines these components until the next call; an empty list takes them away. */
+    pin(items: Array<{
+        fiber: Fiber;
+        label: string;
+    }>): void;
+    private redraw;
+    takeCostMs(): number;
+    reset(): void;
+    flash(pairs: Array<[Element, string, Fiber]>, withoutDom: Set<Fiber>, mounted?: Set<Fiber>): void;
+    private measure;
+    private draw;
+    /** Labels repeat from frame to frame while a box fades: measured once each. */
+    private readonly labelWidths;
+    private widthOf;
+    /** A box around everything a picked component draws, in the colour of picking, and its label above. */
+    private drawPinned;
+    /** Grey when the render changed nothing; otherwise green, amber and red by how often it came. */
+    private colourOf;
+    private clear;
+    private resize;
+}
+
+/** One thing to do again, with enough of the element to find it on a freshly loaded page. */
+interface ReplayStep {
+    kind: 'click' | 'typing' | 'key' | 'change' | 'submit' | 'scroll';
+    /** Milliseconds after the previous step began (the first: after the replay began). */
+    afterMs: number;
+    /** How long it took; typing spreads its characters over it. */
+    durationMs: number;
+    what: string;
+    selector?: string;
+    nth?: number;
+    key?: string;
+    chars?: number;
+    /** The typed or chosen value, only when the recording kept values. */
+    value?: string;
+    scrollTo?: number;
+}
+interface ReplayPlan {
+    from?: string;
+    steps: ReplayStep[];
+    /** How long to go on recording after the last step: the tail of the original, for the same background. */
+    tailMs: number;
+    /** Actions that cannot be done again, and why. */
+    skipped: string[];
+}
+
+type Corner = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+
+interface PanelOptions {
+    corner: Corner;
+    highlight: boolean;
+    shortcuts: {
+        record: string;
+        pick: string;
+    };
+    interrupted: {
+        id: string;
+    } | null;
+}
+/**
+ * The panel's state; the markup is a preact view of it (`components/PanelView.tsx`), redrawn from `sync()`.
+ * The view lives in the panel's own shadow root, so the app's React never sees it.
+ */
+declare class Panel {
+    private engine;
+    private options;
+    readonly host: HTMLDivElement;
+    private shadow;
+    private container;
+    private state;
+    private scope;
+    private before;
+    private liveTimer;
+    private picker;
+    private busy;
+    private visible;
+    /** Set by the page for as long as it has nothing to record (a front page, docs); never remembered. */
+    private suppressed;
+    private tree;
+    private result;
+    private message;
+    private highlighter;
+    /** A commit or action picked on the timeline: its outlines alone are on the page until the pick is undone. */
+    private outlining;
+    /** The pointer that just finished a drag of the dot; its click opens nothing. */
+    private dragged;
+    private readonly handlers;
+    constructor(engine: Engine, options: PanelOptions);
+    setHighlighter(highlighter: Highlighter): void;
+    /** Panel host goes on <html>, outside body: the app's root lookups and DOM observers never see it. */
+    mount(): void;
+    get shadowRoot(): ShadowRoot;
+    /** Something the view shows has changed outside the panel — a component's file came back from the dev server. */
+    redraw(): void;
+    /** Hides the panel, its outlines and its shortcuts while `on`, without touching what the person chose to see. */
+    suppress(on: boolean): void;
+    show(): void;
+    /** Renders in the area are outlined all the time the panel is shown, not only while recording. */
+    private syncIdleHighlight;
+    private initialVisibility;
+    /** What the view can ask for, in one place; each line is a method below. */
+    private buildHandlers;
+    /** The area, the note and the watched components are put aside, so the reloaded page can pick the recording up. */
+    private reloadIntoRecording;
+    private copyScope;
+    /**
+     * The clipboard is written in the same task as the click, never after an await: browsers may refuse a copy
+     * that leaves the user's gesture.
+     */
+    private copyArea;
+    /**
+     * The area picked before the reload, found again by its component path once the app renders it.
+     * A page without that component keeps the whole app as the area, silently.
+     */
+    private restoreScope;
+    /**
+     * A recording from the page load finds its area itself, before the panel's own search does and then stops; the
+     * panel shows that area, or the pill says Pick while the recording is of one component only.
+     */
+    private adoptRecordingScope;
+    /** Hovering the area's name outlines it on the page, unless the picker is already drawing something. */
+    private outlineScope;
+    private setHighlight;
+    private setNote;
+    private sync;
+    private viewProps;
+    private toggleWatch;
+    private start;
+    /** The roots of a picked commit or action, on the page as it is now: every instance of each, labelled with its hits. */
+    private outlineRoots;
+    /** Reloads and does the actions of the report again, recording: the same scenario after a change of the code. */
+    private repeat;
+    /** Where a replay is: the header says it instead of the running numbers. */
+    private replaying;
+    replayProgress(at: number | null, of?: number): void;
+    /** A replay has done its steps: stop as Stop does, and say why if it could not finish them. */
+    finish(failure: string | null): Promise<void>;
+    private showResult;
+    /** The component path of the area the report was recorded in. */
+    private resultArea;
+    /** The last recording against the one before it in this tab, when they are of the same page and area. */
+    private compared;
+    private stop;
+    private togglePicker;
+    /** Reopens the tree on the current area; without one, picks from scratch. */
+    private editScope;
+    /** The area as it was before the tree opened: Esc puts it back, whatever was tried in between. */
+    private rememberScope;
+    /** The committed fiber of the area; after a remount the area is found again by its component path. */
+    private scopeTarget;
+    /** What was just copied, by the key of the button that copied it: that button shows a tick for a moment. */
+    private copied;
+    private copiedTimer;
+    private copy;
+    private onPicked;
+    private setScope;
+    private showTree;
+    private say;
+    private setCollapsed;
+    private onShortcut;
+    /**
+     * Dragging moves the panel by inline styles, which no render touches; on release the dock becomes state.
+     * The dot is a button, so the drag takes over only once the pointer has really moved.
+     */
+    private onDragStart;
+    /** A drag that started on the dot ends in a click; that one click must not open the panel. */
+    private openFromDot;
+    private persist;
+}
+
+declare const format: {
+    summarize: typeof summarize;
+    reasonLine: typeof reasonLine;
+    hookText: typeof hookText;
+    actionText: typeof actionText;
+};
+
+interface ClientConfig extends BootConfig {
+    panel: false | {
+        corner: Corner;
+        highlight: boolean;
+        shortcuts: {
+            record: string;
+            pick: string;
+        };
+    };
+}
+interface HotContext {
+    on(event: string, cb: (payload: any) => void): void;
+}
+interface RecorderGlobal {
+    version: string;
+    engine: Engine;
+    panel: Panel | null;
+    /** The same formatting as the panel and the MCP server, for scripts that print their own answer. */
+    format: typeof format;
+    /** Does the steps of a recording again while one is being recorded; `record_page` calls it for a replay. */
+    replay(plan: ReplayPlan): Promise<void>;
+}
+declare global {
+    interface Window {
+        [GLOBAL_KEY]?: RecorderGlobal;
+    }
+}
+/** Called by the virtual entry the Vite plugin injects at the top of <head>: runs before the app's modules. */
+declare function boot(config: ClientConfig, plugins: PluginEntry[], hot?: HotContext): RecorderGlobal;
+
+export { type BootConfig, type ClientConfig, type RecorderGlobal, boot };