react-jitter 0.3.0

package/README.md

@@ -0,0 +1,241 @@
+# React Jitter
+
+[![npm version](https://badge.fury.io/js/react-jitter.svg)](https://badge.fury.io/js/react-jitter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+React Jitter is a developer tool to help you understand why your React components re-render. It pinpoints the exact hooks and values that have changed, so you can optimize your application's performance with precision.
+
+## Table of Contents
+
+- [Motivation](#motivation)
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Usage](#usage)
+- [API and Configuration](#api-and-configuration)
+- [How It Works](#how-it-works)
+- [Limitations](#limitations)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Motivation
+
+Unnecessary re-renders are a common source of performance issues in React applications. When a component re-renders, it can be difficult to trace the root cause. React Profiler reports "Hook 7 changed" but not the name of hook or what exactly changed. It also does not provide anything useful for context changes and it just says "Context changed".
+
+Existing tools like `why-did-you-render` require you to manually whitelist the hooks and components you want to track. This is impractical in large codebases where you want to monitor everything without tedious configuration. Others, like `react-scan`, are excellent for a high-level overview but does not report hook changes.
+
+React Jitter solves these problems by instrumenting your code at build time with an SWC plugin. It tells you the exact hook that caused a re-render and shows you the previous and current values so you can see exactly what changed.
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install --save-dev react-jitter
+```
+
+### Usage
+
+React Jitter is designed to be used **during development only**. You must ensure that both the SWC plugin and the runtime are disabled in your production builds to prevent instrumenting your production code.
+
+#### Enabling the SWC Plugin (Development Only)
+
+##### Next.js
+
+In `next.config.js`, conditionally add the plugin and its configuration based on the environment:
+
+```js
+const isDevelopment = process.env.NODE_ENV === "development";
+
+const nextConfig = {
+  swcMinify: true,
+  experimental: {
+    swcPlugins: isDevelopment
+      ? [
+          [
+            "react-jitter/plugin-swc",
+            {
+              // An array of hooks to ignore. For example, `["useSelector"]`.
+              ignoreHooks: [],
+              // An array of glob patterns for files to exclude from instrumentation.
+              // By default, `**/node_modules/**` is excluded.
+              exclude: [],
+              // When true, the arguments of a hook will be captured as strings
+              // and included in the `onHookChange` callback. This is disabled
+              // by default because it can significantly increase the bundle size,
+              // especially if hooks receive large objects or functions as arguments.
+              includeArguments: false,
+            },
+          ],
+        ]
+      : [],
+  },
+};
+
+module.exports = nextConfig;
+```
+
+##### `.swcrc`
+
+Since `.swcrc` is a static JSON file, you cannot use logic within it. You should use separate build scripts or a JavaScript-based configuration file (e.g., `swc.config.js`) to apply different SWC configurations for your development and production environments.
+
+#### Initializing the Runtime (Development Only)
+
+Once the plugin is configured, you need to initialize the runtime in your application. In your main application file (e.g., `_app.tsx` in Next.js), ensure the call is only made in development:
+
+```tsx
+// In your app's entry file (e.g., _app.tsx)
+
+import { reactJitter } from "react-jitter/runtime";
+
+if (process.env.NODE_ENV === "development") {
+  reactJitter({
+    enabled: true,
+    // This function is called whenever a hook's value changes.
+    onHookChange: (change) => {
+      console.log("Hook changed:", change);
+    },
+    // This function is called after a component finishes rendering.
+    onRender: (render) => {
+      console.log("Component rendered:", render);
+    }
+  });
+}
+```
+
+You can also change `enabled`, `onHookChange`, and `onRender` at runtime from your browser's developer console. This is useful for temporarily disabling logging or changing the callback behavior without a full page reload.
+
+```js
+// Disable React Jitter
+window.reactJitter.enabled = false;
+
+// Re-enable React Jitter
+window.reactJitter.enabled = true;
+
+// Change the onHookChange callback
+window.reactJitter.onHookChange = (change) => {
+  if (change.unstable) {
+    console.warn("Unstable hook value:", change);
+  }
+};
+
+// Change the onRender callback
+window.reactJitter.onRender = (render) => {
+  if (render.renderCount > 10) {
+    console.warn("High render count:", render);
+  }
+}
+```
+
+Modern bundlers will tree-shake the `import` and the function call from your production build, so it will have zero performance impact.
+
+## API and Configuration
+
+The `reactJitter` function accepts a configuration object with two callbacks: `onHookChange` and `onRender`.
+
+- `onHookChange`: Called whenever a hook's value changes. It receives a `change` object with details about the hook, its location, and the value that changed.
+- `onRender`: Called after a component finishes rendering. It receives a `render` object with metadata about the component's render cycle.
+
+Here is an example of the `change` object from `onHookChange` when an unstable object is detected:
+
+```json
+{
+  "hook": "useUser",
+  "file": "/src/components/UserProfile.tsx",
+  "line": 12,
+  "offset": 18,
+  "scope": {
+    "name": "UserProfile",
+    "file": "/src/components/UserProfile.tsx",
+    "line": 8,
+    "offset": 1
+  },
+  "unstable": true,
+  "unstableKeys": ["address"],
+  "changedKeys": [],
+  "previousResult": {
+    "id": "user-123",
+    "address": { "street": "123 Main St" }
+  },
+  "currentResult": {
+    "id": "user-123",
+    "address": { "street": "123 Main St" }
+  }
+}
+```
+
+In this case, the `address` object was re-created, causing an unstable reference even though its contents are the same.
+
+Here is an example of the `render` object from `onRender`:
+
+```json
+{
+  "scopeId": "UserProfile-0",
+  "renderCount": 5,
+  "name": "UserProfile",
+  "id": "UserProfile",
+  "file": "/src/components/UserProfile.tsx",
+  "line": 8,
+  "offset": 1,
+  "hookResults": {
+    "4f23ef0": {
+      "id": "user-123",
+      "address": { "street": "123 Main St" }
+    }
+  }
+}
+```
+
+This object provides the component's unique instance ID, its render count, location metadata, and a map of all hook results for the current render.
+
+You can use the `includeArguments` option to identify which context has changed. When `includeArguments` is set to `true` in the SWC plugin configuration, the `onHookChange` callback will include the arguments passed to the hook. This is especially useful for `useContext`, as it allows you to see which context was used.
+
+Here is an example of the `change` object when `includeArguments` is enabled:
+
+```json
+{
+  "hook": "useContext",
+  "arguments": ["UserContext"],
+  "file": "/src/components/UserProfile.tsx",
+  "line": 12,
+  "offset": 18,
+  "scope": {
+    "name": "UserProfile",
+    "file": "/src/components/UserProfile.tsx",
+    "line": 8,
+    "offset": 1
+  },
+  "unstable": false,
+  "unstableKeys": [],
+  "changedKeys": ["user"],
+  "previousResult": {
+    "user": { "name": "John" }
+  },
+  "currentResult": {
+    "user": { "name": "Jane" }
+  }
+}
+```
+
+In this example, the `arguments` field shows that the `UserContext` was used, and the `changedKeys` field shows that the `user` property has changed.
+
+
+## How It Works
+
+React Jitter is composed of two parts:
+
+1.  **SWC Plugin**: A plugin for the [SWC compiler](httpss://swc.rs) that transforms your code to add instrumentation. It finds your React components and wraps your hook calls with a light monitoring function.
+2.  **Runtime**: A small runtime library that is injected into your components. It keeps track of the values returned by your hooks and, when they change, it reports the differences.
+
+One of the most common causes of unnecessary re-renders is "unstable" objects and functions that are re-created on every render. `react-jitter` helps you identify these issues by tracking when a value's reference changes and reporting it to you.
+
+## Limitations
+
+`react-jitter` detects React components using a set of heuristics. It looks for functions that either use hooks or return JSX, and whose names start with a capital letter. While this covers most common cases, it may not detect all components reliably, especially if you use less common patterns for defining components.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request if you have any ideas for improvement.
+
+## License
+
+This project is licensed under the MIT License.

package/index.d.ts

@@ -0,0 +1,28 @@
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+declare module 'react-jitter' {
+  /**
+   * Configuration options for react-jitter
+   */
+  export interface ReactJitterOptions {
+    /**
+     * List of hook names to ignore (not transform)
+     * By default, all default react hooks are ignored except useContext and useReducer.
+     */
+    ignoreHooks?: string[];
+
+    /**
+     * List of glob patterns to exclude from transformation
+     * By default, all node_modules are excluded.
+     */
+    exclude?: string[];
+  }
+
+  /**
+   * Configuration for react-jitter plugin
+   * Can be either a boolean to enable/disable or an options object
+   */
+  export type ReactJitterConfig = Prettify<ReactJitterOptions>;
+}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "react-jitter",
+  "version": "0.3.0",
+  "description": "A developer tool for debugging React performance issues caused by hook changes and component re-renders.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    },
+    "./runtime": {
+      "types": "./runtime/dist/index.d.ts",
+      "import": "./runtime/dist/index.mjs",
+      "require": "./runtime/dist/index.js"
+    },
+    "./plugin-swc": {
+      "default": "./plugin-swc/swc_plugin_react_jitter.wasm"
+    }
+  },
+  "main": "plugin-swc/swc_plugin_react_jitter.wasm",
+  "types": "./index.d.ts",
+  "typesVersions": {
+    "*": {
+      "runtime": [
+        "runtime/dist/index.d.ts"
+      ],
+      "runtime/*": [
+        "runtime/dist/*"
+      ]
+    }
+  },
+  "files": [
+    "index.d.ts",
+    "plugin-swc/swc_plugin_react_jitter.wasm",
+    "runtime/dist"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "npm run build:runtime && cd plugin-swc && rustup target add wasm32-wasip1 && cargo build --release --target wasm32-wasip1 && cp ./target/wasm32-wasip1/release/swc_plugin_react_jitter.wasm .",
+    "build:debug": "npm run build:runtime && cd plugin-swc && rustup target add wasm32-wasip1 && cargo build --target wasm32-wasip1 && cp ./target/wasm32-wasip1/debug/swc_plugin_react_jitter.wasm .",
+    "build:runtime": "npm run build --prefix runtime",
+    "test": "npm run build && vitest run --testTimeout=0",
+    "test:debug": "TEST_DEBUG=true npm run build:debug && vitest run --testTimeout=0",
+    "cargo:fix": "cd plugin-swc && cargo clippy --fix --all-targets --all-features --allow-dirty -- -D warnings",
+    "release": "npm run build && changeset publish",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "prepare": "husky"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/sidx1024/react-jitter",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sidx1024/react-jitter.git",
+    "directory": ""
+  },
+  "bugs": {
+    "url": "https://github.com/sidx1024/react-jitter/issues"
+  },
+  "author": "sidx1024",
+  "keywords": [
+    "react",
+    "react-hooks",
+    "performance",
+    "re-render",
+    "debug",
+    "developer-tools",
+    "swc",
+    "swc-plugin",
+    "instrumentation"
+  ],
+  "license": "MIT",
+  "workspaces": [
+    ".",
+    "runtime",
+    "plugin-swc"
+  ],
+  "preferUnplugged": true,
+  "dependencies": {
+    "@swc/counter": "^0.1.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.1.3",
+    "@changesets/cli": "^2.29.5",
+    "@swc/core": "^1.12.0",
+    "@types/node": "^22.13.9",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.2",
+    "vitest": "^3.0.7"
+  },
+  "lint-staged": {
+    "ignore": [
+      "runtime/dist/**/*"
+    ],
+    "*.{js,jsx,ts,tsx}": [
+      "biome format --write --no-errors-on-unmatched",
+      "biome lint --no-errors-on-unmatched"
+    ],
+    "*.rs": [
+      "bash -c 'npm run cargo:fix'"
+    ]
+  }
+}

package/runtime/dist/index.d.mts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+
+declare const ScopeSchema: z.ZodObject<{
+    name: z.ZodString;
+    id: z.ZodString;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    offset: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    file: string;
+    line: number;
+    offset: number;
+}, {
+    name: string;
+    id: string;
+    file: string;
+    line: number;
+    offset: number;
+}>;
+declare const HookChangeSchema: z.ZodObject<{
+    unstable: z.ZodBoolean;
+    unstableKeys: z.ZodArray<z.ZodString, "many">;
+    changedKeys: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    unstable: boolean;
+    unstableKeys: string[];
+    changedKeys: string[];
+}, {
+    unstable: boolean;
+    unstableKeys: string[];
+    changedKeys: string[];
+}>;
+type HookChange = z.infer<typeof HookChangeSchema>;
+type HookEndEvent = {
+    id: string;
+    hook: string;
+    file: string;
+    line: number;
+    offset: number;
+    arguments?: string[];
+};
+type ReactJitterOptions = {
+    enabled?: boolean;
+    onHookChange?: (change: HookChange) => void;
+    onRender?: (scope: Scope & {
+        scopeId: string;
+        hookResults: Record<string, unknown>;
+        renderCount: number;
+    }) => void;
+};
+type Scope = z.infer<typeof ScopeSchema>;
+
+type HookCall = HookChange & HookEndEvent & {
+    scope: Scope;
+    previousResult: unknown;
+    currentResult: unknown;
+};
+declare global {
+    interface Window {
+        reactJitter?: {
+            enabled?: boolean;
+            onHookChange?: (change: HookCall) => void;
+            onRender?: (scope: Scope & {
+                hookResults: Record<string, unknown>;
+                renderCount: number;
+            }) => void;
+            clear: () => void;
+        };
+    }
+}
+/**
+ * A React hook that creates a jitter scope for measuring component performance.
+ * @param options Configuration options for the jitter scope
+ * @returns void
+ */
+declare function useJitterScope(scope: Scope): {
+    s: (id: string) => void;
+    e: (hookResult: unknown, hookEndEvent: HookEndEvent) => unknown;
+    re: <T>(renderResult: T) => T;
+};
+declare function reactJitter(options: ReactJitterOptions): void;
+
+export { reactJitter, useJitterScope };

package/runtime/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+
+declare const ScopeSchema: z.ZodObject<{
+    name: z.ZodString;
+    id: z.ZodString;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    offset: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    file: string;
+    line: number;
+    offset: number;
+}, {
+    name: string;
+    id: string;
+    file: string;
+    line: number;
+    offset: number;
+}>;
+declare const HookChangeSchema: z.ZodObject<{
+    unstable: z.ZodBoolean;
+    unstableKeys: z.ZodArray<z.ZodString, "many">;
+    changedKeys: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    unstable: boolean;
+    unstableKeys: string[];
+    changedKeys: string[];
+}, {
+    unstable: boolean;
+    unstableKeys: string[];
+    changedKeys: string[];
+}>;
+type HookChange = z.infer<typeof HookChangeSchema>;
+type HookEndEvent = {
+    id: string;
+    hook: string;
+    file: string;
+    line: number;
+    offset: number;
+    arguments?: string[];
+};
+type ReactJitterOptions = {
+    enabled?: boolean;
+    onHookChange?: (change: HookChange) => void;
+    onRender?: (scope: Scope & {
+        scopeId: string;
+        hookResults: Record<string, unknown>;
+        renderCount: number;
+    }) => void;
+};
+type Scope = z.infer<typeof ScopeSchema>;
+
+type HookCall = HookChange & HookEndEvent & {
+    scope: Scope;
+    previousResult: unknown;
+    currentResult: unknown;
+};
+declare global {
+    interface Window {
+        reactJitter?: {
+            enabled?: boolean;
+            onHookChange?: (change: HookCall) => void;
+            onRender?: (scope: Scope & {
+                hookResults: Record<string, unknown>;
+                renderCount: number;
+            }) => void;
+            clear: () => void;
+        };
+    }
+}
+/**
+ * A React hook that creates a jitter scope for measuring component performance.
+ * @param options Configuration options for the jitter scope
+ * @returns void
+ */
+declare function useJitterScope(scope: Scope): {
+    s: (id: string) => void;
+    e: (hookResult: unknown, hookEndEvent: HookEndEvent) => unknown;
+    re: <T>(renderResult: T) => T;
+};
+declare function reactJitter(options: ReactJitterOptions): void;
+
+export { reactJitter, useJitterScope };

package/runtime/dist/index.js

@@ -0,0 +1,225 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  reactJitter: () => reactJitter,
+  useJitterScope: () => useJitterScope
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = __toESM(require("react"));
+
+// src/utils/getChanges.ts
+var import_fast_equals = require("fast-equals");
+function getChanges(prev, next) {
+  const changedKeys = [];
+  const unstableKeys = [];
+  const isObject = (v) => v !== null && typeof v === "object";
+  const prevIsArr = Array.isArray(prev);
+  const nextIsArr = Array.isArray(next);
+  if (prevIsArr !== nextIsArr) {
+    return {
+      unstable: false,
+      unstableKeys: [],
+      changedKeys: ["*"]
+    };
+  }
+  if (prevIsArr && nextIsArr) {
+    if (prev.length !== next.length) {
+      changedKeys.push("length");
+    }
+    const max = Math.max(prev.length, next.length);
+    for (let i = 0; i < max; i++) {
+      const deepEqItem = (0, import_fast_equals.deepEqual)(prev[i], next[i]);
+      const refDiffItem = isObject(prev[i]) && isObject(next[i]) && prev[i] !== next[i];
+      if (!deepEqItem || refDiffItem) {
+        const key = String(i);
+        changedKeys.push(key);
+        if (refDiffItem && deepEqItem) {
+          unstableKeys.push(key);
+        }
+      }
+    }
+  } else if (isObject(prev) && isObject(next)) {
+    const allKeys = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
+    for (const key of allKeys) {
+      const deepEqProp = (0, import_fast_equals.deepEqual)(prev[key], next[key]);
+      const refDiffProp = isObject(prev[key]) && isObject(next[key]) && prev[key] !== next[key];
+      if (!deepEqProp || refDiffProp) {
+        changedKeys.push(key);
+        if (refDiffProp && deepEqProp) {
+          unstableKeys.push(key);
+        }
+      }
+    }
+  } else {
+    const deepEqRoot = (0, import_fast_equals.deepEqual)(prev, next);
+    const refDiffRoot = isObject(prev) && isObject(next) && prev !== next;
+    const unstable = refDiffRoot && deepEqRoot;
+    const changed = !deepEqRoot || refDiffRoot;
+    return {
+      unstable,
+      unstableKeys: [],
+      changedKeys: changed ? [""] : []
+    };
+  }
+  const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+  const unstableRoot = isPlainObject(prev) && isPlainObject(next) && prev !== next && (0, import_fast_equals.deepEqual)(prev, next);
+  if (unstableRoot && changedKeys.length === 0) {
+    changedKeys.push("");
+    unstableKeys.push("");
+  }
+  return {
+    unstable: unstableKeys.length > 0,
+    unstableKeys,
+    changedKeys
+  };
+}
+
+// src/index.ts
+var scopes = {};
+var hookStack = /* @__PURE__ */ new Map();
+var scopeCounter = {};
+function useJitterScope(scope) {
+  const scopeCount = import_react.default.useRef(getScopeCount(scope)).current;
+  const scopeId = `${scope.id}-${scopeCount}`;
+  if (!scopes[scopeId]) {
+    scopes[scopeId] = {
+      scopeId,
+      renderCount: 0,
+      ...scope,
+      hookResults: {},
+      hookChanges: []
+    };
+  }
+  scopes[scopeId].renderCount++;
+  const hooks = import_react.default.useRef(null);
+  if (!hooks.current) {
+    hooks.current = {
+      s: (id) => {
+        const hookId = `${scopeId}-${id}`;
+        hookStack.set(hookId, null);
+      },
+      e: (hookResult, hookEndEvent) => {
+        const currentScope = scopes[scopeId];
+        if (!currentScope) {
+          return hookResult;
+        }
+        const hookId = `${scopeId}-${hookEndEvent.id}`;
+        if (shouldReportChanges()) {
+          const prevResult = currentScope.hookResults[hookId];
+          const changes = compareChanges(prevResult, hookResult);
+          if (changes) {
+            const hookCall = {
+              hook: hookEndEvent.hook,
+              file: hookEndEvent.file,
+              line: hookEndEvent.line,
+              offset: hookEndEvent.offset,
+              id: hookEndEvent.id,
+              scope,
+              ...changes,
+              previousResult: prevResult,
+              currentResult: hookResult
+            };
+            if (hookEndEvent.arguments) {
+              hookCall.arguments = hookEndEvent.arguments;
+            }
+            scopes[scopeId].hookChanges.push(hookCall);
+            callOnHookChange(hookCall);
+          }
+        }
+        currentScope.hookResults[hookId] = hookResult;
+        hookStack.delete(hookId);
+        return hookResult;
+      },
+      re: (renderResult) => {
+        callOnRender(scopes[scopeId]);
+        return renderResult;
+      }
+    };
+  }
+  return hooks.current;
+}
+function reactJitter(options) {
+  var _a, _b, _c, _d, _e, _f;
+  if (typeof window === "undefined") {
+    return;
+  }
+  const windowGlobal = window;
+  windowGlobal.reactJitter = {
+    enabled: (_b = (_a = windowGlobal.reactJitter) == null ? void 0 : _a.enabled) != null ? _b : options.enabled,
+    onHookChange: (_d = (_c = windowGlobal.reactJitter) == null ? void 0 : _c.onHookChange) != null ? _d : options.onHookChange,
+    onRender: (_f = (_e = windowGlobal.reactJitter) == null ? void 0 : _e.onRender) != null ? _f : options.onRender,
+    clear: () => {
+      Object.keys(scopes).forEach((key) => {
+        scopes[key].renderCount = 0;
+        scopes[key].hookChanges = [];
+        scopes[key].hookResults = {};
+      });
+    }
+  };
+}
+function shouldReportChanges() {
+  var _a;
+  return typeof ((_a = window == null ? void 0 : window.reactJitter) == null ? void 0 : _a.onHookChange) === "function" && window.reactJitter.enabled;
+}
+function callOnHookChange(hookResult) {
+  var _a;
+  if (shouldReportChanges() && ((_a = window.reactJitter) == null ? void 0 : _a.onHookChange)) {
+    window.reactJitter.onHookChange(hookResult);
+  }
+}
+function shouldReportRender() {
+  var _a;
+  return typeof ((_a = window == null ? void 0 : window.reactJitter) == null ? void 0 : _a.onRender) === "function" && window.reactJitter.enabled;
+}
+function callOnRender(scope) {
+  var _a;
+  if (shouldReportRender() && ((_a = window.reactJitter) == null ? void 0 : _a.onRender)) {
+    window.reactJitter.onRender(scope);
+  }
+}
+function getScopeCount(scope) {
+  if (!scopeCounter[scope.id]) {
+    scopeCounter[scope.id] = 0;
+  }
+  return scopeCounter[scope.id]++;
+}
+function compareChanges(prev, current) {
+  if (prev !== "undefined" && prev !== current) {
+    return getChanges(prev, current);
+  }
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  reactJitter,
+  useJitterScope
+});

package/runtime/dist/index.mjs

@@ -0,0 +1,189 @@
+// src/index.ts
+import React from "react";
+
+// src/utils/getChanges.ts
+import { deepEqual } from "fast-equals";
+function getChanges(prev, next) {
+  const changedKeys = [];
+  const unstableKeys = [];
+  const isObject = (v) => v !== null && typeof v === "object";
+  const prevIsArr = Array.isArray(prev);
+  const nextIsArr = Array.isArray(next);
+  if (prevIsArr !== nextIsArr) {
+    return {
+      unstable: false,
+      unstableKeys: [],
+      changedKeys: ["*"]
+    };
+  }
+  if (prevIsArr && nextIsArr) {
+    if (prev.length !== next.length) {
+      changedKeys.push("length");
+    }
+    const max = Math.max(prev.length, next.length);
+    for (let i = 0; i < max; i++) {
+      const deepEqItem = deepEqual(prev[i], next[i]);
+      const refDiffItem = isObject(prev[i]) && isObject(next[i]) && prev[i] !== next[i];
+      if (!deepEqItem || refDiffItem) {
+        const key = String(i);
+        changedKeys.push(key);
+        if (refDiffItem && deepEqItem) {
+          unstableKeys.push(key);
+        }
+      }
+    }
+  } else if (isObject(prev) && isObject(next)) {
+    const allKeys = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
+    for (const key of allKeys) {
+      const deepEqProp = deepEqual(prev[key], next[key]);
+      const refDiffProp = isObject(prev[key]) && isObject(next[key]) && prev[key] !== next[key];
+      if (!deepEqProp || refDiffProp) {
+        changedKeys.push(key);
+        if (refDiffProp && deepEqProp) {
+          unstableKeys.push(key);
+        }
+      }
+    }
+  } else {
+    const deepEqRoot = deepEqual(prev, next);
+    const refDiffRoot = isObject(prev) && isObject(next) && prev !== next;
+    const unstable = refDiffRoot && deepEqRoot;
+    const changed = !deepEqRoot || refDiffRoot;
+    return {
+      unstable,
+      unstableKeys: [],
+      changedKeys: changed ? [""] : []
+    };
+  }
+  const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+  const unstableRoot = isPlainObject(prev) && isPlainObject(next) && prev !== next && deepEqual(prev, next);
+  if (unstableRoot && changedKeys.length === 0) {
+    changedKeys.push("");
+    unstableKeys.push("");
+  }
+  return {
+    unstable: unstableKeys.length > 0,
+    unstableKeys,
+    changedKeys
+  };
+}
+
+// src/index.ts
+var scopes = {};
+var hookStack = /* @__PURE__ */ new Map();
+var scopeCounter = {};
+function useJitterScope(scope) {
+  const scopeCount = React.useRef(getScopeCount(scope)).current;
+  const scopeId = `${scope.id}-${scopeCount}`;
+  if (!scopes[scopeId]) {
+    scopes[scopeId] = {
+      scopeId,
+      renderCount: 0,
+      ...scope,
+      hookResults: {},
+      hookChanges: []
+    };
+  }
+  scopes[scopeId].renderCount++;
+  const hooks = React.useRef(null);
+  if (!hooks.current) {
+    hooks.current = {
+      s: (id) => {
+        const hookId = `${scopeId}-${id}`;
+        hookStack.set(hookId, null);
+      },
+      e: (hookResult, hookEndEvent) => {
+        const currentScope = scopes[scopeId];
+        if (!currentScope) {
+          return hookResult;
+        }
+        const hookId = `${scopeId}-${hookEndEvent.id}`;
+        if (shouldReportChanges()) {
+          const prevResult = currentScope.hookResults[hookId];
+          const changes = compareChanges(prevResult, hookResult);
+          if (changes) {
+            const hookCall = {
+              hook: hookEndEvent.hook,
+              file: hookEndEvent.file,
+              line: hookEndEvent.line,
+              offset: hookEndEvent.offset,
+              id: hookEndEvent.id,
+              scope,
+              ...changes,
+              previousResult: prevResult,
+              currentResult: hookResult
+            };
+            if (hookEndEvent.arguments) {
+              hookCall.arguments = hookEndEvent.arguments;
+            }
+            scopes[scopeId].hookChanges.push(hookCall);
+            callOnHookChange(hookCall);
+          }
+        }
+        currentScope.hookResults[hookId] = hookResult;
+        hookStack.delete(hookId);
+        return hookResult;
+      },
+      re: (renderResult) => {
+        callOnRender(scopes[scopeId]);
+        return renderResult;
+      }
+    };
+  }
+  return hooks.current;
+}
+function reactJitter(options) {
+  var _a, _b, _c, _d, _e, _f;
+  if (typeof window === "undefined") {
+    return;
+  }
+  const windowGlobal = window;
+  windowGlobal.reactJitter = {
+    enabled: (_b = (_a = windowGlobal.reactJitter) == null ? void 0 : _a.enabled) != null ? _b : options.enabled,
+    onHookChange: (_d = (_c = windowGlobal.reactJitter) == null ? void 0 : _c.onHookChange) != null ? _d : options.onHookChange,
+    onRender: (_f = (_e = windowGlobal.reactJitter) == null ? void 0 : _e.onRender) != null ? _f : options.onRender,
+    clear: () => {
+      Object.keys(scopes).forEach((key) => {
+        scopes[key].renderCount = 0;
+        scopes[key].hookChanges = [];
+        scopes[key].hookResults = {};
+      });
+    }
+  };
+}
+function shouldReportChanges() {
+  var _a;
+  return typeof ((_a = window == null ? void 0 : window.reactJitter) == null ? void 0 : _a.onHookChange) === "function" && window.reactJitter.enabled;
+}
+function callOnHookChange(hookResult) {
+  var _a;
+  if (shouldReportChanges() && ((_a = window.reactJitter) == null ? void 0 : _a.onHookChange)) {
+    window.reactJitter.onHookChange(hookResult);
+  }
+}
+function shouldReportRender() {
+  var _a;
+  return typeof ((_a = window == null ? void 0 : window.reactJitter) == null ? void 0 : _a.onRender) === "function" && window.reactJitter.enabled;
+}
+function callOnRender(scope) {
+  var _a;
+  if (shouldReportRender() && ((_a = window.reactJitter) == null ? void 0 : _a.onRender)) {
+    window.reactJitter.onRender(scope);
+  }
+}
+function getScopeCount(scope) {
+  if (!scopeCounter[scope.id]) {
+    scopeCounter[scope.id] = 0;
+  }
+  return scopeCounter[scope.id]++;
+}
+function compareChanges(prev, current) {
+  if (prev !== "undefined" && prev !== current) {
+    return getChanges(prev, current);
+  }
+  return null;
+}
+export {
+  reactJitter,
+  useJitterScope
+};