@agent-scope/runtime 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { ComponentType, ComponentNode, PageReport, ConsoleEntry, CapturedError, HookState, SuspenseBoundaryInfo } from '@agent-scope/core';
+export { CapturedError, ComponentNode, PageReport, SuspenseBoundaryInfo } from '@agent-scope/core';
+
+/**
+ * devtools-hook.ts
+ *
+ * Installs and manages the React DevTools global hook
+ * (`window.__REACT_DEVTOOLS_GLOBAL_HOOK__`).
+ *
+ * React checks for this hook at module initialisation time, so it MUST be
+ * installed before any React bundle is evaluated.  Call `installHook()` as
+ * early as possible (e.g. the very first script on the page).
+ */
+/**
+ * Minimal shape of a React renderer as surfaced through the DevTools hook.
+ *
+ * React passes a much larger object; we only reference the fields we need.
+ */
+interface ReactRenderer {
+    /** Opaque renderer ID assigned by the hook on injection. */
+    id: number;
+    /** The renderer object passed by React via `inject()`. */
+    renderer: any;
+    /** Set of fiber root containers managed by this renderer. */
+    fiberRoots: Set<any>;
+}
+/**
+ * The shape we install at `window.__REACT_DEVTOOLS_GLOBAL_HOOK__`.
+ *
+ * React calls `inject(renderer)` when it boots, giving us access to its
+ * internal fiber roots.  Everything else is just enough scaffolding to keep
+ * React happy.
+ */
+interface ScopeDevToolsHook {
+    /** Required by React – signals that DevTools are present. */
+    isDisabled: false;
+    /** Required by React – signals DevTools support for profiling. */
+    supportsFiber: true;
+    /**
+     * Called by React when it initialises a new renderer instance.
+     * Returns the renderer's numeric ID.
+     */
+    inject(renderer: unknown): number;
+    /** Called by React before each commit (we no-op this). */
+    onCommitFiberRoot(rendererID: number, root: unknown, priorityLevel: unknown): void;
+    /** Called by React when an unmount occurs (we no-op this). */
+    onCommitFiberUnmount(rendererID: number, fiber: unknown): void;
+    /** Called by React before post-commit effects (we no-op this). */
+    onPostCommitFiberRoot(rendererID: number, root: unknown): void;
+    /** Extension point: registered renderers keyed by ID. */
+    _renderers: Map<number, ReactRenderer>;
+    /** Whether the hook was installed by Scope (vs. pre-existing DevTools). */
+    _isScopeHook: true;
+}
+/**
+ * Install the Scope DevTools hook at `window.__REACT_DEVTOOLS_GLOBAL_HOOK__`.
+ *
+ * - If no hook exists yet, installs a new Scope hook.
+ * - If a Scope hook is already installed, returns the existing instance.
+ * - If a *third-party* hook is already present (e.g. real React DevTools),
+ *   we patch it minimally so that renderer registrations are forwarded to us
+ *   as well.
+ *
+ * Must be called **before React is loaded** to intercept `inject()`.
+ */
+declare function installHook(): ScopeDevToolsHook;
+/**
+ * Retrieve the currently installed hook.
+ *
+ * Returns `null` if `installHook()` has not yet been called.
+ */
+declare function getHook(): ScopeDevToolsHook | null;
+/**
+ * Return a snapshot of all registered React renderers.
+ *
+ * Empty until React calls `inject()`.
+ */
+declare function getRenderers(): ReactRenderer[];
+/**
+ * Wait until at least one React renderer has registered with the hook.
+ *
+ * @param timeout - Maximum milliseconds to wait (default: 10 000).
+ * @returns A promise that resolves with the first registered renderer.
+ * @throws If the timeout elapses with no renderer.
+ */
+declare function waitForReact(timeout?: number): Promise<ReactRenderer>;
+
+/**
+ * fiber-walker.ts
+ *
+ * Traverses a React fiber tree and converts it into the `ComponentNode` tree
+ * defined in `@agent-scope/core`.
+ *
+ * Fiber internals are undocumented React implementation details.  We rely on:
+ *   - `fiber.tag`           — type classifier (see FIBER_TAGS below)
+ *   - `fiber.type`          — function/class reference or string for host elements
+ *   - `fiber.memoizedProps` — current props snapshot
+ *   - `fiber.child`         — first child fiber
+ *   - `fiber.sibling`       — next sibling fiber
+ *   - `fiber._debugSource`  — source location injected by babel (dev only)
+ *   - `fiber._debugID`      — internal numeric ID (dev only, may be absent)
+ *   - `fiber.index`         — position among siblings
+ */
+
+/**
+ * Minimal shape of a React fiber as accessed by this walker.
+ * Only the fields we actually read are declared here.
+ */
+interface Fiber {
+    tag: number;
+    type: any;
+    memoizedProps: Record<string, any> | null;
+    child: Fiber | null;
+    sibling: Fiber | null;
+    return: Fiber | null;
+    /** Present in React dev builds (>=16). Numeric per-session fiber ID. */
+    _debugID?: number;
+    /** Position among siblings (0-based). Used as fallback ID. */
+    index: number;
+    /** Injected by `babel-plugin-transform-react-jsx-source` (dev only). */
+    _debugSource?: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber: number;
+    } | null;
+    [key: string]: any;
+}
+interface WalkOptions {
+    /**
+     * When `true`, host elements (div, span, etc.) are included in the output.
+     * Default: `false`.
+     */
+    includeHostElements?: boolean;
+}
+/**
+ * Derive the display name from a fiber's `type` field.
+ *
+ * Resolution order:
+ *  1. `type.displayName`
+ *  2. `type.name` (function/class name — unless inferred from a property key)
+ *  3. For forwardRef wrappers: inner `render.displayName` / `render.name`
+ *  4. For memo wrappers: inner `type.displayName` / `type.name`
+ *  5. String tags for host elements ("div", "span", …)
+ *  6. Fallback: "Anonymous"
+ */
+declare function extractName(fiber: Fiber): string;
+/**
+ * Map a fiber tag (and optionally the `type` object's `$$typeof`) to one of
+ * our `ComponentType` discriminants.
+ */
+declare function classifyType(fiber: Fiber): ComponentType;
+/**
+ * Walk a fiber and all its descendants, collecting `ComponentNode`s.
+ *
+ * @param rootFiber - The starting fiber.
+ * @param options   - Walk configuration.
+ * @returns The `ComponentNode` for `rootFiber`, or `null` if the root should
+ *          be skipped.  Children are populated recursively.
+ */
+declare function walkFiber(fiber: Fiber | null, options?: WalkOptions): ComponentNode | null;
+/**
+ * Walk a fiber root (the object stored in `ReactRenderer.fiberRoots`) and
+ * return the root `ComponentNode`, or `null` if the tree is empty.
+ *
+ * `fiberRoot.current` is the `HostRoot` fiber — we skip it and return the
+ * first meaningful child.
+ */
+declare function walkFiberRoot(fiberRoot: any, options?: WalkOptions): ComponentNode | null;
+
+/**
+ * capture.ts
+ *
+ * High-level `capture()` function — wires together the DevTools hook and fiber
+ * walker to produce a partial `PageReport`.
+ */
+
+interface CaptureOptions extends WalkOptions {
+    /**
+     * URL to record in the report.
+     * Defaults to `window.location.href` in a browser context.
+     */
+    url?: string;
+    /**
+     * Timeout in milliseconds to wait for React to boot before giving up.
+     * Default: 10 000.
+     */
+    reactTimeout?: number;
+}
+/** The fields populated by `capture()`.  The rest can be added by callers. */
+type CaptureResult = Pick<PageReport, "url" | "timestamp" | "capturedIn" | "tree" | "consoleEntries" | "errors" | "suspenseBoundaries">;
+/**
+ * Capture a snapshot of the current React component tree.
+ *
+ * Ensures the DevTools hook is installed, waits for React to register a
+ * renderer (if it hasn't already), then walks the first available fiber root.
+ *
+ * Console messages emitted during the capture window are recorded via the
+ * console interceptor and included in the returned `consoleEntries` field.
+ *
+ * Also detects error boundaries that have caught errors and Suspense
+ * boundaries with their current suspension status.
+ *
+ * @returns A partial `PageReport` containing `url`, `timestamp`, `capturedIn`,
+ *          `tree`, `consoleEntries`, `errors`, and `suspenseBoundaries`.
+ * @throws  If no React renderer registers within `reactTimeout` ms, or if the
+ *          fiber tree is empty.
+ */
+declare function capture(options?: CaptureOptions): Promise<CaptureResult>;
+
+/**
+ * console-interceptor.ts
+ *
+ * Monkey-patches `console.log`, `console.warn`, `console.error`,
+ * `console.info`, `console.debug`, `console.group`, `console.groupCollapsed`,
+ * `console.table`, and `console.trace` to capture messages with React
+ * component attribution.
+ *
+ * Component attribution is resolved by reading the DevTools hook's
+ * currently-active fiber (set during React render).  When no fiber is active
+ * (effect, event handler, async callback) `componentName` is `null`.
+ *
+ * The interceptor never suppresses output — every patched method calls the
+ * original implementation with all original arguments.
+ */
+
+/**
+ * Install the console interceptor.
+ *
+ * Replaces `console.log`, `console.warn`, `console.error`, `console.info`,
+ * `console.debug`, `console.group`, `console.groupCollapsed`, `console.table`,
+ * and `console.trace` with wrappers that record entries.
+ *
+ * Idempotent — calling `install` twice without `uninstall` in between is safe.
+ */
+declare function installConsoleInterceptor(): void;
+/**
+ * Uninstall the console interceptor and restore all original methods.
+ *
+ * Idempotent — safe to call even if the interceptor is not installed.
+ */
+declare function uninstallConsoleInterceptor(): void;
+/**
+ * Return a snapshot of all captured `ConsoleEntry` objects since the last
+ * `clearConsoleEntries()` call (or since install).
+ *
+ * The returned array is a shallow copy — mutations do not affect the buffer.
+ */
+declare function getConsoleEntries(): ConsoleEntry[];
+/**
+ * Clear the captured entries buffer.
+ */
+declare function clearConsoleEntries(): void;
+
+/**
+ * error-detector.ts
+ *
+ * Detects React error boundaries in the fiber tree and extracts information
+ * about any errors they have caught.
+ *
+ * React error boundaries are class components that implement at least one of:
+ *   - `static getDerivedStateFromError(error)` — static method
+ *   - `componentDidCatch(error, info)`          — instance method
+ *
+ * When a boundary has caught an error, React stores error info in the fiber's
+ * `memoizedState` (the current component state snapshot).  Common patterns:
+ *   - `{ hasError: true, error: Error }` (class-level state)
+ *   - `{ error: Error }` (minimal pattern)
+ *
+ * We walk the fiber tree, identify boundary components, inspect their state,
+ * and build `CapturedError` objects when an error is present.
+ */
+
+/**
+ * Walk the fiber tree depth-first and collect `CapturedError` entries for
+ * every error boundary that is currently holding a caught error.
+ *
+ * @param rootFiber - Top of the fiber tree (typically `HostRoot.child`).
+ * @returns Array of `CapturedError` objects; empty when nothing has been caught.
+ */
+declare function detectErrors(rootFiber: Fiber | null): CapturedError[];
+
+/**
+ * hooks-extractor.ts
+ *
+ * Extracts `HookState[]` from a React fiber's `memoizedState` linked list.
+ *
+ * React stores hooks as a singly-linked list where each node has:
+ *   - `memoizedState` — the hook's stored value (shape varies by hook type)
+ *   - `queue`         — update queue present on useState / useReducer
+ *   - `next`          — pointer to the next hook node in call order
+ *
+ * Hook types are NOT tagged by React, so we identify them by inspecting the
+ * shape of each node (duck-typing).  The heuristics below mirror the internal
+ * structure documented in React's source (ReactFiberHooks.js).
+ *
+ * @internal
+ */
+
+/**
+ * Extract an ordered list of `HookState` snapshots from a fiber's
+ * `memoizedState` linked list.
+ *
+ * @param fiber - A React fiber object (typed as `any` because React doesn't
+ *                export its internal fiber shape).
+ * @returns     An ordered array of `HookState` entries (one per hook call),
+ *              or an empty array if the fiber has no hooks or is null.
+ */
+declare function extractHooks(fiber: any): HookState[];
+
+/**
+ * profiler.ts
+ *
+ * Instruments React's commit cycle to capture per-component render timing data.
+ *
+ * React exposes profiling data on fiber objects in development/profiling builds:
+ *   - `fiber.actualDuration`    — wall-clock ms spent rendering this fiber + descendants
+ *   - `fiber.selfBaseDuration`  — ms spent rendering just this fiber (excl. children)
+ *   - `fiber.actualStartTime`   — performance.now() timestamp when render began
+ *
+ * We hook into `onCommitFiberRoot` on the DevTools hook to intercept every
+ * commit, walk the work-in-progress subtree, and accumulate counts + durations
+ * keyed by fiber identity.
+ */
+
+/** Public snapshot returned by `getProfilingData`. */
+interface ProfilingSnapshot {
+    renderCount: number;
+    renderDuration: number;
+}
+/**
+ * Install the profiler onto a DevTools hook.
+ *
+ * Wraps `hook.onCommitFiberRoot` so that every React commit triggers a walk
+ * of the committed fiber subtree to accumulate profiling data.
+ *
+ * Safe to call multiple times — subsequent calls on the same hook are no-ops.
+ */
+declare function installProfiler(hook: ScopeDevToolsHook): void;
+/**
+ * Retrieve the accumulated profiling snapshot for a fiber by its numeric ID.
+ *
+ * @param fiberId - The fiber's `_debugID` (or synthetic ID assigned by this module).
+ * @returns `{ renderCount, renderDuration }` if data exists, `null` otherwise.
+ */
+declare function getProfilingData(fiberIdParam: number): ProfilingSnapshot | null;
+/**
+ * Reset all accumulated profiling data and the installed state.
+ *
+ * Primarily used in tests and when re-initialising the capture session.
+ * Note: this does NOT restore the original `onCommitFiberRoot` handler —
+ * call `installProfiler` again on a fresh hook after resetting.
+ */
+declare function resetProfilingData(): void;
+
+/**
+ * suspense-detector.ts
+ *
+ * Detects `<Suspense>` boundaries in the fiber tree and determines their
+ * current status at capture time.
+ *
+ * React stores Suspense state in the fiber's `memoizedState` field using an
+ * internal linked-list structure.  The first node in the list is the dehydrated
+ * / retrying state object when the boundary is suspended.
+ *
+ * Status heuristics (based on React internals):
+ *
+ *   resolved  — `memoizedState === null`
+ *               The boundary rendered its normal children successfully.
+ *
+ *   pending   — `memoizedState.dehydrated` is set, OR the state object
+ *               contains a thenable (`then` function) anywhere at the top
+ *               level, indicating React is still waiting for data.
+ *
+ *   fallback  — `memoizedState` is non-null but does not look like a pending
+ *               thenable; the fallback subtree is being rendered.  This covers
+ *               the case where the promise has been thrown but not yet
+ *               resolved, and React is showing the fallback UI.
+ *
+ * Note: these are approximations over undocumented internals.  React does not
+ * expose a public API for querying Suspense status from outside the component.
+ */
+
+/**
+ * Walk the fiber tree and collect `SuspenseBoundaryInfo` for every
+ * `<Suspense>` boundary found.
+ *
+ * @param rootFiber - Starting fiber (typically the HostRoot's first child).
+ * @returns Flat list of Suspense boundary descriptors.
+ */
+declare function detectSuspenseBoundaries(rootFiber: Fiber | null): SuspenseBoundaryInfo[];
+
+/**
+ * @agent-scope/runtime
+ *
+ * Browser instrumentation — captures React component trees at runtime.
+ * Depends on @agent-scope/core for types.
+ *
+ * @packageDocumentation
+ */
+
+/** Options for initializing the Scope runtime */
+interface RuntimeOptions {
+    /** Called whenever a new PageReport is captured */
+    onCapture?: (report: PageReport) => void;
+    /** Maximum number of reports to buffer before evicting the oldest */
+    bufferSize?: number;
+}
+/** Manages an active capture session */
+declare class ScopeRuntime {
+    private readonly buffer;
+    private readonly options;
+    constructor(options?: RuntimeOptions);
+    /** Record a captured PageReport */
+    record(report: PageReport): void;
+    /** Return all buffered reports and clear the buffer */
+    flush(): PageReport[];
+    /** Return a read-only snapshot of the buffer */
+    getBuffer(): readonly PageReport[];
+    /** Find a node by fiber ID within a component tree */
+    static findNode(root: ComponentNode, id: number): ComponentNode | null;
+}
+/** Create and return a new ScopeRuntime instance */
+declare function createRuntime(options?: RuntimeOptions): ScopeRuntime;
+
+export { type CaptureOptions, type CaptureResult, type Fiber, type ProfilingSnapshot, type ReactRenderer, type RuntimeOptions, type ScopeDevToolsHook, ScopeRuntime, type WalkOptions, capture, classifyType, clearConsoleEntries, createRuntime, detectErrors, detectSuspenseBoundaries, extractHooks, extractName, getConsoleEntries, getHook, getProfilingData, getRenderers, installConsoleInterceptor, installHook, installProfiler, resetProfilingData, uninstallConsoleInterceptor, waitForReact, walkFiber, walkFiberRoot };