@domscribe/react 0.1.0

package/adapter/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * React adapter type definitions
+ * @module @domscribe/react/adapter/types
+ */
+import type { FrameworkAdapter } from '@domscribe/runtime';
+/**
+ * React DevTools global hook shape (window.__REACT_DEVTOOLS_GLOBAL_HOOK__)
+ */
+export interface ReactDevToolsHook {
+    renderers: Map<number, ReactDevToolsRenderer>;
+    rendererInterfaces?: Map<number, ReactDevToolsRendererInterface>;
+}
+/**
+ * Renderer entry exposed by the DevTools hook
+ */
+export interface ReactDevToolsRenderer {
+    findFiberByHostInstance?: (instance: Element) => unknown;
+    version?: string;
+}
+/**
+ * Renderer interface entry exposed by the DevTools hook
+ */
+export interface ReactDevToolsRendererInterface {
+    version?: string;
+}
+/**
+ * Capture strategy for React component data
+ *
+ * - `devtools`: Use React DevTools hook (most reliable, requires DevTools)
+ * - `fiber`: Direct Fiber tree access (fast, but React internal API)
+ * - `best-effort`: Try multiple strategies in order of reliability
+ */
+export declare enum CaptureStrategy {
+    DEVTOOLS = "devtools",
+    FIBER = "fiber",
+    BEST_EFFORT = "best-effort"
+}
+/**
+ * Configuration options for ReactAdapter
+ */
+export interface ReactAdapterOptions {
+    /**
+     * Capture strategy to use
+     * @default CaptureStrategy.BEST_EFFORT
+     */
+    strategy?: CaptureStrategy;
+    /**
+     * Maximum depth to traverse the Fiber tree
+     * @default 50
+     */
+    maxTreeDepth?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Include wrappers (HOC, memo, forwardRef) in component names
+     * @default true
+     */
+    includeWrappers?: boolean;
+    /**
+     * Custom hook name resolvers for better debugging
+     * Maps hook index to semantic name (e.g., { 0: 'count', 1: 'setCount' })
+     */
+    hookNameResolvers?: Map<string, Map<number, string>>;
+}
+/**
+ * Internal state for ReactAdapter
+ */
+export interface ReactAdapterState {
+    /**
+     * Whether the adapter is initialized
+     */
+    initialized: boolean;
+    /**
+     * Detected React version
+     */
+    version?: string;
+    /**
+     * Whether React DevTools hook is available
+     */
+    hasDevTools: boolean;
+    /**
+     * Whether Fiber internals are accessible
+     */
+    hasFiberAccess: boolean;
+    /**
+     * Active capture strategy
+     */
+    activeStrategy: CaptureStrategy;
+}
+/**
+ * Result of a component resolution operation
+ */
+export interface ComponentResolutionResult {
+    /**
+     * Whether the resolution was successful
+     */
+    success: boolean;
+    /**
+     * The component instance (Fiber node)
+     */
+    component?: unknown;
+    /**
+     * The capture strategy that succeeded
+     */
+    strategy?: CaptureStrategy;
+    /**
+     * Error if resolution failed
+     */
+    error?: Error;
+}
+/**
+ * Extended FrameworkAdapter with React-specific methods
+ */
+export interface ReactFrameworkAdapter extends FrameworkAdapter {
+    /**
+     * Get the active capture strategy
+     */
+    getActiveStrategy(): CaptureStrategy;
+    /**
+     * Get the React version
+     */
+    getReactVersion(): string | null;
+    /**
+     * Check if React DevTools is available
+     */
+    hasDevToolsAccess(): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/adapter/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../packages/domscribe-react/src/adapter/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC9C,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC;CAClE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uBAAuB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,oBAAY,eAAe;IACzB,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,WAAW,gBAAgB;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAE3B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,cAAc,EAAE,eAAe,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAE3B;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;OAEG;IACH,iBAAiB,IAAI,eAAe,CAAC;IAErC;;OAEG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;OAEG;IACH,iBAAiB,IAAI,OAAO,CAAC;CAC9B"}

package/adapter/types.js

@@ -0,0 +1,17 @@
+/**
+ * React adapter type definitions
+ * @module @domscribe/react/adapter/types
+ */
+/**
+ * Capture strategy for React component data
+ *
+ * - `devtools`: Use React DevTools hook (most reliable, requires DevTools)
+ * - `fiber`: Direct Fiber tree access (fast, but React internal API)
+ * - `best-effort`: Try multiple strategies in order of reliability
+ */
+export var CaptureStrategy;
+(function (CaptureStrategy) {
+    CaptureStrategy["DEVTOOLS"] = "devtools";
+    CaptureStrategy["FIBER"] = "fiber";
+    CaptureStrategy["BEST_EFFORT"] = "best-effort";
+})(CaptureStrategy || (CaptureStrategy = {}));

package/auto-init.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auto-init.d.ts.map

package/auto-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-init.d.ts","sourceRoot":"","sources":["../../../packages/domscribe-react/src/auto-init.ts"],"names":[],"mappings":""}

package/auto-init.js

@@ -0,0 +1,40 @@
+/**
+ * Auto-initializing entry point for React adapter.
+ *
+ * Importing this module automatically initializes RuntimeManager with ReactAdapter.
+ * Used by the webpack plugin which adds this as an entry point.
+ *
+ * When used with the webpack plugin, `__DOMSCRIBE_RUNTIME_OPTIONS__` and
+ * `__DOMSCRIBE_ADAPTER_OPTIONS__` are injected via DefinePlugin. Falls back
+ * to empty objects when not defined (e.g. direct import without the plugin).
+ *
+ * @module @domscribe/react/auto-init
+ */
+import { RuntimeManager } from '@domscribe/runtime';
+import { createReactAdapter } from './adapter/react-adapter.js';
+try {
+    const runtimeOpts = typeof __DOMSCRIBE_RUNTIME_OPTIONS__ !== 'undefined'
+        ? __DOMSCRIBE_RUNTIME_OPTIONS__
+        : {};
+    const adapterOpts = typeof __DOMSCRIBE_ADAPTER_OPTIONS__ !== 'undefined'
+        ? __DOMSCRIBE_ADAPTER_OPTIONS__
+        : {};
+    // Reconstruct hookNameResolvers from plain object to Map<string, Map<number, string>>
+    const rawResolvers = adapterOpts.hookNameResolvers;
+    const hookNameResolvers = rawResolvers
+        ? new Map(Object.entries(rawResolvers).map(([k, v]) => [
+            k,
+            new Map(Object.entries(v).map(([i, n]) => [Number(i), n])),
+        ]))
+        : undefined;
+    RuntimeManager.getInstance().initialize({
+        ...runtimeOpts,
+        adapter: createReactAdapter({
+            ...adapterOpts,
+            hookNameResolvers,
+        }),
+    });
+}
+catch (e) {
+    console.warn('[domscribe] Failed to auto-init React runtime:', e instanceof Error ? e.message : String(e));
+}

package/component/component-name-resolver.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ComponentNameResolver - Resolve component names from React Fiber nodes
+ *
+ * Handles name resolution with wrapper detection (HOC, memo, forwardRef),
+ * fallback strategies, and display name formatting.
+ *
+ * @module @domscribe/react/component/component-name-resolver
+ */
+import type { ExtendedReactFiber } from '../fiber/types.js';
+import type { NameResolutionResult, NameResolutionOptions } from './types.js';
+/**
+ * ComponentNameResolver class for resolving component names from Fiber nodes
+ */
+export declare class ComponentNameResolver {
+    /**
+     * Resolve the name of a component from its Fiber node
+     *
+     * @param fiber - Fiber node to resolve name from
+     * @param options - Resolution options
+     * @returns Name resolution result
+     * @throws {NameResolutionError} If fiber is invalid
+     */
+    resolve(fiber: ExtendedReactFiber, options?: NameResolutionOptions): NameResolutionResult;
+    /**
+     * Resolve host component (DOM element) name
+     *
+     * @param fiber - Host component Fiber node
+     * @returns Name resolution result
+     */
+    private resolveHostComponent;
+    /**
+     * Resolve text node name
+     *
+     * @returns Name resolution result for text nodes
+     */
+    private resolveTextNode;
+    /**
+     * Resolve component name without wrapper analysis
+     *
+     * @param fiber - Fiber node
+     * @param options - Resolution options
+     * @returns Name resolution result
+     */
+    private resolveSimple;
+    /**
+     * Resolve component name with wrapper analysis
+     *
+     * @param fiber - Fiber node
+     * @param options - Resolution options
+     * @returns Name resolution result with wrapper chain
+     */
+    private resolveWithWrappers;
+    /**
+     * Extract displayName from Fiber type
+     *
+     * @param fiber - Fiber node
+     * @returns Display name or null
+     */
+    private extractDisplayName;
+    /**
+     * Extract name from Fiber type
+     *
+     * @param fiber - Fiber node
+     * @returns Type name or null
+     */
+    private extractTypeName;
+    /**
+     * Extract name from Fiber elementType
+     *
+     * @param fiber - Fiber node
+     * @returns Element type name or null
+     */
+    private extractElementTypeName;
+    /**
+     * Detect HOC pattern from component name
+     *
+     * @param fiber - Fiber node
+     * @returns HOC name or null
+     */
+    private detectHOCPattern;
+    /**
+     * Unwrap a memo component to get the inner component
+     *
+     * @param fiber - Memo Fiber node
+     * @returns Unwrapped Fiber
+     */
+    private unwrapMemo;
+    /**
+     * Unwrap a forwardRef component to get the inner component
+     *
+     * @param fiber - ForwardRef Fiber node
+     * @returns Unwrapped Fiber
+     */
+    private unwrapForwardRef;
+    /**
+     * Unwrap an HOC to get the inner component
+     *
+     * @param fiber - HOC Fiber node
+     * @returns Unwrapped Fiber (or original if can't unwrap)
+     */
+    private unwrapHOC;
+    /**
+     * Format a component name with its wrapper chain
+     *
+     * @param name - Component name
+     * @param wrappers - Wrapper names
+     * @returns Formatted name
+     */
+    private formatWrappedName;
+    /**
+     * Normalize resolution options with defaults
+     *
+     * @param options - User-provided options
+     * @returns Normalized options
+     */
+    private normalizeOptions;
+}
+//# sourceMappingURL=component-name-resolver.d.ts.map

package/component/component-name-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-name-resolver.d.ts","sourceRoot":"","sources":["../../../../packages/domscribe-react/src/component/component-name-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAQ9E;;GAEG;AACH,qBAAa,qBAAqB;IAChC;;;;;;;OAOG;IACH,OAAO,CACL,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB;IA0BvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAoDrB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA6D3B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAoBvB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAgC9B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAsBlB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAUjB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IASzB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAWzB"}

package/component/component-name-resolver.js

@@ -0,0 +1,361 @@
+/**
+ * ComponentNameResolver - Resolve component names from React Fiber nodes
+ *
+ * Handles name resolution with wrapper detection (HOC, memo, forwardRef),
+ * fallback strategies, and display name formatting.
+ *
+ * @module @domscribe/react/component/component-name-resolver
+ */
+import { REACT_FIBER_TAGS, COMMON_HOC_PATTERNS, DEFAULT_OPTIONS, } from '../utils/constants.js';
+import { NameResolutionError } from '../errors/index.js';
+/**
+ * ComponentNameResolver class for resolving component names from Fiber nodes
+ */
+export class ComponentNameResolver {
+    /**
+     * Resolve the name of a component from its Fiber node
+     *
+     * @param fiber - Fiber node to resolve name from
+     * @param options - Resolution options
+     * @returns Name resolution result
+     * @throws {NameResolutionError} If fiber is invalid
+     */
+    resolve(fiber, options) {
+        if (!fiber) {
+            throw new NameResolutionError('Fiber node is required');
+        }
+        const opts = this.normalizeOptions(options);
+        // Handle host components (DOM elements)
+        if (fiber.tag === REACT_FIBER_TAGS.HostComponent) {
+            return this.resolveHostComponent(fiber);
+        }
+        // Handle text nodes
+        if (fiber.tag === REACT_FIBER_TAGS.HostText) {
+            return this.resolveTextNode();
+        }
+        // Resolve with wrapper analysis if enabled
+        if (opts.includeWrappers) {
+            return this.resolveWithWrappers(fiber, opts);
+        }
+        // Simple resolution
+        return this.resolveSimple(fiber, opts);
+    }
+    /**
+     * Resolve host component (DOM element) name
+     *
+     * @param fiber - Host component Fiber node
+     * @returns Name resolution result
+     */
+    resolveHostComponent(fiber) {
+        const tagName = typeof fiber.type === 'string' ? fiber.type : 'UnknownElement';
+        return {
+            name: tagName,
+            displayName: tagName,
+            method: 'type-name',
+            confidence: 1.0,
+            wrappers: [],
+        };
+    }
+    /**
+     * Resolve text node name
+     *
+     * @returns Name resolution result for text nodes
+     */
+    resolveTextNode() {
+        return {
+            name: 'Text',
+            displayName: 'Text',
+            method: 'type-name',
+            confidence: 1.0,
+            wrappers: [],
+        };
+    }
+    /**
+     * Resolve component name without wrapper analysis
+     *
+     * @param fiber - Fiber node
+     * @param options - Resolution options
+     * @returns Name resolution result
+     */
+    resolveSimple(fiber, options) {
+        // Try type.displayName
+        const displayName = this.extractDisplayName(fiber);
+        if (displayName) {
+            return {
+                name: displayName,
+                displayName,
+                method: 'displayName',
+                confidence: 1.0,
+                wrappers: [],
+            };
+        }
+        // Try type.name
+        const typeName = this.extractTypeName(fiber);
+        if (typeName) {
+            // Determine if function or class
+            const isFunction = typeof fiber.type === 'function';
+            return {
+                name: typeName,
+                displayName: typeName,
+                method: isFunction ? 'function-name' : 'type-name',
+                confidence: 0.8,
+                wrappers: [],
+            };
+        }
+        // Try elementType
+        const elementTypeName = this.extractElementTypeName(fiber);
+        if (elementTypeName) {
+            return {
+                name: elementTypeName,
+                displayName: elementTypeName,
+                method: 'type-name',
+                confidence: 0.5,
+                wrappers: [],
+            };
+        }
+        // Fallback
+        return {
+            name: options.fallbackName,
+            displayName: options.fallbackName,
+            method: 'fallback',
+            confidence: 0.0,
+            wrappers: [],
+        };
+    }
+    /**
+     * Resolve component name with wrapper analysis
+     *
+     * @param fiber - Fiber node
+     * @param options - Resolution options
+     * @returns Name resolution result with wrapper chain
+     */
+    resolveWithWrappers(fiber, options) {
+        const wrappers = [];
+        let currentFiber = fiber;
+        let depth = 0;
+        // Unwrap layers
+        while (depth < options.maxWrapperDepth) {
+            // Check for memo
+            if (currentFiber.tag === REACT_FIBER_TAGS.MemoComponent ||
+                currentFiber.tag === REACT_FIBER_TAGS.SimpleMemoComponent) {
+                wrappers.push('memo');
+                const unwrapped = this.unwrapMemo(currentFiber);
+                if (unwrapped === currentFiber)
+                    break;
+                currentFiber = unwrapped;
+            }
+            // Check for forwardRef
+            else if (currentFiber.tag === REACT_FIBER_TAGS.ForwardRef) {
+                wrappers.push('forwardRef');
+                const unwrapped = this.unwrapForwardRef(currentFiber);
+                if (unwrapped === currentFiber)
+                    break;
+                currentFiber = unwrapped;
+            }
+            // Check for HOC patterns
+            else {
+                const hocName = this.detectHOCPattern(currentFiber);
+                if (hocName) {
+                    wrappers.push(hocName);
+                    const unwrapped = this.unwrapHOC(currentFiber);
+                    if (unwrapped === currentFiber)
+                        break;
+                    currentFiber = unwrapped;
+                }
+                else {
+                    break; // No more wrappers
+                }
+            }
+            depth++;
+        }
+        // Get the innermost component name
+        const innerResult = this.resolveSimple(currentFiber, options);
+        // Build display name with wrappers
+        const displayName = wrappers.length > 0
+            ? this.formatWrappedName(innerResult.name, wrappers)
+            : innerResult.name;
+        return {
+            name: innerResult.name,
+            displayName,
+            method: innerResult.method,
+            confidence: innerResult.confidence,
+            wrappers,
+        };
+    }
+    /**
+     * Extract displayName from Fiber type
+     *
+     * @param fiber - Fiber node
+     * @returns Display name or null
+     */
+    extractDisplayName(fiber) {
+        const type = fiber.type;
+        // Check function components (e.g., MyComponent.displayName = 'Pretty')
+        if (typeof type === 'function' &&
+            'displayName' in type &&
+            typeof type.displayName === 'string' &&
+            type.displayName.length > 0) {
+            return type.displayName;
+        }
+        // Check object types (e.g., memo/forwardRef wrappers with displayName)
+        if (type &&
+            typeof type === 'object' &&
+            'displayName' in type &&
+            typeof type.displayName === 'string' &&
+            type.displayName.length > 0) {
+            return type.displayName;
+        }
+        return null;
+    }
+    /**
+     * Extract name from Fiber type
+     *
+     * @param fiber - Fiber node
+     * @returns Type name or null
+     */
+    extractTypeName(fiber) {
+        const type = fiber.type;
+        if (typeof type === 'function' && type.name) {
+            return type.name;
+        }
+        if (type &&
+            typeof type === 'object' &&
+            'name' in type &&
+            typeof type.name === 'string' &&
+            type.name.length > 0) {
+            return type.name;
+        }
+        return null;
+    }
+    /**
+     * Extract name from Fiber elementType
+     *
+     * @param fiber - Fiber node
+     * @returns Element type name or null
+     */
+    extractElementTypeName(fiber) {
+        const elementType = fiber.elementType;
+        if (typeof elementType === 'string') {
+            return elementType;
+        }
+        if (typeof elementType === 'function' && elementType.name) {
+            return elementType.name;
+        }
+        if (elementType &&
+            typeof elementType === 'object' &&
+            'displayName' in elementType &&
+            typeof elementType.displayName === 'string') {
+            return elementType.displayName;
+        }
+        if (elementType &&
+            typeof elementType === 'object' &&
+            'name' in elementType &&
+            typeof elementType.name === 'string') {
+            return elementType.name;
+        }
+        return null;
+    }
+    /**
+     * Detect HOC pattern from component name
+     *
+     * @param fiber - Fiber node
+     * @returns HOC name or null
+     */
+    detectHOCPattern(fiber) {
+        const name = this.extractTypeName(fiber) || this.extractDisplayName(fiber);
+        if (!name) {
+            return null;
+        }
+        const matchedPattern = COMMON_HOC_PATTERNS.find((pattern) => name.startsWith(pattern));
+        return matchedPattern || null;
+    }
+    /**
+     * Unwrap a memo component to get the inner component
+     *
+     * @param fiber - Memo Fiber node
+     * @returns Unwrapped Fiber
+     */
+    unwrapMemo(fiber) {
+        // Try to get the inner type from elementType
+        if (fiber.elementType &&
+            typeof fiber.elementType === 'object' &&
+            fiber.elementType !== null &&
+            'type' in fiber.elementType) {
+            const innerType = fiber.elementType.type;
+            // Create a synthetic fiber with the inner type and reset tag
+            // so the unwrap loop doesn't re-match this as a memo wrapper
+            return {
+                ...fiber,
+                tag: REACT_FIBER_TAGS.FunctionComponent,
+                type: innerType,
+                elementType: innerType,
+            };
+        }
+        return fiber;
+    }
+    /**
+     * Unwrap a forwardRef component to get the inner component
+     *
+     * @param fiber - ForwardRef Fiber node
+     * @returns Unwrapped Fiber
+     */
+    unwrapForwardRef(fiber) {
+        // Try to get the render function from elementType
+        if (fiber.elementType &&
+            typeof fiber.elementType === 'object' &&
+            fiber.elementType !== null &&
+            'render' in fiber.elementType) {
+            const renderFn = fiber.elementType.render;
+            // Create a synthetic fiber with the render function as type and reset tag
+            // so the unwrap loop doesn't re-match this as a forwardRef wrapper
+            return {
+                ...fiber,
+                tag: REACT_FIBER_TAGS.FunctionComponent,
+                type: renderFn,
+                elementType: renderFn,
+            };
+        }
+        return fiber;
+    }
+    /**
+     * Unwrap an HOC to get the inner component
+     *
+     * @param fiber - HOC Fiber node
+     * @returns Unwrapped Fiber (or original if can't unwrap)
+     */
+    unwrapHOC(fiber) {
+        // For HOCs, we can't reliably unwrap without runtime inspection
+        // This is a best-effort attempt using child
+        if (fiber.child) {
+            return fiber.child;
+        }
+        return fiber;
+    }
+    /**
+     * Format a component name with its wrapper chain
+     *
+     * @param name - Component name
+     * @param wrappers - Wrapper names
+     * @returns Formatted name
+     */
+    formatWrappedName(name, wrappers) {
+        if (wrappers.length === 0) {
+            return name;
+        }
+        // Format: wrapper1(wrapper2(Component))
+        return `${wrappers.join('(')}(${name}${')'.repeat(wrappers.length)}`;
+    }
+    /**
+     * Normalize resolution options with defaults
+     *
+     * @param options - User-provided options
+     * @returns Normalized options
+     */
+    normalizeOptions(options) {
+        return {
+            includeWrappers: options?.includeWrappers ?? false,
+            maxWrapperDepth: options?.maxWrapperDepth ?? DEFAULT_OPTIONS.MAX_WRAPPER_DEPTH,
+            fallbackName: options?.fallbackName ?? DEFAULT_OPTIONS.FALLBACK_COMPONENT_NAME,
+        };
+    }
+}