How We Rebuilt React DevTools with Replay Routines

• the “backend” logic that is injected into every web page, talks to React as it renders, and collects information about the changes to the React component tree

• The RDT UI components that normally are displayed inside of the browser’s own devtools. The RDT UI layer parses the tree operation data, formats it, and renders the tree of component names.

javascript
<App>           // ID: 24
  <Counters>    // ID: 42
    <Counter>   // ID: 111
    <Counter>   // ID: 173
    <Counter>   // ID: 246

plain text
operations for renderer:1 and root:19
  Re-order node 42 children 111,173,246

json
{
    point: "24663410078278296235742819197649521",
    time: 10696,
    kind: "react-devtools-bridge",
    contents: '{"event":"operations","payload":[1,19,0,3,42,3,111,173,246]}',
  }

typescript
// Snippet: introspect variables in a given stack frame to look
// for objects that appear to be React Fiber instances:
const pause = await client.Session.createPause({ point }, sessionId)
const secondFrame = pause.data.frames![1]
const secondFrameSourceId =
  secondFrame.location[secondFrame.location.length - 2].sourceId
const frameSource = sources.find(
  source => source.sourceId == secondFrameSourceId
)!

if (!frameSource.url!.includes('react-dom')) {
  console.log('Not a React component render')
  return
}

// Get local scope bindings
const localScopeId = secondFrame.scopeChain[0]
const scope = await client.Pause.getScope(
  { scope: localScopeId },
  sessionId,
  pause.pauseId
)

// Loop over the bindings to find the React fiber node
for (const obj of scope.data.scopes![0].bindings!) {
  if (obj.object) {
    const preview = await client.Pause.getObjectPreview(
      { object: obj.object },
      sessionId,
      pause.pauseId
    )

    // more variable introspection omitted
  }
}

javascript
// Some of our custom Chromium "stub" logic:
const stubHook = {
  supportsFiber: true,
  inject,
  onCommitFiberUnmount,
  onCommitFiberRoot,
  onPostCommitFiberRoot,
  renderers: new Map()
}

window.__REACT_DEVTOOLS_SAVED_RENDERERS__ = []

Object.defineProperty(window, '__REACT_DEVTOOLS_GLOBAL_HOOK__', {
  configurable: true,
  enumerable: false,
  get() {
    return stubHook
  }
})

let uidCounter = 0

function inject(renderer) {
  const id = ++uidCounter
  window.__RECORD_REPLAY_ANNOTATION_HOOK__('react-devtools-hook', 'inject')
  window.__REACT_DEVTOOLS_SAVED_RENDERERS__.push(renderer)
  return id
}

function onCommitFiberUnmount(rendererID, fiber) {
  window.__RECORD_REPLAY_ANNOTATION_HOOK__(
    'react-devtools-hook',
    'commit-fiber-unmount'
  )
}

• Each “routine” is written as a separate file that exports an object with {name, version, runRoutine, shouldRun}. Those entries get added to a global list of available routines.

• As a recording is being loaded for debugging, the backend checks each routine entry to see if it should process this recording, based on the recorded browser type and version

• Each routine is spun off as a background task for execution. The routine can use any of our protocol analysis APIs to introspect the recording, and saves new annotations. Those annotations are cached, and will be used on future debugging sessions for this recording.

typescript
interface ExtractedData {
  point: ExecutionPoint
  time: number
  someRoutineSpecificData: number
}

async function runReactDevtoolsRoutine(routine: Routine, cx: Context) {
  // Collect the annotations that were created during the recording.
  // These mark the "interesting" timestamps we want to process.
  const annotations = await routine.getAnnotations(
    'some-annotation-from-our-browser-fork',
    cx
  )

  // For each of those timestamps, do further processing using
  // Replay's protocol API. The exact introspection steps
  // and returned data will be specific to each routine.
  const allPointResults: ExtractedData[] = await Promise.all(
    annotations.map(async annotation => {
      const { point, time, contents } = annotation
      const { message } = JSON.parse(contents)
      const evaluationArgs: EvaluationArgs = {
        routine,
        point,
        cx
      }

      const someRoutineSpecificData = await retrieveUsefulDataForTimestamp(
        evaluationArgs,
        message
      )

      return {
        point,
        time,
        someRoutineSpecificData
      }
    })
  )

  // Save the final annotations with the processed data,
  // so that the Replay client can load these and use for display.
  for (const { point, time, someRoutineSpecificData } of allPointResults) {
    const annotation: Annotation = {
      point,
      time,
      kind: 'some-final-annotation-for-routine',
      contents: JSON.stringify({
        event: 'data',
        payload: someRoutineSpecificData
      })
    }

    routine.addAnnotation(annotation)
  }
}

// Define the routine entry so that the backend can run it as needed
export const ExampleRoutine: RoutineSpec = {
  name: 'Example',
  version: 2,
  runRoutine: runExampleRoutine,
  shouldRun: ({ runtime, date, platform }) => runtime == 'chromium'
}

• Fetch the original in-recording annotations that marked all the timestamps where React had committed an update to the component tree and tried to update the DevTools, as captured by our stub functions inside Chromium

• For each commit timestamp, use pause code evaluation to:
• Delete the stub global “hook” object we’d added to Chromium
• Inject the entire React DevTools global hook installation bundle and evaluate it, so that the real hook exists in that pause point’s browser instance
• Update that global hook with the real React renderer instance, as captured by the stub functions, to match how it would have been configured if the real DevTools had been part of the page originally
• Inject the full RDT “backend” bundle and evaluate it, so that the rest of the RDT logic is in the pause
• Take the arguments that React had passed to our stub callback functions, and forward those to the real RDT hook processing callbacks, so that the RDT backend logic does its normal walk through the component fiber tree and determines what’s changed in this commit
• Capture the final “operations” array, and serialize it back to the routine script

• Map the array of operations+timestamps, and turn those into annotations

• Write the annotations to our backend for persistence

typescript
async function fetchReactOperationsForPoint(
  evaluationArgs: EvaluationArgs,
  type: 'inject' | 'commit-fiber-root' | 'commit-fiber-unmount'
): Promise<number[][]> {
  // Delete the stub `REACT_DEVTOOLS_GLOBAL_HOOK` object from our browser fork,
  // so that we can install the real React DevTools instead.
  await evaluateNoArgsFunction(evaluationArgs, mutateWindowForSetup)
  // Evaluate the actual RDT hook installation file, so that this pause
  // has the initial RDT infrastructure available
  await evaluateNoArgsFunction(evaluationArgs, installHookWrapper)
  await evaluateNoArgsFunction(evaluationArgs, readRenderers)

  // When we install the rest of the RDT backend logic, it will emit an
  // event containing the operations array. Subscribe to that event
  // so that we can capture the array and retrieve it.
  await evaluateNoArgsFunction(evaluationArgs, subscribeToOperations)

  // Evaluate the actual RDT backend logic file, so that the rest of the
  // RDT logic is installed in this pause.
  await evaluateNoArgsFunction(evaluationArgs, reactDevToolsWrapper)

  // Our stub code saved references to the React renderers that were in the page.
  // Force-inject those into the RDT backend so that they're connected properly.
  await evaluateNoArgsFunction(evaluationArgs, injectExistingRenderers)

  // There's two primary React events that we care about:
  // - a "root commit", which adds or rearranges components in the tree
  // - an "unmount" event, which removes a component from the tree
  // In either case, we're paused in our stub wrapper function, with the right
  // function args in the current scope.
  // Call the real RDT hook object function with those arguments, which will
  // do the appropriate tree processing and emit an event with the operations array.
  if (type === 'commit-fiber-root') {
    await evaluateNoArgsFunction(evaluationArgs, forwardOnCommitFiberRoot)
  } else if (type === 'commit-fiber-unmount') {
    await evaluateNoArgsFunction(evaluationArgs, forwardOnCommitFiberUnmount)
  }

  // Serialize the operations array that we captured in a global `window` field.
  const operationsText = await evaluateNoArgsFunction(
    evaluationArgs,
    getOperations
  )
  const { operations } = JSON.parse(operationsText) as {
    operations: number[][]
  }
  return operations
}

• Replay: Chrome + React DevTools integration test - Vite Counter app

• Client-side RDT updates: https://github.com/replayio/devtools/pull/8397

• Chromium stub functions: https://github.com/replayio/chromium/pull/293

• React DevTools fork: https://github.com/replayio/react/compare/main…replayio:react:feature/replay-react-devtools

typescript
/* Copyright 2022 Record Replay Inc. */

// Routine to run the react devtools backend in a recording and generate its operations arrays.

import { Annotation, ExecutionPoint } from '@replayio/protocol'
import { pointStringCompare } from '../../../shared/point'
import { ArrayMap } from '../../../shared/array-map'
import { assert } from '../../../shared/assert'
import { Context } from '../../../shared/context'
import { Routine, RoutineSpec } from '../routine'

const REACT_HOOK_KEY = '__REACT_DEVTOOLS_GLOBAL_HOOK__'

// These are plain JS files that are being imported at build time,
// so that we can stringify the JS functions and send them to be
// evaluated at runtime. We don't currently have a good way to
// include these files as assets in a backend deployment otherwise.
// @ts-ignore
import { reactDevToolsWrapper } from './assets/react_devtools_backend'
// @ts-ignore
import { installHookWrapper } from './assets/installHook'

async function evaluateInTopFrame(
  routine: Routine,
  point: ExecutionPoint,
  expression: string,
  cx: Context
): Promise<string> {
  const pause = await routine.ensurePause(point, cx)
  const frames = await pause.getFrames()
  assert(frames && frames.length, 'No frames for evaluation')

  const topFrameId = frames[0].frameId

  const rv = await pause.evaluate(topFrameId, expression, cx)
  return rv?.value ?? 'null'
}

declare global {
  interface Window {
    testValue: number
    [REACT_HOOK_KEY]: any
    __REACT_DEVTOOLS_SAVED_RENDERERS__: any[]
    savedOperations: number[][]
    evaluationLogs: string[]
    logMessage: (message: string) => void
  }
}

// EVALUATED REMOTE FUNCTIONS:

// Evaluated in the pause to do initial setup
function mutateWindowForSetup() {
  // Makeshift debug logging for code being evaluated in the pause.
  // Call `window.logMessage("abc") into the RDT bundles, and
  // then we retrieve this array at the end to see what happened.
  window.evaluationLogs = []
  window.logMessage = function (message) {
    window.evaluationLogs.push(message)
  }

  // Save the emitted RDT operations from this pause
  window.savedOperations = []

  // Delete the stub hook from our browser fork
  delete window.__REACT_DEVTOOLS_GLOBAL_HOOK__
}

// function readWindow() {
//   return JSON.stringify(window.__REACT_DEVTOOLS_GLOBAL_HOOK__);
// }

function readRenderers() {
  return JSON.stringify({
    renderers: window.__REACT_DEVTOOLS_SAVED_RENDERERS__
  })
}

// function getMessages() {
//   return JSON.stringify({ messages: window.evaluationLogs });
// }

function getOperations() {
  return JSON.stringify({ operations: window.savedOperations })
}

// Evaluated in the pause to connect the saved renderer instances with the RDT backend
function injectExistingRenderers() {
  window.__REACT_DEVTOOLS_SAVED_RENDERERS__.forEach(renderer => {
    window.__REACT_DEVTOOLS_GLOBAL_HOOK__.inject(renderer)
  })
}

// Evaluated in the pause to save emitted operations arrays
function subscribeToOperations() {
  // @ts-ignore
  window.__REACT_DEVTOOLS_GLOBAL_HOOK__.sub('operations', newOperations => {
    window.savedOperations.push(newOperations)
  })
}

// Evaluated in the pause to force the RDT backend to evaluate an unmount
function forwardOnCommitFiberUnmount() {
  const renderer = window.__REACT_DEVTOOLS_GLOBAL_HOOK__.rendererInterfaces.get(
    // @ts-ignore
    rendererID
  )

  // @ts-ignore
  window.__REACT_DEVTOOLS_GLOBAL_HOOK__.onCommitFiberUnmount(
    // @ts-ignore
    rendererID,
    // @ts-ignore
    fiber
  )
  renderer.flushPendingEvents()
}

// Evaluated in the pause to force the RDT backend to evaluate a commit
function forwardOnCommitFiberRoot() {
  // @ts-ignore
  window.__REACT_DEVTOOLS_GLOBAL_HOOK__.onCommitFiberRoot(
    // @ts-ignore
    rendererID,
    // @ts-ignore
    root,
    // @ts-ignore
    priorityLevel
  )
}

interface EvaluationArgs {
  routine: Routine
  point: ExecutionPoint
  cx: Context
}

// Take a function, stringify it, evaluate it in the pause, and return the result
async function evaluateNoArgsFunction(
  evaluationArgs: EvaluationArgs,
  fn: () => any
) {
  const { routine, point, cx } = evaluationArgs
  return evaluateInTopFrame(routine, point, `(${fn})()`, cx)
}

interface OperationsInfo {
  point: ExecutionPoint
  time: number
  operations: number[]
}

// Maximum number of points in the recording we will gather operations from.
// const MaxOperations = 500;

async function fetchReactOperationsForPoint(
  evaluationArgs: EvaluationArgs,
  type: 'inject' | 'commit-fiber-root' | 'commit-fiber-unmount'
): Promise<number[][]> {
  // Delete the stub `REACT_DEVTOOLS_GLOBAL_HOOK` object from our browser fork,
  // so that we can install the real React DevTools instead.
  await evaluateNoArgsFunction(evaluationArgs, mutateWindowForSetup)
  // Evaluate the actual RDT hook installation file, so that this pause
  // has the initial RDT infrastructure available
  await evaluateNoArgsFunction(evaluationArgs, installHookWrapper)
  await evaluateNoArgsFunction(evaluationArgs, readRenderers)

  // When we install the rest of the RDT backend logic, it will emit an
  // event containing the operations array. Subscribe to that event
  // so that we can capture the array and retrieve it.
  await evaluateNoArgsFunction(evaluationArgs, subscribeToOperations)

  // Evaluate the actual RDT backend logic file, so that the rest of the
  // RDT logic is installed in this pause.
  await evaluateNoArgsFunction(evaluationArgs, reactDevToolsWrapper)

  // Our stub code saved references to the React renderers that were in the page.
  // Force-inject those into the RDT backend so that they're connected properly.
  await evaluateNoArgsFunction(evaluationArgs, injectExistingRenderers)

  // There's two primary React events that we care about:
  // - a "root commit", which adds or rearranges components in the tree
  // - an "unmount" event, which removes a component from the tree
  // In either case, we're paused in our stub wrapper function, with the right
  // function args in the current scope.
  // Call the real RDT hook object function with those arguments, which will
  // do the appropriate tree processing and emit an event with the operations array.
  if (type === 'commit-fiber-root') {
    await evaluateNoArgsFunction(evaluationArgs, forwardOnCommitFiberRoot)
  } else if (type === 'commit-fiber-unmount') {
    await evaluateNoArgsFunction(evaluationArgs, forwardOnCommitFiberUnmount)
  }

  // Serialize the operations array that we captured in a global `window` field.
  const operationsText = await evaluateNoArgsFunction(
    evaluationArgs,
    getOperations
  )
  const { operations } = JSON.parse(operationsText) as {
    operations: number[][]
  }
  return operations
}

async function runReactDevtoolsRoutine(routine: Routine, cx: Context) {
  const hookAnnotations: ArrayMap<string, Annotation> = new ArrayMap()

  const annotations = await routine.getAnnotations('react-devtools-hook', cx)
  annotations.forEach(annotation => {
    const { message } = JSON.parse(annotation.contents)
    hookAnnotations.add(message, annotation)
  })

  const fiberCommits = hookAnnotations.map.get('commit-fiber-root') || []
  const fiberUnmounts = hookAnnotations.map.get('commit-fiber-unmount') || []

  const commitsWithUpdates = fiberCommits.concat(fiberUnmounts)
  commitsWithUpdates.sort((a, b) => pointStringCompare(a.point, b.point))

  // TODO Batch these into groups of 25 or so? Also apply MAX_OPERATIONS?
  const allPointResults: OperationsInfo[] = await Promise.all(
    commitsWithUpdates.map(async commitAnnotation => {
      const { point, time, contents } = commitAnnotation
      const { message } = JSON.parse(contents)
      const evaluationArgs: EvaluationArgs = {
        routine,
        point,
        cx
      }

      const operations = await fetchReactOperationsForPoint(
        evaluationArgs,
        message
      )

      return {
        point,
        time,
        operations: operations[0]
      }
    })
  )

  const allOperations = allPointResults.filter(p => !!p.operations)

  // TODO Do we care about MaxOperations? We already did the processing work to fetch them.
  // if (allOperations.length > MaxOperations) {
  //   allOperations.length = MaxOperations;
  // }

  // Unmounts will not know about the current root ID. Normally the backend will
  // set this when flushing the unmount operations during the next onCommitFiberRoot
  // call, but we can fill in the roots ourselves by looking for the next commit.
  for (let i = 0; i < allOperations.length; i++) {
    const { operations } = allOperations[i]
    if (operations[1] === null) {
      for (let j = i + 1; j < allOperations.length; j++) {
        const { operations: laterOperations } = allOperations[j]
        if (
          laterOperations[1] !== null &&
          operations[0] === laterOperations[0]
        ) {
          operations[1] = laterOperations[1]
          break
        }
      }
    }
  }

  const finalCalculatedAnnotations: Annotation[] = []

  for (const { point, time, operations } of allOperations) {
    // Ignore operations which don't include any changes.
    if (operations.length <= 3) {
      continue
    }

    const annotation: Annotation = {
      point,
      time,
      kind: 'react-devtools-bridge',
      contents: JSON.stringify({ event: 'operations', payload: operations })
    }

    finalCalculatedAnnotations.push(annotation)
    cx.logger.debug('BackendOperations', { point, time, operations })
    routine.addAnnotation(annotation)
  }
}

export const ReactDevtoolsRoutine: RoutineSpec = {
  name: 'ReactDevtools',
  version: 2,
  runRoutine: runReactDevtoolsRoutine,
  shouldRun: ({ runtime }) => runtime == 'chromium'
}