why-render-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [YEAR] [COPYRIGHT HOLDER]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# Why Render
+
+React DevTools shows that something re-rendered. Why Render shows you why.
+
+Add `useWhyRerender` to any component and get a console diff of exactly which props changed since the last render, so you can immediately tell whether a re-render was caused by a real prop change — or something else entirely.
+
+## Table of Contents
+
+- [Install](#install)
+- [Setup](#setup)
+  - [Wiring up global setup](#wiring-up-global-setup)
+- [Usage](#usage)
+- [Options](#options)
+- [Examples](#examples)
+  - [1. Basic component usage](#1-basic-component-usage)
+  - [2. A component whose props change](#2-a-component-whose-props-change)
+  - [3. A component that re-renders without its props changing](#3-a-component-that-re-renders-without-its-props-changing)
+  - [4. Inspecting previous and next values with `verbose`](#4-inspecting-previous-and-next-values-with-verbose)
+  - [5. Temporarily disabling tracking for one component](#5-temporarily-disabling-tracking-for-one-component)
+  - [6. A realistic parent/child example](#6-a-realistic-parentchild-example)
+- [Expected Output](#expected-output)
+- [Troubleshooting](#troubleshooting)
+
+## Install
+
+```bash
+npm install why-render-react
+```
+
+## Setup
+
+Why Render is off by default. Call `setup()` once, before your app renders, to turn it on:
+
+```ts
+import { setup } from "why-render-react"
+
+setup(true)
+```
+
+`setup()` also accepts strings, so you can wire it to an environment variable:
+
+```ts
+setup(process.env.USE_WHY_RENDER) // enabled only if the value is "true" (case-insensitive)
+```
+
+Pass `false` (or leave it unset) to keep Why Render off:
+
+```ts
+setup(false)
+```
+
+This is a one-time, app-wide switch — call it once at your entry point, not inside individual components.
+
+> **Important:** if any component calls `useWhyRerender` before `setup()` has run, it will throw an error. Always call `setup()` first.
+
+### Wiring up global setup
+
+`setup()` only needs to run once for your whole app — typically in your entry file, before rendering:
+
+```tsx
+// main.tsx
+import { setup } from "why-render-react"
+import { createRoot } from "react-dom/client"
+import App from "./App"
+
+setup(process.env.NODE_ENV !== "production")
+
+createRoot(document.getElementById("root")!).render(<App />)
+```
+
+Every component that calls `useWhyRerender` anywhere in the tree will start (or stop) logging based on that single call. *(full file: [`examples/00-setup.tsx`](./examples/00-setup.tsx))*
+
+## Usage
+
+Add `useWhyRerender` inside any component you want to debug, passing it a name and that component's current props:
+
+```tsx
+import { useWhyRerender } from "why-render-react"
+
+function CarCard(props: CarCardProps) {
+  useWhyRerender({ name: "CarCard", props })
+
+  return <div>{props.color}</div>
+}
+```
+
+It's a React hook, so it follows the same rules as other hooks — call it unconditionally, at the top level of your component. Every time `CarCard` renders, Why Render logs what changed (or didn't) since the last render.
+
+## Options
+
+`useWhyRerender` takes a single options object:
+
+| Option       | Type        | Required | Default   | What it does                                                                                  |
+| ------------ | ----------- | -------- | --------- | --------------------------------------------------------------------------------------------- |
+| `name`     | `string`  | Yes      | —        | The label shown for this component in the console output.                                     |
+| `props`    | `object`  | Yes      | —        | The component's current props to track.                                                       |
+| `verbose`  | `boolean` | No       | `false` | Also logs each changed prop's previous and next value.                                        |
+| `isActive` | `boolean` | No       | `true`  | Set to`false` to turn off logging for just this component, without affecting anything else. |
+
+> Note: the field is `isActive`. If your editor or docs show `isActivate` anywhere, that's an internal naming detail — the option you pass is `isActive`.
+
+## Examples
+
+### 1. Basic component usage
+
+*(full file: [`examples/01-basic-usage.tsx`](./examples/01-basic-usage.tsx))*
+
+```tsx
+function CarCard(props: CarCardProps) {
+  useWhyRerender({ name: "CarCard", props })
+
+  return <div>{props.color}</div>
+}
+```
+
+### 2. A component whose props change
+
+*(full file: [`examples/02-props-change.tsx`](./examples/02-props-change.tsx))*
+
+```tsx
+function CarCard({ color }: { color: string }) {
+  useWhyRerender({ name: "CarCard", props: { color } })
+  return <div>{color}</div>
+}
+
+function Garage() {
+  const [color, setColor] = useState("blue")
+
+  return (
+    <>
+      <button onClick={() => setColor("red")}>Repaint</button>
+      <CarCard color={color} />
+    </>
+  )
+}
+```
+
+Clicking "Repaint" changes `color` and re-renders `CarCard`. The console shows `color` as the prop that changed — confirming the re-render was caused by that prop.
+
+### 3. A component that re-renders without its props changing
+
+Components can re-render for reasons that have nothing to do with their own props — most commonly, because their parent re-rendered. This is exactly the case Why Render helps you catch:
+
+*(full file: [`examples/03-rerender-without-prop-change.tsx`](./examples/03-rerender-without-prop-change.tsx))*
+
+```tsx
+function CarCard({ color }: { color: string }) {
+  useWhyRerender({ name: "CarCard", props: { color } })
+  return <div>{color}</div>
+}
+
+function Garage() {
+  const [, forceTick] = useState(0)
+
+  return (
+    <>
+      {/* Re-renders Garage (and CarCard) every second, but color never changes */}
+      <button onClick={() => forceTick((t) => t + 1)}>Refresh</button>
+      <CarCard color="blue" />
+    </>
+  )
+}
+```
+
+Clicking "Refresh" re-renders `Garage`, which re-renders `CarCard` even though `color` is still `"blue"`. Why Render logs that no props changed on that render — telling you to look at the parent, state, or context instead of the props.
+
+### 4. Inspecting previous and next values with `verbose`
+
+*(full file: [`examples/04-verbose.tsx`](./examples/04-verbose.tsx))*
+
+```tsx
+function CarCard({ color }: { color: string }) {
+  useWhyRerender({ name: "CarCard", props: { color }, verbose: true })
+  return <div>{color}</div>
+}
+```
+
+With `verbose: true`, each changed prop's previous and next value is included in the output, so you don't have to guess what it changed *from* and *to*.
+
+### 5. Temporarily disabling tracking for one component
+
+*(full file: [`examples/05-disable-instance.tsx`](./examples/05-disable-instance.tsx))*
+
+```tsx
+function NoisyWidget(props: NoisyWidgetProps) {
+  useWhyRerender({ name: "NoisyWidget", props, isActive: false })
+  return (/* ... */)
+}
+```
+
+Use this when one component re-renders constantly (e.g. on every keystroke) and its logging is drowning out everything else. Setting `isActive: false` only silences `NoisyWidget` — `setup()` stays enabled, and every other component's `useWhyRerender` call keeps logging normally:
+
+```tsx
+function Dashboard(props: DashboardProps) {
+  useWhyRerender({ name: "Dashboard", props }) // still logs
+
+  return (
+    <>
+      <Sidebar {...sidebarProps} />          {/* still logs */}
+      <NoisyWidget {...widgetProps} />        {/* silenced */}
+    </>
+  )
+}
+```
+
+### 6. A realistic parent/child example
+
+*(full file: [`examples/06-parent-child.tsx`](./examples/06-parent-child.tsx))*
+
+```tsx
+function CarCard({ id, color, onSelect }: CarCardProps) {
+  useWhyRerender({ name: "CarCard", props: { id, color, onSelect }, verbose: true })
+
+  return <div onClick={() => onSelect(id)}>{color}</div>
+}
+
+function CarList({ cars }: { cars: Car[] }) {
+  const [selectedId, setSelectedId] = useState<number | null>(null)
+
+  return (
+    <>
+      {cars.map((car) => (
+        <CarCard
+          key={car.id}
+          id={car.id}
+          color={car.color}
+          // A new function is created on every CarList render, so this prop
+          // "changes" on every render even though the click behavior is the same.
+          onSelect={(id) => setSelectedId(id)}
+        />
+      ))}
+    </>
+  )
+}
+```
+
+Every time `CarList` re-renders (e.g. when `selectedId` changes), each `CarCard` gets a brand-new `onSelect` function. Why Render flags `onSelect` as changed on every render — a common, easy-to-miss cause of unnecessary re-renders that's hard to spot just by eyeballing the code.
+
+## Expected Output
+
+**First render — nothing to compare yet:**
+
+```
+[why-rerender] <CarCard> render #1 → initial mount
+```
+
+**A later render where a prop actually changed** (this line expands to show details):
+
+```
+▶ [why-rerender] <CarCard> render #3 → 1 prop changed
+    CHANGED   color
+```
+
+With `verbose: true`, the same line also includes the previous and next values:
+
+```
+▶ [why-rerender] <CarCard> render #3 → 1 prop changed
+    CHANGED   color   { prev: "blue", next: "red" }
+```
+
+**A render where no props changed** (see [Example 3](#3-a-component-that-re-renders-without-its-props-changing)):
+
+```
+[why-rerender] <CarCard> render #4 → no prop changes — check state, context, or parent re-render
+```
+
+## Troubleshooting
+
+**Error: "WhyRenderConfig has not been configured"** — `setup()` hasn't run yet. Call it once, before your app renders (see [Setup](#setup)).
+
+**Nothing is logging, and no error was thrown** — check:
+
+1. `setup()` was actually called with a value that resolves to enabled — `setup(false)`, a missing environment variable, or a typo like `"tru"` will silently disable it.
+2. That component's call doesn't have `isActive: false` set (see [Example 5](#5-temporarily-disabling-tracking-for-one-component)).
+
+**One component is too noisy to debug around** — set `isActive: false` on that component instead of disabling `setup()` for the whole app.
+
+**A prop keeps showing as "changed" even though it looks the same** — this usually means a new object, array, or function is being created for that prop on every render (see [Example 6](#6-a-realistic-parentchild-example)). Since these are different values in JavaScript even when their contents look identical, Why Render correctly reports them as changed.
+
+# License
+
+### MIT License
+
+Copyright (c) why-render contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/diff.d.ts

@@ -0,0 +1,34 @@
+import type { DIFFERENT_PROPS, PropChange } from "./global/index.t.js";
+/**
+ * Compares a component's previous and current props and returns the
+ * list of props that were added, removed, or changed.
+ *
+ * Values are compared with `Object.is`, so:
+ * - Primitives are compared by value (`NaN` is treated as equal to
+ *   `NaN`; `+0` and `-0` are treated as different).
+ * - Objects, arrays, and functions are compared by reference — a new
+ *   object/array/function on every render (e.g. an inline `() => {}` or
+ *   `{ ...props }`) is reported as `"changed"` even if its contents are
+ *   identical.
+ *
+ * @param prev - Props from the previous render, or `null` on the first
+ * render.
+ * @param next - Props from the current render.
+ *
+ * @returns
+ * An empty array when `prev` is `null` (initial mount) or when no props
+ * differ. Otherwise, one `PropChange` entry per prop that was added,
+ * removed, or changed. Keys are iterated via a `Set` built from
+ * `Object.keys(prev)` followed by `Object.keys(next)`, so ordering
+ * follows first-seen order across the two objects rather than any
+ * guaranteed sort.
+ *
+ * @example
+ * ```ts
+ * diffProps({ prev: { id: 1 }, next: { id: 2 } })
+ * // => [{ prop: "id", prev: 1, next: 2, type: "changed" }]
+ * ```
+ */
+declare const diffProps: ({ prev, next }: DIFFERENT_PROPS) => PropChange[];
+export default diffProps;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,QAAA,MAAM,SAAS,GAAI,gBAAa,eAAe,KAAE,UAAU,EAuB1D,CAAA;AAED,eAAe,SAAS,CAAA"}

package/dist/diff.js

@@ -0,0 +1,55 @@
+/**
+ * Compares a component's previous and current props and returns the
+ * list of props that were added, removed, or changed.
+ *
+ * Values are compared with `Object.is`, so:
+ * - Primitives are compared by value (`NaN` is treated as equal to
+ *   `NaN`; `+0` and `-0` are treated as different).
+ * - Objects, arrays, and functions are compared by reference — a new
+ *   object/array/function on every render (e.g. an inline `() => {}` or
+ *   `{ ...props }`) is reported as `"changed"` even if its contents are
+ *   identical.
+ *
+ * @param prev - Props from the previous render, or `null` on the first
+ * render.
+ * @param next - Props from the current render.
+ *
+ * @returns
+ * An empty array when `prev` is `null` (initial mount) or when no props
+ * differ. Otherwise, one `PropChange` entry per prop that was added,
+ * removed, or changed. Keys are iterated via a `Set` built from
+ * `Object.keys(prev)` followed by `Object.keys(next)`, so ordering
+ * follows first-seen order across the two objects rather than any
+ * guaranteed sort.
+ *
+ * @example
+ * ```ts
+ * diffProps({ prev: { id: 1 }, next: { id: 2 } })
+ * // => [{ prop: "id", prev: 1, next: 2, type: "changed" }]
+ * ```
+ */
+const diffProps = ({ prev, next }) => {
+    if (!prev)
+        return [];
+    const changes = [];
+    const keys = new Set([
+        ...Object.keys(prev),
+        ...Object.keys(next),
+    ]);
+    for (const key of keys) {
+        const inPrev = key in prev;
+        const inNext = key in next;
+        if (!inPrev) {
+            changes.push({ prop: key, prev: undefined, next: next[key], type: "added" });
+        }
+        else if (!inNext) {
+            changes.push({ prop: key, prev: prev[key], next: undefined, type: "removed" });
+        }
+        else if (!Object.is(prev[key], next[key])) {
+            changes.push({ prop: key, prev: prev[key], next: next[key], type: "changed" });
+        }
+    }
+    return changes;
+};
+export default diffProps;
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,SAAS,GAAG,CAAC,EAAC,IAAI,EAAE,IAAI,EAAiB,EAAe,EAAE;IAC5D,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAA;IAEpB,MAAM,OAAO,GAAiB,EAAE,CAAA;IAEhC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC;QACjB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QACpB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;KACvB,CAAC,CAAA;IAEF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,CAAA;QAC1B,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,CAAA;QAE1B,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAC,SAAS,EAAE,IAAI,EAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAC,CAAC,CAAA;QAC5E,CAAC;aAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAC,CAAC,CAAA;QAC9E,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC1C,OAAO,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,SAAS,EAAC,CAAC,CAAA;QAC9E,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAA;AAClB,CAAC,CAAA;AAED,eAAe,SAAS,CAAA"}

package/dist/global/index.t.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Discriminates the kind of change detected for a single prop between
+ * two renders.
+ *
+ * - `"changed"` — the prop exists on both the previous and next render,
+ *   but its value differs (compared with `Object.is`).
+ * - `"added"` — the prop exists on the next render but did not exist on
+ *   the previous render.
+ * - `"removed"` — the prop existed on the previous render but no longer
+ *   exists on the next render.
+ */
+export type PropChangeType = 'changed' | 'added' | 'removed';
+/**
+ * Shape of a component's props object as seen by Why Render.
+ *
+ * This is intentionally a loose `Record<string, unknown>` so that
+ * `useWhyRerender` can accept any component's props without requiring
+ * callers to type them explicitly.
+ */
+export type META_TYPE = Record<string, unknown>;
+/**
+ * Describes a single prop that differs between the previous and the
+ * current render, as produced by `diffProps`.
+ */
+export interface PropChange {
+    /** The prop's key/name. */
+    prop: string;
+    /** The prop's value on the previous render, or `undefined` if it was added. */
+    prev: unknown;
+    /** The prop's value on the current render, or `undefined` if it was removed. */
+    next: unknown;
+    /** What kind of change this is. */
+    type: PropChangeType;
+}
+/**
+ * Input to `diffProps`: the previous and current props objects to
+ * compare.
+ */
+export interface DIFFERENT_PROPS {
+    /**
+     * Props from the previous render, or `null` on the very first render
+     * (in which case `diffProps` returns an empty array).
+     */
+    prev: META_TYPE | null;
+    /** Props from the current render. */
+    next: META_TYPE;
+}
+/**
+ * Identifies a component instance and how many times it has rendered,
+ * used to build the console log header.
+*/
+export interface LabelOptions {
+    /** Human-readable component name, as passed to `useWhyRerender`. */
+    name: string;
+    /** 1-based render count for this component instance. */
+    count: number;
+}
+/**
+ * Options passed to the internal `log` function to print a single
+ * render's console output.
+ */
+export interface LogOptions extends LabelOptions {
+    /**
+     * The list of prop changes to print, or one of two sentinel strings:
+     * `"initial"` for the first render, or `"no-prop-changes"` for a
+     * render the hook determined had no prop changes.
+     */
+    changes: PropChange[] | 'initial' | 'no-prop-changes';
+    /**
+     * When `true`, each changed prop is logged together with its
+     * previous and next values. When `false`, only the prop name and
+     * change type are logged.
+     */
+    verbose: boolean;
+}
+//# sourceMappingURL=index.t.d.ts.map

package/dist/global/index.t.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.t.d.ts","sourceRoot":"","sources":["../../src/global/index.t.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE/C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,EAAE,OAAO,CAAC;IACd,gFAAgF;IAChF,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,cAAc,CAAC;CACxB;AAGD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,qCAAqC;IACrC,IAAI,EAAE,SAAS,CAAC;CACnB;AAGD;;;EAGE;AACF,MAAM,WAAW,YAAY;IACzB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACjB;AAGD;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC5C;;;;OAIG;IACH,OAAO,EAAE,UAAU,EAAE,GAAG,SAAS,GAAG,iBAAiB,CAAC;IACtD;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;CACnB"}

package/dist/global/index.t.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.t.js.map

package/dist/global/index.t.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.t.js","sourceRoot":"","sources":["../../src/global/index.t.ts"],"names":[],"mappings":""}

package/dist/global/useRerender.t.d.ts

@@ -0,0 +1,26 @@
+import type { META_TYPE } from "./index.t.js";
+/**
+ * Arguments accepted by `useWhyRerender`.
+*/
+export interface Rerender {
+    /** Human-readable name for the component, used in console output. */
+    name: string;
+    /** The component's current props to compare against the previous render. */
+    props: META_TYPE;
+    /**
+     * When `true`, logs the previous and next value for each changed
+     * prop. Defaults to `false` when omitted.
+     */
+    verbose?: boolean;
+    /**
+     *Controls whether Why Render should track this component.
+    * Set to `false` to temporarily disable logging for this component.
+    * This does not disable Why Render globally.
+    * @default true
+    * @example
+    *  ```ts
+    * isActivate: false * ```
+    * */
+    isActive?: boolean;
+}
+//# sourceMappingURL=useRerender.t.d.ts.map

package/dist/global/useRerender.t.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRerender.t.d.ts","sourceRoot":"","sources":["../../src/global/useRerender.t.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAG7C;;EAEE;AACF,MAAM,WAAW,QAAQ;IACrB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,EAAC,SAAS,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;;;;;;QAQI;IACJ,QAAQ,CAAC,EAAC,OAAO,CAAA;CACpB"}

package/dist/global/useRerender.t.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useRerender.t.js.map

package/dist/global/useRerender.t.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRerender.t.js","sourceRoot":"","sources":["../../src/global/useRerender.t.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { useWhyRerender, setup } from "./useWhyRerender.js";
+import type { Rerender } from "./global/useRerender.t.js";
+export { useWhyRerender, setup, type Rerender };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,EACH,cAAc,EACd,KAAK,EACL,KAAK,QAAQ,EAChB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+import { useWhyRerender, setup } from "./useWhyRerender.js";
+export { useWhyRerender, setup };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EACH,cAAc,EACd,KAAK,EAER,CAAA"}

package/dist/logger.d.ts

@@ -0,0 +1,25 @@
+import type { LogOptions } from "./global/index.t.js";
+/**
+ * Prints a single render's diagnostic output to the console.
+ *
+ * Behavior depends on `changes`:
+ * - `"initial"` — logs a single `console.log` line noting the initial
+ *   mount.
+ * - `"no-prop-changes"` — logs a single `console.log` line suggesting
+ *   the re-render was caused by state, context, or a parent re-render
+ *   rather than a prop change.
+ * - An array of `PropChange` — opens a collapsed console group
+ *   (`console.groupCollapsed` / `console.groupEnd`) with one color-coded
+ *   `console.log` line per entry, labeled `CHANGED`, `ADDED`, or
+ *   `REMOVED`. When `verbose` is `true`, each line also includes an
+ *   object with the prop's previous and next values.
+ *
+ * This function only produces console output; it has no return value
+ * and throws no errors of its own.
+ *
+ * @param LogOptions - The component name, render count, changes to report,
+ * and verbosity flag.
+ */
+declare const log: ({ name, count, changes, verbose }: LogOptions) => void;
+export default log;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,QAAA,MAAM,GAAG,GAAI,mCAAiC,UAAU,KAAE,IA8BzD,CAAA;AAED,eAAe,GAAG,CAAA"}

package/dist/logger.js

@@ -0,0 +1,47 @@
+import { PAD_SIZE, setBodyText, setHeader, LABEL_STYLE } from "./utils/utils.js";
+/**
+ * Prints a single render's diagnostic output to the console.
+ *
+ * Behavior depends on `changes`:
+ * - `"initial"` — logs a single `console.log` line noting the initial
+ *   mount.
+ * - `"no-prop-changes"` — logs a single `console.log` line suggesting
+ *   the re-render was caused by state, context, or a parent re-render
+ *   rather than a prop change.
+ * - An array of `PropChange` — opens a collapsed console group
+ *   (`console.groupCollapsed` / `console.groupEnd`) with one color-coded
+ *   `console.log` line per entry, labeled `CHANGED`, `ADDED`, or
+ *   `REMOVED`. When `verbose` is `true`, each line also includes an
+ *   object with the prop's previous and next values.
+ *
+ * This function only produces console output; it has no return value
+ * and throws no errors of its own.
+ *
+ * @param LogOptions - The component name, render count, changes to report,
+ * and verbosity flag.
+ */
+const log = ({ name, count, changes, verbose }) => {
+    const header = setHeader({ name, count });
+    if (changes === "initial") {
+        console.log(header, LABEL_STYLE, '→ initial mount');
+        return;
+    }
+    if (changes === "no-prop-changes") {
+        console.log(header, LABEL_STYLE, '→ no prop changes — check state, context, or parent re-render');
+        return;
+    }
+    console.groupCollapsed(header, LABEL_STYLE, `→ ${changes.length} prop${changes.length > 1 ? 's' : ''} changed`);
+    for (const c of changes) {
+        const label = c.type.toUpperCase().padEnd(PAD_SIZE);
+        const typeStyle = setBodyText(c.type);
+        if (verbose) {
+            console.log(`%c ${label} %c${c.prop}`, typeStyle, '', { prev: c.prev, next: c.next });
+        }
+        else {
+            console.log(`%c ${label} %c${c.prop}`, typeStyle, '');
+        }
+    }
+    console.groupEnd();
+};
+export default log;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKjF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,GAAG,GAAG,CAAC,EAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAa,EAAO,EAAE;IAC7D,MAAM,MAAM,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAA;QACnD,OAAO;IACX,CAAC;IAED,IAAI,OAAO,KAAK,iBAAiB,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,+DAA+D,CAAC,CAAA;QACjG,OAAM;IACV,CAAC;IAED,OAAO,CAAC,cAAc,CAClB,MAAM,EACN,WAAW,EACX,KAAK,OAAO,CAAC,MAAM,QAAQ,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,UAAU,CACrE,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACnD,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAErC,IAAI,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;QACzF,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,CAAA;QACzD,CAAC;IACL,CAAC;IACD,OAAO,CAAC,QAAQ,EAAE,CAAA;AAEtB,CAAC,CAAA;AAED,eAAe,GAAG,CAAA"}