@agent-scope/core 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,633 @@
+/**
+ * All primitive and structural JavaScript value types that can appear in a
+ * serialized value payload.
+ *
+ * - `'truncated'` — The value was too large / deeply nested and was cut off.
+ * - `'circular'`  — A circular reference was detected at this position.
+ */
+type SerializedValueType = "string" | "number" | "boolean" | "null" | "undefined" | "object" | "array" | "function" | "symbol" | "bigint" | "date" | "map" | "set" | "circular" | "truncated";
+/**
+ * A safely-serialized snapshot of a JavaScript value.
+ *
+ * Because arbitrary React props and state can reference non-serializable
+ * objects (functions, symbols, circular graphs, etc.), every value crossing
+ * the wire is wrapped in this envelope.
+ *
+ * @example
+ * // A plain string
+ * { type: 'string', value: 'hello', preview: '"hello"' }
+ *
+ * @example
+ * // A truncated object
+ * { type: 'truncated', preview: '{ a: 1, b: 2, … }' }
+ */
+interface SerializedValue {
+    /** Discriminant describing the original JavaScript type. */
+    type: SerializedValueType;
+    /**
+     * The actual value, only present for primitives and simple composites that
+     * can be round-tripped through JSON without loss.
+     *
+     * For types where `value` is absent (`function`, `symbol`, `circular`,
+     * `truncated`), rely on `preview` instead.
+     */
+    value?: unknown;
+    /**
+     * A human-readable string representation suitable for display in DevTools.
+     *
+     * Always present when `value` is absent; optional (but encouraged) for
+     * primitive types so that tooling can render without extra formatting.
+     */
+    preview?: string;
+}
+
+/**
+ * Describes a single React context consumed by a component.
+ *
+ * Recorded for every `React.createContext` context that a component reads
+ * during render, including both `useContext` and legacy `contextType`.
+ */
+interface ContextConsumption {
+    /**
+     * The `displayName` set on the context object via
+     * `MyContext.displayName = 'MyContext'`.
+     *
+     * `null` when the context was not given a display name (unfortunately
+     * common with anonymous or library-authored contexts).
+     */
+    contextName: string | null;
+    /**
+     * A serialized snapshot of the context value at the time of capture.
+     *
+     * Reflects the value provided by the nearest `<Context.Provider>` ancestor,
+     * or the default value from `React.createContext(defaultValue)` when no
+     * provider is present.
+     */
+    value: SerializedValue;
+    /**
+     * Whether this context consumption triggered a re-render of the component
+     * during the capture window (i.e. the value changed between the previous
+     * and current render).
+     */
+    didTriggerRender: boolean;
+}
+
+/**
+ * All React hook types tracked by the Scope runtime.
+ *
+ * Built-in hooks are listed by their canonical name.  Any hook whose name
+ * could not be identified (or a third-party hook not in this list) maps to
+ * `'custom'`.
+ */
+type HookType = "useState" | "useReducer" | "useEffect" | "useLayoutEffect" | "useMemo" | "useCallback" | "useRef" | "useContext" | "useId" | "useSyncExternalStore" | "useTransition" | "useDeferredValue" | "custom";
+/**
+ * A snapshot of a single hook slot recorded for a component during a render.
+ *
+ * Hook slots are ordered by call order within the component function body.
+ * The combination of component ID + hook index is stable across renders as
+ * long as the rules of hooks are respected.
+ */
+interface HookState {
+    /**
+     * The type of hook.  `'custom'` is used for third-party or project-local
+     * hooks that wrap one or more built-in hooks.
+     */
+    type: HookType;
+    /**
+     * The inferred name of a custom hook, e.g. `"useTheme"` or `"useLocalStorage"`.
+     *
+     * `null` for built-in hooks where the name is already conveyed by `type`.
+     */
+    name: string | null;
+    /**
+     * Serialized snapshot of the hook's current value.
+     *
+     * - For `useState` / `useReducer`: the current state value.
+     * - For `useMemo` / `useCallback`: the memoized value / function reference.
+     * - For `useRef`: the current `.current` value.
+     * - For `useContext`: the current context value (mirrored in `ContextConsumption`).
+     * - For effect hooks and others: typically `undefined` (no meaningful value).
+     */
+    value: SerializedValue;
+    /**
+     * Serialized snapshot of the hook's dependency array.
+     *
+     * Present for `useEffect`, `useLayoutEffect`, `useMemo`, `useCallback`,
+     * and `useSyncExternalStore`.  `null` for hooks that do not accept deps.
+     */
+    deps: SerializedValue[] | null;
+    /**
+     * Whether the effect hook registered a cleanup function on its last run.
+     *
+     * `true`  — a cleanup was returned.
+     * `false` — no cleanup (the effect returned `undefined` or `void`).
+     * `null`  — not applicable (non-effect hook or cleanup state unknown).
+     */
+    hasCleanup: boolean | null;
+}
+
+/**
+ * Source location information pointing back to the original source file.
+ *
+ * Populated from React's `__source` prop (injected by the React JSX transform
+ * when `development` mode is enabled) or from babel-plugin-transform-react-jsx-source.
+ */
+interface SourceLocation {
+    /** Absolute or relative path to the source file. */
+    fileName: string;
+    /** 1-based line number of the JSX element. */
+    lineNumber: number;
+    /** 1-based column number of the JSX element. */
+    columnNumber: number;
+}
+
+/**
+ * The React component implementation strategy.
+ *
+ * - `'function'`     — Standard function component.
+ * - `'class'`        — Class component extending `React.Component` or `React.PureComponent`.
+ * - `'forward_ref'`  — Component wrapped with `React.forwardRef`.
+ * - `'memo'`         — Component wrapped with `React.memo` (may also be `forward_ref` inside).
+ * - `'host'`         — A host (DOM / native) element such as `<div>` or `<input>`.
+ */
+type ComponentType = "function" | "class" | "forward_ref" | "memo" | "host";
+/**
+ * A node in the captured React component tree.
+ *
+ * Each `ComponentNode` corresponds to a single React fiber at the time of
+ * capture.  The tree is a depth-first snapshot; fiber siblings are siblings
+ * in `children`.
+ *
+ * @remarks
+ * Host elements (type `'host'`) still appear in the tree so consumers have a
+ * full structural picture, but their `state`, `context`, and `source` fields
+ * are typically empty.
+ */
+interface ComponentNode {
+    /**
+     * The React fiber's internal numeric ID.  Stable for the lifetime of a
+     * mounted component; reused after unmount.
+     */
+    id: number;
+    /**
+     * The resolved display name of the component.
+     *
+     * Resolution order:
+     * 1. `Component.displayName`
+     * 2. `Component.name` (function/class name)
+     * 3. The JSX tag name for host elements (e.g. `"div"`)
+     * 4. `"Anonymous"` as a last resort
+     */
+    name: string;
+    /**
+     * Implementation strategy of the component.
+     * @see {@link ComponentType}
+     */
+    type: ComponentType;
+    /**
+     * Source location of the component definition, derived from babel's
+     * `__source` prop or the DevTools fiber source data.
+     *
+     * `null` for host elements and in production builds where source maps are
+     * stripped.
+     */
+    source: SourceLocation | null;
+    /**
+     * Serialized snapshot of the component's props at the time of capture.
+     *
+     * For host elements this reflects the element's HTML attributes / React
+     * props.  Children are included as a serialized value (not expanded into
+     * sub-nodes; the tree already encodes the hierarchy via `children`).
+     */
+    props: SerializedValue;
+    /**
+     * Ordered list of hook slots recorded for this component.
+     *
+     * Ordered by hook call-order (i.e. slot 0 = first `use*` call in the
+     * component body).  Empty for class components and host elements.
+     */
+    state: HookState[];
+    /**
+     * All React contexts consumed by this component during the capture window.
+     */
+    context: ContextConsumption[];
+    /**
+     * Number of times this component rendered during the capture window.
+     *
+     * A value of `1` is expected for a fresh mount; values > 1 indicate
+     * re-renders within the window (useful for surfacing performance issues).
+     */
+    renderCount: number;
+    /**
+     * Total wall-clock time in milliseconds spent in this component's render
+     * across all renders recorded in `renderCount`.
+     *
+     * Measured from the start of the fiber's `beginWork` to the end of
+     * `completeWork`.  Does not include child render time.
+     */
+    renderDuration: number;
+    /**
+     * Ordered list of child component nodes.
+     *
+     * Depth-first; an empty array means the component is a leaf node.
+     */
+    children: ComponentNode[];
+}
+
+/**
+ * The console method level of a captured console call.
+ */
+type ConsoleLevel = "log" | "warn" | "error" | "info" | "debug" | "group" | "groupCollapsed" | "table" | "trace";
+/**
+ * A single intercepted `console.*` call recorded during the capture window.
+ */
+interface ConsoleEntry {
+    /**
+     * The console method that was called, e.g. `"warn"`, `"error"`, `"log"`.
+     */
+    level: ConsoleLevel;
+    /**
+     * Serialized snapshot of each argument passed to the console method.
+     *
+     * Arguments are captured in order.  Large or circular values are
+     * represented with `SerializedValue.type === 'truncated' | 'circular'`.
+     */
+    args: SerializedValue[];
+    /**
+     * Unix timestamp (milliseconds) when this console call occurred.
+     */
+    timestamp: number;
+    /**
+     * The display name of the nearest React component on the call-stack at the
+     * time of the console call, if it could be attributed.
+     *
+     * `null` when attribution is unavailable (e.g. called outside a render).
+     */
+    componentName: string | null;
+    /**
+     * A condensed single-line text preview built from the raw arguments, useful
+     * for quick rendering in lists.
+     */
+    preview: string;
+}
+
+/**
+ * Semantic version of the `PageReport` schema.
+ *
+ * Consumers should compare this value when reading stored reports to detect
+ * schema drift.  Follows semver: breaking changes bump the major version.
+ */
+declare const SCHEMA_VERSION: "0.1.0";
+/**
+ * All valid React hook types tracked by the Scope runtime.
+ *
+ * @see {@link HookType}
+ */
+declare const HOOK_TYPES: readonly HookType[];
+/**
+ * All valid component implementation strategies.
+ *
+ * @see {@link ComponentType}
+ */
+declare const COMPONENT_TYPES: readonly ComponentType[];
+/**
+ * All valid serialized value types.
+ *
+ * @see {@link SerializedValueType}
+ */
+declare const SERIALIZED_VALUE_TYPES: readonly SerializedValueType[];
+/**
+ * All valid console entry levels.
+ *
+ * @see {@link ConsoleLevel}
+ */
+declare const CONSOLE_LEVELS: readonly ConsoleLevel[];
+
+/**
+ * A JavaScript error captured during the page report window.
+ *
+ * Covers both unhandled exceptions (`window.onerror` / `unhandledrejection`)
+ * and errors thrown inside React error boundaries.
+ */
+interface CapturedError {
+    /**
+     * The error message string, taken from `Error.prototype.message` when
+     * available, or the string-coerced thrown value otherwise.
+     */
+    message: string;
+    /**
+     * The error constructor name, e.g. `"TypeError"`, `"RangeError"`, or the
+     * name of a custom subclass.  `"Error"` for plain `new Error(…)`.
+     */
+    name: string;
+    /**
+     * The raw stack trace string as provided by the runtime.
+     *
+     * Source-mapped frames are NOT performed here; consumers that need mapped
+     * stacks should apply a source-map transform at analysis time.
+     *
+     * `null` when the thrown value was not an `Error` instance or the runtime
+     * did not provide a stack.
+     */
+    stack: string | null;
+    /**
+     * Source location pointing to where the error was thrown, derived from the
+     * top frame of `stack` when parseable.  `null` otherwise.
+     */
+    source: SourceLocation | null;
+    /**
+     * The display name of the nearest React component in whose render / effect
+     * the error originated, if it could be attributed.
+     */
+    componentName: string | null;
+    /**
+     * Unix timestamp (milliseconds) at the moment the error was observed.
+     */
+    timestamp: number;
+    /**
+     * How the error was captured.
+     *
+     * - `'boundary'`   — caught by a React ErrorBoundary
+     * - `'unhandled'`  — surfaced via `window.onerror`
+     * - `'rejection'`  — surfaced via `window.onunhandledrejection`
+     * - `'console'`    — passed to `console.error` directly
+     */
+    capturedBy: "boundary" | "unhandled" | "rejection" | "console";
+}
+
+/**
+ * Routing information extracted from the active URL at the time the page
+ * report was captured.
+ *
+ * Framework-specific adapters (Next.js, React Router, TanStack Router, etc.)
+ * should fill in as many fields as they can resolve; unknown fields are `null`.
+ */
+interface RouteInfo {
+    /**
+     * The matched route pattern, e.g. `/users/:id` or `/blog/[slug]`.
+     *
+     * `null` when the framework could not identify a named route for the
+     * current URL.
+     */
+    pattern: string | null;
+    /**
+     * Extracted route parameters, e.g. `{ id: '42' }`.
+     *
+     * `null` when no dynamic segments are present or the adapter cannot
+     * resolve them.
+     */
+    params: Record<string, string> | null;
+    /**
+     * Parsed query-string entries at the time of capture.
+     *
+     * Keys map to the *first* occurrence of each parameter name.  Use the raw
+     * `url` on the parent `PageReport` for full fidelity.
+     */
+    query: Record<string, string>;
+    /**
+     * The name of the route as defined in the router configuration, if any.
+     * Useful for grouping reports by named route in analytics.
+     */
+    name: string | null;
+}
+
+/**
+ * Information about a single `<Suspense>` boundary observed in the component
+ * tree at capture time.
+ */
+interface SuspenseBoundaryInfo {
+    /**
+     * Stable numeric identifier for this boundary, corresponding to the React
+     * fiber's internal ID.
+     */
+    id: number;
+    /**
+     * Display name of the component that rendered this `<Suspense>` boundary.
+     *
+     * When the boundary is rendered inline (not wrapped), this will be the name
+     * of the nearest named ancestor component.
+     */
+    componentName: string;
+    /**
+     * Whether the boundary was in a suspended (loading) state at the moment the
+     * report was captured.
+     */
+    isSuspended: boolean;
+    /**
+     * Total wall-clock time in milliseconds that this boundary spent in the
+     * suspended state during the capture window.
+     *
+     * `null` when the boundary was never triggered or timing data is unavailable.
+     */
+    suspendedDuration: number | null;
+    /**
+     * Name of the fallback component or element rendered while suspended.
+     *
+     * `null` when the fallback is `null` / not identifiable.
+     */
+    fallbackName: string | null;
+    /**
+     * Source location of the `<Suspense>` element in the original source.
+     */
+    source: SourceLocation | null;
+}
+
+/**
+ * A complete snapshot of a React application page at a single point in time.
+ *
+ * `PageReport` is the top-level transport and storage unit for Scope.  Every
+ * other type in `@agent-scope/core` is a node or sub-node of this structure.
+ *
+ * @example
+ * ```ts
+ * const report: PageReport = {
+ *   url: 'https://app.example.com/dashboard',
+ *   route: { pattern: '/dashboard', params: null, query: {}, name: 'dashboard' },
+ *   timestamp: Date.now(),
+ *   capturedIn: 42,
+ *   tree: rootComponentNode,
+ *   errors: [],
+ *   suspenseBoundaries: [],
+ *   consoleEntries: [],
+ * };
+ * ```
+ */
+interface PageReport {
+    /**
+     * The full URL of the page at capture time, including protocol, host, path,
+     * and query string.  Fragment (`#hash`) is excluded.
+     */
+    url: string;
+    /**
+     * Router-level metadata for the current URL, populated by a
+     * framework-specific adapter.
+     *
+     * `null` when no routing adapter is installed or the current URL could not
+     * be matched to a known route.
+     */
+    route: RouteInfo | null;
+    /**
+     * Unix timestamp in milliseconds when the capture was initiated.
+     *
+     * Use this to correlate reports across users, sessions, or CI runs.
+     */
+    timestamp: number;
+    /**
+     * Total wall-clock time in milliseconds from the start of the capture
+     * request to the moment the final `PageReport` object was assembled.
+     *
+     * Useful for monitoring the overhead of the Scope runtime itself.
+     */
+    capturedIn: number;
+    /**
+     * The root node of the captured React component tree.
+     *
+     * Typically corresponds to the top-most fiber in the React tree (e.g. the
+     * element passed to `ReactDOM.createRoot(...).render(<App />)`).
+     */
+    tree: ComponentNode;
+    /**
+     * All JavaScript errors observed during the capture window.
+     *
+     * Includes unhandled exceptions, unhandled promise rejections, React error
+     * boundary catches, and direct `console.error` calls attributed to an error.
+     */
+    errors: CapturedError[];
+    /**
+     * All `<Suspense>` boundaries found in the component tree, flattened into a
+     * list for quick access without tree traversal.
+     */
+    suspenseBoundaries: SuspenseBoundaryInfo[];
+    /**
+     * All `console.*` calls intercepted during the capture window.
+     *
+     * Entries are ordered by `timestamp` ascending.
+     */
+    consoleEntries: ConsoleEntry[];
+}
+
+/**
+ * Type guard for {@link SourceLocation}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `SourceLocation` interface.
+ */
+declare function isSourceLocation(value: unknown): value is SourceLocation;
+/**
+ * Type guard for {@link SerializedValue}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `SerializedValue` interface.
+ */
+declare function isSerializedValue(value: unknown): value is SerializedValue;
+/**
+ * Type guard for {@link RouteInfo}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `RouteInfo` interface.
+ */
+declare function isRouteInfo(value: unknown): value is RouteInfo;
+/**
+ * Type guard for {@link ContextConsumption}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `ContextConsumption` interface.
+ */
+declare function isContextConsumption(value: unknown): value is ContextConsumption;
+/**
+ * Type guard for {@link HookState}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `HookState` interface.
+ */
+declare function isHookState(value: unknown): value is HookState;
+/**
+ * Type guard for {@link ComponentNode}.
+ *
+ * Performs a shallow check of the node itself; `children` are verified to be
+ * arrays of objects but are **not** recursively validated to keep the guard
+ * O(1) per node.  Use {@link isComponentNodeDeep} for full tree validation.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `ComponentNode` interface.
+ */
+declare function isComponentNode(value: unknown): value is ComponentNode;
+/**
+ * Recursively validates a `ComponentNode` and its entire subtree.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` and all descendant nodes conform to `ComponentNode`.
+ */
+declare function isComponentNodeDeep(value: unknown): value is ComponentNode;
+/**
+ * Type guard for {@link CapturedError}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `CapturedError` interface.
+ */
+declare function isCapturedError(value: unknown): value is CapturedError;
+/**
+ * Type guard for {@link SuspenseBoundaryInfo}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `SuspenseBoundaryInfo` interface.
+ */
+declare function isSuspenseBoundaryInfo(value: unknown): value is SuspenseBoundaryInfo;
+/**
+ * Type guard for {@link ConsoleEntry}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `ConsoleEntry` interface.
+ */
+declare function isConsoleEntry(value: unknown): value is ConsoleEntry;
+/**
+ * Type guard for {@link PageReport}.
+ *
+ * Validates the top-level shape of a `PageReport`.  The component tree
+ * (`tree`) is shallowly validated via {@link isComponentNode}.  Use
+ * {@link isPageReportDeep} if you need full recursive tree validation.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` conforms to the `PageReport` interface.
+ */
+declare function isPageReport(value: unknown): value is PageReport;
+/**
+ * Like {@link isPageReport} but also recursively validates the entire
+ * component tree via {@link isComponentNodeDeep}.
+ *
+ * @param value - Any value to test.
+ * @returns `true` when `value` and its full component tree are valid.
+ */
+declare function isPageReportDeep(value: unknown): value is PageReport;
+
+/**
+ * serialize() — Convert any JavaScript value to a SerializedValue snapshot.
+ *
+ * Features:
+ *  - Handles all primitives: string, number, boolean, null, undefined
+ *  - Handles complex types: object, array, function, symbol, bigint
+ *  - Handles built-ins: Date, Map, Set
+ *  - Circular reference detection via WeakSet → { type: 'circular' }
+ *  - Depth limiting → { type: 'truncated' }
+ *  - Configurable truncation for strings, arrays, and object properties
+ */
+
+interface SerializeOptions {
+    /** Maximum recursion depth for nested objects/arrays. Default: 5. */
+    maxDepth?: number;
+    /** Maximum length of serialized strings before truncation. Default: 200. */
+    maxStringLength?: number;
+    /** Maximum number of array items to serialize. Default: 100. */
+    maxArrayLength?: number;
+    /** Maximum number of object properties to serialize. Default: 50. */
+    maxProperties?: number;
+}
+/**
+ * Convert any JavaScript value to a safely-serialized {@link SerializedValue}.
+ *
+ * @param value  - The value to serialize.
+ * @param options - Optional tuning parameters.
+ */
+declare function serialize(value: unknown, options?: SerializeOptions): SerializedValue;
+
+export { COMPONENT_TYPES, CONSOLE_LEVELS, type CapturedError, type ComponentNode, type ComponentType, type ConsoleEntry, type ConsoleLevel, type ContextConsumption, HOOK_TYPES, type HookState, type HookType, type PageReport, type RouteInfo, SCHEMA_VERSION, SERIALIZED_VALUE_TYPES, type SerializeOptions, type SerializedValue, type SerializedValueType, type SourceLocation, type SuspenseBoundaryInfo, isCapturedError, isComponentNode, isComponentNodeDeep, isConsoleEntry, isContextConsumption, isHookState, isPageReport, isPageReportDeep, isRouteInfo, isSerializedValue, isSourceLocation, isSuspenseBoundaryInfo, serialize };