bippy 0.6.1 → 0.7.0-dev.697d535

package/README.md

@@ -1,655 +1,415 @@
-> [!WARNING]
-> ⚠️⚠️⚠️ **this project may break production apps and cause unexpected behavior** ⚠️⚠️⚠️
->
-> this project uses react internals, which can change at any time. we don't recommend depending on internals unless you really, _really_ have to. by proceeding, you acknowledge the risk of breaking your own code or apps that use your code.
-
-# <img src="https://github.com/aidenybai/bippy/blob/main/.github/public/bippy.png?raw=true" width="60" align="center" /> bippy
+<h1>
+  <img src="./.github/public/bippy.png" width="48" alt="" valign="middle" />
+  bippy
+</h1>
 
 [![version](https://img.shields.io/npm/v/bippy?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/bippy)
 [![downloads](https://img.shields.io/npm/dt/bippy.svg?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/bippy)
 
-bippy is a toolkit to **hack into react internals**
-
-by default, you cannot access react internals. bippy bypasses this by “pretending” to be react devtools, giving you access to the fiber tree and other internals.
-
-- works outside of react: no react code modification needed
-- utility functions that work across modern react (v17-19)
-- no prior react source code knowledge required
+bippy hacks into React internals.
 
-```jsx
-import { instrument, traverseFiber } from "bippy"; // must be imported BEFORE react
-
-instrument({
-  onCommitFiberRoot(rendererID, root) {
-    traverseFiber(root.current, (fiber) => {
-      // prints every fiber in the current React tree
-      console.log("fiber:", fiber);
-    });
-  },
-});
-```
-
-## how it works & motivation
-
-bippy allows you to **access** and **use** react fibers **outside** of react components.
-
-a react fiber is a “unit of execution.” this means react will do something based on the data in a fiber. each fiber either represents a composite (function/class component) or a host (dom element).
-
-> here is a [live visualization](https://jser.pro/ddir/rie?reactVersion=18.3.1&snippetKey=hq8jm2ylzb9u8eh468) of what the fiber tree looks like, and here is a [deep dive article](https://jser.dev/2023-07-18-how-react-rerenders/).
-
-fibers are useful because they contain information about the react app (component props, state, contexts, etc.). a simplified version of a fiber looks roughly like this:
-
-```typescript
-interface Fiber {
-  // component type (function/class)
-  type: any;
+React keeps its internals out of reach. bippy opens them up for metaprogramming, letting you inspect the [Fiber](https://youtu.be/ZCuYPiUIONs) tree, track renders, and access the renderer directly.
 
-  child: Fiber | null;
-  sibling: Fiber | null;
-
-  // stateNode is the host fiber (e.g. DOM element)
-  stateNode: Node | null;
+> [!WARNING]
+> ⚠️⚠️⚠️ **This project may break production apps and cause unexpected behavior.** ⚠️⚠️⚠️
+>
+> This project uses React internals, which can change at any time. We don’t recommend depending on them unless you have to. By proceeding, you acknowledge the risk of breaking your own code or apps that use your code.
 
-  // parent fiber
-  return: Fiber | null;
+## How React works internally
 
-  // the previous or current version of the fiber
-  alternate: Fiber | null;
+A Fiber is both a node in React’s internal representation of the UI and a unit of work that React can schedule. As a [UI runtime](https://overreacted.io/react-as-a-ui-runtime/), React produces and maintains a tree in a host environment such as the browser. Fiber is the data structure React uses to reconcile that UI.
 
-  // saved props input
-  memoizedProps: any;
+React builds the Fiber tree as it renders your [component tree](https://react.dev/learn/understanding-your-ui-as-a-tree). Each Fiber is a mutable object representing a component, host element, text node, or internal boundary. It stores the node’s props, state, position in the tree, and pending work.
 
-  // state (useState, useReducer, useSES, etc.)
-  memoizedState: any;
+Consider this component tree:
 
-  // contexts (useContext)
-  dependencies: Dependencies | null;
+```tsx
+const Button = () => <button>Save</button>;
 
-  // effects (useEffect, useLayoutEffect, etc.)
-  updateQueue: any;
-}
+const App = () => (
+  <main>
+    <Button />
+  </main>
+);
 ```
 
-here, the `child`, `sibling`, and `return` properties are pointers to other fibers in the tree.
-
-additionally, `memoizedProps`, `memoizedState`, and `dependencies` are the fiber's props, state, and contexts.
-
-while all of the information is there, it's awkward to work with, and changes frequently across different versions of react. bippy simplifies this by providing utility functions like:
-
-- `traverseRenderedFibers` to detect renders and `traverseFiber` to traverse the overall fiber tree
-  - _(instead of `child`, `sibling`, and `return` pointers)_
-- `traverseProps`, `traverseState`, and `traverseContexts` to traverse the fiber's props, state, and contexts
-  - _(instead of `memoizedProps`, `memoizedState`, and `dependencies`)_
-
-however, react doesn't expose fibers to you directly. so, we have to hack our way around to access them.
+Each rendered tree has a [`FiberRoot`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactInternalTypes.js#L212-L221) container. Its `current` field points to the `HostRoot` Fiber at the top of the tree. `HostRoot`, `FunctionComponent`, and `HostComponent` are [React’s internal work tags](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactWorkTags.js#L44-L49).
 
-luckily, react [reads from a property](https://github.com/facebook/react/blob/6a4b46cd70d2672bc4be59dcb5b8dede22ed0cef/packages/react-reconciler/src/ReactFiberDevToolsHook.js#L48) in the window object: `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` and runs handlers on it when certain events happen. this property must exist before react's bundle is executed. this is intended for react devtools, but we can use it to our advantage.
-
-here's what it roughly looks like:
-
-```typescript
-interface __REACT_DEVTOOLS_GLOBAL_HOOK__ {
-  // list of renderers (react-dom, react-native, etc.)
-  renderers: Map<RendererID, reactRenderer>;
-
-  // called when react has rendered everything for an update and the fiber tree is fully built and ready to
-  // apply changes to the host tree (e.g. DOM mutations)
-  onCommitFiberRoot: (rendererID: RendererID, root: FiberRoot, commitPriority?: number) => void;
+```text
+FiberRoot
+└── current → HostRoot Fiber
+              └── App                FunctionComponent
+                  └── main           HostComponent
+                      └── Button     FunctionComponent
+                          └── button HostComponent
+```
 
-  // called when effects run
-  onPostCommitFiberRoot: (rendererID: RendererID, root: FiberRoot) => void;
+Fibers are actual linked objects. React defines their shape in the [`Fiber` type](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactInternalTypes.js#L87-L174) and initializes them in [`FiberNode`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactFiber.js#L134-L173). The host Fiber for `<button>` resembles this object:
 
-  // called when a specific fiber unmounts
-  onCommitFiberUnmount: (rendererID: RendererID, fiber: Fiber) => void;
+```js
+FiberNode {
+  tag: 5,
+  type: "button",
+  stateNode: HTMLButtonElement {},
+  return: FiberNode { … },
+  child: null,
+  sibling: null,
+  memoizedProps: { children: "Save" },
+  flags: 0,
+  alternate: null
 }
 ```
 
-bippy works by monkey-patching `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` with our own custom handlers. bippy simplifies this by providing utility functions like:
+The fields connect React’s component tree, pending work, and rendered output:
 
-- `instrument` to safely patch `window.__REACT_DEVTOOLS_GLOBAL_HOOK__`
-  - _(instead of directly mutating `onCommitFiberRoot`, …)_
-- `traverseRenderedFibers` to traverse the fiber tree and determine which fibers have actually rendered
-  - _(instead of `child`, `sibling`, and `return` pointers)_
-- `traverseFiber` to traverse the fiber tree, regardless of whether it has rendered
-  - _(instead of `child`, `sibling`, and `return` pointers)_
-- `setFiberId` / `getFiberId` to set and get a fiber's id
-  - _(instead of anonymous fibers with no identity)_
+- [`tag`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactInternalTypes.js#L100-L101) identifies the Fiber’s internal node kind
+- [`type`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactInternalTypes.js#L106-L114) identifies the component or host element, while `stateNode` points to its renderer-owned instance
+- [`return`, `child`, and `sibling`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactInternalTypes.js#L122-L131) form the linked tree
+- [`memoizedProps`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactInternalTypes.js#L142-L150) and `memoizedState` contain the inputs used to produce the current output
+- [`flags`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactFiberFlags.js#L14-L52) records work that React must perform during the commit phase
+- [`alternate`](https://github.com/facebook/react/blob/beef6d60f46a97f5c20471df81760fcf365d63ef/packages/react-reconciler/src/ReactFiber.js#L322-L351) links the current Fiber to its work-in-progress counterpart
 
-## how to use
+During an update, React builds a work-in-progress tree beside the current tree. React can pause or discard this work. During the [commit phase](https://react.dev/learn/render-and-commit#step-3-react-commits-changes-to-the-dom), React applies the finished work and makes that tree current.
 
-we recommend installing via npm.
+React does not expose Fiber as a public API. bippy “hacks into React” by accessing it anyway, giving you a consistent way to inspect Fiber trees across React versions and renderers.
 
-import this package before your react app runs. it adds a special object to the global scope that react reports its internals to (react devtools uses the same mechanism). as soon as react loads and attaches, bippy starts collecting data about what is going on in react's internals.
+## Install bippy
+
+Install bippy:
 
 ```shell
 npm install bippy
 ```
 
-since bippy must load before react, some bundlers need specific configuration to get the import order right.
+Import bippy before React or any React renderer.
 
-### next.js
+### Next.js
 
-in next.js 15.3+, use the [`instrumentation-client.js`](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client) file to ensure bippy loads before react. create this file at the root of your application (or inside the `src` folder if you're using the src directory structure):
+Next.js 15.3 and later can load bippy through [`instrumentation-client.ts`](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client). Create the file at the project root or in `src`:
 
 ```typescript
-// instrumentation-client.ts
 import "bippy";
 ```
 
-this file executes before react hydration, making it the ideal place to initialize bippy.
-
-### vite
+### Vite
 
-in vite, import bippy at the very top of your main entry point (typically `src/main.tsx` or `src/main.ts`) before any react imports:
+Import bippy at the top of your Vite entry point, before any React imports:
 
 ```typescript
-// src/main.tsx
 import "bippy";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+```
+
+## API Reference
 
-// ... rest of your code
+### `getFiber`
+
+Returns the Fiber associated with a renderer host instance, such as an element from the Document Object Model (DOM). The result is `null` when no registered renderer recognizes the instance.
+
+```typescript
+import { getFiber } from "bippy";
+
+const element = document.querySelector("button");
+const fiber = getFiber(element);
 ```
 
-the import order is critical: import bippy before any react packages.
+`getFiberFromHostInstance` is an alias for `getFiber`.
 
-> **note for library maintainers**: if you're building a library and want to define your own utility functions while minimizing bundle size, you can use `bippy/install-hook-only` (~90 bytes) instead of the main `bippy` export. this only installs the react devtools hook without importing any utility functions, allowing you to import only what you need from `bippy/core` or define your own fiber utilities. that said, the full `bippy` package is only ~4 KB gzipped, so bundle size is rarely a concern.
+### `useFiber`
 
-> ```typescript
-> import "bippy/install-hook-only"; // only installs the hook
-> import { getRDTHook, traverseFiber } from "bippy/core"; // import only what you need
-> import * as React from "react"; // import react AFTER the hook is installed
->
-> const hook = getRDTHook();
-> // define your own utilities or use only specific ones
-> ```
+Returns the calling component’s Fiber. During server rendering it returns `undefined` because there is no client Fiber for the component.
 
-## API reference
+```tsx
+import { useFiber } from "bippy";
 
-### instrument
+const Component = () => {
+  const fiber = useFiber();
+  console.log(fiber?.type);
+  return null;
+};
+```
+
+### `instrument`
 
-patches `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` with your handlers. import bippy before react, and call `instrument` before any other methods.
+Registers lifecycle handlers and returns an unsubscribe function.
 
-bippy patches each hook event once and dispatches it to a set of listeners, so multiple `instrument` calls compose instead of replacing each other. `instrument` returns an unsubscribe function that removes exactly the handlers you registered (also a `Disposable`, so it works with `using`).
+Available handlers include:
+
+- `onActive`: runs when instrumentation becomes active
+- `onScheduleFiberRoot`: runs when React schedules a root
+- `onCommitFiberRoot`: runs when React commits a root
+- `onPostCommitFiberRoot`: runs after commit effects
+- `onCommitFiberUnmount`: runs when React unmounts a Fiber
 
 ```typescript
-import { instrument } from "bippy"; // must be imported BEFORE react
-import * as React from "react";
+import { instrument } from "bippy";
 
 const unsubscribe = instrument({
-  onCommitFiberRoot(rendererID, root) {
-    console.log("root ready to commit", root);
-  },
-  onPostCommitFiberRoot(rendererID, root) {
-    console.log("root with effects committed", root);
-  },
   onCommitFiberUnmount(rendererID, fiber) {
-    console.log("fiber unmounted", fiber);
+    console.log(rendererID, fiber);
   },
 });
 
-// later, stop listening (other instrument() subscribers keep working)
 unsubscribe();
 ```
 
-### getRDTHook
+Call the returned function to unsubscribe those handlers.
+
+### `getRDTHook`
 
-returns the `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` object. great for advanced use cases, such as accessing or modifying the `renderers` property.
+Returns the React DevTools global hook at `globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__`. Use it to access registered renderers and Fiber roots directly.
 
 ```typescript
 import { getRDTHook } from "bippy";
 
 const hook = getRDTHook();
-console.log(hook);
+console.log(hook.renderers);
 ```
 
-### traverseRenderedFibers
+### `traverseRenderedFibers`
 
-not every fiber in the fiber tree renders. `traverseRenderedFibers` allows you to traverse the fiber tree and determine which fibers have actually rendered.
+Visits Fibers that mounted, updated, or unmounted in a commit. The callback receives the Fiber and its `mount`, `update`, or `unmount` phase.
 
 ```typescript
-import { instrument, traverseRenderedFibers } from "bippy"; // must be imported BEFORE react
-import * as React from "react";
+import { instrument, traverseRenderedFibers } from "bippy";
 
 instrument({
   onCommitFiberRoot(rendererID, root) {
-    traverseRenderedFibers(root, (fiber) => {
-      console.log("fiber rendered", fiber);
+    traverseRenderedFibers(root, (fiber, phase) => {
+      console.log(rendererID, phase, fiber);
     });
   },
 });
 ```
 
-### traverseFiber
+Call it with the same root across commits so bippy can compare the current and previous trees.
 
-calls a callback on every fiber in the fiber tree.
+### `traverseFiber`
 
-```typescript
-import { instrument, traverseFiber } from "bippy"; // must be imported BEFORE react
-import * as React from "react";
-
-instrument({
-  onCommitFiberRoot(rendererID, root) {
-    traverseFiber(root.current, (fiber) => {
-      console.log(fiber);
-    });
-  },
-});
-```
-
-### traverseProps
-
-traverses the props of a fiber.
+Walks down from a Fiber and calls a selector for each node. Return `true` to stop and return the selected Fiber. Pass `true` as the third argument to walk toward the root instead.
 
 ```typescript
-import { traverseProps } from "bippy";
-
-// ...
+import { isHostFiber, traverseFiber } from "bippy";
 
-traverseProps(fiber, (propName, next, prev) => {
-  console.log(propName, next, prev);
+const buttonFiber = traverseFiber(fiber, (candidateFiber) => {
+  return isHostFiber(candidateFiber) && candidateFiber.type === "button";
 });
 ```
 
-### traverseState
-
-traverses the state (`useState`, `useReducer`, etc.) and effects that set state of a fiber.
-
-```typescript
-import { traverseState } from "bippy";
-
-// ...
+The selector can also return a promise. In that case, `traverseFiber` returns a promise for the selected Fiber.
 
-traverseState(fiber, (next, prev) => {
-  console.log(next, prev);
-});
-```
-
-### traverseContexts
+### `didFiberRender`
 
-traverses the contexts (`useContext`) of a fiber.
+Returns whether a Fiber has rendered. It does not identify whether the render happened during a specific commit.
 
 ```typescript
-import { traverseContexts } from "bippy";
+import { didFiberRender } from "bippy";
 
-// ...
-
-traverseContexts(fiber, (next, prev) => {
-  console.log(next, prev);
-});
+console.log(didFiberRender(fiber));
 ```
 
-### setFiberId / getFiberId
+Use `traverseRenderedFibers` to inspect renders from a specific commit.
 
-set and get a persistent identity for a fiber. by default, fibers are anonymous and have no identity.
+### `didFiberCommit`
 
-```typescript
-import { setFiberId, getFiberId } from "bippy";
-
-// ...
-
-setFiberId(fiber);
-console.log("unique id for fiber:", getFiberId(fiber));
-```
-
-### isHostFiber
-
-returns `true` if the fiber is a host fiber (e.g., a DOM node in react-dom).
+Returns whether a Fiber or its subtree has committed work. It does not identify a specific commit.
 
 ```typescript
-import { isHostFiber } from "bippy";
+import { didFiberCommit } from "bippy";
 
-if (isHostFiber(fiber)) {
-  console.log("fiber is a host fiber");
-}
+console.log(didFiberCommit(fiber));
 ```
 
-### isCompositeFiber
+### `setFiberId`
 
-returns `true` if the fiber is a composite fiber. composite fibers represent class components, function components, memoized components, and so on (anything that can actually render output).
+Assigns a numeric ID to a Fiber.
 
 ```typescript
-import { isCompositeFiber } from "bippy";
+import { setFiberId } from "bippy";
 
-if (isCompositeFiber(fiber)) {
-  console.log("fiber is a composite fiber");
-}
+setFiberId(fiber, 123);
 ```
 
-### getDisplayName
+### `getFiberId`
 
-returns the display name of the fiber's component, falling back to the component's function or class name if available.
+Returns a stable numeric ID across Fiber updates. It creates an ID when none has been assigned.
 
 ```typescript
-import { getDisplayName } from "bippy";
+import { getFiberId } from "bippy";
 
-console.log(getDisplayName(fiber));
+const fiberId = getFiberId(fiber);
 ```
 
-### getType
+### `isFiber`
 
-returns the underlying type (the component definition) for a given fiber. for example, this could be a function component or class component.
-
-```jsx
-import { getType } from "bippy";
-import { memo } from "react";
+Returns whether a value contains the core fields required by a Fiber.
 
-const RealComponent = () => {
-  return <div>hello</div>;
-};
-const MemoizedComponent = memo(() => {
-  return <div>hello</div>;
-});
+```typescript
+import { isFiber } from "bippy";
 
-console.log(getType(fiberForMemoizedComponent) === RealComponent);
+console.log(isFiber(value));
 ```
 
-### getNearestHostFiber / getNearestHostFibers
+### `isHostFiber`
 
-`getNearestHostFiber` returns the closest host fiber above or below a given fiber. `getNearestHostFibers` returns all host fibers associated with the provided fiber and its subtree.
+Returns whether a Fiber represents a renderer host instance, such as a DOM element or React Native view.
 
-```jsx
-import { getNearestHostFiber, getNearestHostFibers } from "bippy";
-
-// ...
+```typescript
+import { isHostFiber } from "bippy";
 
-function Component() {
-  return (
-    <>
-      <div>hello</div>
-      <div>world</div>
-    </>
-  );
+if (isHostFiber(fiber)) {
+  console.log(fiber.stateNode);
 }
-
-console.log(getNearestHostFiber(fiberForComponent)); // <div>hello</div>
-console.log(getNearestHostFibers(fiberForComponent)); // [<div>hello</div>, <div>world</div>]
 ```
 
-### getTimings
+### `isCompositeFiber`
 
-returns the self and total render times for the fiber.
+Returns whether a Fiber represents a function, class, memo, or forward-ref component.
 
 ```typescript
-// timings don't exist in react production builds
-if (fiber.actualDuration !== undefined) {
-  const { selfTime, totalTime } = getTimings(fiber);
-  console.log(selfTime, totalTime);
-}
-```
-
-### getFiberStack
-
-returns an array representing the stack of fibers from the current fiber up to the root.
+import { isCompositeFiber } from "bippy";
 
-```typescript
-[fiber, fiber.return, fiber.return.return, ...]
+console.log(isCompositeFiber(fiber));
 ```
 
-### getMutatedHostFibers
+### `hasMemoCache`
 
-returns an array of all host fibers that have committed and rendered in the provided fiber's subtree.
+Returns whether a Fiber uses a React Compiler memo cache.
 
 ```typescript
-import { getMutatedHostFibers } from "bippy";
+import { hasMemoCache } from "bippy";
 
-console.log(getMutatedHostFibers(fiber));
+console.log(hasMemoCache(fiber));
 ```
 
-### isValidFiber
+### `getDisplayName`
 
-returns `true` if the given object is a valid React Fiber (i.e., has a tag, stateNode, return, child, sibling, etc.).
+Returns the display name of a Fiber type.
 
 ```typescript
-import { isValidFiber } from "bippy";
+import { getDisplayName } from "bippy";
 
-console.log(isValidFiber(fiber));
+console.log(getDisplayName(fiber.type));
 ```
 
-### getFiberFromHostInstance
+### `getType`
 
-returns the fiber associated with a given host instance (e.g., a DOM element).
+Unwraps memo and forward-ref wrappers and returns the underlying component definition.
 
 ```typescript
-import { getFiberFromHostInstance } from "bippy";
+import { getType } from "bippy";
 
-const fiber = getFiberFromHostInstance(document.querySelector("div"));
-console.log(fiber);
+console.log(getType(fiber.type));
 ```
 
-### getLatestFiber
+### `getLatestFiber`
 
-returns the latest fiber (since it may be double-buffered). usually use this in combination with `getFiberFromHostInstance`.
+Returns the latest version of a Fiber. Use it when you retain a Fiber across renders.
 
 ```typescript
-import { getLatestFiber } from "bippy";
+import { getFiber, getLatestFiber } from "bippy";
 
-const latestFiber = getLatestFiber(getFiberFromHostInstance(document.querySelector("div")));
-console.log(latestFiber);
+const fiber = getFiber(document.body);
+const latestFiber = fiber ? getLatestFiber(fiber) : null;
 ```
 
-### overrideProps
+### `getRenderer`
 
-overrides component props at runtime by modifying the fiber's props.
+Returns the React renderer that owns a Fiber, or `null` when the renderer is unavailable.
 
 ```typescript
-import { overrideProps } from "bippy";
-
-// override props on a fiber
-overrideProps(fiber, {
-  title: "new title",
-  config: {
-    enabled: true,
-    count: 42,
-  },
-});
+import { getRenderer } from "bippy";
+
+const renderer = getRenderer(fiber);
+renderer?.overrideProps?.(fiber, ["title"], "new title");
+renderer?.scheduleUpdate?.(fiber);
 ```
 
-the function accepts a fiber and a partial object containing the props to override. bippy automatically flattens nested objects into property paths.
+Renderer capabilities are optional and vary by renderer version.
 
-### overrideHookState
+### React internals
 
-overrides hook state (`useState`, `useReducer`, etc.) at runtime by hook id.
+The main `bippy` entry point exports the React internals used by its APIs.
 
 ```typescript
-import { overrideHookState } from "bippy";
-
-// override the first hook (id: 0) with a new value
-overrideHookState(fiber, 0, "new state value");
-
-// override nested state object
-overrideHookState(fiber, 1, {
-  user: {
-    name: "john",
-    age: 30,
-  },
-});
-```
-
-the hook id parameter corresponds to the order of hooks in the component (0-indexed). pass either a primitive value or an object for nested state updates.
-
-### overrideContext
-
-overrides react context values at runtime by finding the appropriate context provider.
+import {
+  MutationMask,
+  ReactBuildType,
+  ReactFiberFlags,
+  ReactSymbols,
+  getReactWorkTags,
+  getReactWorkTagsForFiber,
+  getReactWorkTagsForRenderer,
+} from "bippy";
+import type {
+  Fiber,
+  FiberRoot,
+  ReactDevToolsGlobalHook,
+  ReactRenderer,
+  RendererDispatcherRef,
+} from "bippy";
+```
+
+These definitions follow React’s private implementation and may change between React versions.
+
+### `getSource`
+
+Returns the source location for a Fiber from these renderers:
+
+- DOM
+- Native
+- Terminal
+- Canvas
+- PDF
+- Custom
 
 ```typescript
-import { overrideContext } from "bippy";
-
-// override context value
-overrideContext(fiber, MyContext, {
-  theme: "dark",
-  user: {
-    id: 123,
-    name: "jane",
-  },
-});
+import { getSource } from "bippy/source";
 
-// override with primitive value
-overrideContext(fiber, ThemeContext, "dark");
+const source = await getSource(fiber);
+console.log(source);
 ```
 
-the function traverses up the fiber tree to find the context provider matching the provided context type and overrides its value.
+Production builds may omit source information. Runtimes without `fetch` receive unsymbolicated locations.
 
-### getSource
-
-gets the source code location of a composite fiber.
+Pass a custom `SourceFetch` for packaged bundles, virtual filesystems, or renderer-specific URLs:
 
 ```typescript
-import { getSource } from "bippy/source";
+import { getSource, type SourceFetch } from "bippy/source";
 
-// random fiber on the DOM
-const hostFiber = getFiberFromHostInstance(document.querySelector("div"));
+const sourceFetch: SourceFetch = async (url, init) => {
+  const artifact = sourceArtifacts.get(url);
+  if (!artifact) return fetch(url, init);
 
-// get nearest composite fiber up the tree
-const compositeFiber = traverseFiber(
-  hostFiber,
-  (fiber) => {
-    if (isCompositeFiber(fiber)) {
-      return fiber;
-    }
-  },
-  true,
-);
+  const sourceMapUrl = artifact.sourceMapUrl;
+  const headers = sourceMapUrl ? { SourceMap: sourceMapUrl } : undefined;
+  return new Response(artifact.content, { headers });
+};
 
-const source = await getSource(compositeFiber);
-// {
-//   columnNumber: 12,
-//   fileName: 'path/to/file.tsx',
-//   lineNumber: 12,
-// }
+const source = await getSource(fiber, true, sourceFetch);
 ```
 
-> **caveats:**
->
-> - only available in dev mode
-> - only works for composite fibers (function/class components)
-> - captures the location where the component is _used_, not where it's _defined_
-> - in react 18, resolves `_debugSource` directly (see [react#31981](https://github.com/facebook/react/issues/31981))
-> - in react >18, `_debugSource` is not available for host fibers
-
-### getOwnerStack / getParentStack
-
-returns a symbolicated stack of components above a fiber.
-
-`getOwnerStack` walks the chain of components that _created_ this fiber's JSX (react's `_debugOwner` chain), with exact creation-site locations on react 19, including server component owners. wrappers that merely render `{children}` don't appear. it automatically falls back to `getParentStack` when no usable owner frames exist (e.g. react <19).
+### `getOwnerStack`
 
-`getParentStack` walks _all_ ancestors in the render tree (the fiber's `return` chain), including `{children}` wrappers. works on every react version.
+Returns the symbolicated stack of components that created a Fiber’s JSX. It falls back to the parent stack when owner information is unavailable.
 
 ```typescript
-import { getOwnerStack, getParentStack } from "bippy/source";
+import { getOwnerStack } from "bippy/source";
 
 const ownerFrames = await getOwnerStack(fiber);
-// [{ functionName: "Button", fileName: "src/button.tsx", lineNumber: 12, ... }, ...]
-
-const parentFrames = await getParentStack(fiber);
-// includes every wrapper between the fiber and the root
 ```
 
-### instrumentReactRefresh
+### `getParentStack`
 
-subscribes to fast refresh (HMR) updates from `bippy/react-refresh`. works with any bundler that uses react-refresh (vite, next.js webpack, next.js turbopack, metro) without bundler-specific code: bippy auto-detects the bundler's HMR transport and augments each update with the hot-updated source file paths.
-
-the handler runs after react has re-rendered with the new component types, so `updatedFibers`/`staleFibers` are the mounted fibers matching the hot-swapped component types.
-
-returns an unsubscribe function (a no-op during SSR, so no environment checks needed). the returned function is also a `Disposable`, so it works with `using`.
+Returns the symbolicated stack of every ancestor in a Fiber’s return chain.
 
 ```typescript
-import { instrumentReactRefresh } from "bippy/react-refresh";
-import { getDisplayName } from "bippy";
-
-const unsubscribe = instrumentReactRefresh({
-  onRefresh(update) {
-    for (const fiber of update.updatedFibers) {
-      console.log("hot updated:", getDisplayName(fiber.type));
-    }
-    console.log("changed files:", update.filePaths);
-  },
-});
-
-// later
-unsubscribe();
-```
+import { getParentStack } from "bippy/source";
 
-## example
-
-here's a mini toy version of [`react-scan`](https://github.com/aidenybai/react-scan) that highlights renders in your app.
-
-```javascript
-import { instrument, getNearestHostFiber, traverseRenderedFibers } from "bippy"; // must be imported BEFORE react
-
-const highlightFiber = (fiber) => {
-  if (!(fiber.stateNode instanceof HTMLElement)) return;
-  // fiber.stateNode is a DOM element
-  const rect = fiber.stateNode.getBoundingClientRect();
-  const highlight = document.createElement("div");
-  highlight.style.border = "1px solid red";
-  highlight.style.position = "fixed";
-  highlight.style.top = `${rect.top}px`;
-  highlight.style.left = `${rect.left}px`;
-  highlight.style.width = `${rect.width}px`;
-  highlight.style.height = `${rect.height}px`;
-  highlight.style.zIndex = "999999999";
-  document.documentElement.appendChild(highlight);
-  setTimeout(() => {
-    document.documentElement.removeChild(highlight);
-  }, 100);
-};
-
-/**
- * `instrument` is a function that installs the react DevTools global
- * hook and allows you to set up custom handlers for react fiber events.
- */
-instrument({
-  /**
-   * `onCommitFiberRoot` is a handler that is called when react is
-   * ready to commit a fiber root. this means that react is has
-   * rendered your entire app and is ready to apply changes to
-   * the host tree (e.g. via DOM mutations).
-   */
-  onCommitFiberRoot(rendererID, root) {
-    /**
-     * `traverseRenderedFibers` traverses the fiber tree and determines which
-     * fibers have actually rendered.
-     *
-     * A fiber tree contains many fibers that may have not rendered. this
-     * can be because it bailed out (e.g. `useMemo`) or because it wasn't
-     * actually rendered (if <Child> re-rendered, then <Parent> didn't
-     * actually render, but exists in the fiber tree).
-     */
-    traverseRenderedFibers(root, (fiber) => {
-      /**
-       * `getNearestHostFiber` is a utility function that finds the
-       * nearest host fiber to a given fiber.
-       *
-       * a host fiber for `react-dom` is a fiber that has a DOM element
-       * as its `stateNode`.
-       */
-      const hostFiber = getNearestHostFiber(fiber);
-      highlightFiber(hostFiber);
-    });
-  },
-});
+const parentFrames = await getParentStack(fiber);
 ```
 
-## glossary
-
-- fiber: a “unit of execution” in react, representing a component or dom element
-- commit: the process of applying changes to the host tree (e.g. DOM mutations)
-- render: the process of building the fiber tree by executing component function/classes
-- host tree: the tree of UI elements that react mutates (e.g. DOM elements)
-- reconciler (or “renderer”): custom bindings for react, e.g. react-dom, react-native, react-three-fiber, etc to mutate the host tree
-- `rendererID`: the id of the reconciler, starting at 1 (can be from multiple reconciler instances)
-- `root`: a special `FiberRoot` type that contains the container fiber (the one you pass to `ReactDOM.createRoot`) in the `current` property
-- `onCommitFiberRoot`: called when react is ready to commit a fiber root
-- `onPostCommitFiberRoot`: called when react has committed a fiber root and effects have run
-- `onCommitFiberUnmount`: called when a fiber unmounts
-
-## misc
-
-we initially created bippy for [react-scan](https://github.com/aidenybai/react-scan), which ships with safeguards so it only runs in development or error-guarded in production.
-
-if you're seeking more robust solutions, you might consider [its-fine](https://github.com/pmndrs/its-fine) for accessing fibers within react using hooks, or [react-devtools-inline](https://www.npmjs.com/package/react-devtools-inline) for a headful interface.
-
-if you plan to use this project beyond experimentation, please review [react-scan's source code](https://github.com/aidenybai/react-scan) to understand our safeguarding practices.
+## Acknowledgements
 
-the original bippy character is owned and created by [@dairyfreerice](https://www.instagram.com/dairyfreerice). this project is not related to the bippy brand, i just think the character is cute.
+[@dairyfreerice](https://www.instagram.com/dairyfreerice) created and owns the original bippy character. this project has nothing to do with the bippy brand, i think the character is cute.