@flotrace/runtime-core 2.2.3 → 2.3.0

package/dist/index.d.mts

@@ -1,8 +1,185 @@
+/**
+ * Shared utilities for the @flotrace/runtime-core JSX runtime entries.
+ *
+ * The JSX runtime (jsx-dev-runtime.ts) writes the FLOTRACE_SOURCE symbol onto
+ * a JSX element's props at creation time. The fiber walker reads the same
+ * symbol back from `fiber.memoizedProps` during tree walking. Centralising
+ * the symbol identity + helpers here means there's exactly one place to look
+ * for "what shape is fiber.memoizedProps[FLOTRACE_SOURCE]".
+ *
+ * Per PRD-JSX-RUNTIME.md §8 + IMPLEMENTATION-PLAN-JSX-RUNTIME.md Phase 1.
+ */
+/**
+ * Global symbol so the same identity is reachable from any module — including
+ * dynamically-loaded chunks and multiple bundled copies of runtime-core that
+ * may end up linked into the same app (workspace + npm registry mix). The
+ * `Symbol.for()` registry guarantees one global slot.
+ */
+declare const FLOTRACE_SOURCE: unique symbol;
+/**
+ * Adoption sentinel — the dev runtime sets this on first jsxDEV call so the
+ * walker (and `runtime:ready` event) can detect that the user opted in via
+ * `"jsxImportSource": "@flotrace/runtime-core"`. No per-call telemetry; this
+ * is a one-time boolean.
+ */
+declare const JSX_RUNTIME_ACTIVE_KEY: unique symbol;
+/**
+ * Source attribution attached to a React element's props at JSX-creation time.
+ * Stored under the `FLOTRACE_SOURCE` symbol key so it doesn't appear in
+ * `Object.keys(props)` or React's unknown-DOM-prop warnings.
+ */
+interface FlotraceJsxSource {
+    /** Normalized file path (bundler prefixes stripped). */
+    fileName: string;
+    /** 1-indexed line number. */
+    lineNumber: number;
+    /** 1-indexed column number. */
+    columnNumber: number;
+    /** FNV-1a 32-bit hash of `${fileName}:${lineNumber}:${columnNumber}`, 8 hex chars. */
+    callSiteId: string;
+    /** Map of prop key → inline-literal kind, only present when literals detected. */
+    inline?: Record<string, 'fn' | 'obj' | 'arr'>;
+}
+/** Subset of the compiler-supplied `source` argument passed to jsxDEV. */
+interface JsxSourceArg {
+    fileName: string;
+    lineNumber: number;
+    columnNumber: number;
+}
+/**
+ * Normalize a bundler-specific file path to a canonical form. Different
+ * bundlers emit different path styles for the SAME line of source code:
+ *
+ *   Vite dev          → `file:///abs/src/Foo.tsx`
+ *   Webpack dev       → `webpack-internal:///./src/Foo.tsx`
+ *   esbuild           → `./src/Foo.tsx`
+ *   Next.js Turbopack → `[project]/src/Foo.tsx` (left as-is — no known prefix)
+ *   Windows           → `C:\Users\foo\src\Foo.tsx`
+ *
+ * Without normalization, the same line of code produces a different
+ * `callSiteId` after a bundler swap (or even after switching between Next.js
+ * Webpack and Turbopack), breaking per-callsite metrics + HMR-stable watches.
+ *
+ * Normalization rules (order matters):
+ *   1. Strip `file://` prefix.
+ *   2. Strip `webpack-internal:///./` prefix.
+ *   3. Trim leading `./`.
+ *   4. Lowercase Windows drive letters (`C:\` → `c:\`).
+ */
+declare function normalizeJsxSourcePath(fileName: string): string;
+/**
+ * FNV-1a 32-bit hash → 8-char hex string. Fast, stable, and sufficient for
+ * a non-cryptographic per-callsite identity. Operates on the NORMALIZED path
+ * so the same source line produces the same hash regardless of bundler.
+ *
+ * Collision probability across a 5000-callsite app via the birthday paradox
+ * on a 32-bit hash space: 1 − e^(−5000²/(2 × 2³²)) ≈ 0.3%. Acceptable for a
+ * UI key — a one-in-300 chance of two callsites sharing a row in the Hot
+ * Call Sites table is preferable to the wire-format weight of a longer hash.
+ * Not suitable as a security token.
+ */
+declare function computeCallSiteId(source: JsxSourceArg): string;
+/**
+ * Record a render timestamp for a call site. Caller may inject `now` for
+ * deterministic tests; production callers use the default `performance.now()`.
+ */
+declare function recordCallSiteRender(callSiteId: string, now?: number): void;
+/** Read-only snapshot of recorded timestamps for a call site. */
+declare function getCallSiteRenders(callSiteId: string): readonly number[];
+/**
+ * Renders-per-second over the last `windowMs` ms. Walks backwards through the
+ * ring buffer; stops at the first entry older than the cutoff (entries are
+ * monotonically non-decreasing because the runtime only ever appends).
+ *
+ * Caller may inject `now` for deterministic tests.
+ */
+declare function getCallSiteRenderRate(callSiteId: string, windowMs?: number, now?: number): number;
+/**
+ * Clear all ring-buffer state. Called by the walker uninstall path so HMR
+ * rapid-reconnect cycles don't accumulate stale entries across sessions.
+ */
+declare function clearCallSiteRenders(): void;
+/**
+ * Compute a `runtime:callSiteMetrics` payload from the ring buffer — one
+ * entry per callsite that has rendered within the last `windowMs` ms (5s
+ * default). Callsites with zero recent activity are omitted so the wire-
+ * format payload stays small on idle apps.
+ *
+ * Returns `null` when no callsite has activity → caller skips the WebSocket
+ * send entirely. This is load-bearing: a 5000-callsite app with no live
+ * renders should NOT emit a 5000-entry map of zeros every second.
+ *
+ * The `now` arg lets tests inject deterministic timestamps.
+ */
+declare function computeCallSiteMetricsPayload(windowMs?: number, now?: number): Record<string, number> | null;
+/**
+ * Payload emitted whenever a JSX call site fires twice in the same commit
+ * with the same React `key`. Shape mirrors `RuntimeDuplicateKeyMessage` minus
+ * the wire-format envelope (`type` + `timestamp`) — those are added by the
+ * caller (typically `FloTraceProvider`) at WS-send time.
+ */
+interface DuplicateKeyEvent {
+    callSiteId: string;
+    fileName: string;
+    lineNumber: number;
+    columnNumber: number;
+    duplicateKey: string;
+    occurrences: number;
+}
+declare function setDuplicateKeyEmitter(emitter: ((evt: DuplicateKeyEvent) => void) | null): void;
+/**
+ * One-time boolean stored on `globalThis` under `JSX_RUNTIME_ACTIVE_KEY`. The
+ * dev jsx-runtime sets it on first `jsxDEV` call; the walker reads it to
+ * include `jsxRuntimeActive: true` on `runtime:ready` for adoption telemetry.
+ *
+ * No per-call telemetry — this is a single boolean, set once.
+ */
+declare function markJsxRuntimeActive(): void;
+declare function isJsxRuntimeActive(): boolean;
+/**
+ * Detect props that look like fresh-each-render literals — the #1 React perf
+ * footgun (an inline `onClick={() => ...}` invalidates `memo` + breaks
+ * `useEffect` dep arrays). This signal can ONLY be observed at JSX-creation
+ * time; after React commits, the prop on the fiber looks identical whether it
+ * was a literal or `useCallback`/`useMemo`'d ref.
+ *
+ * Heuristics (conservative — false-negatives are acceptable; false-positives
+ * train users to ignore the warning, so we err toward silence):
+ *
+ *   - **Functions**: only flagged when the fn has no `.name`. `useCallback`'d
+ *     fns preserve the inner fn's name, named methods are hoisted — the
+ *     anonymous-arrow case is what catches `{() => doX()}` and `{e => h(e)}`.
+ *   - **Arrays**: only non-empty arrays. `[]` literals are usually intentional
+ *     empty defaults and not a perf concern in their own right.
+ *   - **Plain objects**: detected via prototype check (`Object.prototype` or
+ *     `null` prototype). React elements (`$$typeof`), class instances, dates,
+ *     maps, sets — all skipped.
+ *
+ * Returns `undefined` when nothing is flagged, so callers can use a single
+ * truthy check before serialising.
+ */
+declare function detectInlineLiterals(props: Record<string, unknown>): Record<string, 'fn' | 'obj' | 'arr'> | undefined;
+
 /**
  * Types for @flotrace/runtime package
  * These mirror the shared types from the extension but are standalone
  * to avoid importing from the extension package.
  */
+
+/**
+ * Confidence tier for `LiveTreeNode` source attribution. Drives the
+ * OriginBadge variant in the renderer:
+ *
+ *   - `'exact'`     — JSX-runtime symbol present OR `_debugSource.fileName`
+ *                     populated (Babel JSX plugin / React 17–18 dev).
+ *   - `'inferred'`  — path resolved via the owner-chain walk or
+ *                     `_debugStack.stack` first-non-react frame (R19+).
+ *   - `'package'`   — fiber classified as framework/library; user clicks won't
+ *                     land in user code anyway.
+ *   - `'unknown'`   — no signal at any tier. Renders an amber `?` pill so the
+ *                     UI is honest about what it doesn't know.
+ */
+type SourceConfidence = 'exact' | 'inferred' | 'package' | 'unknown';
 /**
  * Serialized value for safe transmission over WebSocket
  */
@@ -26,7 +203,7 @@ type SerializedValue = null | boolean | number | string | SerializedValue[] | {
 /**
  * Messages sent from runtime to extension
  */
-type RuntimeMessage = RuntimeReadyMessage | RuntimeRenderMessage | RuntimePropsUpdateMessage | RuntimeNodePropsMessage | RuntimeZustandUpdateMessage | RuntimeReduxUpdateMessage | RuntimeRouterUpdateMessage | RuntimeContextUpdateMessage | RuntimeDisconnectMessage | RuntimeTreeSnapshotMessage | RuntimeTreeDiffMessage | RuntimeNodeHooksMessage | RuntimeNodeEffectsMessage | RuntimeDetailedRenderReasonMessage | RuntimeTimelineEventMessage | RuntimeTanStackQueryUpdateMessage | RuntimeRenderTriggerMessage | RuntimeRenderCascadeMessage | RuntimePropDrillingMessage | RuntimeActionStateMessage | RuntimeOptimisticDiffMessage | RuntimeNextjsContextMessage | RuntimeRscPayloadMessage | RuntimeHydrationEventMessage | RuntimeNetworkRequestMessage | RuntimeLocalStateCorrelationMessage | RuntimeValueTraceMessage | RuntimePongMessage;
+type RuntimeMessage = RuntimeReadyMessage | RuntimeRenderMessage | RuntimePropsUpdateMessage | RuntimeNodePropsMessage | RuntimeZustandUpdateMessage | RuntimeReduxUpdateMessage | RuntimeRouterUpdateMessage | RuntimeContextUpdateMessage | RuntimeDisconnectMessage | RuntimeTreeSnapshotMessage | RuntimeTreeDiffMessage | RuntimeNodeHooksMessage | RuntimeNodeEffectsMessage | RuntimeDetailedRenderReasonMessage | RuntimeTimelineEventMessage | RuntimeTanStackQueryUpdateMessage | RuntimeRenderTriggerMessage | RuntimeRenderCascadeMessage | RuntimePropDrillingMessage | RuntimeActionStateMessage | RuntimeOptimisticDiffMessage | RuntimeNextjsContextMessage | RuntimeRscPayloadMessage | RuntimeHydrationEventMessage | RuntimeCallSiteMetricsMessage | RuntimeDuplicateKeyMessage | RuntimeNetworkRequestMessage | RuntimeLocalStateCorrelationMessage | RuntimeValueTraceMessage | RuntimePongMessage;
 interface RuntimeReadyMessage {
     type: 'runtime:ready';
     appName?: string;
@@ -55,6 +232,14 @@ interface RuntimeReadyMessage {
      *  release script keeps runtime-core pinned identically, so a separate
      *  core-version field would be redundant. */
     runtimeVersion?: string;
+    /**
+     * Milestone 8 Phase 5 — adoption signal for the JSX-runtime opt-in
+     * (`"jsxImportSource": "@flotrace/runtime-core"`). `true` when the dev
+     * runtime's global sentinel has been set (i.e. at least one user
+     * component went through `jsxDEV`). Desktop forwards to telemetry so
+     * the admin dashboard can track rollout rate. No PII; one-time boolean.
+     */
+    jsxRuntimeActive?: boolean;
 }
 interface RuntimeRenderMessage {
     type: 'runtime:render';
@@ -226,6 +411,22 @@ interface LiveTreeNode {
     isLibrary?: boolean;
     /** Short display label for the library source (e.g. 'framer', 'fontawesome', 'sonner') */
     libraryName?: string;
+    /**
+     * Source attribution captured at JSX-creation time by the optional
+     * `@flotrace/runtime-core/jsx-dev-runtime` opt-in. Present only when the
+     * user has set `"jsxImportSource": "@flotrace/runtime-core"` in their
+     * tsconfig.json — the highest-confidence source signal available.
+     *
+     * When present, `filePath` / `lineNumber` are filled from `jsxSource` so
+     * existing consumers (click-to-IDE, breadcrumb path display) keep working
+     * without changes.
+     */
+    jsxSource?: FlotraceJsxSource;
+    /**
+     * Confidence tier of the resolved source. See `SourceConfidence` doc-comment
+     * for the four tiers and what each means for the UI.
+     */
+    sourceConfidence?: SourceConfidence;
 }
 /**
  * Enhanced render reason with specific prop/state/context changes.
@@ -460,6 +661,8 @@ interface CascadeNode {
     children: CascadeNode[];
     depth: number;
     isMemoized: boolean;
+    /** JSX-runtime attribution (Milestone 8 Phase 6) — mirror of shared LiveTreeNode field. */
+    jsxSource?: FlotraceJsxSource;
 }
 type LanePriority = 'sync' | 'discrete' | 'continuous' | 'default' | 'transition' | 'deferred' | 'idle' | 'offscreen';
 interface LaneInfo {
@@ -494,6 +697,8 @@ interface PropDrillingChainNode {
     role: 'source' | 'passthrough' | 'consumer';
     hookCount: number;
     hasContextHook: boolean;
+    /** JSX-runtime attribution (Milestone 8 Phase 6). */
+    jsxSource?: FlotraceJsxSource;
 }
 interface PropDrillingChain {
     chainId: string;
@@ -521,21 +726,27 @@ interface RuntimePropDrillingMessage {
         treeSize: number;
     };
 }
+/**
+ * State of a single useActionState / useOptimistic hook instance on a fiber.
+ * Mirror of `ActionStateEntry` in flotrace-desktop's `shared/liveMessages.ts`
+ * — keep the field set in sync.
+ */
+interface ActionStateEntry {
+    hookIndex: number;
+    hookKind: 'action' | 'optimistic';
+    isPending: boolean;
+    state: SerializedValue;
+    error?: SerializedValue;
+    pendingSince?: number;
+    durationMs?: number;
+}
 /** Sent whenever a useActionState or useOptimistic hook changes on any fiber */
 interface RuntimeActionStateMessage {
     type: 'runtime:actionState';
     nodeId: string;
     componentName: string;
     /** One entry per useActionState / useOptimistic hook on this fiber */
-    actions: Array<{
-        hookIndex: number;
-        hookKind: 'action' | 'optimistic';
-        isPending: boolean;
-        state: SerializedValue;
-        error?: SerializedValue;
-        pendingSince?: number;
-        durationMs?: number;
-    }>;
+    actions: ActionStateEntry[];
     timestamp: number;
 }
 /** Sent when a useOptimistic value diverges from its underlying actual value */
@@ -557,12 +768,17 @@ interface RuntimeNextjsContextMessage {
     initialRoute?: string;
     timestamp: number;
 }
+/**
+ * RSC / Next.js cache header status. Mirror of the union in
+ * `shared/liveMessages.ts`'s `RscPayloadEntry.cacheStatus` — keep in sync.
+ */
+type RscCacheStatus = 'HIT' | 'MISS' | 'STALE' | 'unknown';
 /** Sent when an RSC / Next.js data fetch is intercepted (metadata only, no values) */
 interface RuntimeRscPayloadMessage {
     type: 'runtime:rscPayload';
     route: string;
     payloadSizeBytes: number;
-    cacheStatus: 'HIT' | 'MISS' | 'STALE' | 'unknown';
+    cacheStatus: RscCacheStatus;
     timestamp: number;
 }
 /** Sent when React hydration completes or a mismatch is detected */
@@ -573,6 +789,48 @@ interface RuntimeHydrationEventMessage {
     errorMessage?: string;
     timestamp: number;
 }
+/**
+ * Per-callsite render frequency snapshot. Emitted at most once per second by
+ * the runtime when the JSX-runtime opt-in is active — the ring buffer in
+ * `jsxRuntimeUtils.ts` is the source of truth, this message is a periodic
+ * compaction of the buffer into "renders/sec over last 5s" so the desktop
+ * doesn't need to mirror the buffer.
+ *
+ * Independent of the React Profiler — works in concurrent rendering where the
+ * Profiler may miss commits. Only emitted when there's at least one callsite
+ * with non-zero recent activity (no metric-flood on idle apps).
+ */
+interface RuntimeCallSiteMetricsMessage {
+    type: 'runtime:callSiteMetrics';
+    /** Map of callSiteId → renders/sec over the last 5-second window. */
+    metrics: Record<string, number>;
+    timestamp: number;
+}
+/**
+ * Duplicate-key warning. Emitted by the JSX runtime when it observes the same
+ * `(callSiteId, key)` pair on two or more JSX calls within a single commit —
+ * the classic `{items.map(item => <Row key={item.id} />)}` pattern where
+ * `item.id` repeats. React logs a console warning for this; we surface it
+ * with full file:line attribution so the user can navigate directly to the
+ * map call site.
+ *
+ * One message per (callSiteId, duplicateKey) per emission window — the
+ * runtime de-duplicates so a list with 100 duplicate rows doesn't spam 100
+ * messages.
+ */
+interface RuntimeDuplicateKeyMessage {
+    type: 'runtime:duplicateKey';
+    /** The JSX call site that produced the duplicates. */
+    callSiteId: string;
+    fileName: string;
+    lineNumber: number;
+    columnNumber: number;
+    /** The key value that appeared more than once. */
+    duplicateKey: string;
+    /** How many times the same key fired at this call site in the commit. */
+    occurrences: number;
+    timestamp: number;
+}
 /** Metadata for a single intercepted network request. Privacy-first: no bodies, no query params, no auth headers. */
 interface NetworkRequestEntry {
     /** Incrementing request ID */
@@ -646,6 +904,13 @@ type TraceStep = {
     /** If this step came via a rename edge in the drilling graph. */
     renamedFrom?: string;
     confidence: TraceConfidence;
+    /**
+     * JSX-runtime attribution of the PARENT fiber that wrote the value into
+     * this prop (Milestone 8 Phase 6). Captured by `readJsxSourceFromFiber`
+     * on the ancestor at trace-resolution time. Undefined when the parent
+     * fiber lacks attribution.
+     */
+    callSiteOfParentJsx?: FlotraceJsxSource;
 } | {
     kind: 'hook-state';
     nodeId: string;
@@ -708,15 +973,12 @@ interface ValueTrace {
     steps: TraceStep[];
     /** Wall-clock time the resolver completed. */
     resolvedAtMs: number;
-    /** True when the 50ms budget tripped and the chain is partial. */
-    truncated?: boolean;
     /**
      * Optional error hint for friendly empty states.
      * - `value-not-found`: target path doesn't exist on the current fiber.
      * - `no-fiber`: nodeId no longer present in fiberRefMap (component unmounted).
-     * - `budget-exceeded`: bailed before finding origin.
      */
-    error?: 'value-not-found' | 'no-fiber' | 'budget-exceeded';
+    error?: 'value-not-found' | 'no-fiber';
 }
 interface RuntimeValueTraceMessage {
     type: 'runtime:valueTrace';
@@ -898,7 +1160,8 @@ declare const DEFAULT_CONFIG: ResolvedFloTraceConfig;
  *   2. Store match    — scan Zustand / Redux / TanStack Query live snapshots
  *   3. API match      — feed matched reference into fetchOriginRegistry WeakMap
  *
- * On-demand only — never runs per-render. Hard 50 ms wall-clock budget.
+ * On-demand only — never runs per-render. Bounded by MAX_PROP_CHAIN_DEPTH and
+ * SCAN_DEPTH structural limits; no wall-clock budget so every trace runs to origin.
  * Uses reference identity (`===`) before fingerprinting to keep common cases fast.
  *
  * See docs/PRD-VALUE-LINEAGE.md §6 and docs/IMPLEMENTATION-PLAN-VALUE-LINEAGE.md Phase 2.
@@ -1183,7 +1446,7 @@ declare function uninstallFiberTreeWalker(): void;
  *
  * Works across React 18 and 19 by probing different internal property names.
  */
-interface FiberLike {
+interface FiberLike$1 {
     type: {
         name?: string;
         displayName?: string;
@@ -1196,7 +1459,7 @@ interface FiberLike {
             displayName?: string;
         };
     } | ((...args: unknown[]) => unknown) | string | null;
-    return: FiberLike | null;
+    return: FiberLike$1 | null;
     tag: number;
 }
 /**
@@ -1206,16 +1469,16 @@ interface FiberLike {
  * Strategy 2 (React 19): __CLIENT_INTERNALS...owner field (renamed + flattened)
  * Both return the fiber currently being rendered (null between renders).
  */
-declare function getCurrentRenderingFiber(): FiberLike | null;
+declare function getCurrentRenderingFiber(): FiberLike$1 | null;
 /**
  * Extract display name from a fiber node.
  */
-declare function getComponentNameFromFiber(fiber: FiberLike): string | null;
+declare function getComponentNameFromFiber(fiber: FiberLike$1): string | null;
 /**
  * Walk up the fiber tree to build an ancestor chain of component names.
  * Stops after 10 levels to prevent excessive traversal.
  */
-declare function buildAncestorChain(fiber: FiberLike): string[];
+declare function buildAncestorChain(fiber: FiberLike$1): string[];
 
 /**
  * Hook Inspector for @flotrace/runtime
@@ -1716,4 +1979,99 @@ declare function installRscPayloadInterceptor(client: FloTraceWebSocketClient):
 /** Remove the RSC payload interceptor and restore original fetch */
 declare function uninstallRscPayloadInterceptor(): void;
 
-export { DEFAULT_CONFIG, type DetailedRenderReason, type DetailedRenderReasonType, type EffectInfo, type Fiber$1 as Fiber, type FiberEffect, type FiberHookState, type FiberTreeWalkerOptions, type FloTraceConfig, FloTraceWebSocketClient, type FrameworkInfo, type HookInfo, type HookType, type LiveTreeNode, type MutationCorrelation, type NetworkRequestEntry, type PropChange, type ReduxStoreApi, type ResolvedFloTraceConfig, type RuntimeTreeDiffMessage, type RuntimeValueTraceMessage, type SerializedValue, type TanStackMutationInfo, type TanStackQueryClientApi, type TanStackQueryEvent, type TanStackQueryInfo, type TimelineEvent, type TimelineEventType, type TraceConfidence, type TraceStep, type TrackingOptions, type ValueTrace, type ValueTraceInput, type ZustandStoreApi, buildAncestorChain, clearFetchOriginTags, detectServerComponent, detectWebFramework, disposeWebSocketClient, findFetchOrigin, getChangedKeys, getComponentNameFromFiber, getCurrentRenderingFiber, getDetailedRenderReason, getFiberRefMap, getNodeEffects, getNodeHooks, getNodeProps, getReduxSnapshot, getTanstackSnapshot, getTimeline, getWebSocketClient, getZustandSnapshot, hasActiveTags, inspectEffects, inspectHooks, installFiberTreeWalker, installReduxTracker, installRscPayloadInterceptor, installTanStackQueryTracker, installTimelineTracker, installZustandTracker, isReduxStore, isTanStackQueryClient, maybeEmitNextjsContext, recordTimelineEvent, requestFullSnapshot, requestTreeSnapshot, resetNextjsDetection, resolveValueTrace, serializeProps, serializeValue, tagFetchData, uninstallFiberTreeWalker, uninstallReduxTracker, uninstallRscPayloadInterceptor, uninstallTanStackQueryTracker, uninstallTimelineTracker, uninstallZustandTracker };
+/**
+ * Fiber debug recorder — buffers fiber + LiveTreeNode observations into
+ * capped in-memory tables, then dumps them to the console *on demand*.
+ *
+ * Why not log eagerly? `getComponentName` runs once per fiber per commit.
+ * A 200-node tree at 60Hz produces ~12k console entries/sec, which OOMs
+ * DevTools. The recorder keeps recording silent until you ask for a dump.
+ *
+ * Usage (from any console — Next.js app, FloTrace renderer, Electron main):
+ *   globalThis.__FT_DEBUG = true   // start recording
+ *   __ft.dump()                    // print digest (fibers + snapshots)
+ *   __ft.fibers()                  // just the fiber-name table
+ *   __ft.snapshots()               // just the snapshot timeline
+ *   __ft.tail(20)                  // recent activity
+ *   __ft.clear()                   // reset buffers
+ *   __ft.export()                  // returns a JSON object
+ *   __ft.download()                // browser-only: save buffers as JSON
+ *   __ft.size()                    // current buffer sizes
+ *
+ * All recorders are no-ops when __FT_DEBUG is falsy, so the wired call
+ * sites cost ~1 boolean check each.
+ */
+
+interface FiberRecord {
+    /** Resolved component name (what FloTrace ultimately shows on the node). */
+    name: string;
+    /** Raw `fiber.type.name` — present even for ForwardRef/Memo's inner render. */
+    rawName: string | undefined;
+    /** Raw `fiber.type.displayName` — what the author explicitly set. */
+    rawDisplayName: string | undefined;
+    kind: 'function' | 'class' | 'forwardRef' | 'memo' | 'host' | 'unknown';
+    /** Fiber tag number (0=Function, 1=Class, 11=ForwardRef, 14=Memo, etc.). */
+    fiberTag: number | undefined;
+    looksMinified: boolean;
+    count: number;
+    contexts: Set<string>;
+    firstSeen: number;
+    lastSeen: number;
+    /** First captured _debugSource (if any) — only available in dev builds. */
+    source?: {
+        fileName?: string;
+        lineNumber?: number;
+    };
+    /** First non-null react key observed (useful for diagnosing list rows). */
+    exampleKey?: string;
+}
+interface TreeRecord {
+    ts: number;
+    ctx: string;
+    rootName: string;
+    totalNodes: number;
+    maxDepth: number;
+    minifiedLike: number;
+    topNames: string;
+}
+declare global {
+    var __FT_DEBUG: boolean | undefined;
+    var __ft: FtConsoleApi | undefined;
+}
+declare function setFiberDebug(enabled: boolean): void;
+type FiberLike = {
+    tag?: number;
+    type?: unknown;
+    key?: string | null;
+    _debugSource?: {
+        fileName?: string;
+        lineNumber?: number;
+    } | null;
+};
+declare function describeFiberType(fiber: FiberLike): {
+    kind: FiberRecord['kind'];
+    name: string | undefined;
+    displayName: string | undefined;
+    resolved: string;
+    looksMinified: boolean;
+};
+declare function logTreeSnapshot(tree: LiveTreeNode | null, context?: string): void;
+declare const logTreeSummary: typeof logTreeSnapshot;
+interface FtConsoleApi {
+    dump(): void;
+    fibers(): void;
+    snapshots(): void;
+    tail(n?: number): void;
+    clear(): void;
+    size(): {
+        fibers: number;
+        snapshots: number;
+    };
+    export(): {
+        fibers: Array<Record<string, unknown>>;
+        snapshots: TreeRecord[];
+    };
+    download(filename?: string): void;
+}
+
+export { type ActionStateEntry, DEFAULT_CONFIG, type DetailedRenderReason, type DetailedRenderReasonType, type DuplicateKeyEvent, type EffectInfo, FLOTRACE_SOURCE, type Fiber$1 as Fiber, type FiberEffect, type FiberHookState, type FiberTreeWalkerOptions, type FloTraceConfig, FloTraceWebSocketClient, type FlotraceJsxSource, type FrameworkInfo, type HookInfo, type HookType, JSX_RUNTIME_ACTIVE_KEY, type LiveTreeNode, type MutationCorrelation, type NetworkRequestEntry, type PropChange, type ReduxStoreApi, type ResolvedFloTraceConfig, type RscCacheStatus, type RuntimeActionStateMessage, type RuntimeCallSiteMetricsMessage, type RuntimeDuplicateKeyMessage, type RuntimeHydrationEventMessage, type RuntimeNextjsContextMessage, type RuntimeOptimisticDiffMessage, type RuntimeRscPayloadMessage, type RuntimeTreeDiffMessage, type RuntimeValueTraceMessage, type SerializedValue, type SourceConfidence, type TanStackMutationInfo, type TanStackQueryClientApi, type TanStackQueryEvent, type TanStackQueryInfo, type TimelineEvent, type TimelineEventType, type TraceConfidence, type TraceStep, type TrackingOptions, type ValueTrace, type ValueTraceInput, type ZustandStoreApi, buildAncestorChain, clearCallSiteRenders, clearFetchOriginTags, computeCallSiteId, computeCallSiteMetricsPayload, describeFiberType, detectInlineLiterals, detectServerComponent, detectWebFramework, disposeWebSocketClient, findFetchOrigin, getCallSiteRenderRate, getCallSiteRenders, getChangedKeys, getComponentNameFromFiber, getCurrentRenderingFiber, getDetailedRenderReason, getFiberRefMap, getNodeEffects, getNodeHooks, getNodeProps, getReduxSnapshot, getTanstackSnapshot, getTimeline, getWebSocketClient, getZustandSnapshot, hasActiveTags, inspectEffects, inspectHooks, installFiberTreeWalker, installReduxTracker, installRscPayloadInterceptor, installTanStackQueryTracker, installTimelineTracker, installZustandTracker, isJsxRuntimeActive, isReduxStore, isTanStackQueryClient, logTreeSnapshot, logTreeSummary, markJsxRuntimeActive, maybeEmitNextjsContext, normalizeJsxSourcePath, recordCallSiteRender, recordTimelineEvent, requestFullSnapshot, requestTreeSnapshot, resetNextjsDetection, resolveValueTrace, serializeProps, serializeValue, setDuplicateKeyEmitter, setFiberDebug, tagFetchData, uninstallFiberTreeWalker, uninstallReduxTracker, uninstallRscPayloadInterceptor, uninstallTanStackQueryTracker, uninstallTimelineTracker, uninstallZustandTracker };