@domscribe/react 0.1.0

package/adapter/react-adapter.d.ts

@@ -0,0 +1,121 @@
+/**
+ * ReactAdapter - React framework adapter for Domscribe
+ *
+ * Implements the FrameworkAdapter interface to provide runtime context capture
+ * for React applications. Supports multiple capture strategies:
+ * - DevTools: Use React DevTools hook (most reliable, requires DevTools)
+ * - Fiber: Direct Fiber tree access (fast, but uses React internal API)
+ * - Best-effort: Try multiple strategies in order of reliability
+ *
+ * @module @domscribe/react/adapter/react-adapter
+ */
+import type { ComponentTreeNode } from '@domscribe/runtime';
+import type { ReactAdapterOptions, ReactFrameworkAdapter } from './types.js';
+import { CaptureStrategy } from './types.js';
+import type { Nullable } from '../utils/types.js';
+/**
+ * ReactAdapter class implementing FrameworkAdapter interface
+ */
+export declare class ReactAdapter implements ReactFrameworkAdapter {
+    readonly name = "react";
+    readonly version?: string;
+    private _version?;
+    private state;
+    private options;
+    private fiberWalker;
+    private nameResolver;
+    private propsExtractor;
+    private stateExtractor;
+    constructor(options?: ReactAdapterOptions);
+    /**
+     * Detect React version from global React object or DevTools
+     */
+    private detectReactVersion;
+    /**
+     * Check if React DevTools hook is available
+     */
+    private checkDevToolsAvailability;
+    /**
+     * Get the React DevTools hook object
+     */
+    private getDevToolsHook;
+    /**
+     * Check if we can access Fiber internals
+     */
+    private checkFiberAccess;
+    /**
+     * Get component instance from a DOM element
+     *
+     * @param element - The DOM element to query
+     * @returns Component instance (Fiber node) or null if not found
+     */
+    getComponentInstance(element: HTMLElement): Nullable<unknown>;
+    /**
+     * Capture component props
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Serialized props object or null
+     */
+    captureProps(component: unknown): Nullable<Record<string, unknown>>;
+    /**
+     * Capture component state
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Serialized state object or null
+     */
+    captureState(component: unknown): Nullable<Record<string, unknown>>;
+    /**
+     * Get component name
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Component name or null
+     */
+    getComponentName(component: unknown): Nullable<string>;
+    /**
+     * Get component tree
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Component tree node or null
+     */
+    getComponentTree(component: unknown): Nullable<ComponentTreeNode>;
+    /**
+     * Get the active capture strategy
+     */
+    getActiveStrategy(): CaptureStrategy;
+    /**
+     * Get the React version
+     */
+    getReactVersion(): string | null;
+    /**
+     * Check if React DevTools is available
+     */
+    hasDevToolsAccess(): boolean;
+    /**
+     * Resolve component from DOM element using active strategy
+     */
+    private resolveComponent;
+    /**
+     * Resolve component via React DevTools hook
+     */
+    private resolveViaDevTools;
+    /**
+     * Resolve component via direct Fiber access
+     */
+    private resolveViaFiber;
+    /**
+     * Get Fiber node from DOM element using internal React keys
+     */
+    private getFiberFromElement;
+    /**
+     * Build component tree from a Fiber node
+     */
+    private buildComponentTree;
+}
+/**
+ * Create a ReactAdapter instance
+ *
+ * @param options - Adapter options
+ * @returns ReactAdapter instance
+ */
+export declare function createReactAdapter(options?: ReactAdapterOptions): ReactAdapter;
+//# sourceMappingURL=react-adapter.d.ts.map

package/adapter/react-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-adapter.d.ts","sourceRoot":"","sources":["../../../../packages/domscribe-react/src/adapter/react-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EACV,mBAAmB,EAGnB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAM7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AASlD;;GAEG;AACH,qBAAa,YAAa,YAAW,qBAAqB;IACxD,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAAgC;IAG/C,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,cAAc,CAAiB;gBAE3B,OAAO,CAAC,EAAE,mBAAmB;IAuDzC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IASjC;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC;IAmB7D;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAmBnE;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAmBnE;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;IAkBtD;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC,iBAAiB,CAAC;IAmBjE;;OAEG;IACH,iBAAiB,IAAI,eAAe;IAIpC;;OAEG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAQ5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6C1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAoCvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAuE3B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,CAEd"}

package/adapter/react-adapter.js

@@ -0,0 +1,486 @@
+/**
+ * ReactAdapter - React framework adapter for Domscribe
+ *
+ * Implements the FrameworkAdapter interface to provide runtime context capture
+ * for React applications. Supports multiple capture strategies:
+ * - DevTools: Use React DevTools hook (most reliable, requires DevTools)
+ * - Fiber: Direct Fiber tree access (fast, but uses React internal API)
+ * - Best-effort: Try multiple strategies in order of reliability
+ *
+ * @module @domscribe/react/adapter/react-adapter
+ */
+import { CaptureStrategy } from './types.js';
+import { FiberWalker } from '../fiber/fiber-walker.js';
+import { ComponentNameResolver } from '../component/component-name-resolver.js';
+import { PropsExtractor } from '../component/props-extractor.js';
+import { StateExtractor } from '../component/state-extractor.js';
+import { DEVTOOLS_HOOK_KEY, REACT_ELEMENT_KEYS } from '../utils/constants.js';
+import { isReactFiber, hasReactFiberKey, isComponentFiber, isReactDevToolsHook, } from '../utils/type-guards.js';
+import { FiberAccessError, ComponentResolutionError } from '../errors/index.js';
+/**
+ * ReactAdapter class implementing FrameworkAdapter interface
+ */
+export class ReactAdapter {
+    name = 'react';
+    version;
+    _version;
+    state;
+    options;
+    // Utilities
+    fiberWalker;
+    nameResolver;
+    propsExtractor;
+    stateExtractor;
+    constructor(options) {
+        // Initialize utilities
+        this.fiberWalker = new FiberWalker();
+        this.nameResolver = new ComponentNameResolver();
+        this.propsExtractor = new PropsExtractor();
+        this.stateExtractor = new StateExtractor();
+        // Normalize options with defaults
+        this.options = {
+            strategy: options?.strategy ?? CaptureStrategy.BEST_EFFORT,
+            maxTreeDepth: options?.maxTreeDepth ?? 50,
+            debug: options?.debug ?? false,
+            includeWrappers: options?.includeWrappers ?? true,
+            hookNameResolvers: options?.hookNameResolvers ?? new Map(),
+        };
+        // Initialize state
+        this.state = {
+            initialized: false,
+            hasDevTools: false,
+            hasFiberAccess: false,
+            activeStrategy: this.options.strategy,
+        };
+        try {
+            // Detect React version
+            this._version = this.detectReactVersion();
+            this.state.version = this._version;
+            // Set readonly version property
+            Object.defineProperty(this, 'version', {
+                value: this._version,
+                writable: false,
+                configurable: false,
+            });
+            // Check for DevTools hook
+            this.state.hasDevTools = this.checkDevToolsAvailability();
+            // Check for Fiber access
+            this.state.hasFiberAccess = this.checkFiberAccess();
+            this.state.initialized = true;
+            if (this.options.debug) {
+                console.log('[ReactAdapter] Initialized:', this.state);
+            }
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] Initialization failed:', error);
+            }
+            this.state.initialized = false;
+        }
+    }
+    /**
+     * Detect React version from global React object or DevTools
+     */
+    detectReactVersion() {
+        // Try React.version
+        if (typeof window !== 'undefined' && 'React' in window) {
+            const React = window
+                .React;
+            if (React?.version) {
+                return React.version;
+            }
+        }
+        // Try DevTools hook
+        if (this.state.hasDevTools) {
+            const hook = this.getDevToolsHook();
+            if (typeof hook === 'object' &&
+                hook !== null &&
+                'rendererInterfaces' in hook) {
+                const interfaces = hook.rendererInterfaces;
+                const firstRenderer = interfaces.values().next().value;
+                if (firstRenderer &&
+                    typeof firstRenderer === 'object' &&
+                    firstRenderer !== null &&
+                    'version' in firstRenderer) {
+                    return String(firstRenderer.version);
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if React DevTools hook is available
+     */
+    checkDevToolsAvailability() {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        const hook = this.getDevToolsHook();
+        return hook !== null && typeof hook === 'object';
+    }
+    /**
+     * Get the React DevTools hook object
+     */
+    getDevToolsHook() {
+        if (typeof window === 'undefined') {
+            return null;
+        }
+        const hook = window[DEVTOOLS_HOOK_KEY];
+        if (isReactDevToolsHook(hook)) {
+            return hook;
+        }
+        return null;
+    }
+    /**
+     * Check if we can access Fiber internals
+     */
+    checkFiberAccess() {
+        // Try to find a React root in the document
+        if (typeof document === 'undefined') {
+            return false;
+        }
+        // Look for React root nodes
+        const reactRoots = document.querySelectorAll('[data-reactroot]');
+        if (reactRoots.length > 0) {
+            const rootElement = reactRoots[0];
+            return hasReactFiberKey(rootElement);
+        }
+        // Try finding any element with React Fiber keys
+        const allElements = document.querySelectorAll('*');
+        for (let i = 0; i < Math.min(allElements.length, 100); i++) {
+            if (hasReactFiberKey(allElements[i])) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // ============================================================================
+    // FrameworkAdapter Interface Implementation
+    // ============================================================================
+    /**
+     * Get component instance from a DOM element
+     *
+     * @param element - The DOM element to query
+     * @returns Component instance (Fiber node) or null if not found
+     */
+    getComponentInstance(element) {
+        if (!this.state.initialized) {
+            return null;
+        }
+        try {
+            const result = this.resolveComponent(element);
+            if (result.success && result.component) {
+                return result.component;
+            }
+            return null;
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] getComponentInstance failed:', error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Capture component props
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Serialized props object or null
+     */
+    captureProps(component) {
+        if (!this.state.initialized || !isReactFiber(component)) {
+            return null;
+        }
+        try {
+            const result = this.propsExtractor.extract(component);
+            if (result.success && result.props) {
+                return result.props;
+            }
+            return null;
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] captureProps failed:', error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Capture component state
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Serialized state object or null
+     */
+    captureState(component) {
+        if (!this.state.initialized || !isReactFiber(component)) {
+            return null;
+        }
+        try {
+            const result = this.stateExtractor.extract(component);
+            if (result.success && result.state) {
+                return result.state;
+            }
+            return null;
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] captureState failed:', error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Get component name
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Component name or null
+     */
+    getComponentName(component) {
+        if (!this.state.initialized || !isReactFiber(component)) {
+            return null;
+        }
+        try {
+            const result = this.nameResolver.resolve(component, {
+                includeWrappers: this.options.includeWrappers,
+            });
+            return result.name || null;
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] getComponentName failed:', error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Get component tree
+     *
+     * @param component - The component instance (Fiber node)
+     * @returns Component tree node or null
+     */
+    getComponentTree(component) {
+        if (!this.state.initialized || !isReactFiber(component)) {
+            return null;
+        }
+        try {
+            return this.buildComponentTree(component);
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] getComponentTree failed:', error);
+            }
+            return null;
+        }
+    }
+    // ============================================================================
+    // React-Specific Methods
+    // ============================================================================
+    /**
+     * Get the active capture strategy
+     */
+    getActiveStrategy() {
+        return this.state.activeStrategy;
+    }
+    /**
+     * Get the React version
+     */
+    getReactVersion() {
+        return this._version ?? null;
+    }
+    /**
+     * Check if React DevTools is available
+     */
+    hasDevToolsAccess() {
+        return this.state.hasDevTools;
+    }
+    // ============================================================================
+    // Private Helper Methods
+    // ============================================================================
+    /**
+     * Resolve component from DOM element using active strategy
+     */
+    resolveComponent(element) {
+        // Try strategies in order based on active strategy
+        if (this.state.activeStrategy === CaptureStrategy.DEVTOOLS) {
+            return this.resolveViaDevTools(element);
+        }
+        else if (this.state.activeStrategy === CaptureStrategy.FIBER) {
+            return this.resolveViaFiber(element);
+        }
+        else {
+            // Best-effort: try both
+            const devToolsResult = this.resolveViaDevTools(element);
+            if (devToolsResult.success) {
+                return devToolsResult;
+            }
+            return this.resolveViaFiber(element);
+        }
+    }
+    /**
+     * Resolve component via React DevTools hook
+     */
+    resolveViaDevTools(element) {
+        try {
+            const hook = this.getDevToolsHook();
+            if (!hook) {
+                return {
+                    success: false,
+                    error: new ComponentResolutionError('DevTools hook not available'),
+                };
+            }
+            for (const renderer of hook.renderers.values()) {
+                if (renderer?.findFiberByHostInstance) {
+                    const fiber = renderer.findFiberByHostInstance(element);
+                    if (isReactFiber(fiber)) {
+                        // Find nearest component Fiber (not host Fiber)
+                        const componentFiber = this.fiberWalker.findNearestComponentFiber(fiber);
+                        if (componentFiber) {
+                            return {
+                                success: true,
+                                component: componentFiber,
+                                strategy: CaptureStrategy.DEVTOOLS,
+                            };
+                        }
+                    }
+                }
+            }
+            return {
+                success: false,
+                error: new ComponentResolutionError('Could not resolve Fiber via DevTools'),
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error
+                    ? error
+                    : new ComponentResolutionError('DevTools resolution failed'),
+            };
+        }
+    }
+    /**
+     * Resolve component via direct Fiber access
+     */
+    resolveViaFiber(element) {
+        try {
+            // Get Fiber node from element
+            const fiber = this.getFiberFromElement(element);
+            if (!fiber) {
+                return {
+                    success: false,
+                    error: new FiberAccessError('Could not find Fiber on element'),
+                };
+            }
+            // Find nearest component Fiber
+            const componentFiber = this.fiberWalker.findNearestComponentFiber(fiber);
+            if (!componentFiber) {
+                return {
+                    success: false,
+                    error: new FiberAccessError('Could not find component Fiber'),
+                };
+            }
+            return {
+                success: true,
+                component: componentFiber,
+                strategy: CaptureStrategy.FIBER,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error
+                    ? error
+                    : new FiberAccessError('Fiber resolution failed'),
+            };
+        }
+    }
+    /**
+     * Get Fiber node from DOM element using internal React keys
+     */
+    getFiberFromElement(element) {
+        // React attaches Fiber to DOM elements using internal keys
+        // These keys vary by React version:
+        // - React 16-17: __reactInternalInstance$...
+        // - React 18+: __reactFiber$...
+        const keys = Object.keys(element);
+        const fiberKey = keys.find((key) => key.startsWith(REACT_ELEMENT_KEYS.FIBER_16) ||
+            key.startsWith(REACT_ELEMENT_KEYS.FIBER_17_18));
+        if (!fiberKey) {
+            return null;
+        }
+        const fiber = element[fiberKey];
+        if (isReactFiber(fiber)) {
+            return fiber;
+        }
+        return null;
+    }
+    /**
+     * Build component tree from a Fiber node
+     */
+    buildComponentTree(fiber, depth = 0) {
+        if (depth >= this.options.maxTreeDepth) {
+            return null;
+        }
+        try {
+            const name = this.getComponentName(fiber);
+            if (!name) {
+                return null;
+            }
+            const node = {
+                name,
+                instance: fiber,
+            };
+            // Add props
+            const props = this.captureProps(fiber);
+            if (props) {
+                node.props = props;
+            }
+            // Add state
+            const state = this.captureState(fiber);
+            if (state) {
+                node.state = state;
+            }
+            // Add parent if within depth limit
+            if (fiber.return) {
+                const parentFiber = this.fiberWalker.findNearestComponentFiber(fiber.return);
+                if (parentFiber) {
+                    const parentNode = this.buildComponentTree(parentFiber, depth + 1);
+                    if (parentNode) {
+                        node.parent = parentNode;
+                    }
+                }
+            }
+            // Add children if within depth limit
+            if (depth + 1 < this.options.maxTreeDepth) {
+                const allChildren = this.fiberWalker.getChildren(fiber);
+                // Filter to only component fibers
+                const componentChildren = allChildren.filter((child) => isComponentFiber(child));
+                if (componentChildren.length > 0) {
+                    node.children = [];
+                    for (const child of componentChildren) {
+                        const childNode = this.buildComponentTree(child, depth + 1);
+                        if (childNode) {
+                            node.children.push(childNode);
+                        }
+                    }
+                }
+            }
+            return node;
+        }
+        catch (error) {
+            if (this.options.debug) {
+                console.error('[ReactAdapter] buildComponentTree failed:', error);
+            }
+            return null;
+        }
+    }
+}
+/**
+ * Create a ReactAdapter instance
+ *
+ * @param options - Adapter options
+ * @returns ReactAdapter instance
+ */
+export function createReactAdapter(options) {
+    return new ReactAdapter(options);
+}