@devlens/react 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
+import { DevLensConfig, DevLensEngine } from '@devlens/core';
+export { DetectedIssue, DevLensConfig, IssueCategory, Severity } from '@devlens/core';
+
+interface DevLensProviderProps {
+    children: ReactNode;
+    config?: DevLensConfig;
+}
+declare function DevLensProvider({ children, config, }: DevLensProviderProps): react_jsx_runtime.JSX.Element;
+
+interface DevLensErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+declare class DevLensErrorBoundary extends Component<DevLensErrorBoundaryProps, ErrorBoundaryState> {
+    static contextType: react.Context<DevLensEngine | null>;
+    context: DevLensEngine | null;
+    constructor(props: DevLensErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
+declare function useDevLens(): DevLensEngine | null;
+declare function useGuardedState<T extends object>(initialState: T | (() => T), label?: string): [T, React.Dispatch<React.SetStateAction<T>>];
+declare function useGuardedEffect(data: Record<string, unknown>, label?: string): void;
+
+declare const DevLensContext: react.Context<DevLensEngine | null>;
+
+export { DevLensContext, DevLensErrorBoundary, type DevLensErrorBoundaryProps, DevLensProvider, type DevLensProviderProps, useDevLens, useGuardedEffect, useGuardedState };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
+import { DevLensConfig, DevLensEngine } from '@devlens/core';
+export { DetectedIssue, DevLensConfig, IssueCategory, Severity } from '@devlens/core';
+
+interface DevLensProviderProps {
+    children: ReactNode;
+    config?: DevLensConfig;
+}
+declare function DevLensProvider({ children, config, }: DevLensProviderProps): react_jsx_runtime.JSX.Element;
+
+interface DevLensErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+declare class DevLensErrorBoundary extends Component<DevLensErrorBoundaryProps, ErrorBoundaryState> {
+    static contextType: react.Context<DevLensEngine | null>;
+    context: DevLensEngine | null;
+    constructor(props: DevLensErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
+declare function useDevLens(): DevLensEngine | null;
+declare function useGuardedState<T extends object>(initialState: T | (() => T), label?: string): [T, React.Dispatch<React.SetStateAction<T>>];
+declare function useGuardedEffect(data: Record<string, unknown>, label?: string): void;
+
+declare const DevLensContext: react.Context<DevLensEngine | null>;
+
+export { DevLensContext, DevLensErrorBoundary, type DevLensErrorBoundaryProps, DevLensProvider, type DevLensProviderProps, useDevLens, useGuardedEffect, useGuardedState };

package/dist/index.js

@@ -0,0 +1,162 @@
+'use strict';
+
+var react = require('react');
+var core = require('@devlens/core');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/provider.tsx
+var DevLensContext = react.createContext(null);
+function isProductionEnv() {
+  try {
+    return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  } catch {
+    return false;
+  }
+}
+function DevLensProvider({
+  children,
+  config = {}
+}) {
+  const engineRef = react.useRef(
+    null
+  );
+  const cleanupRef = react.useRef(null);
+  const installedRef = react.useRef(false);
+  if (config.enabled === false || isProductionEnv()) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+  }
+  if (!engineRef.current) {
+    engineRef.current = core.createDetectionEngine(config);
+  }
+  react.useEffect(() => {
+    const engine = engineRef.current;
+    if (!engine || installedRef.current) return;
+    installedRef.current = true;
+    const networkConfig = config.modules?.network === false ? void 0 : config.modules?.network;
+    const catcherConfig = config.modules?.catcher === false ? void 0 : config.modules?.catcher;
+    const interceptors = [];
+    if (networkConfig !== void 0 || config.modules?.network !== false) {
+      const network = core.createNetworkInterceptor(engine, networkConfig);
+      network.install();
+      interceptors.push(network);
+    }
+    if (catcherConfig !== void 0 || config.modules?.catcher !== false) {
+      const catcher = core.createGlobalCatcher(engine, catcherConfig);
+      catcher.install();
+      interceptors.push(catcher);
+    }
+    cleanupRef.current = () => {
+      for (const interceptor of interceptors) {
+        interceptor.uninstall();
+      }
+      installedRef.current = false;
+    };
+    return () => {
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+    };
+  }, []);
+  return /* @__PURE__ */ jsxRuntime.jsx(DevLensContext.Provider, { value: engineRef.current, children });
+}
+var DevLensErrorBoundary = class extends react.Component {
+  constructor(props) {
+    super(props);
+    this.reset = () => {
+      this.setState({ error: null });
+    };
+    this.state = { error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, errorInfo) {
+    const engine = this.context;
+    if (engine?.isEnabled()) {
+      const issue = {
+        id: `unhandled-error:render:${error.message}`,
+        timestamp: Date.now(),
+        severity: "error",
+        category: "unhandled-error",
+        message: `React render error: ${error.message}`,
+        details: {
+          componentStack: errorInfo.componentStack ?? "unavailable"
+        },
+        stack: error.stack,
+        source: "DevLensErrorBoundary",
+        suggestion: "A React component threw during render. Check the component stack above."
+      };
+      engine.report(issue);
+    }
+    this.props.onError?.(error, errorInfo);
+  }
+  render() {
+    const { error } = this.state;
+    const { children, fallback } = this.props;
+    if (error) {
+      if (typeof fallback === "function") {
+        return fallback(error, this.reset);
+      }
+      if (fallback !== void 0) {
+        return fallback;
+      }
+      return /* @__PURE__ */ jsxRuntime.jsxs("div", { role: "alert", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("p", { children: "Something went wrong:" }),
+        /* @__PURE__ */ jsxRuntime.jsx("pre", { children: error.message })
+      ] });
+    }
+    return children;
+  }
+};
+DevLensErrorBoundary.contextType = DevLensContext;
+function useDevLens() {
+  return react.useContext(DevLensContext);
+}
+function useGuardedState(initialState, label) {
+  const engine = useDevLens();
+  const [state, setState] = react.useState(initialState);
+  const guardedState = react.useMemo(() => {
+    if (!engine || !engine.isEnabled()) return state;
+    if (state === null || state === void 0) return state;
+    if (typeof state !== "object") return state;
+    const guardian = core.createDataGuardian(engine);
+    return guardian.guard(state, label);
+  }, [state, engine, label]);
+  return [guardedState, setState];
+}
+function useGuardedEffect(data, label) {
+  const engine = useDevLens();
+  const dataRef = react.useRef(data);
+  dataRef.current = data;
+  react.useEffect(() => {
+    if (!engine || !engine.isEnabled()) return;
+    const currentData = dataRef.current;
+    const resolvedLabel = label ?? "useGuardedEffect";
+    const entries = Object.entries(currentData);
+    for (const [key, value] of entries) {
+      if (value === null || value === void 0) {
+        const issue = {
+          id: `render-data:${resolvedLabel}:${key}`,
+          timestamp: Date.now(),
+          severity: "warn",
+          category: "render-data",
+          message: `Render data "${key}" is ${value === null ? "null" : "undefined"} in ${resolvedLabel}`,
+          path: `${resolvedLabel}.${key}`,
+          foundValue: value,
+          expectedType: "non-nullish value",
+          source: resolvedLabel,
+          suggestion: `"${key}" is ${value === null ? "null" : "undefined"} \u2014 this may cause the UI to not render correctly. Check data loading.`
+        };
+        engine.report(issue);
+      }
+    }
+  });
+}
+
+exports.DevLensContext = DevLensContext;
+exports.DevLensErrorBoundary = DevLensErrorBoundary;
+exports.DevLensProvider = DevLensProvider;
+exports.useDevLens = useDevLens;
+exports.useGuardedEffect = useGuardedEffect;
+exports.useGuardedState = useGuardedState;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/provider.tsx","../src/error-boundary.tsx","../src/hooks.ts"],"names":["createContext","useRef","createDetectionEngine","useEffect","createNetworkInterceptor","createGlobalCatcher","Component","jsxs","jsx","useContext","useState","useMemo","createDataGuardian"],"mappings":"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","file":"index.js","sourcesContent":["import { createContext } from 'react';\nimport type { DevLensEngine } from '@devlens/core';\n\nexport const DevLensContext = createContext<DevLensEngine | null>(null);\n","import { useEffect, useRef, type ReactNode } from 'react';\nimport type { DevLensConfig } from '@devlens/core';\nimport {\n  createDetectionEngine,\n  createNetworkInterceptor,\n  createGlobalCatcher,\n} from '@devlens/core';\nimport { DevLensContext } from './context';\n\nexport interface DevLensProviderProps {\n  children: ReactNode;\n  config?: DevLensConfig;\n}\n\nfunction isProductionEnv(): boolean {\n  try {\n    return (\n      typeof process !== 'undefined' &&\n      process.env?.NODE_ENV === 'production'\n    );\n  } catch {\n    return false;\n  }\n}\n\nexport function DevLensProvider({\n  children,\n  config = {},\n}: DevLensProviderProps) {\n  const engineRef = useRef<ReturnType<typeof createDetectionEngine> | null>(\n    null,\n  );\n  const cleanupRef = useRef<(() => void) | null>(null);\n  const installedRef = useRef(false);\n\n  if (config.enabled === false || isProductionEnv()) {\n    return <>{children}</>;\n  }\n\n  if (!engineRef.current) {\n    engineRef.current = createDetectionEngine(config);\n  }\n\n  useEffect(() => {\n    const engine = engineRef.current;\n    if (!engine || installedRef.current) return;\n\n    installedRef.current = true;\n\n    const networkConfig =\n      config.modules?.network === false ? undefined : config.modules?.network;\n    const catcherConfig =\n      config.modules?.catcher === false ? undefined : config.modules?.catcher;\n\n    const interceptors: Array<{ uninstall(): void }> = [];\n\n    if (networkConfig !== undefined || config.modules?.network !== false) {\n      const network = createNetworkInterceptor(engine, networkConfig);\n      network.install();\n      interceptors.push(network);\n    }\n\n    if (catcherConfig !== undefined || config.modules?.catcher !== false) {\n      const catcher = createGlobalCatcher(engine, catcherConfig);\n      catcher.install();\n      interceptors.push(catcher);\n    }\n\n    cleanupRef.current = () => {\n      for (const interceptor of interceptors) {\n        interceptor.uninstall();\n      }\n      installedRef.current = false;\n    };\n\n    return () => {\n      cleanupRef.current?.();\n      cleanupRef.current = null;\n    };\n  }, []);\n\n  return (\n    <DevLensContext.Provider value={engineRef.current}>\n      {children}\n    </DevLensContext.Provider>\n  );\n}\n","import { Component, type ReactNode, type ErrorInfo } from 'react';\nimport type { DevLensEngine, DetectedIssue } from '@devlens/core';\nimport { DevLensContext } from './context';\n\nexport interface DevLensErrorBoundaryProps {\n  children: ReactNode;\n  fallback?:\n    | ReactNode\n    | ((error: Error, reset: () => void) => ReactNode);\n  onError?: (error: Error, errorInfo: ErrorInfo) => void;\n}\n\ninterface ErrorBoundaryState {\n  error: Error | null;\n}\n\nexport class DevLensErrorBoundary extends Component<\n  DevLensErrorBoundaryProps,\n  ErrorBoundaryState\n> {\n  static contextType = DevLensContext;\n  declare context: DevLensEngine | null;\n\n  constructor(props: DevLensErrorBoundaryProps) {\n    super(props);\n    this.state = { error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): ErrorBoundaryState {\n    return { error };\n  }\n\n  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {\n    const engine = this.context;\n\n    if (engine?.isEnabled()) {\n      const issue: DetectedIssue = {\n        id: `unhandled-error:render:${error.message}`,\n        timestamp: Date.now(),\n        severity: 'error',\n        category: 'unhandled-error',\n        message: `React render error: ${error.message}`,\n        details: {\n          componentStack: errorInfo.componentStack ?? 'unavailable',\n        },\n        stack: error.stack,\n        source: 'DevLensErrorBoundary',\n        suggestion:\n          'A React component threw during render. Check the component stack above.',\n      };\n      engine.report(issue);\n    }\n\n    this.props.onError?.(error, errorInfo);\n  }\n\n  reset = (): void => {\n    this.setState({ error: null });\n  };\n\n  render(): ReactNode {\n    const { error } = this.state;\n    const { children, fallback } = this.props;\n\n    if (error) {\n      if (typeof fallback === 'function') {\n        return fallback(error, this.reset);\n      }\n      if (fallback !== undefined) {\n        return fallback;\n      }\n      return (\n        <div role=\"alert\">\n          <p>Something went wrong:</p>\n          <pre>{error.message}</pre>\n        </div>\n      );\n    }\n\n    return children;\n  }\n}\n","import { useContext, useState, useMemo, useEffect, useRef } from 'react';\nimport type { DevLensEngine, DetectedIssue } from '@devlens/core';\nimport { createDataGuardian } from '@devlens/core';\nimport { DevLensContext } from './context';\n\nexport function useDevLens(): DevLensEngine | null {\n  return useContext(DevLensContext);\n}\n\nexport function useGuardedState<T extends object>(\n  initialState: T | (() => T),\n  label?: string,\n): [T, React.Dispatch<React.SetStateAction<T>>] {\n  const engine = useDevLens();\n  const [state, setState] = useState<T>(initialState);\n\n  const guardedState = useMemo(() => {\n    if (!engine || !engine.isEnabled()) return state;\n    if (state === null || state === undefined) return state;\n    if (typeof state !== 'object') return state;\n\n    const guardian = createDataGuardian(engine);\n    return guardian.guard(state, label);\n  }, [state, engine, label]);\n\n  return [guardedState, setState];\n}\n\nexport function useGuardedEffect(\n  data: Record<string, unknown>,\n  label?: string,\n): void {\n  const engine = useDevLens();\n  const dataRef = useRef(data);\n  dataRef.current = data;\n\n  useEffect(() => {\n    if (!engine || !engine.isEnabled()) return;\n\n    const currentData = dataRef.current;\n    const resolvedLabel = label ?? 'useGuardedEffect';\n\n    const entries = Object.entries(currentData);\n    for (const [key, value] of entries) {\n      if (value === null || value === undefined) {\n        const issue: DetectedIssue = {\n          id: `render-data:${resolvedLabel}:${key}`,\n          timestamp: Date.now(),\n          severity: 'warn',\n          category: 'render-data',\n          message: `Render data \"${key}\" is ${value === null ? 'null' : 'undefined'} in ${resolvedLabel}`,\n          path: `${resolvedLabel}.${key}`,\n          foundValue: value,\n          expectedType: 'non-nullish value',\n          source: resolvedLabel,\n          suggestion: `\"${key}\" is ${value === null ? 'null' : 'undefined'} — this may cause the UI to not render correctly. Check data loading.`,\n        };\n        engine.report(issue);\n      }\n    }\n  });\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,155 @@
+import { createContext, Component, useRef, useEffect, useContext, useState, useMemo } from 'react';
+import { createDetectionEngine, createNetworkInterceptor, createGlobalCatcher, createDataGuardian } from '@devlens/core';
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+
+// src/provider.tsx
+var DevLensContext = createContext(null);
+function isProductionEnv() {
+  try {
+    return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  } catch {
+    return false;
+  }
+}
+function DevLensProvider({
+  children,
+  config = {}
+}) {
+  const engineRef = useRef(
+    null
+  );
+  const cleanupRef = useRef(null);
+  const installedRef = useRef(false);
+  if (config.enabled === false || isProductionEnv()) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  if (!engineRef.current) {
+    engineRef.current = createDetectionEngine(config);
+  }
+  useEffect(() => {
+    const engine = engineRef.current;
+    if (!engine || installedRef.current) return;
+    installedRef.current = true;
+    const networkConfig = config.modules?.network === false ? void 0 : config.modules?.network;
+    const catcherConfig = config.modules?.catcher === false ? void 0 : config.modules?.catcher;
+    const interceptors = [];
+    if (networkConfig !== void 0 || config.modules?.network !== false) {
+      const network = createNetworkInterceptor(engine, networkConfig);
+      network.install();
+      interceptors.push(network);
+    }
+    if (catcherConfig !== void 0 || config.modules?.catcher !== false) {
+      const catcher = createGlobalCatcher(engine, catcherConfig);
+      catcher.install();
+      interceptors.push(catcher);
+    }
+    cleanupRef.current = () => {
+      for (const interceptor of interceptors) {
+        interceptor.uninstall();
+      }
+      installedRef.current = false;
+    };
+    return () => {
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(DevLensContext.Provider, { value: engineRef.current, children });
+}
+var DevLensErrorBoundary = class extends Component {
+  constructor(props) {
+    super(props);
+    this.reset = () => {
+      this.setState({ error: null });
+    };
+    this.state = { error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, errorInfo) {
+    const engine = this.context;
+    if (engine?.isEnabled()) {
+      const issue = {
+        id: `unhandled-error:render:${error.message}`,
+        timestamp: Date.now(),
+        severity: "error",
+        category: "unhandled-error",
+        message: `React render error: ${error.message}`,
+        details: {
+          componentStack: errorInfo.componentStack ?? "unavailable"
+        },
+        stack: error.stack,
+        source: "DevLensErrorBoundary",
+        suggestion: "A React component threw during render. Check the component stack above."
+      };
+      engine.report(issue);
+    }
+    this.props.onError?.(error, errorInfo);
+  }
+  render() {
+    const { error } = this.state;
+    const { children, fallback } = this.props;
+    if (error) {
+      if (typeof fallback === "function") {
+        return fallback(error, this.reset);
+      }
+      if (fallback !== void 0) {
+        return fallback;
+      }
+      return /* @__PURE__ */ jsxs("div", { role: "alert", children: [
+        /* @__PURE__ */ jsx("p", { children: "Something went wrong:" }),
+        /* @__PURE__ */ jsx("pre", { children: error.message })
+      ] });
+    }
+    return children;
+  }
+};
+DevLensErrorBoundary.contextType = DevLensContext;
+function useDevLens() {
+  return useContext(DevLensContext);
+}
+function useGuardedState(initialState, label) {
+  const engine = useDevLens();
+  const [state, setState] = useState(initialState);
+  const guardedState = useMemo(() => {
+    if (!engine || !engine.isEnabled()) return state;
+    if (state === null || state === void 0) return state;
+    if (typeof state !== "object") return state;
+    const guardian = createDataGuardian(engine);
+    return guardian.guard(state, label);
+  }, [state, engine, label]);
+  return [guardedState, setState];
+}
+function useGuardedEffect(data, label) {
+  const engine = useDevLens();
+  const dataRef = useRef(data);
+  dataRef.current = data;
+  useEffect(() => {
+    if (!engine || !engine.isEnabled()) return;
+    const currentData = dataRef.current;
+    const resolvedLabel = label ?? "useGuardedEffect";
+    const entries = Object.entries(currentData);
+    for (const [key, value] of entries) {
+      if (value === null || value === void 0) {
+        const issue = {
+          id: `render-data:${resolvedLabel}:${key}`,
+          timestamp: Date.now(),
+          severity: "warn",
+          category: "render-data",
+          message: `Render data "${key}" is ${value === null ? "null" : "undefined"} in ${resolvedLabel}`,
+          path: `${resolvedLabel}.${key}`,
+          foundValue: value,
+          expectedType: "non-nullish value",
+          source: resolvedLabel,
+          suggestion: `"${key}" is ${value === null ? "null" : "undefined"} \u2014 this may cause the UI to not render correctly. Check data loading.`
+        };
+        engine.report(issue);
+      }
+    }
+  });
+}
+
+export { DevLensContext, DevLensErrorBoundary, DevLensProvider, useDevLens, useGuardedEffect, useGuardedState };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/provider.tsx","../src/error-boundary.tsx","../src/hooks.ts"],"names":["jsx","useRef","useEffect"],"mappings":"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","file":"index.mjs","sourcesContent":["import { createContext } from 'react';\nimport type { DevLensEngine } from '@devlens/core';\n\nexport const DevLensContext = createContext<DevLensEngine | null>(null);\n","import { useEffect, useRef, type ReactNode } from 'react';\nimport type { DevLensConfig } from '@devlens/core';\nimport {\n  createDetectionEngine,\n  createNetworkInterceptor,\n  createGlobalCatcher,\n} from '@devlens/core';\nimport { DevLensContext } from './context';\n\nexport interface DevLensProviderProps {\n  children: ReactNode;\n  config?: DevLensConfig;\n}\n\nfunction isProductionEnv(): boolean {\n  try {\n    return (\n      typeof process !== 'undefined' &&\n      process.env?.NODE_ENV === 'production'\n    );\n  } catch {\n    return false;\n  }\n}\n\nexport function DevLensProvider({\n  children,\n  config = {},\n}: DevLensProviderProps) {\n  const engineRef = useRef<ReturnType<typeof createDetectionEngine> | null>(\n    null,\n  );\n  const cleanupRef = useRef<(() => void) | null>(null);\n  const installedRef = useRef(false);\n\n  if (config.enabled === false || isProductionEnv()) {\n    return <>{children}</>;\n  }\n\n  if (!engineRef.current) {\n    engineRef.current = createDetectionEngine(config);\n  }\n\n  useEffect(() => {\n    const engine = engineRef.current;\n    if (!engine || installedRef.current) return;\n\n    installedRef.current = true;\n\n    const networkConfig =\n      config.modules?.network === false ? undefined : config.modules?.network;\n    const catcherConfig =\n      config.modules?.catcher === false ? undefined : config.modules?.catcher;\n\n    const interceptors: Array<{ uninstall(): void }> = [];\n\n    if (networkConfig !== undefined || config.modules?.network !== false) {\n      const network = createNetworkInterceptor(engine, networkConfig);\n      network.install();\n      interceptors.push(network);\n    }\n\n    if (catcherConfig !== undefined || config.modules?.catcher !== false) {\n      const catcher = createGlobalCatcher(engine, catcherConfig);\n      catcher.install();\n      interceptors.push(catcher);\n    }\n\n    cleanupRef.current = () => {\n      for (const interceptor of interceptors) {\n        interceptor.uninstall();\n      }\n      installedRef.current = false;\n    };\n\n    return () => {\n      cleanupRef.current?.();\n      cleanupRef.current = null;\n    };\n  }, []);\n\n  return (\n    <DevLensContext.Provider value={engineRef.current}>\n      {children}\n    </DevLensContext.Provider>\n  );\n}\n","import { Component, type ReactNode, type ErrorInfo } from 'react';\nimport type { DevLensEngine, DetectedIssue } from '@devlens/core';\nimport { DevLensContext } from './context';\n\nexport interface DevLensErrorBoundaryProps {\n  children: ReactNode;\n  fallback?:\n    | ReactNode\n    | ((error: Error, reset: () => void) => ReactNode);\n  onError?: (error: Error, errorInfo: ErrorInfo) => void;\n}\n\ninterface ErrorBoundaryState {\n  error: Error | null;\n}\n\nexport class DevLensErrorBoundary extends Component<\n  DevLensErrorBoundaryProps,\n  ErrorBoundaryState\n> {\n  static contextType = DevLensContext;\n  declare context: DevLensEngine | null;\n\n  constructor(props: DevLensErrorBoundaryProps) {\n    super(props);\n    this.state = { error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): ErrorBoundaryState {\n    return { error };\n  }\n\n  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {\n    const engine = this.context;\n\n    if (engine?.isEnabled()) {\n      const issue: DetectedIssue = {\n        id: `unhandled-error:render:${error.message}`,\n        timestamp: Date.now(),\n        severity: 'error',\n        category: 'unhandled-error',\n        message: `React render error: ${error.message}`,\n        details: {\n          componentStack: errorInfo.componentStack ?? 'unavailable',\n        },\n        stack: error.stack,\n        source: 'DevLensErrorBoundary',\n        suggestion:\n          'A React component threw during render. Check the component stack above.',\n      };\n      engine.report(issue);\n    }\n\n    this.props.onError?.(error, errorInfo);\n  }\n\n  reset = (): void => {\n    this.setState({ error: null });\n  };\n\n  render(): ReactNode {\n    const { error } = this.state;\n    const { children, fallback } = this.props;\n\n    if (error) {\n      if (typeof fallback === 'function') {\n        return fallback(error, this.reset);\n      }\n      if (fallback !== undefined) {\n        return fallback;\n      }\n      return (\n        <div role=\"alert\">\n          <p>Something went wrong:</p>\n          <pre>{error.message}</pre>\n        </div>\n      );\n    }\n\n    return children;\n  }\n}\n","import { useContext, useState, useMemo, useEffect, useRef } from 'react';\nimport type { DevLensEngine, DetectedIssue } from '@devlens/core';\nimport { createDataGuardian } from '@devlens/core';\nimport { DevLensContext } from './context';\n\nexport function useDevLens(): DevLensEngine | null {\n  return useContext(DevLensContext);\n}\n\nexport function useGuardedState<T extends object>(\n  initialState: T | (() => T),\n  label?: string,\n): [T, React.Dispatch<React.SetStateAction<T>>] {\n  const engine = useDevLens();\n  const [state, setState] = useState<T>(initialState);\n\n  const guardedState = useMemo(() => {\n    if (!engine || !engine.isEnabled()) return state;\n    if (state === null || state === undefined) return state;\n    if (typeof state !== 'object') return state;\n\n    const guardian = createDataGuardian(engine);\n    return guardian.guard(state, label);\n  }, [state, engine, label]);\n\n  return [guardedState, setState];\n}\n\nexport function useGuardedEffect(\n  data: Record<string, unknown>,\n  label?: string,\n): void {\n  const engine = useDevLens();\n  const dataRef = useRef(data);\n  dataRef.current = data;\n\n  useEffect(() => {\n    if (!engine || !engine.isEnabled()) return;\n\n    const currentData = dataRef.current;\n    const resolvedLabel = label ?? 'useGuardedEffect';\n\n    const entries = Object.entries(currentData);\n    for (const [key, value] of entries) {\n      if (value === null || value === undefined) {\n        const issue: DetectedIssue = {\n          id: `render-data:${resolvedLabel}:${key}`,\n          timestamp: Date.now(),\n          severity: 'warn',\n          category: 'render-data',\n          message: `Render data \"${key}\" is ${value === null ? 'null' : 'undefined'} in ${resolvedLabel}`,\n          path: `${resolvedLabel}.${key}`,\n          foundValue: value,\n          expectedType: 'non-nullish value',\n          source: resolvedLabel,\n          suggestion: `\"${key}\" is ${value === null ? 'null' : 'undefined'} — this may cause the UI to not render correctly. Check data loading.`,\n        };\n        engine.report(issue);\n      }\n    }\n  });\n}\n"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@devlens/react",
+  "version": "1.0.0",
+  "description": "DevLens React integration - automatic error detection for React apps",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "devlens",
+    "crashsense",
+    "react",
+    "debug",
+    "error-boundary",
+    "error-detection",
+    "developer-tools"
+  ],
+  "author": "crashsense",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crashsense/devlens.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/crashsense/devlens#readme",
+  "bugs": {
+    "url": "https://github.com/crashsense/devlens/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "dependencies": {
+    "@devlens/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.4.0",
+    "vitest": "^3.0.0"
+  }
+}