@devlens/react 2.0.0 → 2.0.2

package/README.md

@@ -1,6 +1,21 @@
 # @devlens/react
 
-DevLens React integration -- automatic runtime error detection for React applications.
+**Drop in two components. Never miss a silent failure in React again.**
+
+Your `useEffect` fetches data, but `user.profile` comes back `null`. The page renders blank -- no error, no crash, just... nothing. You open DevTools, add 15 `console.log` statements, and finally find it 20 minutes later.
+
+DevLens catches it the moment it happens. Two lines of setup. Zero config.
+
+## The Problem
+
+React is great at catching render errors, but terrible at surfacing data problems:
+
+- API returns `null` instead of an object -- no error, blank UI
+- A prop is `undefined` because a parent didn't load yet -- silent failure
+- `fetch` returns 500 -- the Promise resolves, `.json()` fails silently
+- A deeply nested property is `null` -- `Cannot read property of null` only after the user clicks
+
+**DevLens surfaces all of these instantly, with full context, before your users notice.**
 
 ## Installation
 
@@ -8,9 +23,9 @@ DevLens React integration -- automatic runtime error detection for React applica
 npm install @devlens/core @devlens/react
 ```
 
-**Peer dependencies:** React >= 17.0.0
+**Requirements:** React >= 17.0.0
 
-## Quick Start
+## Setup -- 30 Seconds
 
 ```tsx
 import { DevLensProvider, DevLensErrorBoundary } from '@devlens/react';
@@ -26,9 +41,14 @@ function App() {
 }
 ```
 
-## Guarded State
+That's it. Open your browser console. DevLens auto-installs:
+- **Network interceptor** -- detects failed fetch/XHR calls
+- **Global catcher** -- captures uncaught errors and unhandled rejections
+- **Error boundary** -- catches React render errors with component stack traces
+
+## Guarded State -- Catch Null Access Before It Crashes
 
-Automatically detect null/undefined access on state objects:
+Replace `useState` with `useGuardedState`. Same API, but now null/undefined property access is detected automatically:
 
 ```tsx
 import { useGuardedState } from '@devlens/react';
@@ -36,44 +56,159 @@ import { useGuardedState } from '@devlens/react';
 function UserProfile() {
   const [user, setUser] = useGuardedState(initialUser, 'UserProfile');
 
-  // If user.profile.avatar is null, DevLens auto-logs:
-  // [NULL] DevLens [WARN] null-access: Property "avatar" is null at path "user.profile.avatar"
+  // If user.profile.avatar is null, DevLens immediately logs:
+  //
+  // [NULL] DevLens [WARN] null-access: Property "avatar" is null
+  //   at path "user.profile.avatar"
+  //   |- Path: user.profile.avatar
+  //   |- Value: null
+  //   |- Source: UserProfile
+  //   \- Suggestion: Check if "avatar" is loaded/initialized before accessing
+
   return <img src={user.profile.avatar} />;
 }
 ```
 
-## Watch Render Data
+**How it works:** `useGuardedState` wraps your state in an ES6 Proxy that detects null/undefined access at any depth. The original state is untouched -- the proxy only observes.
+
+## Guarded Effect -- Watch Data Dependencies
 
-Monitor multiple values for null/undefined:
+Monitor multiple values for null/undefined. Perfect for components that depend on async data:
 
 ```tsx
 import { useGuardedEffect } from '@devlens/react';
 
 function Dashboard({ user, posts, settings }) {
+  // Watch all data dependencies in one call
   useGuardedEffect({ user, posts, settings }, 'Dashboard');
 
+  // If posts is undefined (still loading), DevLens logs:
+  //
   // [RENDER] DevLens [WARN] render-data: "posts" is undefined in Dashboard
-  return <div>...</div>;
+  //   |- Path: Dashboard.posts
+  //   |- Value: undefined
+  //   \- Suggestion: "posts" is undefined -- check data loading in Dashboard
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      {posts.map(p => <Post key={p.id} {...p} />)}
+    </div>
+  );
 }
 ```
 
+## Error Boundary -- Catch Render Crashes with Context
+
+DevLens error boundary captures React render errors and reports them with full component stack traces:
+
+```tsx
+import { DevLensErrorBoundary } from '@devlens/react';
+
+<DevLensErrorBoundary
+  fallback={(error, reset) => (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try Again</button>
+    </div>
+  )}
+  onError={(error, errorInfo) => {
+    // Optional: send to your error tracking service
+    Sentry.captureException(error);
+  }}
+>
+  <RiskyComponent />
+</DevLensErrorBoundary>
+```
+
+**Features:**
+- Render prop fallback with `error` and `reset` function
+- `onError` callback for external error tracking integration
+- Auto-reports to DevLens engine with component stack
+- Default fallback UI if no custom fallback provided
+
+## Configuration
+
+```tsx
+<DevLensProvider
+  config={{
+    enabled: true,
+    minSeverity: 'warn',
+    throttleMs: 1000,
+    maxIssues: 100,
+    modules: {
+      network: {
+        fetch: true,
+        xhr: true,
+        ignoreUrls: ['/health', /\.hot-update\./],
+      },
+      guardian: { maxDepth: 5 },
+      catcher: {
+        windowErrors: true,
+        unhandledRejections: true,
+      },
+    },
+    ignore: {
+      messages: [/ResizeObserver/],
+    },
+  }}
+>
+  <App />
+</DevLensProvider>
+```
+
 ## API Reference
 
+### Components
+
+| Export | Description |
+|--------|-------------|
+| `DevLensProvider` | Wraps your app. Initializes the detection engine, network interceptor, and global catcher. Renders only `children` when disabled. |
+| `DevLensErrorBoundary` | React error boundary that auto-reports to DevLens. Supports render prop fallback with reset, `onError` callback. |
+
+### Hooks
+
 | Export | Description |
 |--------|-------------|
-| `DevLensProvider` | Wrapper component, initializes DevLens |
-| `DevLensErrorBoundary` | Error boundary with DevLens reporting |
-| `useDevLens()` | Access the engine instance |
-| `useGuardedState(initial, label?)` | useState with null/undefined detection |
-| `useGuardedEffect(data, label?)` | Watch data for null/undefined |
+| `useDevLens()` | Returns the `DevLensEngine` instance (or `null` if disabled). Use for custom reporting. |
+| `useGuardedState(initial, label?)` | Drop-in `useState` replacement. Wraps state in a Proxy to detect null/undefined property access at any depth. |
+| `useGuardedEffect(data, label?)` | Watches a `Record<string, unknown>` for null/undefined values. Runs on every render. |
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `DevLensProviderProps` | Props for `DevLensProvider` (`children`, `config?`) |
+| `DevLensErrorBoundaryProps` | Props for `DevLensErrorBoundary` (`children`, `fallback?`, `onError?`) |
+| `DevLensConfig` | Re-exported from `@devlens/core` |
+| `DetectedIssue` | Re-exported from `@devlens/core` |
+
+## Works With
+
+- **React 17, 18, 19** -- all supported
+- **Next.js** -- client components only (DevLens is browser-side)
+- **Remix, Vite, CRA** -- any React setup
+- **@devlens/ui** -- add the [visual debug panel](https://www.npmjs.com/package/@devlens/ui) for a full browser overlay
+
+## Why @devlens/react
+
+- **30-second setup** -- wrap your app, done
+- **Zero config** -- detects network, null access, render data, errors out of the box
+- **~5KB** ESM bundle -- barely noticeable
+- **Production-safe** -- auto-disabled in production, zero overhead, tree-shakeable
+- **Non-invasive** -- no patching React internals, clean Proxy-based detection
+- **Full TypeScript** -- complete type declarations, strict mode compatible
+
+## Roadmap
 
-## Details
+| Version | Feature | Status |
+|---------|---------|--------|
+| v2.0 | React integration with guarded hooks and error boundary | Current |
+| v3.0 | AI-powered analysis -- integrate Claude and Gemini models to analyze detected issues and generate root-cause explanations with fix suggestions | Planned |
 
-- ~5KB ESM bundle
-- Dual ESM + CJS output
-- Full TypeScript declarations
-- Production-safe -- auto-disabled in production
+The v3.0 AI integration will analyze patterns across your detected issues, identify root causes, and suggest fixes -- directly in your dev console or UI panel.
 
 ## License
 
-MIT -- [github.com/crashsense/devlens](https://github.com/crashsense/devlens)
+MIT -- [GitHub](https://github.com/crashsense/devlens) -- [Changelog](https://github.com/crashsense/devlens/blob/main/CHANGELOG.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devlens/react",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "DevLens React integration - automatic error detection for React apps",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -57,7 +57,7 @@
     "react-dom": ">=17.0.0"
   },
   "dependencies": {
-    "@devlens/core": "2.0.0"
+    "@devlens/core": "2.0.2"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",