@atlassian/chippy 0.0.0-stage → 0.0.1-beta.1

package/lib/types/avalanche/reporter.d.ts

@@ -0,0 +1,610 @@
+/**
+ * Projects the detector's live fiber history into ranked evidence and the
+ * serializable report consumed by bridge commands and offline analysis. The
+ * detector owns capture-time truth; this layer owns interpretation and output
+ * ordering, so presentation changes do not alter hot-path collection.
+ */
+import type { ComponentType, ChangedHook, Fiber, ThrashInfo } from './internals.js';
+import type { ReportDTO } from './report-serializer.js';
+import { type CommitMetricsAdapter, type CommitMetricsDelta, type CommitMetricsSnapshot, type IntegrationMode } from './commit-metrics-adapter.js';
+export type SortBy = 'effect' | 'callback' | 'memo' | 'total';
+export interface Source {
+    sourceId: string;
+    type: ComponentType;
+    depth: number;
+    renderCount: number;
+    causedUpdates: number;
+    collateralUpdates: number;
+    maxCollateralUpdates: number;
+    maxPenetrationDepth: number;
+    updateHistory: Record<number, Record<number, ChangedHook> | 'repeat' | string>;
+    collateralByCommit: Record<number, number>;
+    fiber?: Fiber;
+    /** Changed hook indices from this source's latest self-update; maps debugHook indices to debug-render events. */
+    debugHookIndices?: number[];
+    /**
+     * RESTART WASTE TRACKING - identifies sources contributing to restart waste
+     *
+     * Restarts = wasted renders (component rendered but work was discarded)
+     * Attribution: proportional to sources that fired in each commit with restarts
+     *
+     * Example: Commit has 1000 restarts, 2 sources fire
+     *   → Each source attributed 500 restarts
+     *
+     * High restartWaste = this source triggers commits that cause React to restart work
+     */
+    restartWaste?: number;
+    maxRestartWaste?: number;
+    restartWasteByCommit?: Record<number, number>;
+    /**
+     * Components that were amplified when this source triggered them.
+     * These are components that re-rendered with unstable hooks (effects, callbacks, memos).
+     * Includes both:
+     * - This source itself (if it has unstable hooks)
+     * - Descendant components that re-rendered with unstable hooks
+     */
+    amplified?: Array<{
+        /** Component that amplified work */
+        sourceId: string;
+        type: ComponentType;
+        depth: number;
+        /** Total effect amplifications across all commits */
+        effectCount: number;
+        /** Total callback amplifications across all commits */
+        callbackCount: number;
+        /** Total memo amplifications across all commits */
+        memoCount: number;
+        /** Total hook amplifications (effect + callback + memo) */
+        hooksTotal: number;
+        /** Commits where this component amplified work */
+        commitIds: number[];
+        /** Per-commit breakdown: { commitId: { effects, callbacks, memos } } */
+        byCommit: Record<number, {
+            effects: number;
+            callbacks: number;
+            memos: number;
+        }>;
+        /** Latest amplification details */
+        lastAmplification: {
+            depth: number;
+            thrashedHooks: ThrashInfo[];
+            fiber?: Fiber;
+        };
+    }>;
+}
+export interface Amplifier {
+    type: ComponentType;
+    renderCount: number;
+    instancesTotal: number;
+    maxInstancesPerCommit: number;
+    hooksTotal: number;
+    maxHooksPerCommit: number;
+    effectCount: number;
+    callbackCount: number;
+    memoCount: number;
+    lastAmplification: {
+        depth: number;
+        thrashedHooks: ThrashInfo[];
+        fiber?: Fiber;
+    };
+}
+/**
+ * Linked thrasher - connects thrashing info to source identity.
+ *
+ * This enables:
+ * - thrasher.sourceId → navigate to source
+ * - thrasher.isSource → prioritize fixes (source+thrasher = high impact)
+ * - thrasher.commitIds → correlate with commitStats
+ * - source.thrashing → see hook instability for a source
+ */
+export interface AmplifierSource {
+    /** Human-readable ID (e.g., "Counter#1@5" in dev, "Unknown#1@5" in prod) */
+    sourceId: string;
+    /** Component type (function reference) */
+    type: ComponentType;
+    /** Depth in component tree */
+    depth: number;
+    /** Collateral damage caused by this source (0 if not tracked) */
+    collateralUpdates: number;
+    /** Total effect amplifications across all commits */
+    effectCount: number;
+    /** Total callback amplifications across all commits */
+    callbackCount: number;
+    /** Total memo amplifications across all commits */
+    memoCount: number;
+    /** Total hook amplifications (effect + callback + memo) */
+    hooksTotal: number;
+    /** Commits where this component amplified work */
+    commitIds: number[];
+    /** Per-commit breakdown: { commitId: { effects, callbacks, memos } } */
+    byCommit: Record<number, {
+        effects: number;
+        callbacks: number;
+        memos: number;
+    }>;
+    /** If not a source, which sourceId caused this to re-render? */
+    causedBySourceId: string | null;
+    /** Latest amplification details */
+    lastAmplification: {
+        depth: number;
+        thrashedHooks: ThrashInfo[];
+        fiber?: Fiber;
+    };
+}
+/**
+ * Commit stats tuple: [collateral, sources, restarts, performedWork, effects, memos, callbacks, contextUpdates, unmountedComponents, unmountedSubtrees]
+ * Use these numbers to find which commits to investigate in DevTools.
+ * - collateral: components re-rendered as victims
+ * - sources: components that initiated updates (update sources)
+ * - restarts: extra renders due to external store mutations, priority changes, etc.
+ * - performedWork: components with PerformedWork flag (actual work React processed)
+ * - effects/memos/callbacks: thrashing hooks (effects likely cause next commit!)
+ * - contextUpdates: number of Context Providers whose value changed this commit
+ * - unmountedComponents: total component fibers unmounted this commit
+ * - unmountedSubtrees: number of distinct unmount "branch starts" (topmost deleted components)
+ */
+export type CommitStats = [
+    collateral: number,
+    sources: number,
+    restarts: number,
+    performedWork: number,
+    effects: number,
+    memos: number,
+    callbacks: number,
+    contextUpdates: number,
+    unmountedComponents: number,
+    unmountedSubtrees: number
+];
+/**
+ * Human-readable keys for CommitStats tuple positions.
+ * Use with commitStats[commit][commitStatsKeys.collateral]
+ */
+export declare const commitStatsKeys: {
+    readonly collateral: 0;
+    readonly sources: 1;
+    readonly restarts: 2;
+    readonly performedWork: 3;
+    readonly effects: 4;
+    readonly memos: 5;
+    readonly callbacks: 6;
+    readonly contextUpdates: 7;
+    readonly unmountedComponents: 8;
+    readonly unmountedSubtrees: 9;
+};
+/**
+ * Report metadata - profiling context and overhead metrics.
+ */
+export interface ReportMeta {
+    /** Report format version - increment when changing data structure */
+    version: number;
+    /** Total commits processed */
+    commits: number;
+    /** Detector configuration used during profiling */
+    config: {
+        /** Detection level: 'stats' (minimal), 'sources', 'amplifiers', or 'full' */
+        detectionLevel: DetectionLevel;
+        /** Effect thrashing sensitivity: 'non-primitive' or 'all' */
+        effectThrashMode: 'non-primitive' | 'all';
+        /** Whether fibers were captured (for debugging) */
+        captureFibers: boolean;
+        /** Update history size per source */
+        historySize: number;
+    };
+    /** memoizedUpdaters availability and coverage */
+    memoizedUpdatersSupport: {
+        available: boolean;
+        commitsWithData: number;
+        coverage: string;
+    };
+    /**
+     * Which commit-hook integration model produced this report. Determines what
+     * is reliably present in `commitStats[N]` and `metricsByCommit[N]`.
+     *
+     * 'adapter:<id>' — A commit metrics adapter (for example `adapter:atl`) drove
+     *              the commit callback with host render counters. ALL fields below
+     *              are populated and `metricsByCommit` is present.
+     * 'devtools' — Reconstructed entirely from the React DevTools commit hook
+     *              (fiber walk only). The fiber-walk fields are real measurements:
+     *              collateral, sources, performedWork, effects, memos, callbacks,
+     *              contextUpdates. The render-counter math (restarts) is NOT
+     *              available — `commitStats[N][2]` will be 0 (semantically
+     *              "unknown / not measurable in this mode") and `metricsByCommit`
+     *              is empty. This is normal on stock react-dom.
+     * 'none'     — Detector wasn't installed when this report was generated.
+     *
+     * Reports before the adapter seam used `'atl'` for `'adapter:atl'`.
+     */
+    integrationMode: IntegrationMode;
+    /** Id of the commit metrics adapter that drove this report, or null. */
+    metricsAdapter: string | null;
+    /**
+     * Per-field availability map for `commitStats[N]` indices. `false` means the
+     * value is a placeholder (typically 0) that consumers should treat as unknown
+     * rather than a real measurement of zero.
+     *
+     * Stable across all commits in a given report — set once from integrationMode.
+     */
+    dataAvailability: {
+        /** [0] perCommit.totalCollateral — reconstructed from fiber walk */
+        collateral: boolean;
+        /** [1] perCommit.selfUpdated.size — reconstructed from fiber walk */
+        sources: boolean;
+        /** [2] derived from the adapter's render-counter delta — only in 'adapter:<id>' mode */
+        restarts: boolean;
+        /** [3] perCommit.committedComponentCount — reconstructed from fiber walk */
+        performedWork: boolean;
+        /** [4] perCommit.effectCount — reconstructed from fiber walk */
+        effects: boolean;
+        /** [5] perCommit.memoCount — reconstructed from fiber walk */
+        memos: boolean;
+        /** [6] perCommit.callbackCount — reconstructed from fiber walk */
+        callbacks: boolean;
+        /** [7] perCommit.contextUpdates — reconstructed from fiber walk */
+        contextUpdates: boolean;
+        /** Adapter counters in metricsByCommit — only in 'adapter:<id>' mode */
+        metricsByCommit: boolean;
+        /** @deprecated Alias of `metricsByCommit`, kept for one release. */
+        atlByCommit: boolean;
+    };
+    /** Amplifier summary (when detectionMode: 'amplifierMetrics') */
+    amplifiersMetrics?: {
+        totalHookThrashes: number;
+        affectedComponentCount: number;
+    };
+    /**
+     * Timing summary - shows detector overhead and commit durations.
+     * Use this to justify avalanche-detector overhead in production.
+     */
+    timing: {
+        /** Total time spent in detector across all commits (ms) */
+        totalDetectorOverhead: number;
+        /** Average detector overhead per commit (ms) */
+        avgDetectorOverhead: number;
+        /** Total time from first to last commit (ms) */
+        totalTimeSpan: number;
+        /** Average time between commits (ms) */
+        avgTimeBetweenCommits: number;
+    };
+}
+export interface HostUnmountSummary {
+    elements: number;
+    text: number;
+    tagsTop: Array<[string, number]>;
+    testIdsTop: Array<[string, number]>;
+    rolesTop: Array<[string, number]>;
+    ariaLabels: string[];
+    textHints: string[];
+}
+export interface UnmountSample {
+    name: string;
+    key: string | null;
+    depth: number | null;
+    count: number;
+    source?: {
+        fileName?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    } | null;
+    host?: HostUnmountSummary;
+}
+export type InteractionCaptureLevel = 'off' | 'explicit' | 'noisy' | 'all';
+export interface InteractionActionLocation {
+    dom: {
+        tag: string | null;
+        text: string;
+        nearestTestId: string | null;
+    };
+    targetFiber: {
+        name: string | null;
+        key: string | null;
+        source: {
+            fileName?: string;
+            lineNumber?: number;
+            columnNumber?: number;
+        } | null;
+        ownerStackKind: 'owners' | 'parents';
+        ownerStack: Array<{
+            name: string | null;
+            key: string | null;
+            props: string[];
+            hookCount: number;
+            hookCountTruncated: boolean;
+            hookCountMax: number;
+            source: {
+                fileName?: string;
+                lineNumber?: number;
+                columnNumber?: number;
+            } | null;
+        }>;
+    } | null;
+}
+export interface InteractionAction {
+    /** Sequential action id within this detector capture. */
+    id: number;
+    /** Native event name, e.g. click, keydown, wheel. */
+    action: string;
+    /** performance.now() at event capture time. Kept live-only; DTO emits deltaTime. */
+    timestamp: number;
+    /** DOM-grounded event target plus target component/ownership stack. */
+    location: InteractionActionLocation;
+}
+export type PropChangeKind = 'same' | 'ref-changed' | 'scalar-changed' | 'added' | 'removed';
+export interface PropValueSummary {
+    type: string;
+    isArray: boolean;
+    isFunction: boolean;
+    isNull: boolean;
+    preview: string;
+    display?: string;
+    length?: number;
+    keysTop?: string[];
+    sample?: unknown[];
+}
+export interface PropChangeEvidence {
+    name: string;
+    kind: PropChangeKind;
+    prev: PropValueSummary;
+    current: PropValueSummary;
+}
+export interface RenderedComponentEvidence {
+    sourceId: string;
+    name: string;
+    depth: number;
+    parentSourceId: string | null;
+    ownerSourceId: string | null;
+    isSelfSource: boolean;
+    propChanges: PropChangeEvidence[];
+    hasPropChanges: boolean;
+    trasherCounts: {
+        effects: number;
+        callbacks: number;
+        memos: number;
+    };
+}
+export interface CommitInteractionAction {
+    /** Original action id — must match InteractionAction.id for describe-action lookup. */
+    id: number;
+    /** Last commit id at the moment this action was observed. */
+    lastCommitId: number;
+    /** Milliseconds from action capture to the linked commit. */
+    deltaTime: number;
+    action: string;
+    location: InteractionAction['location'];
+}
+export interface Report {
+    /** Metadata: version, counts, overhead metrics */
+    meta: ReportMeta;
+    /** Components that caused updates, sorted by collateral damage */
+    sources: Source[];
+    /** Bridge to DevTools - maps commit ID to sources that fired in that commit */
+    sourcesByCommit: Record<number, Array<{
+        sourceId: string;
+        type: ComponentType;
+        depth: number;
+        /** Collateral damage caused by this source in THIS commit */
+        collateral: number;
+        /** Position in top N sources list (1-based), or null if not in top N */
+        rank: number | null;
+        /** Index into sources[] array for full accumulated data, or null if not in top N */
+        sourceIndex: number | null;
+        hooks?: Array<{
+            index: number;
+            prevValue: unknown;
+            currentValue: unknown;
+        }>;
+        isRepeat?: boolean;
+    }>>;
+    /**
+     * Per-commit metrics to find the needle: [collateral, effects, memos, callbacks]
+     * High collateral = avalanche. High effects = likely causes next commit!
+     */
+    commitStats: Record<number, CommitStats>;
+    /**
+     * Per-commit timing data - correlate restarts with commit duration.
+     * High commitStats[N].restarts + high commitTimings[N].timeSinceLastCommit = React wasted work.
+     */
+    commitTimings: Record<number, CommitTiming>;
+    /**
+     * Per-commit counter deltas from the commit metrics adapter - low-level React
+     * work per commit. With the ATL adapter:
+     * metricsByCommit[N].componentRenderWithHooksCount + finishClassComponentCount
+     * should equal commitStats[N].collateral + commitStats[N].sources
+     */
+    metricsByCommit?: Record<number, CommitMetricsDelta>;
+    /** @deprecated Alias of `metricsByCommit`, kept for one release. */
+    atlByCommit?: Record<number, CommitMetricsDelta>;
+    /** @deprecated Use amplifierSources instead for full source linkage */
+    amplifiers?: Amplifier[];
+    /**
+     * Amplifier sources - components that amplified the update cost with hook re-executions.
+     * Shows which components responded to updates with expensive work (effects, memos, callbacks).
+     * Linked to the source that triggered them.
+     */
+    amplifierSources?: AmplifierSource[];
+    /**
+     * Per-commit Suspense boundary transitions.
+     * Only populated for commits where at least one boundary entered or left fallback.
+     * Empty object when no Suspense transitions occurred during the capture.
+     */
+    suspenseByCommit: Record<number, SuspenseBoundaryEvent[]>;
+    /** Bounded samples of component subtrees unmounted per commit. */
+    unmountsByCommit?: Record<number, UnmountSample[]>;
+    /** Compact user/browser actions linked to nearby commits. */
+    interactionsByCommit?: Record<number, CommitInteractionAction[]>;
+    /** Structural evidence for each component that rendered in a commit. */
+    renderedByCommit?: Record<number, RenderedComponentEvidence[]>;
+    /**
+     * Convert this report to a serializable DTO (safe for JSON.stringify, IPC, network).
+     * Strips non-serializable fields like Fiber references and ComponentType functions.
+     */
+    toSerializable(): ReportDTO;
+}
+export interface DetectorOptions {
+    ignore?: ComponentType[];
+    effectThrashMode?: 'non-primitive' | 'all';
+    captureFibers?: boolean;
+    /**
+     * Detection mode - controls what the detector tracks (tiered for performance):
+     *
+     * Use DETECTION_LEVEL constants for clarity:
+     * - DETECTION_LEVEL.LEVEL1_STATS ('stats'): Only commitStats, super fast
+     * - DETECTION_LEVEL.LEVEL2_SOURCES ('sources'): + source tracking
+     * - DETECTION_LEVEL.LEVEL3_AMPLIFIER_METRICS ('amplifierMetrics'): + aggregate amplifier counts only
+     * - DETECTION_LEVEL.LEVEL3_AMPLIFIERS ('amplifiers'): + full amplifier arrays
+     *
+     * Shortcuts:
+     * - false: Alias for 'stats' (minimal overhead)
+     * - true: Alias for 'full' (maximum detail)
+     *
+     * Performance hierarchy (fastest to slowest):
+     * stats < sources < amplifierMetrics < amplifiers ≈ full
+     */
+    detectionMode?: boolean | 'full' | 'amplifiers' | 'amplifierMetrics' | 'sources' | 'stats' | false;
+    historySize?: number;
+    /**
+     * Browser action capture level. Defaults to 'explicit' to capture high-signal
+     * actions (click/keyboard/input) while leaving noisy wheel/move capture opt-in.
+     */
+    interactionCapture?: InteractionCaptureLevel;
+    /** Extra native event names to capture in addition to the selected level. */
+    interactionEvents?: string[];
+    /** Time window for linking captured actions to a commit, in ms. Default: 1000. */
+    interactionWindowMs?: number;
+    /**
+     * Commit metrics adapter for host render counters. Defaults to the adapter
+     * registered with `registerCommitMetricsAdapter` when the detector installs.
+     * Pass `null` to run on the DevTools hook only.
+     */
+    metricsAdapter?: CommitMetricsAdapter | null;
+    /** @deprecated Historical option used by older call sites. Prefer `detector.report(topN)` */
+    topN?: number;
+}
+export type ThrashMode = 'full' | 'counts' | false;
+export type DetectionLevel = 'stats' | 'sources' | 'amplifierMetrics' | 'amplifiers' | 'full';
+/**
+ * Internal amplifier source state - keyed by sourceId for navigation.
+ */
+export interface AmplifierSourceState {
+    type: ComponentType;
+    depth: number;
+    effectCount: number;
+    callbackCount: number;
+    memoCount: number;
+    hooksTotal: number;
+    commitIds: number[];
+    byCommit: Record<number, {
+        effects: number;
+        callbacks: number;
+        memos: number;
+    }>;
+    /** sourceId that caused this component to re-render (if not self-caused) */
+    causedBySourceId: string | null;
+    lastAmplification: {
+        depth: number;
+        thrashedHooks: ThrashInfo[];
+        fiber?: Fiber;
+    };
+}
+/**
+ * Commit timing data - measures React commit duration and detector overhead.
+ * All times in milliseconds.
+ */
+export interface CommitTiming {
+    /** Time from previous commit end to this commit end (includes React work + idle time) */
+    timeSinceLastCommit: number;
+    /** Time spent in avalanche detector processing (our overhead) */
+    detectorOverhead: number;
+}
+/**
+ * Internal profiler state - tracks all avalanche detection data.
+ *
+ * This is the core state structure that accumulates across commits.
+ * Most users should use the `Report` interface from `detector.report()` instead.
+ */
+export interface ProfilerState {
+    /** Total commits processed since install() or reset() */
+    commits: number;
+    /**
+     * All detected sources, keyed by stable source ID (e.g., "Button#1@3").
+     * Source = component that caused an update (not just re-rendered).
+     */
+    sources: Map<string, Omit<Source, 'sourceId'>>;
+    /** @deprecated Use amplifierSources instead */
+    amplifiers: Map<ComponentType, Omit<Amplifier, 'type'>>;
+    /**
+     * Amplifier sources keyed by sourceId.
+     * Enables source↔amplifier navigation and per-commit breakdown.
+     */
+    amplifierSources: Map<string, AmplifierSourceState>;
+    /**
+     * Aggregate thrashing counts (only if detectThrashing: 'counts').
+     * Lightweight alternative to full thrashing analysis.
+     */
+    thrashCounts: null | {
+        totalHooks: number;
+        affectedComponents: Set<ComponentType>;
+    };
+    /** Whether React DevTools hook exposes memoizedUpdaters (React 18.3.1+) */
+    memoizedUpdatersAvailable: boolean;
+    /** Number of commits where memoizedUpdaters data was present */
+    commitsWithMemoizedUpdaters: number;
+    /** Per-commit stats: [collateral, effects, memos, callbacks] */
+    commitStats: Record<number, CommitStats>;
+    /**
+     * Per-commit counter deltas from the commit metrics adapter.
+     * Enables full reconciliation with Avalanche counts.
+     */
+    metricsByCommit: Record<number, CommitMetricsDelta>;
+    /** Last adapter snapshot (for delta calculation) */
+    lastMetricsSnapshot: CommitMetricsSnapshot | null;
+    /**
+     * Per-commit timing data - measures commit duration and detector overhead.
+     * Enables correlation: high restarts → longer commit times.
+     */
+    commitTimings: Record<number, CommitTiming>;
+    /** Timestamp when last commit ended (for delta calculation) */
+    lastCommitEndTime: number;
+    /**
+     * Per-commit Suspense boundary transitions.
+     * Only populated for commits where at least one boundary entered or left fallback.
+     */
+    suspenseByCommit: Record<number, SuspenseBoundaryEvent[]>;
+    /** Bounded samples of component subtrees unmounted per commit. */
+    unmountsByCommit: Record<number, UnmountSample[]>;
+    /** Recent action breadcrumbs captured from native events. */
+    interactionActions: InteractionAction[];
+    /** Compact user/browser actions linked to nearby commits. */
+    interactionsByCommit: Record<number, CommitInteractionAction[]>;
+    /** Structural evidence for each component that rendered in a commit. */
+    renderedByCommit: Record<number, RenderedComponentEvidence[]>;
+}
+/**
+ * A Suspense boundary state transition captured during a commit.
+ * Only emitted when the boundary actually entered or left the fallback state.
+ * Boundaries that render without delay (no fallback shown) produce no events.
+ */
+export interface SuspenseBoundaryEvent {
+    /** Tree depth of the Suspense fiber */
+    depth: number;
+    /** true = boundary entered fallback (primary → suspended) */
+    entered: boolean;
+    /** true = boundary left fallback (suspended → primary revealed) */
+    left: boolean;
+    /** The Suspense fiber itself (only present when captureFibers is true) */
+    fiber?: Fiber;
+}
+export interface ReportOptions {
+    /** Minimum collateral damage to include a source in sourcesByCommit (default: 0 - show all) */
+    minCollateral?: number;
+}
+export declare function buildReport(state: ProfilerState, thrashMode: ThrashMode, topN: number, sortBy: SortBy, options?: ReportOptions, detectorConfig?: {
+    effectThrashMode: 'non-primitive' | 'all';
+    captureFibers: boolean;
+    historySize: number;
+    detectionLevel?: DetectionLevel;
+    /**
+     * Integration model that produced this report. Determines what's reliable
+     * in commitStats and metricsByCommit. Defaults to 'none'.
+     */
+    integrationMode?: IntegrationMode;
+}): Report;

package/lib/types/chippy-bridge/fiber-source.d.ts

@@ -0,0 +1,37 @@
+import { type OriginalPosition } from './source-map.js';
+export type FiberSourceLocation = {
+    fileName: string;
+    lineNumber: number;
+    columnNumber: number | null;
+};
+export type StackFrame = {
+    url: string;
+    line: number;
+    column: number;
+    function?: string;
+};
+export type SourceFiber = {
+    type?: unknown;
+    _debugSource?: unknown;
+    _debugStack?: unknown;
+};
+export type FetchModule = (url: string) => Promise<string | null>;
+export type CallSiteResolver = {
+    locate(frames: readonly StackFrame[]): Promise<FiberSourceLocation | null>;
+    readonly stats: {
+        modules: number;
+        sites: number;
+        located: number;
+    };
+};
+export declare function parseStackFrames(stack: string): StackFrame[];
+export declare function isVendorPath(path: string): boolean;
+export declare function writerLocationOf(frames: readonly StackFrame[], originalFor: (frame: StackFrame) => OriginalPosition | null): FiberSourceLocation | null;
+export declare function createCallSiteResolver(fetchModule: FetchModule): CallSiteResolver;
+export declare function getFiberStackFrames(fiber: SourceFiber | null | undefined): StackFrame[];
+/** Stable synchronous source, before any async source-map upgrade. */
+export declare function getFiberSourceCandidate(fiber: SourceFiber | null | undefined): FiberSourceLocation | null;
+/** Synchronous source read used by fiber walks and snapshots. */
+export declare function getFiberSource(fiber: SourceFiber | null | undefined): FiberSourceLocation | null;
+/** Resolve a React 19 stack frame through the module's inline or external map. */
+export declare function resolveFiberSource(fiber: SourceFiber | null | undefined, resolver?: CallSiteResolver): Promise<FiberSourceLocation | null>;

package/lib/types/chippy-bridge/react-renderer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared React DevTools renderer discovery.
+ *
+ * React-DOM registers a renderer object into
+ * `window.__REACT_DEVTOOLS_GLOBAL_HOOK__.renderers` at injection time (only when
+ * the hook exists before react-dom evaluates). That renderer object is the single
+ * entry point for several Chippy capabilities:
+ *
+ *   - `currentDispatcherRef` → debug-render hook replay (see debug-render/core.ts)
+ *   - `scheduleUpdate`        → fiber-schedule-update nudge (see fiber-schedule-update.ts)
+ *
+ * Both used to walk `hook.renderers` themselves. This module is the one place that
+ * knows how to enumerate renderers, so capabilities select the field they need
+ * without duplicating the iteration (and its Map/entries quirks).
+ */
+export type ReactRenderer = {
+    currentDispatcherRef?: {
+        current: unknown;
+    } | null;
+    scheduleUpdate?: (fiber: unknown) => void;
+    version?: string;
+    rendererPackageName?: string;
+    [key: string]: unknown;
+};
+export type DevtoolsHookLike = {
+    renderers?: Map<number, ReactRenderer> | {
+        entries(): IterableIterator<[number, ReactRenderer]>;
+    };
+};
+/**
+ * Enumerate every registered React renderer. Returns [] when the DevTools hook
+ * is absent or empty (production builds without the shim, or hook installed too
+ * late for react-dom to register).
+ */
+export declare function getReactRenderers(scope?: typeof globalThis): ReactRenderer[];
+/**
+ * First renderer that exposes a usable `currentDispatcherRef`. Used by
+ * debug-render to patch the hook dispatcher.
+ */
+export declare function getDispatcherRef(scope?: typeof globalThis): {
+    current: unknown;
+} | null;
+/**
+ * First renderer that exposes a callable `scheduleUpdate`. This is the exact
+ * function React DevTools uses to force a re-render on a fiber. It is only
+ * present on development React builds. Returns null on production builds (or
+ * when the DevTools-hook shim was missing at page boot).
+ */
+export declare function getScheduleUpdate(scope?: typeof globalThis): ((fiber: unknown) => void) | null;