From f1878304da92a5ddbe59535ad0d6a3ccc9c170c5 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 22:07:42 -0700
Subject: [PATCH 01/16] feat(react-grab): render scan with copyable performance
 trace

Adds a toolbar render scan that outlines re-rendering components on a
canvas overlay. Stopping the scan copies an agent-readable JSON trace
(per-component render cost ranked by actualDuration, plus
long-animation-frames captured via PerformanceObserver) to the clipboard
and flashes a "Copied" pill on the toolbar. Scan state persists across
reloads via sessionStorage (SSR-guarded) so it survives dev-server HMR.

Structured into focused modules: scan-trace-recorder (DOM-free profiling
model), scanner (canvas outlines), and scan-controller (lifecycle, copy,
persistence). Extracts shared drawRoundedRectangle/parseBorderRadiusValue
utils out of overlay-canvas.
---
 .changeset/render-scan-trace.md               |   5 +
 apps/website-v2/app/layout.tsx                |   5 +-
 .../react-grab/src/components/copied-pill.tsx |  24 ++
 .../src/components/icons/icon-scan.tsx        |  30 +++
 .../src/components/icons/icon-stop.tsx        |  23 ++
 .../src/components/overlay-canvas.tsx         |  40 +--
 .../react-grab/src/components/renderer.tsx    |   3 +
 .../src/components/toolbar/index.tsx          |  54 +++-
 packages/react-grab/src/constants.ts          |  17 ++
 packages/react-grab/src/core/index.tsx        |   8 +
 packages/react-grab/src/core/plugins/scan.ts  |  10 +
 .../react-grab/src/core/scan-controller.ts    |  67 +++++
 .../src/core/scan-trace-recorder.ts           | 152 ++++++++++++
 packages/react-grab/src/core/scanner.ts       | 233 ++++++++++++++++++
 packages/react-grab/src/types.ts              |  38 +++
 .../src/utils/draw-rounded-rectangle.ts       |  31 +++
 .../src/utils/parse-border-radius-value.ts    |   5 +
 .../src/utils/scan-active-storage.ts          |  21 ++
 .../src/utils/serialize-scan-trace.ts         |  51 ++++
 19 files changed, 777 insertions(+), 40 deletions(-)
 create mode 100644 .changeset/render-scan-trace.md
 create mode 100644 packages/react-grab/src/components/copied-pill.tsx
 create mode 100644 packages/react-grab/src/components/icons/icon-scan.tsx
 create mode 100644 packages/react-grab/src/components/icons/icon-stop.tsx
 create mode 100644 packages/react-grab/src/core/plugins/scan.ts
 create mode 100644 packages/react-grab/src/core/scan-controller.ts
 create mode 100644 packages/react-grab/src/core/scan-trace-recorder.ts
 create mode 100644 packages/react-grab/src/core/scanner.ts
 create mode 100644 packages/react-grab/src/utils/draw-rounded-rectangle.ts
 create mode 100644 packages/react-grab/src/utils/parse-border-radius-value.ts
 create mode 100644 packages/react-grab/src/utils/scan-active-storage.ts
 create mode 100644 packages/react-grab/src/utils/serialize-scan-trace.ts

diff --git a/.changeset/render-scan-trace.md b/.changeset/render-scan-trace.md
new file mode 100644
index 000000000..b2575be54
--- /dev/null
+++ b/.changeset/render-scan-trace.md
@@ -0,0 +1,5 @@
+---
+"react-grab": minor
+---
+
+Add a render scan that highlights re-rendering components on a canvas overlay, and copies an agent-readable performance trace (per-component render cost + long-animation-frames) to the clipboard when you stop scanning. The toolbar shows a "Copied" pill on stop, and the scan state persists across reloads via sessionStorage.
diff --git a/apps/website-v2/app/layout.tsx b/apps/website-v2/app/layout.tsx
index 593196d1f..87a615869 100644
--- a/apps/website-v2/app/layout.tsx
+++ b/apps/website-v2/app/layout.tsx
@@ -3,6 +3,7 @@ import { Geist_Mono, Inter } from "next/font/google";
 import { ThemeProvider } from "next-themes";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import "./globals.css";
+import Script from "next/script";
 
 const inter = Inter({
   variable: "--font-inter",
@@ -35,8 +36,10 @@ export default function RootLayout({
       suppressHydrationWarning
       className={`${inter.variable} ${geistMono.variable} antialiased`}
     >
+      <head>
+        <Script src="/script.js" strategy="beforeInteractive" />
+      </head>
       <body>
-        <script src="/script.js" defer />
         <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
           <TooltipProvider>{children}</TooltipProvider>
         </ThemeProvider>
diff --git a/packages/react-grab/src/components/copied-pill.tsx b/packages/react-grab/src/components/copied-pill.tsx
new file mode 100644
index 000000000..e58c6d44e
--- /dev/null
+++ b/packages/react-grab/src/components/copied-pill.tsx
@@ -0,0 +1,24 @@
+import type { Component } from "solid-js";
+import { IconCheck } from "./icons/icon-check.jsx";
+
+interface CopiedPillProps {
+  text: string;
+}
+
+// Static, non-interactive "copied" confirmation pill. Used for passive
+// confirmations (e.g. the toolbar scan-trace toast) that only need to show a
+// message, without the focus/keyboard/dismiss machinery of CompletionView.
+export const CopiedPill: Component<CopiedPillProps> = (props) => {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      class="contain-layout shrink-0 flex items-center gap-0.5 py-1.5 px-2 w-fit h-fit max-w-[280px] rounded-full antialiased bg-[var(--rg-panel-bg)] [font-synthesis:none]"
+    >
+      <IconCheck size={14} aria-hidden="true" class="text-[var(--rg-text-primary-85)] shrink-0" />
+      <span class="text-[var(--rg-text-primary)] text-[13px] leading-4 font-sans font-medium h-fit tabular-nums overflow-hidden text-ellipsis whitespace-nowrap min-w-0">
+        {props.text}
+      </span>
+    </div>
+  );
+};
diff --git a/packages/react-grab/src/components/icons/icon-scan.tsx b/packages/react-grab/src/components/icons/icon-scan.tsx
new file mode 100644
index 000000000..2be5688e4
--- /dev/null
+++ b/packages/react-grab/src/components/icons/icon-scan.tsx
@@ -0,0 +1,30 @@
+import type { Component } from "solid-js";
+
+interface IconScanProps {
+  size?: number;
+  class?: string;
+}
+
+export const IconScan: Component<IconScanProps> = (props) => {
+  const size = () => props.size ?? 14;
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size()}
+      height={size()}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class={props.class}
+    >
+      <path d="M3 7V5a2 2 0 0 1 2-2h2" />
+      <path d="M17 3h2a2 2 0 0 1 2 2v2" />
+      <path d="M21 17v2a2 2 0 0 1-2 2h-2" />
+      <path d="M7 21H5a2 2 0 0 1-2-2v-2" />
+    </svg>
+  );
+};
diff --git a/packages/react-grab/src/components/icons/icon-stop.tsx b/packages/react-grab/src/components/icons/icon-stop.tsx
new file mode 100644
index 000000000..0302cb314
--- /dev/null
+++ b/packages/react-grab/src/components/icons/icon-stop.tsx
@@ -0,0 +1,23 @@
+import type { Component } from "solid-js";
+
+interface IconStopProps {
+  size?: number;
+  class?: string;
+}
+
+export const IconStop: Component<IconStopProps> = (props) => {
+  const size = () => props.size ?? 14;
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size()}
+      height={size()}
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      class={props.class}
+    >
+      <rect x="5" y="5" width="14" height="14" rx="3.5" />
+    </svg>
+  );
+};
diff --git a/packages/react-grab/src/components/overlay-canvas.tsx b/packages/react-grab/src/components/overlay-canvas.tsx
index b505003bc..cfcf5b078 100644
--- a/packages/react-grab/src/components/overlay-canvas.tsx
+++ b/packages/react-grab/src/components/overlay-canvas.tsx
@@ -19,6 +19,8 @@ import {
 import { nativeCancelAnimationFrame, nativeRequestAnimationFrame } from "../utils/native-raf.js";
 import { supportsDisplayP3 } from "../utils/supports-display-p3.js";
 import { adjustLerpForFrameDuration } from "../utils/adjust-lerp-for-frame-duration.js";
+import { parseBorderRadiusValue } from "../utils/parse-border-radius-value.js";
+import { drawRoundedRectangle } from "../utils/draw-rounded-rectangle.js";
 
 const DEFAULT_LAYER_STYLE = {
   borderColor: OVERLAY_BORDER_COLOR_DEFAULT,
@@ -130,12 +132,6 @@ export const OverlayCanvas: Component<OverlayCanvasProps> = (props) => {
     }
   };
 
-  const parseBorderRadiusValue = (borderRadius: string): number => {
-    if (!borderRadius) return 0;
-    const match = borderRadius.match(/^(\d+(?:\.\d+)?)/);
-    return match ? parseFloat(match[1]) : 0;
-  };
-
   const createAnimatedBounds = (
     id: string,
     bounds: OverlayBounds,
@@ -181,38 +177,6 @@ export const OverlayCanvas: Component<OverlayCanvasProps> = (props) => {
   const resolveBoundsArray = (instance: SelectionLabelInstance): OverlayBounds[] =>
     instance.boundsMultiple ?? [instance.bounds];
 
-  const drawRoundedRectangle = (
-    context: OffscreenCanvasRenderingContext2D,
-    rectX: number,
-    rectY: number,
-    rectWidth: number,
-    rectHeight: number,
-    cornerRadius: number,
-    fillColor: string,
-    strokeColor: string,
-    opacity: number = 1,
-  ) => {
-    if (rectWidth <= 0 || rectHeight <= 0) return;
-
-    const maxCornerRadius = Math.min(rectWidth / 2, rectHeight / 2);
-    const clampedCornerRadius = Math.min(cornerRadius, maxCornerRadius);
-
-    const shouldSetGlobalAlpha = opacity !== 1;
-    if (shouldSetGlobalAlpha) context.globalAlpha = opacity;
-    context.beginPath();
-    if (clampedCornerRadius > 0) {
-      context.roundRect(rectX, rectY, rectWidth, rectHeight, clampedCornerRadius);
-    } else {
-      context.rect(rectX, rectY, rectWidth, rectHeight);
-    }
-    context.fillStyle = fillColor;
-    context.fill();
-    context.strokeStyle = strokeColor;
-    context.lineWidth = 1;
-    context.stroke();
-    if (shouldSetGlobalAlpha) context.globalAlpha = 1;
-  };
-
   const renderDragLayer = () => {
     const layer = layers.drag;
     if (!layer.context) return;
diff --git a/packages/react-grab/src/components/renderer.tsx b/packages/react-grab/src/components/renderer.tsx
index b6d8c83de..3532d2351 100644
--- a/packages/react-grab/src/components/renderer.tsx
+++ b/packages/react-grab/src/components/renderer.tsx
@@ -143,6 +143,9 @@ export const ReactGrabRenderer: Component<ReactGrabRendererProps> = (props) => {
       <Show when={props.toolbarVisible !== false}>
         <Toolbar
           isActive={props.isActive}
+          isScanning={props.isScanning}
+          onToggleScan={props.onToggleScan}
+          scanCopied={props.scanCopied}
           isContextMenuOpen={props.contextMenuPosition !== null}
           onToggle={props.onToggleActive}
           onActivateAction={props.onActivateAction}
diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index 3f89fa017..ffedf85e3 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -1,10 +1,13 @@
-import { createEffect, createSignal, on, onCleanup, onMount, type Component } from "solid-js";
+import { createEffect, createSignal, on, onCleanup, onMount, Show, type Component } from "solid-js";
 import type { Position } from "../../types.js";
 import { cn } from "../../utils/cn.js";
+import { CopiedPill } from "../copied-pill.js";
 import { loadToolbarState, saveToolbarState, type SnapEdge, type ToolbarState } from "./state.js";
 import { IconSelect } from "../icons/icon-select.jsx";
 import { IconComment } from "../icons/icon-comment.jsx";
 import { IconStyle } from "../icons/icon-style.jsx";
+import { IconScan } from "../icons/icon-scan.jsx";
+import { IconStop } from "../icons/icon-stop.jsx";
 import { ToolbarActionButton } from "./toolbar-action-button.jsx";
 import {
   TOOLBAR_SNAP_MARGIN_PX,
@@ -19,6 +22,8 @@ import {
   DEFAULT_ACTION_ID,
   COMMENT_ACTION_ID,
   EDIT_ACTION_ID,
+  SCAN_ACTION_ID,
+  LABEL_GAP_PX,
 } from "../../constants.js";
 import { freezeUpdates } from "../../utils/freeze-updates.js";
 import { freezeGlobalAnimations, unfreezeGlobalAnimations } from "../../utils/freeze-animations.js";
@@ -39,6 +44,9 @@ import { accumulateRotationDeg } from "../../utils/accumulate-rotation.js";
 
 interface ToolbarProps {
   isActive?: boolean;
+  isScanning?: boolean;
+  onToggleScan?: () => void;
+  scanCopied?: boolean;
   isContextMenuOpen?: boolean;
   onToggle?: () => void;
   onActivateAction?: (actionId: string) => void;
@@ -146,6 +154,20 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
     }
   };
 
+  const scanCopiedToastStyle = (): Record<string, string> => {
+    const gap = `calc(100% + ${LABEL_GAP_PX}px)`;
+    switch (tooltipPosition()) {
+      case "bottom":
+        return { top: gap, left: "50%", transform: "translateX(-50%)" };
+      case "left":
+        return { right: gap, top: "50%", transform: "translateY(-50%)" };
+      case "right":
+        return { left: gap, top: "50%", transform: "translateY(-50%)" };
+      default:
+        return { bottom: gap, left: "50%", transform: "translateX(-50%)" };
+    }
+  };
+
   const stopEventPropagation = (event: Event) => {
     event.stopImmediatePropagation();
   };
@@ -281,6 +303,7 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
     props.onActivateAction?.(COMMENT_ACTION_ID),
   );
   const handleStyle = drag.createDragAwareHandler(() => props.onActivateAction?.(EDIT_ACTION_ID));
+  const handleScan = drag.createDragAwareHandler(() => props.onToggleScan?.());
 
   const actionButtonClass =
     "group contain-layout flex items-center justify-center cursor-pointer interactive-scale a11y-hitbox";
@@ -655,6 +678,15 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
         props.onSelectHoverChange?.(false);
       }}
     >
+      <Show when={props.scanCopied}>
+        <div
+          data-react-grab-scan-copied
+          class="absolute pointer-events-none"
+          style={scanCopiedToastStyle()}
+        >
+          <CopiedPill text="Copied performance trace" />
+        </div>
+      </Show>
       <ToolbarContent
         isCollapsed={isCollapsed()}
         snapEdge={snapEdge()}
@@ -747,6 +779,26 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
               tooltipPosition={tooltipPosition()}
               tooltip="Style"
             />
+            <ToolbarActionButton
+              actionId={SCAN_ACTION_ID}
+              isToggle
+              label={props.isScanning ? "Stop scanning renders" : "Scan renders"}
+              isActive={Boolean(props.isScanning)}
+              class={actionButtonClass}
+              wrapperClass={actionButtonWrapperClass()}
+              onClick={handleScan}
+              {...createFreezeHandlers(SCAN_ACTION_ID, { shouldFreezeInteractions: false })}
+              icon={
+                props.isScanning ? (
+                  <IconStop size={14} class={actionIconClass(true)} />
+                ) : (
+                  <IconScan size={14} class={actionIconClass(false)} />
+                )
+              }
+              tooltipVisible={isTooltipVisible(SCAN_ACTION_ID) && !props.isScanning}
+              tooltipPosition={tooltipPosition()}
+              tooltip="Scan"
+            />
           </>
         }
       />
diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index e9f6a9568..1e13946d5 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -135,6 +135,23 @@ export const TOOLBAR_DEFAULT_POSITION_RATIO = 0.5;
 export const DEFAULT_ACTION_ID = "copy";
 export const COMMENT_ACTION_ID = "comment";
 export const EDIT_ACTION_ID = "edit";
+export const SCAN_ACTION_ID = "scan";
+
+// Render-scan overlay (bippy-driven re-render outlines). Reuses the shared
+// overlay pink (OVERLAY_*_COLOR_DEFAULT) and rounded-rect drawing; the scan
+// canvas lives outside the overlay shadow root, so it sits one step below the
+// overlay canvas to keep the selection/toolbar layers visually on top.
+export const Z_INDEX_SCAN_CANVAS = Z_INDEX_OVERLAY_CANVAS - 1;
+export const SCAN_OUTLINE_DURATION_MS = 900;
+export const LONG_ANIMATION_FRAME_ENTRY_TYPE = "long-animation-frame";
+export const MAX_SCAN_TRACE_COMPONENTS = 100;
+export const MAX_SCAN_TRACE_LOAF_ENTRIES = 100;
+export const MAX_SCAN_TRACE_LOAF_SCRIPTS = 10;
+export const SCAN_LABEL_TEXT_COLOR = "rgba(255, 255, 255, 0.95)";
+export const SCAN_LABEL_HEIGHT_PX = 15;
+export const SCAN_LABEL_PADDING_PX = 4;
+export const SCAN_LABEL_FONT =
+  "11px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
 
 export const TOOLTIP_DELAY_MS = 400;
 export const TOOLTIP_GRACE_PERIOD_MS = 800;
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index f78945325..8aa5e3021 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -126,6 +126,8 @@ import { copyPlugin } from "./plugins/copy.js";
 import { commentPlugin } from "./plugins/comment.js";
 import { editPlugin } from "./plugins/edit.js";
 import { openPlugin } from "./plugins/open.js";
+import { createScanPlugin } from "./plugins/scan.js";
+import { createScanController } from "./scan-controller.js";
 import {
   freezeAnimations,
   freezeAllAnimations,
@@ -1601,6 +1603,8 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       handleActivateAction(currentToolbarState()?.defaultAction ?? DEFAULT_ACTION_ID);
     };
 
+    const scanController = createScanController();
+
     const enterCommentModeForElement = (element: Element, positionX: number, positionY: number) => {
       actions.setPendingCommentMode(false);
       actions.clearInputText();
@@ -3587,6 +3591,9 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
                 toolbarVisible={pluginRegistry.store.theme.toolbar.enabled}
                 isActive={isActivated()}
                 onToggleActive={handleToggleActive}
+                isScanning={scanController.isScanning()}
+                onToggleScan={scanController.toggle}
+                scanCopied={scanController.scanCopied()}
                 onActivateAction={handleActivateAction}
                 activeActionId={activeActionId()}
                 enabled={isEnabled()}
@@ -3760,6 +3767,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
     for (const plugin of builtInPlugins) {
       pluginRegistry.register(plugin, api);
     }
+    pluginRegistry.register(createScanPlugin(scanController.scanner), api);
 
     setTimeout(() => {
       isNextProjectRuntime(true);
diff --git a/packages/react-grab/src/core/plugins/scan.ts b/packages/react-grab/src/core/plugins/scan.ts
new file mode 100644
index 000000000..bca368234
--- /dev/null
+++ b/packages/react-grab/src/core/plugins/scan.ts
@@ -0,0 +1,10 @@
+import type { Plugin } from "../../types.js";
+import type { ScannerController } from "../scanner.js";
+import { SCAN_ACTION_ID } from "../../constants.js";
+
+export const createScanPlugin = (scanner: ScannerController): Plugin => ({
+  name: SCAN_ACTION_ID,
+  setup: () => ({
+    cleanup: () => scanner.stop(),
+  }),
+});
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
new file mode 100644
index 000000000..00a2f7402
--- /dev/null
+++ b/packages/react-grab/src/core/scan-controller.ts
@@ -0,0 +1,67 @@
+import { createSignal, onCleanup, type Accessor } from "solid-js";
+import { FEEDBACK_DURATION_MS } from "../constants.js";
+import { copyContent } from "../utils/copy-content.js";
+import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
+import { loadScanActive, saveScanActive } from "../utils/scan-active-storage.js";
+import { createScanner, type ScannerController } from "./scanner.js";
+
+export interface ScanController {
+  scanner: ScannerController;
+  isScanning: Accessor<boolean>;
+  scanCopied: Accessor<boolean>;
+  toggle: () => void;
+}
+
+// Owns the full scan lifecycle: the canvas scanner, the reactive scanning
+// state, clipboard copy of the trace on stop, the transient "copied" toast,
+// and persistence across reloads. Must run inside a reactive owner.
+export const createScanController = (): ScanController => {
+  const scanner = createScanner();
+  const [isScanning, setIsScanning] = createSignal(false);
+  const [scanCopied, setScanCopied] = createSignal(false);
+  let scanCopiedTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  const flashCopied = () => {
+    setScanCopied(true);
+    clearTimeout(scanCopiedTimeout);
+    scanCopiedTimeout = setTimeout(() => setScanCopied(false), FEEDBACK_DURATION_MS);
+  };
+
+  const toggle = () => {
+    const wasScanning = scanner.isScanning();
+    scanner.toggle();
+    const nowScanning = scanner.isScanning();
+    setIsScanning(nowScanning);
+    saveScanActive(nowScanning);
+    if (!wasScanning || nowScanning) return;
+    const trace = scanner.takeTrace();
+    if (!trace) return;
+    if (copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
+      flashCopied();
+    }
+  };
+
+  // Persisting across reloads keeps the scan running through dev-server HMR
+  // restarts. Defer to DOMContentLoaded so the scanner's canvas has a
+  // document.body to attach to.
+  const restore = () => {
+    if (!loadScanActive() || scanner.isScanning()) return;
+    scanner.start();
+    setIsScanning(true);
+  };
+  if (typeof document !== "undefined") {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", restore, { once: true });
+      onCleanup(() => document.removeEventListener("DOMContentLoaded", restore));
+    } else {
+      restore();
+    }
+  }
+
+  onCleanup(() => {
+    clearTimeout(scanCopiedTimeout);
+    scanner.dispose();
+  });
+
+  return { scanner, isScanning, scanCopied, toggle };
+};
diff --git a/packages/react-grab/src/core/scan-trace-recorder.ts b/packages/react-grab/src/core/scan-trace-recorder.ts
new file mode 100644
index 000000000..2ffb25c92
--- /dev/null
+++ b/packages/react-grab/src/core/scan-trace-recorder.ts
@@ -0,0 +1,152 @@
+import type { Fiber } from "bippy";
+import {
+  LONG_ANIMATION_FRAME_ENTRY_TYPE,
+  MAX_SCAN_TRACE_COMPONENTS,
+  MAX_SCAN_TRACE_LOAF_ENTRIES,
+  MAX_SCAN_TRACE_LOAF_SCRIPTS,
+} from "../constants.js";
+import type {
+  ScanComponentProfile,
+  ScanLoafScript,
+  ScanLongAnimationFrame,
+  ScanTrace,
+} from "../types.js";
+
+// The `long-animation-frame` entry shape is not yet in the DOM lib types, so
+// we model the fields we read off PerformanceObserver entries here.
+interface LongAnimationFrameScriptTiming {
+  invoker?: string;
+  invokerType?: string;
+  sourceURL?: string;
+  sourceFunctionName?: string;
+  duration?: number;
+  forcedStyleAndLayoutDuration?: number;
+}
+
+interface LongAnimationFrameTiming extends PerformanceEntry {
+  renderStart?: number;
+  styleAndLayoutStart?: number;
+  blockingDuration?: number;
+  scripts?: LongAnimationFrameScriptTiming[];
+}
+
+export interface ScanTraceRecorder {
+  begin: () => void;
+  end: () => void;
+  beginCommit: (timestamp: number) => void;
+  recordFiber: (componentName: string, fiber: Fiber) => void;
+  takeTrace: () => ScanTrace | null;
+}
+
+const isLongAnimationFrameSupported = (): boolean =>
+  typeof PerformanceObserver !== "undefined" &&
+  Boolean(PerformanceObserver.supportedEntryTypes?.includes(LONG_ANIMATION_FRAME_ENTRY_TYPE));
+
+// Pure, DOM-free profiling model: accumulates per-component render cost and
+// long-animation-frame entries over a scan session. Kept separate from the
+// canvas scanner so it can be reasoned about and tested on its own.
+export const createScanTraceRecorder = (): ScanTraceRecorder => {
+  const componentProfiles = new Map<string, ScanComponentProfile>();
+  const longAnimationFrames: ScanLongAnimationFrame[] = [];
+  let commitCount = 0;
+  let scanStartTimestamp = 0;
+  let scanStartEpochMs = 0;
+  let currentCommitTimestamp = 0;
+  let observer: PerformanceObserver | null = null;
+
+  const recordLongAnimationFrames = (list: PerformanceObserverEntryList): void => {
+    for (const entry of list.getEntries()) {
+      if (longAnimationFrames.length >= MAX_SCAN_TRACE_LOAF_ENTRIES) break;
+      // getEntries() is typed as the base PerformanceEntry; the runtime entry
+      // carries the long-animation-frame fields modeled above.
+      const loafEntry = entry as LongAnimationFrameTiming;
+      const scripts: ScanLoafScript[] = (loafEntry.scripts ?? [])
+        .slice(0, MAX_SCAN_TRACE_LOAF_SCRIPTS)
+        .map((script) => ({
+          invoker: script.invoker ?? "",
+          invokerType: script.invokerType ?? "",
+          sourceURL: script.sourceURL ?? "",
+          sourceFunctionName: script.sourceFunctionName ?? "",
+          durationMs: script.duration ?? 0,
+          forcedStyleAndLayoutDurationMs: script.forcedStyleAndLayoutDuration ?? 0,
+        }));
+      longAnimationFrames.push({
+        startTimeMs: loafEntry.startTime,
+        durationMs: loafEntry.duration,
+        blockingDurationMs: loafEntry.blockingDuration ?? 0,
+        renderStartMs: loafEntry.renderStart ?? 0,
+        styleAndLayoutStartMs: loafEntry.styleAndLayoutStart ?? 0,
+        scripts,
+      });
+    }
+  };
+
+  const begin = (): void => {
+    componentProfiles.clear();
+    longAnimationFrames.length = 0;
+    commitCount = 0;
+    scanStartTimestamp = performance.now();
+    scanStartEpochMs = Date.now();
+    if (!isLongAnimationFrameSupported()) return;
+    observer = new PerformanceObserver(recordLongAnimationFrames);
+    try {
+      observer.observe({ type: LONG_ANIMATION_FRAME_ENTRY_TYPE, buffered: false });
+    } catch {
+      observer = null;
+    }
+  };
+
+  const end = (): void => {
+    observer?.disconnect();
+    observer = null;
+  };
+
+  const beginCommit = (timestamp: number): void => {
+    currentCommitTimestamp = timestamp;
+    commitCount += 1;
+  };
+
+  const recordFiber = (componentName: string, fiber: Fiber): void => {
+    const actualDurationMs = fiber.actualDuration ?? 0;
+    const selfDurationMs = fiber.selfBaseDuration ?? 0;
+    const existingProfile = componentProfiles.get(componentName);
+    if (existingProfile) {
+      existingProfile.renderCount += 1;
+      existingProfile.totalActualDurationMs += actualDurationMs;
+      existingProfile.totalSelfDurationMs += selfDurationMs;
+      if (actualDurationMs > existingProfile.maxActualDurationMs) {
+        existingProfile.maxActualDurationMs = actualDurationMs;
+      }
+      existingProfile.lastRenderTimestamp = currentCommitTimestamp;
+    } else {
+      componentProfiles.set(componentName, {
+        componentName,
+        renderCount: 1,
+        totalActualDurationMs: actualDurationMs,
+        maxActualDurationMs: actualDurationMs,
+        totalSelfDurationMs: selfDurationMs,
+        lastRenderTimestamp: currentCommitTimestamp,
+      });
+    }
+  };
+
+  const takeTrace = (): ScanTrace | null => {
+    if (componentProfiles.size === 0 && longAnimationFrames.length === 0) return null;
+    const components = Array.from(componentProfiles.values())
+      .sort(
+        (first, second) =>
+          second.totalActualDurationMs - first.totalActualDurationMs ||
+          second.renderCount - first.renderCount,
+      )
+      .slice(0, MAX_SCAN_TRACE_COMPONENTS);
+    return {
+      startedAtEpochMs: scanStartEpochMs,
+      durationMs: performance.now() - scanStartTimestamp,
+      commitCount,
+      components,
+      longAnimationFrames: longAnimationFrames.slice(),
+    };
+  };
+
+  return { begin, end, beginCommit, recordFiber, takeTrace };
+};
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
new file mode 100644
index 000000000..4f466ba78
--- /dev/null
+++ b/packages/react-grab/src/core/scanner.ts
@@ -0,0 +1,233 @@
+import {
+  instrument,
+  getDisplayName,
+  getNearestHostFiber,
+  isCompositeFiber,
+  traverseRenderedFibers,
+  type Fiber,
+  type FiberRoot,
+} from "bippy";
+import {
+  MIN_DEVICE_PIXEL_RATIO,
+  OVERLAY_BORDER_COLOR_DEFAULT,
+  OVERLAY_FILL_COLOR_DEFAULT,
+  SCAN_LABEL_FONT,
+  SCAN_LABEL_HEIGHT_PX,
+  SCAN_LABEL_PADDING_PX,
+  SCAN_LABEL_TEXT_COLOR,
+  SCAN_OUTLINE_DURATION_MS,
+  Z_INDEX_SCAN_CANVAS,
+} from "../constants.js";
+import type { ScanTrace } from "../types.js";
+import { createScanTraceRecorder } from "./scan-trace-recorder.js";
+import { hideFromThirdParties } from "../utils/hide-from-third-parties.js";
+import { nativeCancelAnimationFrame, nativeRequestAnimationFrame } from "../utils/native-raf.js";
+import { isUsefulComponentName } from "../utils/is-useful-component-name.js";
+import { createElementBounds } from "../utils/create-element-bounds.js";
+import { drawRoundedRectangle } from "../utils/draw-rounded-rectangle.js";
+import { parseBorderRadiusValue } from "../utils/parse-border-radius-value.js";
+
+interface ScanOutline {
+  componentName: string;
+  renderCount: number;
+  lastRenderTimestamp: number;
+}
+
+export interface ScannerController {
+  start: () => void;
+  stop: () => void;
+  toggle: () => void;
+  isScanning: () => boolean;
+  takeTrace: () => ScanTrace | null;
+  dispose: () => void;
+}
+
+let handleCommit: (rendererId: number, root: FiberRoot) => void = () => {};
+
+if (typeof window !== "undefined") {
+  instrument({
+    name: "react-grab-scan",
+    onCommitFiberRoot(_rendererId, root) {
+      return handleCommit(_rendererId, root);
+    },
+  });
+}
+
+export const createScanner = (): ScannerController => {
+  let isScanning = false;
+  let canvas: HTMLCanvasElement | null = null;
+  let context: CanvasRenderingContext2D | null = null;
+  let viewportWidth = 0;
+  let viewportHeight = 0;
+  let devicePixelRatio = 1;
+  let animationFrameId: number | null = null;
+
+  const outlines = new Map<HTMLElement, ScanOutline>();
+  const recorder = createScanTraceRecorder();
+
+  // Set once per commit so the per-fiber recorder reads a single clock value
+  // instead of calling performance.now() inside the hot fiber walk.
+  let currentCommitTimestamp = 0;
+
+  const recordRenderedFiber = (fiber: Fiber): void => {
+    if (!isCompositeFiber(fiber)) return;
+    const componentName = getDisplayName(fiber.type);
+    if (!componentName || !isUsefulComponentName(componentName)) return;
+
+    recorder.recordFiber(componentName, fiber);
+
+    const hostFiber = getNearestHostFiber(fiber);
+    const element = hostFiber?.stateNode;
+    if (!(element instanceof HTMLElement)) return;
+
+    const existingOutline = outlines.get(element);
+    if (existingOutline) {
+      existingOutline.componentName = componentName;
+      existingOutline.renderCount += 1;
+      existingOutline.lastRenderTimestamp = currentCommitTimestamp;
+    } else {
+      outlines.set(element, {
+        componentName,
+        renderCount: 1,
+        lastRenderTimestamp: currentCommitTimestamp,
+      });
+    }
+  };
+
+  handleCommit = (_rendererId: number, root: FiberRoot): void => {
+    if (!isScanning) return;
+    currentCommitTimestamp = performance.now();
+    recorder.beginCommit(currentCommitTimestamp);
+    traverseRenderedFibers(root, recordRenderedFiber);
+    scheduleFrame();
+  };
+
+  const resizeCanvas = (): void => {
+    if (!canvas) return;
+    devicePixelRatio = Math.max(window.devicePixelRatio || 1, MIN_DEVICE_PIXEL_RATIO);
+    viewportWidth = window.innerWidth;
+    viewportHeight = window.innerHeight;
+    canvas.width = viewportWidth * devicePixelRatio;
+    canvas.height = viewportHeight * devicePixelRatio;
+    canvas.style.width = `${viewportWidth}px`;
+    canvas.style.height = `${viewportHeight}px`;
+    context = canvas.getContext("2d");
+    if (context) context.scale(devicePixelRatio, devicePixelRatio);
+  };
+
+  const ensureCanvas = (): void => {
+    if (canvas) return;
+    canvas = document.createElement("canvas");
+    canvas.setAttribute("data-react-grab-scan-canvas", "");
+    hideFromThirdParties(canvas);
+    canvas.style.position = "fixed";
+    canvas.style.top = "0";
+    canvas.style.left = "0";
+    canvas.style.pointerEvents = "none";
+    canvas.style.zIndex = String(Z_INDEX_SCAN_CANVAS);
+    document.body.appendChild(canvas);
+    resizeCanvas();
+  };
+
+  const drawOutline = (element: HTMLElement, outline: ScanOutline, opacity: number): void => {
+    if (!context) return;
+    const elementBounds = createElementBounds(element);
+    if (elementBounds.width <= 0 && elementBounds.height <= 0) return;
+
+    drawRoundedRectangle(
+      context,
+      elementBounds.x,
+      elementBounds.y,
+      elementBounds.width,
+      elementBounds.height,
+      parseBorderRadiusValue(elementBounds.borderRadius),
+      OVERLAY_FILL_COLOR_DEFAULT,
+      OVERLAY_BORDER_COLOR_DEFAULT,
+      opacity,
+    );
+
+    const labelText =
+      outline.renderCount > 1
+        ? `${outline.componentName} ×${outline.renderCount}`
+        : outline.componentName;
+    context.globalAlpha = opacity;
+    context.font = SCAN_LABEL_FONT;
+    const labelWidth = context.measureText(labelText).width + SCAN_LABEL_PADDING_PX * 2;
+    const labelTop =
+      elementBounds.y - SCAN_LABEL_HEIGHT_PX >= 0
+        ? elementBounds.y - SCAN_LABEL_HEIGHT_PX
+        : elementBounds.y;
+    context.fillStyle = OVERLAY_BORDER_COLOR_DEFAULT;
+    context.fillRect(elementBounds.x, labelTop, labelWidth, SCAN_LABEL_HEIGHT_PX);
+    context.fillStyle = SCAN_LABEL_TEXT_COLOR;
+    context.textBaseline = "middle";
+    context.fillText(
+      labelText,
+      elementBounds.x + SCAN_LABEL_PADDING_PX,
+      labelTop + SCAN_LABEL_HEIGHT_PX / 2,
+    );
+    context.globalAlpha = 1;
+  };
+
+  const renderFrame = (): void => {
+    animationFrameId = null;
+    if (!context) return;
+
+    context.clearRect(0, 0, viewportWidth, viewportHeight);
+
+    const currentTimestamp = performance.now();
+    let hasActiveOutlines = false;
+
+    for (const [element, outline] of outlines) {
+      const elapsedSinceRenderMs = currentTimestamp - outline.lastRenderTimestamp;
+      if (elapsedSinceRenderMs >= SCAN_OUTLINE_DURATION_MS || !element.isConnected) {
+        outlines.delete(element);
+        continue;
+      }
+      drawOutline(element, outline, 1 - elapsedSinceRenderMs / SCAN_OUTLINE_DURATION_MS);
+      hasActiveOutlines = true;
+    }
+
+    if (isScanning && hasActiveOutlines) scheduleFrame();
+  };
+
+  const scheduleFrame = (): void => {
+    if (animationFrameId !== null) return;
+    animationFrameId = nativeRequestAnimationFrame(renderFrame);
+  };
+
+  const start = (): void => {
+    if (isScanning) return;
+    isScanning = true;
+    recorder.begin();
+    ensureCanvas();
+    window.addEventListener("resize", resizeCanvas);
+    scheduleFrame();
+  };
+
+  // The recorder's trace is intentionally preserved after stop() so the caller
+  // can read it via takeTrace(); the next start() clears it via recorder.begin().
+  const stop = (): void => {
+    if (!isScanning) return;
+    isScanning = false;
+    recorder.end();
+    window.removeEventListener("resize", resizeCanvas);
+    if (animationFrameId !== null) {
+      nativeCancelAnimationFrame(animationFrameId);
+      animationFrameId = null;
+    }
+    outlines.clear();
+    canvas?.remove();
+    canvas = null;
+    context = null;
+  };
+
+  return {
+    start,
+    stop,
+    toggle: () => (isScanning ? stop() : start()),
+    isScanning: () => isScanning,
+    takeTrace: recorder.takeTrace,
+    dispose: stop,
+  };
+};
diff --git a/packages/react-grab/src/types.ts b/packages/react-grab/src/types.ts
index 8d5b56f16..7f70806ca 100644
--- a/packages/react-grab/src/types.ts
+++ b/packages/react-grab/src/types.ts
@@ -490,6 +490,9 @@ export interface ReactGrabRendererProps {
   toolbarVisible?: boolean;
   isActive?: boolean;
   onToggleActive?: () => void;
+  isScanning?: boolean;
+  onToggleScan?: () => void;
+  scanCopied?: boolean;
   onActivateAction?: (actionId: string) => void;
   activeActionId?: string | null;
   enabled?: boolean;
@@ -585,6 +588,41 @@ export interface CompletionViewProps {
   onShowContextMenu?: () => void;
 }
 
+export interface ScanLoafScript {
+  invoker: string;
+  invokerType: string;
+  sourceURL: string;
+  sourceFunctionName: string;
+  durationMs: number;
+  forcedStyleAndLayoutDurationMs: number;
+}
+
+export interface ScanLongAnimationFrame {
+  startTimeMs: number;
+  durationMs: number;
+  blockingDurationMs: number;
+  renderStartMs: number;
+  styleAndLayoutStartMs: number;
+  scripts: ScanLoafScript[];
+}
+
+export interface ScanComponentProfile {
+  componentName: string;
+  renderCount: number;
+  totalActualDurationMs: number;
+  maxActualDurationMs: number;
+  totalSelfDurationMs: number;
+  lastRenderTimestamp: number;
+}
+
+export interface ScanTrace {
+  startedAtEpochMs: number;
+  durationMs: number;
+  commitCount: number;
+  components: ScanComponentProfile[];
+  longAnimationFrames: ScanLongAnimationFrame[];
+}
+
 export interface SelectionLabelProps {
   tagName?: string;
   componentName?: string;
diff --git a/packages/react-grab/src/utils/draw-rounded-rectangle.ts b/packages/react-grab/src/utils/draw-rounded-rectangle.ts
new file mode 100644
index 000000000..cb6d79db7
--- /dev/null
+++ b/packages/react-grab/src/utils/draw-rounded-rectangle.ts
@@ -0,0 +1,31 @@
+export const drawRoundedRectangle = (
+  context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  rectX: number,
+  rectY: number,
+  rectWidth: number,
+  rectHeight: number,
+  cornerRadius: number,
+  fillColor: string,
+  strokeColor: string,
+  opacity: number = 1,
+): void => {
+  if (rectWidth <= 0 || rectHeight <= 0) return;
+
+  const maxCornerRadius = Math.min(rectWidth / 2, rectHeight / 2);
+  const clampedCornerRadius = Math.min(cornerRadius, maxCornerRadius);
+
+  const shouldSetGlobalAlpha = opacity !== 1;
+  if (shouldSetGlobalAlpha) context.globalAlpha = opacity;
+  context.beginPath();
+  if (clampedCornerRadius > 0) {
+    context.roundRect(rectX, rectY, rectWidth, rectHeight, clampedCornerRadius);
+  } else {
+    context.rect(rectX, rectY, rectWidth, rectHeight);
+  }
+  context.fillStyle = fillColor;
+  context.fill();
+  context.strokeStyle = strokeColor;
+  context.lineWidth = 1;
+  context.stroke();
+  if (shouldSetGlobalAlpha) context.globalAlpha = 1;
+};
diff --git a/packages/react-grab/src/utils/parse-border-radius-value.ts b/packages/react-grab/src/utils/parse-border-radius-value.ts
new file mode 100644
index 000000000..ff2cfce45
--- /dev/null
+++ b/packages/react-grab/src/utils/parse-border-radius-value.ts
@@ -0,0 +1,5 @@
+export const parseBorderRadiusValue = (borderRadius: string): number => {
+  if (!borderRadius) return 0;
+  const match = borderRadius.match(/^(\d+(?:\.\d+)?)/);
+  return match ? Number.parseFloat(match[1]) : 0;
+};
diff --git a/packages/react-grab/src/utils/scan-active-storage.ts b/packages/react-grab/src/utils/scan-active-storage.ts
new file mode 100644
index 000000000..a0dad47ea
--- /dev/null
+++ b/packages/react-grab/src/utils/scan-active-storage.ts
@@ -0,0 +1,21 @@
+const SCAN_ACTIVE_STORAGE_KEY = "react-grab-scan-active";
+
+export const loadScanActive = (): boolean => {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.sessionStorage.getItem(SCAN_ACTIVE_STORAGE_KEY) === "true";
+  } catch {
+    return false;
+  }
+};
+
+export const saveScanActive = (isActive: boolean): void => {
+  if (typeof window === "undefined") return;
+  try {
+    if (isActive) {
+      window.sessionStorage.setItem(SCAN_ACTIVE_STORAGE_KEY, "true");
+    } else {
+      window.sessionStorage.removeItem(SCAN_ACTIVE_STORAGE_KEY);
+    }
+  } catch {}
+};
diff --git a/packages/react-grab/src/utils/serialize-scan-trace.ts b/packages/react-grab/src/utils/serialize-scan-trace.ts
new file mode 100644
index 000000000..bdc113a9c
--- /dev/null
+++ b/packages/react-grab/src/utils/serialize-scan-trace.ts
@@ -0,0 +1,51 @@
+import { VERSION } from "../constants.js";
+import type { ScanTrace } from "../types.js";
+
+const roundToHundredths = (value: number): number => Math.round(value * 100) / 100;
+
+// Serializes a render-scan trace into an agent-readable JSON payload. The
+// shape mirrors the react-scan/lite + LoAF correlation model: rank components
+// by render cost, and pair them with the long-animation-frames captured over
+// the same window so an agent can attribute jank to a component and a script.
+export const serializeScanTrace = (trace: ScanTrace): string => {
+  const payload = {
+    tool: "react-grab",
+    type: "react-render-scan-trace",
+    version: VERSION,
+    description:
+      "Performance trace captured by React Grab's render scan. `components` ranks " +
+      "React components by total render time over the scan; `longAnimationFrames` " +
+      "lists frames >50ms with the scripts that blocked them. Correlate a long " +
+      "animation frame with the components rendering in the same window to find jank.",
+    capturedAt: new Date(trace.startedAtEpochMs).toISOString(),
+    scanDurationMs: Math.round(trace.durationMs),
+    commitCount: trace.commitCount,
+    components: trace.components.map((component) => ({
+      name: component.componentName,
+      renderCount: component.renderCount,
+      totalActualDurationMs: roundToHundredths(component.totalActualDurationMs),
+      avgActualDurationMs: roundToHundredths(
+        component.totalActualDurationMs / component.renderCount,
+      ),
+      maxActualDurationMs: roundToHundredths(component.maxActualDurationMs),
+      totalSelfDurationMs: roundToHundredths(component.totalSelfDurationMs),
+    })),
+    longAnimationFrames: trace.longAnimationFrames.map((frame) => ({
+      startTimeMs: roundToHundredths(frame.startTimeMs),
+      durationMs: roundToHundredths(frame.durationMs),
+      blockingDurationMs: roundToHundredths(frame.blockingDurationMs),
+      renderStartMs: roundToHundredths(frame.renderStartMs),
+      styleAndLayoutStartMs: roundToHundredths(frame.styleAndLayoutStartMs),
+      scripts: frame.scripts.map((script) => ({
+        invoker: script.invoker,
+        invokerType: script.invokerType,
+        sourceURL: script.sourceURL,
+        sourceFunctionName: script.sourceFunctionName,
+        durationMs: roundToHundredths(script.durationMs),
+        forcedStyleAndLayoutDurationMs: roundToHundredths(script.forcedStyleAndLayoutDurationMs),
+      })),
+    })),
+  };
+
+  return JSON.stringify(payload, null, 2);
+};

From b1da6bf1b98ea6f467bb569c21991542f8f349b2 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 22:16:09 -0700
Subject: [PATCH 02/16] fix(react-grab): sync scan state on plugin teardown;
 skip zero-area outlines

- Route scan plugin cleanup through the controller's synced stop so
  isScanning and sessionStorage stay consistent after unregister/dispose
  (was calling scanner.stop() directly, desyncing toolbar + storage).
- drawOutline now skips elements with zero width OR height (was AND), so
  invisible elements no longer render a floating label.
---
 packages/react-grab/src/core/index.tsx        |  2 +-
 packages/react-grab/src/core/plugins/scan.ts  |  7 ++--
 .../react-grab/src/core/scan-controller.ts    | 34 +++++++++++++------
 packages/react-grab/src/core/scanner.ts       |  2 +-
 4 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 8aa5e3021..2fed683e5 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -3767,7 +3767,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
     for (const plugin of builtInPlugins) {
       pluginRegistry.register(plugin, api);
     }
-    pluginRegistry.register(createScanPlugin(scanController.scanner), api);
+    pluginRegistry.register(createScanPlugin(scanController.stop), api);
 
     setTimeout(() => {
       isNextProjectRuntime(true);
diff --git a/packages/react-grab/src/core/plugins/scan.ts b/packages/react-grab/src/core/plugins/scan.ts
index bca368234..65757992e 100644
--- a/packages/react-grab/src/core/plugins/scan.ts
+++ b/packages/react-grab/src/core/plugins/scan.ts
@@ -1,10 +1,11 @@
 import type { Plugin } from "../../types.js";
-import type { ScannerController } from "../scanner.js";
 import { SCAN_ACTION_ID } from "../../constants.js";
 
-export const createScanPlugin = (scanner: ScannerController): Plugin => ({
+// Receives the scan controller's synced stop (not the raw scanner) so plugin
+// teardown keeps the toolbar's isScanning state and sessionStorage in sync.
+export const createScanPlugin = (stopScan: () => void): Plugin => ({
   name: SCAN_ACTION_ID,
   setup: () => ({
-    cleanup: () => scanner.stop(),
+    cleanup: () => stopScan(),
   }),
 });
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
index 00a2f7402..43861ea7e 100644
--- a/packages/react-grab/src/core/scan-controller.ts
+++ b/packages/react-grab/src/core/scan-controller.ts
@@ -10,6 +10,7 @@ export interface ScanController {
   isScanning: Accessor<boolean>;
   scanCopied: Accessor<boolean>;
   toggle: () => void;
+  stop: () => void;
 }
 
 // Owns the full scan lifecycle: the canvas scanner, the reactive scanning
@@ -27,18 +28,31 @@ export const createScanController = (): ScanController => {
     scanCopiedTimeout = setTimeout(() => setScanCopied(false), FEEDBACK_DURATION_MS);
   };
 
-  const toggle = () => {
-    const wasScanning = scanner.isScanning();
-    scanner.toggle();
-    const nowScanning = scanner.isScanning();
+  const syncState = (nowScanning: boolean) => {
     setIsScanning(nowScanning);
     saveScanActive(nowScanning);
-    if (!wasScanning || nowScanning) return;
-    const trace = scanner.takeTrace();
-    if (!trace) return;
-    if (copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
-      flashCopied();
+  };
+
+  // Stops without copying a trace - used for teardown paths (plugin cleanup,
+  // disposal) where the toolbar/storage state must still be kept in sync.
+  const stop = () => {
+    if (!scanner.isScanning()) return;
+    scanner.stop();
+    syncState(false);
+  };
+
+  const toggle = () => {
+    if (scanner.isScanning()) {
+      scanner.stop();
+      syncState(false);
+      const trace = scanner.takeTrace();
+      if (trace && copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
+        flashCopied();
+      }
+      return;
     }
+    scanner.start();
+    syncState(true);
   };
 
   // Persisting across reloads keeps the scan running through dev-server HMR
@@ -63,5 +77,5 @@ export const createScanController = (): ScanController => {
     scanner.dispose();
   });
 
-  return { scanner, isScanning, scanCopied, toggle };
+  return { scanner, isScanning, scanCopied, toggle, stop };
 };
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index 4f466ba78..81184d949 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -132,7 +132,7 @@ export const createScanner = (): ScannerController => {
   const drawOutline = (element: HTMLElement, outline: ScanOutline, opacity: number): void => {
     if (!context) return;
     const elementBounds = createElementBounds(element);
-    if (elementBounds.width <= 0 && elementBounds.height <= 0) return;
+    if (elementBounds.width <= 0 || elementBounds.height <= 0) return;
 
     drawRoundedRectangle(
       context,

From 5eded558e08f8499d79b82019d81173aaf746534 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 22:21:50 -0700
Subject: [PATCH 03/16] fix(react-grab): shorten scan copied toast to "Copied"

---
 packages/react-grab/src/components/toolbar/index.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index ffedf85e3..20066c751 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -684,7 +684,7 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
           class="absolute pointer-events-none"
           style={scanCopiedToastStyle()}
         >
-          <CopiedPill text="Copied performance trace" />
+          <CopiedPill text="Copied" />
         </div>
       </Show>
       <ToolbarContent

From 875c2a44cbdfe6bc183fb0a11748ce1375e3f02e Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 22:30:53 -0700
Subject: [PATCH 04/16] feat(react-grab): scan button shows spinner while
 active, red stop on hover

While scanning, the toolbar button shows a spinner by default and reveals
a red stop icon on hover, making the active state legible and the
click-to-stop affordance explicit.
---
 packages/react-grab/src/components/toolbar/index.tsx | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index 20066c751..21aee1e06 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -8,6 +8,7 @@ import { IconComment } from "../icons/icon-comment.jsx";
 import { IconStyle } from "../icons/icon-style.jsx";
 import { IconScan } from "../icons/icon-scan.jsx";
 import { IconStop } from "../icons/icon-stop.jsx";
+import { IconLoader } from "../icons/icon-loader.jsx";
 import { ToolbarActionButton } from "./toolbar-action-button.jsx";
 import {
   TOOLBAR_SNAP_MARGIN_PX,
@@ -790,7 +791,11 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
               {...createFreezeHandlers(SCAN_ACTION_ID, { shouldFreezeInteractions: false })}
               icon={
                 props.isScanning ? (
-                  <IconStop size={14} class={actionIconClass(true)} />
+                  hoveredActionId() === SCAN_ACTION_ID ? (
+                    <IconStop size={14} class="text-[var(--rg-error-text)]" />
+                  ) : (
+                    <IconLoader size={14} class={actionIconClass(true)} />
+                  )
                 ) : (
                   <IconScan size={14} class={actionIconClass(false)} />
                 )

From 320e46b5ed5cbe6a6163993436bda3af6c87667f Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 22:58:12 -0700
Subject: [PATCH 05/16] fix(react-grab): harden scan lifecycle + add e2e
 coverage

- Teardown no longer writes scan sessionStorage; only an explicit user
  toggle does, so persisted state can't be left inconsistent by cleanup
  ordering (controller stop and plugin cleanup now share one path).
- Skip restoring a persisted scan when no toolbar is available, so it can
  never resume with no way to stop it.
- Toolbar keys the "Copied" toast on a per-copy token so back-to-back
  copies replay the fade instead of getting stuck mid-animation.
- Document name-aggregation in the trace payload so agents aren't misled
  by distinct same-named components being summed.
- Add e2e spec covering start/stop, sessionStorage persistence, reload
  resume, and the copied toast.
---
 packages/react-grab/e2e/scan.spec.ts          | 87 +++++++++++++++++++
 .../react-grab/src/components/copied-pill.tsx | 12 ++-
 .../react-grab/src/components/renderer.tsx    |  2 +-
 .../src/components/toolbar/index.tsx          | 21 +++--
 packages/react-grab/src/core/index.tsx        |  7 +-
 .../react-grab/src/core/scan-controller.ts    | 50 ++++++-----
 packages/react-grab/src/styles.css            | 13 +++
 packages/react-grab/src/types.ts              |  2 +-
 .../src/utils/serialize-scan-trace.ts         |  8 +-
 9 files changed, 162 insertions(+), 40 deletions(-)
 create mode 100644 packages/react-grab/e2e/scan.spec.ts

diff --git a/packages/react-grab/e2e/scan.spec.ts b/packages/react-grab/e2e/scan.spec.ts
new file mode 100644
index 000000000..0cd0ea7f9
--- /dev/null
+++ b/packages/react-grab/e2e/scan.spec.ts
@@ -0,0 +1,87 @@
+import { test, expect, type ReactGrabPageObject } from "./fixtures.js";
+import type { Page } from "@playwright/test";
+
+const ATTRIBUTE_NAME = "data-react-grab";
+const SCAN_ACTIVE_STORAGE_KEY = "react-grab-scan-active";
+
+const waitForToolbar = async (reactGrab: ReactGrabPageObject) => {
+  await expect.poll(() => reactGrab.isToolbarVisible(), { timeout: 2000 }).toBe(true);
+};
+
+// The scan button is independent of the overlay/active flow, so it can't go
+// through the shared clickToolbarAction helper (which waits for activation).
+const clickScanButton = async (page: Page) => {
+  await page.evaluate((attrName) => {
+    const host = document.querySelector(`[${attrName}]`);
+    const root = host?.shadowRoot?.querySelector(`[${attrName}]`);
+    const button = root?.querySelector<HTMLButtonElement>(
+      '[data-react-grab-toolbar-action="scan"]',
+    );
+    button?.click();
+  }, ATTRIBUTE_NAME);
+};
+
+const isScanCanvasPresent = (page: Page): Promise<boolean> =>
+  page.evaluate(() => Boolean(document.querySelector("[data-react-grab-scan-canvas]")));
+
+const isScanCopiedVisible = (page: Page): Promise<boolean> =>
+  page.evaluate((attrName) => {
+    const host = document.querySelector(`[${attrName}]`);
+    const root = host?.shadowRoot?.querySelector(`[${attrName}]`);
+    return Boolean(root?.querySelector("[data-react-grab-scan-copied]"));
+  }, ATTRIBUTE_NAME);
+
+const getStoredScanActive = (page: Page, key: string): Promise<string | null> =>
+  page.evaluate((storageKey) => window.sessionStorage.getItem(storageKey), key);
+
+test.describe("Render scan", () => {
+  test("starts and stops the scan canvas from the toolbar", async ({ reactGrab }) => {
+    await waitForToolbar(reactGrab);
+
+    await clickScanButton(reactGrab.page);
+    await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(true);
+    expect(await reactGrab.getToolbarActionPressed("scan")).toBe(true);
+
+    await clickScanButton(reactGrab.page);
+    await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(false);
+    expect(await reactGrab.getToolbarActionPressed("scan")).toBe(false);
+  });
+
+  test("persists the scanning flag to sessionStorage", async ({ reactGrab }) => {
+    await waitForToolbar(reactGrab);
+
+    await clickScanButton(reactGrab.page);
+    await expect
+      .poll(() => getStoredScanActive(reactGrab.page, SCAN_ACTIVE_STORAGE_KEY), { timeout: 2000 })
+      .toBe("true");
+
+    await clickScanButton(reactGrab.page);
+    await expect
+      .poll(() => getStoredScanActive(reactGrab.page, SCAN_ACTIVE_STORAGE_KEY), { timeout: 2000 })
+      .toBe(null);
+  });
+
+  test("resumes a persisted scan after reload", async ({ reactGrab }) => {
+    await waitForToolbar(reactGrab);
+
+    await clickScanButton(reactGrab.page);
+    await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(true);
+
+    await reactGrab.page.reload();
+    await waitForToolbar(reactGrab);
+
+    await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(true);
+    expect(await reactGrab.getToolbarActionPressed("scan")).toBe(true);
+  });
+
+  test("copies a trace and shows the Copied toast on stop", async ({ reactGrab }) => {
+    await waitForToolbar(reactGrab);
+
+    await clickScanButton(reactGrab.page);
+    // Force a React commit so the trace is non-empty (no trace -> no toast).
+    await reactGrab.page.getByTestId("add-element-button").click();
+
+    await clickScanButton(reactGrab.page);
+    await expect.poll(() => isScanCopiedVisible(reactGrab.page), { timeout: 2000 }).toBe(true);
+  });
+});
diff --git a/packages/react-grab/src/components/copied-pill.tsx b/packages/react-grab/src/components/copied-pill.tsx
index e58c6d44e..487830469 100644
--- a/packages/react-grab/src/components/copied-pill.tsx
+++ b/packages/react-grab/src/components/copied-pill.tsx
@@ -1,19 +1,25 @@
 import type { Component } from "solid-js";
+import { FADE_DURATION_MS, FEEDBACK_DURATION_MS, PANEL_SHADOW } from "../constants.js";
 import { IconCheck } from "./icons/icon-check.jsx";
 
 interface CopiedPillProps {
   text: string;
 }
 
-// Static, non-interactive "copied" confirmation pill. Used for passive
-// confirmations (e.g. the toolbar scan-trace toast) that only need to show a
-// message, without the focus/keyboard/dismiss machinery of CompletionView.
+// Static, non-interactive "copied" confirmation pill for passive confirmations
+// (e.g. the toolbar scan-trace toast). It appears instantly, holds, then fades
+// itself out over its final FADE_DURATION_MS - the same dismissal the selection
+// label uses - so the parent only needs to mount/unmount it.
 export const CopiedPill: Component<CopiedPillProps> = (props) => {
   return (
     <div
       role="status"
       aria-live="polite"
       class="contain-layout shrink-0 flex items-center gap-0.5 py-1.5 px-2 w-fit h-fit max-w-[280px] rounded-full antialiased bg-[var(--rg-panel-bg)] [font-synthesis:none]"
+      style={{
+        filter: `drop-shadow(${PANEL_SHADOW})`,
+        animation: `rg-copied-pill-out ${FADE_DURATION_MS}ms ease-out ${FEEDBACK_DURATION_MS - FADE_DURATION_MS}ms forwards`,
+      }}
     >
       <IconCheck size={14} aria-hidden="true" class="text-[var(--rg-text-primary-85)] shrink-0" />
       <span class="text-[var(--rg-text-primary)] text-[13px] leading-4 font-sans font-medium h-fit tabular-nums overflow-hidden text-ellipsis whitespace-nowrap min-w-0">
diff --git a/packages/react-grab/src/components/renderer.tsx b/packages/react-grab/src/components/renderer.tsx
index 3532d2351..e40018042 100644
--- a/packages/react-grab/src/components/renderer.tsx
+++ b/packages/react-grab/src/components/renderer.tsx
@@ -145,7 +145,7 @@ export const ReactGrabRenderer: Component<ReactGrabRendererProps> = (props) => {
           isActive={props.isActive}
           isScanning={props.isScanning}
           onToggleScan={props.onToggleScan}
-          scanCopied={props.scanCopied}
+          scanCopiedToken={props.scanCopiedToken}
           isContextMenuOpen={props.contextMenuPosition !== null}
           onToggle={props.onToggleActive}
           onActivateAction={props.onActivateAction}
diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index 21aee1e06..d9b22ec07 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -47,7 +47,7 @@ interface ToolbarProps {
   isActive?: boolean;
   isScanning?: boolean;
   onToggleScan?: () => void;
-  scanCopied?: boolean;
+  scanCopiedToken?: number | null;
   isContextMenuOpen?: boolean;
   onToggle?: () => void;
   onActivateAction?: (actionId: string) => void;
@@ -679,14 +679,17 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
         props.onSelectHoverChange?.(false);
       }}
     >
-      <Show when={props.scanCopied}>
-        <div
-          data-react-grab-scan-copied
-          class="absolute pointer-events-none"
-          style={scanCopiedToastStyle()}
-        >
-          <CopiedPill text="Copied" />
-        </div>
+      <Show when={props.scanCopiedToken} keyed>
+        {(scanCopiedToken) => (
+          <div
+            data-react-grab-scan-copied
+            data-scan-copied-token={scanCopiedToken}
+            class="absolute pointer-events-none"
+            style={scanCopiedToastStyle()}
+          >
+            <CopiedPill text="Copied" />
+          </div>
+        )}
       </Show>
       <ToolbarContent
         isCollapsed={isCollapsed()}
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 2fed683e5..01c79509e 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -1603,7 +1603,10 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       handleActivateAction(currentToolbarState()?.defaultAction ?? DEFAULT_ACTION_ID);
     };
 
-    const scanController = createScanController();
+    const scanController = createScanController({
+      isToolbarEnabled: () =>
+        Boolean(pluginRegistry.store.theme.enabled && pluginRegistry.store.theme.toolbar.enabled),
+    });
 
     const enterCommentModeForElement = (element: Element, positionX: number, positionY: number) => {
       actions.setPendingCommentMode(false);
@@ -3593,7 +3596,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
                 onToggleActive={handleToggleActive}
                 isScanning={scanController.isScanning()}
                 onToggleScan={scanController.toggle}
-                scanCopied={scanController.scanCopied()}
+                scanCopiedToken={scanController.scanCopiedToken()}
                 onActivateAction={handleActivateAction}
                 activeActionId={activeActionId()}
                 enabled={isEnabled()}
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
index 43861ea7e..a3dd25243 100644
--- a/packages/react-grab/src/core/scan-controller.ts
+++ b/packages/react-grab/src/core/scan-controller.ts
@@ -5,10 +5,18 @@ import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
 import { loadScanActive, saveScanActive } from "../utils/scan-active-storage.js";
 import { createScanner, type ScannerController } from "./scanner.js";
 
+interface ScanControllerOptions {
+  // Whether there is a toolbar to stop the scan from; a persisted scan only
+  // resumes when true, so it can never run with no way to turn it off.
+  isToolbarEnabled: () => boolean;
+}
+
 export interface ScanController {
   scanner: ScannerController;
   isScanning: Accessor<boolean>;
-  scanCopied: Accessor<boolean>;
+  // A fresh token per successful copy (null when no toast). The toolbar keys
+  // its toast on this so each copy replays the fade, even back-to-back.
+  scanCopiedToken: Accessor<number | null>;
   toggle: () => void;
   stop: () => void;
 }
@@ -16,35 +24,35 @@ export interface ScanController {
 // Owns the full scan lifecycle: the canvas scanner, the reactive scanning
 // state, clipboard copy of the trace on stop, the transient "copied" toast,
 // and persistence across reloads. Must run inside a reactive owner.
-export const createScanController = (): ScanController => {
+export const createScanController = (options: ScanControllerOptions): ScanController => {
   const scanner = createScanner();
   const [isScanning, setIsScanning] = createSignal(false);
-  const [scanCopied, setScanCopied] = createSignal(false);
+  const [scanCopiedToken, setScanCopiedToken] = createSignal<number | null>(null);
+  let scanCopiedCount = 0;
   let scanCopiedTimeout: ReturnType<typeof setTimeout> | undefined;
 
   const flashCopied = () => {
-    setScanCopied(true);
+    scanCopiedCount += 1;
+    setScanCopiedToken(scanCopiedCount);
     clearTimeout(scanCopiedTimeout);
-    scanCopiedTimeout = setTimeout(() => setScanCopied(false), FEEDBACK_DURATION_MS);
+    scanCopiedTimeout = setTimeout(() => setScanCopiedToken(null), FEEDBACK_DURATION_MS);
   };
 
-  const syncState = (nowScanning: boolean) => {
-    setIsScanning(nowScanning);
-    saveScanActive(nowScanning);
-  };
-
-  // Stops without copying a trace - used for teardown paths (plugin cleanup,
-  // disposal) where the toolbar/storage state must still be kept in sync.
+  // Stops the scanner and syncs the in-memory flag, but never writes persisted
+  // intent. sessionStorage is written only by an explicit user toggle, so a
+  // scan survives teardown/reload and resumes on the next init - and teardown
+  // ordering can't leave the persisted state inconsistent.
   const stop = () => {
     if (!scanner.isScanning()) return;
     scanner.stop();
-    syncState(false);
+    setIsScanning(false);
   };
 
   const toggle = () => {
     if (scanner.isScanning()) {
       scanner.stop();
-      syncState(false);
+      setIsScanning(false);
+      saveScanActive(false);
       const trace = scanner.takeTrace();
       if (trace && copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
         flashCopied();
@@ -52,14 +60,14 @@ export const createScanController = (): ScanController => {
       return;
     }
     scanner.start();
-    syncState(true);
+    setIsScanning(true);
+    saveScanActive(true);
   };
 
-  // Persisting across reloads keeps the scan running through dev-server HMR
-  // restarts. Defer to DOMContentLoaded so the scanner's canvas has a
-  // document.body to attach to.
+  // Resume a persisted scan across reloads/HMR. Deferred to DOMContentLoaded so
+  // the scanner's canvas has a document.body to attach to.
   const restore = () => {
-    if (!loadScanActive() || scanner.isScanning()) return;
+    if (!loadScanActive() || scanner.isScanning() || !options.isToolbarEnabled()) return;
     scanner.start();
     setIsScanning(true);
   };
@@ -74,8 +82,8 @@ export const createScanController = (): ScanController => {
 
   onCleanup(() => {
     clearTimeout(scanCopiedTimeout);
-    scanner.dispose();
+    stop();
   });
 
-  return { scanner, isScanning, scanCopied, toggle, stop };
+  return { scanner, isScanning, scanCopiedToken, toggle, stop };
 };
diff --git a/packages/react-grab/src/styles.css b/packages/react-grab/src/styles.css
index b21374578..f746e3393 100644
--- a/packages/react-grab/src/styles.css
+++ b/packages/react-grab/src/styles.css
@@ -337,6 +337,19 @@
   will-change: transform, opacity;
 }
 
+/* Hold, then fade+blur out - matches the selection label's dismissal. The
+   hold duration comes from the animation-delay set inline on the element. */
+@keyframes rg-copied-pill-out {
+  from {
+    opacity: 1;
+    filter: drop-shadow(var(--rg-shadow)) blur(0);
+  }
+  to {
+    opacity: 0;
+    filter: drop-shadow(var(--rg-shadow)) blur(3px);
+  }
+}
+
 .animate-shake-vertical {
   --rg-shake-x: 0;
   --rg-shake-y: 1;
diff --git a/packages/react-grab/src/types.ts b/packages/react-grab/src/types.ts
index 7f70806ca..e691026ca 100644
--- a/packages/react-grab/src/types.ts
+++ b/packages/react-grab/src/types.ts
@@ -492,7 +492,7 @@ export interface ReactGrabRendererProps {
   onToggleActive?: () => void;
   isScanning?: boolean;
   onToggleScan?: () => void;
-  scanCopied?: boolean;
+  scanCopiedToken?: number | null;
   onActivateAction?: (actionId: string) => void;
   activeActionId?: string | null;
   enabled?: boolean;
diff --git a/packages/react-grab/src/utils/serialize-scan-trace.ts b/packages/react-grab/src/utils/serialize-scan-trace.ts
index bdc113a9c..876e90626 100644
--- a/packages/react-grab/src/utils/serialize-scan-trace.ts
+++ b/packages/react-grab/src/utils/serialize-scan-trace.ts
@@ -14,9 +14,11 @@ export const serializeScanTrace = (trace: ScanTrace): string => {
     version: VERSION,
     description:
       "Performance trace captured by React Grab's render scan. `components` ranks " +
-      "React components by total render time over the scan; `longAnimationFrames` " +
-      "lists frames >50ms with the scripts that blocked them. Correlate a long " +
-      "animation frame with the components rendering in the same window to find jank.",
+      "React components by total render time over the scan, aggregated by display " +
+      "name (distinct components sharing a name are summed together); " +
+      "`longAnimationFrames` lists frames >50ms with the scripts that blocked them. " +
+      "Correlate a long animation frame with the components rendering in the same " +
+      "window to find jank.",
     capturedAt: new Date(trace.startedAtEpochMs).toISOString(),
     scanDurationMs: Math.round(trace.durationMs),
     commitCount: trace.commitCount,

From 40899d3178438260d5232cb4ac5c6afd8933ade4 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 23:01:23 -0700
Subject: [PATCH 06/16] feat(react-grab): copy scan trace as a compact log
 instead of JSON

Replaces the verbose JSON payload with a terse, token-efficient log
(positional columns + per-section legend) so it costs far fewer tokens
when pasted to an agent. Enriches LoAF capture to match react-stack:
adds each script's source char position and the frame's
firstUIEventTimestamp, and drops low-signal invoker/styleAndLayoutStart
fields.
---
 .../src/core/scan-trace-recorder.ts           |  10 +-
 packages/react-grab/src/types.ts              |   5 +-
 .../src/utils/serialize-scan-trace.ts         | 105 ++++++++++--------
 3 files changed, 64 insertions(+), 56 deletions(-)

diff --git a/packages/react-grab/src/core/scan-trace-recorder.ts b/packages/react-grab/src/core/scan-trace-recorder.ts
index 2ffb25c92..2b32842f7 100644
--- a/packages/react-grab/src/core/scan-trace-recorder.ts
+++ b/packages/react-grab/src/core/scan-trace-recorder.ts
@@ -15,18 +15,17 @@ import type {
 // The `long-animation-frame` entry shape is not yet in the DOM lib types, so
 // we model the fields we read off PerformanceObserver entries here.
 interface LongAnimationFrameScriptTiming {
-  invoker?: string;
-  invokerType?: string;
   sourceURL?: string;
   sourceFunctionName?: string;
+  sourceCharPosition?: number;
   duration?: number;
   forcedStyleAndLayoutDuration?: number;
 }
 
 interface LongAnimationFrameTiming extends PerformanceEntry {
   renderStart?: number;
-  styleAndLayoutStart?: number;
   blockingDuration?: number;
+  firstUIEventTimestamp?: number;
   scripts?: LongAnimationFrameScriptTiming[];
 }
 
@@ -63,10 +62,9 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
       const scripts: ScanLoafScript[] = (loafEntry.scripts ?? [])
         .slice(0, MAX_SCAN_TRACE_LOAF_SCRIPTS)
         .map((script) => ({
-          invoker: script.invoker ?? "",
-          invokerType: script.invokerType ?? "",
           sourceURL: script.sourceURL ?? "",
           sourceFunctionName: script.sourceFunctionName ?? "",
+          sourceCharPosition: script.sourceCharPosition ?? 0,
           durationMs: script.duration ?? 0,
           forcedStyleAndLayoutDurationMs: script.forcedStyleAndLayoutDuration ?? 0,
         }));
@@ -75,7 +73,7 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
         durationMs: loafEntry.duration,
         blockingDurationMs: loafEntry.blockingDuration ?? 0,
         renderStartMs: loafEntry.renderStart ?? 0,
-        styleAndLayoutStartMs: loafEntry.styleAndLayoutStart ?? 0,
+        firstUIEventTimestampMs: loafEntry.firstUIEventTimestamp ?? 0,
         scripts,
       });
     }
diff --git a/packages/react-grab/src/types.ts b/packages/react-grab/src/types.ts
index e691026ca..d3b6bc538 100644
--- a/packages/react-grab/src/types.ts
+++ b/packages/react-grab/src/types.ts
@@ -589,10 +589,9 @@ export interface CompletionViewProps {
 }
 
 export interface ScanLoafScript {
-  invoker: string;
-  invokerType: string;
   sourceURL: string;
   sourceFunctionName: string;
+  sourceCharPosition: number;
   durationMs: number;
   forcedStyleAndLayoutDurationMs: number;
 }
@@ -602,7 +601,7 @@ export interface ScanLongAnimationFrame {
   durationMs: number;
   blockingDurationMs: number;
   renderStartMs: number;
-  styleAndLayoutStartMs: number;
+  firstUIEventTimestampMs: number;
   scripts: ScanLoafScript[];
 }
 
diff --git a/packages/react-grab/src/utils/serialize-scan-trace.ts b/packages/react-grab/src/utils/serialize-scan-trace.ts
index 876e90626..25659c4a0 100644
--- a/packages/react-grab/src/utils/serialize-scan-trace.ts
+++ b/packages/react-grab/src/utils/serialize-scan-trace.ts
@@ -1,53 +1,64 @@
-import { VERSION } from "../constants.js";
 import type { ScanTrace } from "../types.js";
 
-const roundToHundredths = (value: number): number => Math.round(value * 100) / 100;
+const round1 = (value: number): number => Math.round(value * 10) / 10;
 
-// Serializes a render-scan trace into an agent-readable JSON payload. The
-// shape mirrors the react-scan/lite + LoAF correlation model: rank components
-// by render cost, and pair them with the long-animation-frames captured over
-// the same window so an agent can attribute jank to a component and a script.
+// Renders a render-scan trace as a compact, token-efficient log (not JSON) for
+// pasting to a coding agent. Columns are positional with terse labels and a
+// per-section legend, mirroring the react-scan/lite + LoAF correlation model:
+// rank components by render cost, then list the long-animation-frames so an
+// agent can attribute jank to a component and the script that blocked the frame.
 export const serializeScanTrace = (trace: ScanTrace): string => {
-  const payload = {
-    tool: "react-grab",
-    type: "react-render-scan-trace",
-    version: VERSION,
-    description:
-      "Performance trace captured by React Grab's render scan. `components` ranks " +
-      "React components by total render time over the scan, aggregated by display " +
-      "name (distinct components sharing a name are summed together); " +
-      "`longAnimationFrames` lists frames >50ms with the scripts that blocked them. " +
-      "Correlate a long animation frame with the components rendering in the same " +
-      "window to find jank.",
-    capturedAt: new Date(trace.startedAtEpochMs).toISOString(),
-    scanDurationMs: Math.round(trace.durationMs),
-    commitCount: trace.commitCount,
-    components: trace.components.map((component) => ({
-      name: component.componentName,
-      renderCount: component.renderCount,
-      totalActualDurationMs: roundToHundredths(component.totalActualDurationMs),
-      avgActualDurationMs: roundToHundredths(
-        component.totalActualDurationMs / component.renderCount,
-      ),
-      maxActualDurationMs: roundToHundredths(component.maxActualDurationMs),
-      totalSelfDurationMs: roundToHundredths(component.totalSelfDurationMs),
-    })),
-    longAnimationFrames: trace.longAnimationFrames.map((frame) => ({
-      startTimeMs: roundToHundredths(frame.startTimeMs),
-      durationMs: roundToHundredths(frame.durationMs),
-      blockingDurationMs: roundToHundredths(frame.blockingDurationMs),
-      renderStartMs: roundToHundredths(frame.renderStartMs),
-      styleAndLayoutStartMs: roundToHundredths(frame.styleAndLayoutStartMs),
-      scripts: frame.scripts.map((script) => ({
-        invoker: script.invoker,
-        invokerType: script.invokerType,
-        sourceURL: script.sourceURL,
-        sourceFunctionName: script.sourceFunctionName,
-        durationMs: roundToHundredths(script.durationMs),
-        forcedStyleAndLayoutDurationMs: roundToHundredths(script.forcedStyleAndLayoutDurationMs),
-      })),
-    })),
-  };
+  const lines: string[] = [];
 
-  return JSON.stringify(payload, null, 2);
+  lines.push(
+    `react-grab render scan: ${(trace.durationMs / 1000).toFixed(1)}s, ` +
+      `${trace.commitCount} commits, ${trace.components.length} components, ` +
+      `${trace.longAnimationFrames.length} long frames (>50ms)`,
+  );
+
+  lines.push("");
+  lines.push("components — name total ×renders avg max self (render ms), worst first:");
+  if (trace.components.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const component of trace.components) {
+      lines.push(
+        `  ${component.componentName} ${round1(component.totalActualDurationMs)}` +
+          ` ×${component.renderCount}` +
+          ` avg${round1(component.totalActualDurationMs / component.renderCount)}` +
+          ` max${round1(component.maxActualDurationMs)}` +
+          ` self${round1(component.totalSelfDurationMs)}`,
+      );
+    }
+  }
+
+  lines.push("");
+  lines.push(
+    "long animation frames — @start dur block (ms); scripts url:fn@char dur reflow:",
+  );
+  if (trace.longAnimationFrames.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const frame of trace.longAnimationFrames) {
+      const uiWait =
+        frame.firstUIEventTimestampMs > 0
+          ? ` ui+${round1(frame.firstUIEventTimestampMs - frame.startTimeMs)}`
+          : "";
+      lines.push(
+        `  @${round1(frame.startTimeMs)} dur${round1(frame.durationMs)}` +
+          ` block${round1(frame.blockingDurationMs)}${uiWait}`,
+      );
+      for (const script of frame.scripts) {
+        const reflow =
+          script.forcedStyleAndLayoutDurationMs > 0
+            ? ` reflow${round1(script.forcedStyleAndLayoutDurationMs)}`
+            : "";
+        const url = script.sourceURL || "(inline)";
+        const fn = script.sourceFunctionName || "(anonymous)";
+        lines.push(`    ${url}:${fn}@${script.sourceCharPosition} ${round1(script.durationMs)}ms${reflow}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
 };

From cf7c8535330cfca6f7e2071bf93a51556a5ca90a Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 23:49:19 -0700
Subject: [PATCH 07/16] feat(react-grab): use a filled alert-diamond icon for
 scan

---
 .../react-grab/src/components/icons/icon-scan.tsx | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/packages/react-grab/src/components/icons/icon-scan.tsx b/packages/react-grab/src/components/icons/icon-scan.tsx
index 2be5688e4..3ca938de3 100644
--- a/packages/react-grab/src/components/icons/icon-scan.tsx
+++ b/packages/react-grab/src/components/icons/icon-scan.tsx
@@ -14,17 +14,14 @@ export const IconScan: Component<IconScanProps> = (props) => {
       width={size()}
       height={size()}
       viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      stroke-width="2"
-      stroke-linecap="round"
-      stroke-linejoin="round"
+      fill="currentColor"
       class={props.class}
     >
-      <path d="M3 7V5a2 2 0 0 1 2-2h2" />
-      <path d="M17 3h2a2 2 0 0 1 2 2v2" />
-      <path d="M21 17v2a2 2 0 0 1-2 2h-2" />
-      <path d="M7 21H5a2 2 0 0 1-2-2v-2" />
+      <path
+        fill-rule="evenodd"
+        clip-rule="evenodd"
+        d="M2.7 10.3a2.41 2.41 0 0 0 0 3.41l7.59 7.59a2.41 2.41 0 0 0 3.41 0l7.59-7.59a2.41 2.41 0 0 0 0-3.41L13.7 2.71a2.41 2.41 0 0 0-3.41 0ZM12 7.5a1 1 0 0 1 1 1v3a1 1 0 0 1-2 0v-3a1 1 0 0 1 1-1ZM13.05 15.5a1.05 1.05 0 1 0-2.1 0 1.05 1.05 0 0 0 2.1 0Z"
+      />
     </svg>
   );
 };

From 9742048643965ad45d4270f96a8fa662791c2012 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 23:49:19 -0700
Subject: [PATCH 08/16] feat(react-grab): combine + truncate scan outline
 labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ports react-scan's outline label heuristic: when multiple components
render into the same element, their names are grouped by render count
(e.g. "Row, Cell ×3, List ×1") and the label is truncated with an
ellipsis so a long name or many components can't overflow. Maintains the
per-element name→count map incrementally instead of rebuilding it each
draw, and caches the label so the render loop stays allocation-free.
---
 packages/react-grab/src/constants.ts          |  2 ++
 packages/react-grab/src/core/scanner.ts       | 22 ++++++++-------
 .../src/utils/format-render-label.ts          | 27 +++++++++++++++++++
 3 files changed, 41 insertions(+), 10 deletions(-)
 create mode 100644 packages/react-grab/src/utils/format-render-label.ts

diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index 1e13946d5..6c12d51d3 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -150,6 +150,8 @@ export const MAX_SCAN_TRACE_LOAF_SCRIPTS = 10;
 export const SCAN_LABEL_TEXT_COLOR = "rgba(255, 255, 255, 0.95)";
 export const SCAN_LABEL_HEIGHT_PX = 15;
 export const SCAN_LABEL_PADDING_PX = 4;
+export const SCAN_LABEL_MAX_NAMES_PER_GROUP = 4;
+export const SCAN_LABEL_MAX_CHARS = 40;
 export const SCAN_LABEL_FONT =
   "11px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
 
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index 81184d949..da36332e4 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -26,10 +26,13 @@ import { isUsefulComponentName } from "../utils/is-useful-component-name.js";
 import { createElementBounds } from "../utils/create-element-bounds.js";
 import { drawRoundedRectangle } from "../utils/draw-rounded-rectangle.js";
 import { parseBorderRadiusValue } from "../utils/parse-border-radius-value.js";
+import { formatRenderLabel } from "../utils/format-render-label.js";
 
 interface ScanOutline {
-  componentName: string;
-  renderCount: number;
+  nameCounts: Map<string, number>;
+  // Cached label, recomputed only on commit (not per frame) to keep the
+  // render loop allocation-free.
+  label: string;
   lastRenderTimestamp: number;
 }
 
@@ -82,13 +85,15 @@ export const createScanner = (): ScannerController => {
 
     const existingOutline = outlines.get(element);
     if (existingOutline) {
-      existingOutline.componentName = componentName;
-      existingOutline.renderCount += 1;
+      const { nameCounts } = existingOutline;
+      nameCounts.set(componentName, (nameCounts.get(componentName) ?? 0) + 1);
+      existingOutline.label = formatRenderLabel(nameCounts);
       existingOutline.lastRenderTimestamp = currentCommitTimestamp;
     } else {
+      const nameCounts = new Map<string, number>([[componentName, 1]]);
       outlines.set(element, {
-        componentName,
-        renderCount: 1,
+        nameCounts,
+        label: formatRenderLabel(nameCounts),
         lastRenderTimestamp: currentCommitTimestamp,
       });
     }
@@ -146,10 +151,7 @@ export const createScanner = (): ScannerController => {
       opacity,
     );
 
-    const labelText =
-      outline.renderCount > 1
-        ? `${outline.componentName} ×${outline.renderCount}`
-        : outline.componentName;
+    const labelText = outline.label;
     context.globalAlpha = opacity;
     context.font = SCAN_LABEL_FONT;
     const labelWidth = context.measureText(labelText).width + SCAN_LABEL_PADDING_PX * 2;
diff --git a/packages/react-grab/src/utils/format-render-label.ts b/packages/react-grab/src/utils/format-render-label.ts
new file mode 100644
index 000000000..716e37987
--- /dev/null
+++ b/packages/react-grab/src/utils/format-render-label.ts
@@ -0,0 +1,27 @@
+import { SCAN_LABEL_MAX_CHARS, SCAN_LABEL_MAX_NAMES_PER_GROUP } from "../constants.js";
+
+// Builds the scan outline label from the component names that rendered into one
+// element. Names sharing a render count are grouped under a single `×count`
+// (e.g. "Row, Cell ×3, List ×1"), most-rendered first, and the whole label is
+// truncated with an ellipsis so a long name or many components can't overflow.
+export const formatRenderLabel = (nameCounts: Map<string, number>): string => {
+  const namesByCount = new Map<number, string[]>();
+  for (const [name, count] of nameCounts) {
+    const names = namesByCount.get(count);
+    if (names) {
+      names.push(name);
+    } else {
+      namesByCount.set(count, [name]);
+    }
+  }
+
+  const label = Array.from(namesByCount)
+    .sort(([countA], [countB]) => countB - countA)
+    .map(([count, names]) => {
+      const joined = names.slice(0, SCAN_LABEL_MAX_NAMES_PER_GROUP).join(", ");
+      return count > 1 ? `${joined} ×${count}` : joined;
+    })
+    .join(", ");
+
+  return label.length > SCAN_LABEL_MAX_CHARS ? `${label.slice(0, SCAN_LABEL_MAX_CHARS)}…` : label;
+};

From 29d319ff424ee82d903456444bd7e34ed5eb9b64 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Sun, 31 May 2026 23:56:05 -0700
Subject: [PATCH 09/16] feat(react-grab): hide scan button when no React
 instrumentation

The scan button only makes sense when bippy is instrumenting a React
renderer, so the toolbar now hides it until instrumentation is active.
The scanner module tracks activation (via bippy's onActive + first
commit) and exposes a subscribe; the controller surfaces it as a
reactive scanAvailable signal so the button appears once React mounts.
---
 packages/react-grab/e2e/scan.spec.ts          |  4 +-
 .../react-grab/src/components/renderer.tsx    |  1 +
 .../src/components/toolbar/index.tsx          | 47 ++++++++++---------
 packages/react-grab/src/core/index.tsx        |  1 +
 .../react-grab/src/core/scan-controller.ts    | 13 ++++-
 packages/react-grab/src/core/scanner.ts       | 22 +++++++++
 packages/react-grab/src/types.ts              |  1 +
 7 files changed, 64 insertions(+), 25 deletions(-)

diff --git a/packages/react-grab/e2e/scan.spec.ts b/packages/react-grab/e2e/scan.spec.ts
index 0cd0ea7f9..ce9e41e7f 100644
--- a/packages/react-grab/e2e/scan.spec.ts
+++ b/packages/react-grab/e2e/scan.spec.ts
@@ -71,7 +71,9 @@ test.describe("Render scan", () => {
     await waitForToolbar(reactGrab);
 
     await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(true);
-    expect(await reactGrab.getToolbarActionPressed("scan")).toBe(true);
+    await expect
+      .poll(() => reactGrab.getToolbarActionPressed("scan"), { timeout: 2000 })
+      .toBe(true);
   });
 
   test("copies a trace and shows the Copied toast on stop", async ({ reactGrab }) => {
diff --git a/packages/react-grab/src/components/renderer.tsx b/packages/react-grab/src/components/renderer.tsx
index e40018042..87ac7544b 100644
--- a/packages/react-grab/src/components/renderer.tsx
+++ b/packages/react-grab/src/components/renderer.tsx
@@ -144,6 +144,7 @@ export const ReactGrabRenderer: Component<ReactGrabRendererProps> = (props) => {
         <Toolbar
           isActive={props.isActive}
           isScanning={props.isScanning}
+          scanAvailable={props.scanAvailable}
           onToggleScan={props.onToggleScan}
           scanCopiedToken={props.scanCopiedToken}
           isContextMenuOpen={props.contextMenuPosition !== null}
diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index d9b22ec07..f39133487 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -46,6 +46,7 @@ import { accumulateRotationDeg } from "../../utils/accumulate-rotation.js";
 interface ToolbarProps {
   isActive?: boolean;
   isScanning?: boolean;
+  scanAvailable?: boolean;
   onToggleScan?: () => void;
   scanCopiedToken?: number | null;
   isContextMenuOpen?: boolean;
@@ -783,30 +784,32 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
               tooltipPosition={tooltipPosition()}
               tooltip="Style"
             />
-            <ToolbarActionButton
-              actionId={SCAN_ACTION_ID}
-              isToggle
-              label={props.isScanning ? "Stop scanning renders" : "Scan renders"}
-              isActive={Boolean(props.isScanning)}
-              class={actionButtonClass}
-              wrapperClass={actionButtonWrapperClass()}
-              onClick={handleScan}
-              {...createFreezeHandlers(SCAN_ACTION_ID, { shouldFreezeInteractions: false })}
-              icon={
-                props.isScanning ? (
-                  hoveredActionId() === SCAN_ACTION_ID ? (
-                    <IconStop size={14} class="text-[var(--rg-error-text)]" />
+            <Show when={props.scanAvailable}>
+              <ToolbarActionButton
+                actionId={SCAN_ACTION_ID}
+                isToggle
+                label={props.isScanning ? "Stop scanning renders" : "Scan renders"}
+                isActive={Boolean(props.isScanning)}
+                class={actionButtonClass}
+                wrapperClass={actionButtonWrapperClass()}
+                onClick={handleScan}
+                {...createFreezeHandlers(SCAN_ACTION_ID, { shouldFreezeInteractions: false })}
+                icon={
+                  props.isScanning ? (
+                    hoveredActionId() === SCAN_ACTION_ID ? (
+                      <IconStop size={14} class="text-[var(--rg-error-text)]" />
+                    ) : (
+                      <IconLoader size={14} class={actionIconClass(true)} />
+                    )
                   ) : (
-                    <IconLoader size={14} class={actionIconClass(true)} />
+                    <IconScan size={14} class={actionIconClass(false)} />
                   )
-                ) : (
-                  <IconScan size={14} class={actionIconClass(false)} />
-                )
-              }
-              tooltipVisible={isTooltipVisible(SCAN_ACTION_ID) && !props.isScanning}
-              tooltipPosition={tooltipPosition()}
-              tooltip="Scan"
-            />
+                }
+                tooltipVisible={isTooltipVisible(SCAN_ACTION_ID) && !props.isScanning}
+                tooltipPosition={tooltipPosition()}
+                tooltip="Scan"
+              />
+            </Show>
           </>
         }
       />
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 01c79509e..ac43f160f 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -3595,6 +3595,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
                 isActive={isActivated()}
                 onToggleActive={handleToggleActive}
                 isScanning={scanController.isScanning()}
+                scanAvailable={scanController.isScanAvailable()}
                 onToggleScan={scanController.toggle}
                 scanCopiedToken={scanController.scanCopiedToken()}
                 onActivateAction={handleActivateAction}
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
index a3dd25243..5b1c22900 100644
--- a/packages/react-grab/src/core/scan-controller.ts
+++ b/packages/react-grab/src/core/scan-controller.ts
@@ -3,7 +3,12 @@ import { FEEDBACK_DURATION_MS } from "../constants.js";
 import { copyContent } from "../utils/copy-content.js";
 import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
 import { loadScanActive, saveScanActive } from "../utils/scan-active-storage.js";
-import { createScanner, type ScannerController } from "./scanner.js";
+import {
+  createScanner,
+  isScanAvailable,
+  onScanAvailable,
+  type ScannerController,
+} from "./scanner.js";
 
 interface ScanControllerOptions {
   // Whether there is a toolbar to stop the scan from; a persisted scan only
@@ -13,6 +18,8 @@ interface ScanControllerOptions {
 
 export interface ScanController {
   scanner: ScannerController;
+  // Whether a React renderer is instrumented; the scan button hides when false.
+  isScanAvailable: Accessor<boolean>;
   isScanning: Accessor<boolean>;
   // A fresh token per successful copy (null when no toast). The toolbar keys
   // its toast on this so each copy replays the fade, even back-to-back.
@@ -26,6 +33,8 @@ export interface ScanController {
 // and persistence across reloads. Must run inside a reactive owner.
 export const createScanController = (options: ScanControllerOptions): ScanController => {
   const scanner = createScanner();
+  const [scanAvailable, setScanAvailable] = createSignal(isScanAvailable());
+  onCleanup(onScanAvailable(() => setScanAvailable(true)));
   const [isScanning, setIsScanning] = createSignal(false);
   const [scanCopiedToken, setScanCopiedToken] = createSignal<number | null>(null);
   let scanCopiedCount = 0;
@@ -85,5 +94,5 @@ export const createScanController = (options: ScanControllerOptions): ScanContro
     stop();
   });
 
-  return { scanner, isScanning, scanCopiedToken, toggle, stop };
+  return { scanner, isScanAvailable: scanAvailable, isScanning, scanCopiedToken, toggle, stop };
 };
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index da36332e4..e8bede36e 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -3,6 +3,7 @@ import {
   getDisplayName,
   getNearestHostFiber,
   isCompositeFiber,
+  isInstrumentationActive,
   traverseRenderedFibers,
   type Fiber,
   type FiberRoot,
@@ -47,10 +48,31 @@ export interface ScannerController {
 
 let handleCommit: (rendererId: number, root: FiberRoot) => void = () => {};
 
+// Tracks whether bippy is instrumenting a React renderer. Scanning is
+// meaningless without one, so the toolbar hides the scan button until this
+// flips true (on instrumentation activating or the first React commit).
+let hasActiveInstrumentation = isInstrumentationActive();
+const instrumentationListeners = new Set<() => void>();
+
+const markInstrumentationActive = (): void => {
+  if (hasActiveInstrumentation) return;
+  hasActiveInstrumentation = true;
+  for (const listener of instrumentationListeners) listener();
+};
+
+export const isScanAvailable = (): boolean => hasActiveInstrumentation;
+
+export const onScanAvailable = (listener: () => void): (() => void) => {
+  instrumentationListeners.add(listener);
+  return () => instrumentationListeners.delete(listener);
+};
+
 if (typeof window !== "undefined") {
   instrument({
     name: "react-grab-scan",
+    onActive: markInstrumentationActive,
     onCommitFiberRoot(_rendererId, root) {
+      markInstrumentationActive();
       return handleCommit(_rendererId, root);
     },
   });
diff --git a/packages/react-grab/src/types.ts b/packages/react-grab/src/types.ts
index d3b6bc538..d83add99b 100644
--- a/packages/react-grab/src/types.ts
+++ b/packages/react-grab/src/types.ts
@@ -491,6 +491,7 @@ export interface ReactGrabRendererProps {
   isActive?: boolean;
   onToggleActive?: () => void;
   isScanning?: boolean;
+  scanAvailable?: boolean;
   onToggleScan?: () => void;
   scanCopiedToken?: number | null;
   onActivateAction?: (actionId: string) => void;

From 6eb670fcc4e2d8b6624b149d21e480448a070d6b Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 00:02:46 -0700
Subject: [PATCH 10/16] feat(react-grab): capture per-commit fiber detail like
 react-scan/lite

Reworks the scan trace from a per-component aggregate into what
react-scan/lite records: per commit, the fibers that rendered with their
actualDuration, why they re-rendered (change description: props/state/
hooks/context/parent-cascade/mount) and where they live (source
file:line), plus the long-animation-frames over the same window so an
agent can correlate a slow frame with the commit and component behind it.

Ports lite's change-description and fiber-source (via bippy + bippy/source),
computes the parent-cascade flag from the nearest composite ancestor, and
caps stored commits/fibers so the copied log stays compact. The clipboard
log now lists commits slowest-first with each fiber's self time, reason,
and source, followed by the LoAF section.
---
 packages/react-grab/src/constants.ts          |   3 +-
 .../src/core/scan-trace-recorder.ts           | 108 +++++++++++------
 packages/react-grab/src/core/scanner.ts       |  13 +-
 packages/react-grab/src/types.ts              |  29 +++--
 .../src/utils/get-change-description.ts       | 111 ++++++++++++++++++
 .../react-grab/src/utils/get-fiber-source.ts  |  27 +++++
 .../src/utils/serialize-scan-trace.ts         |  49 +++++---
 7 files changed, 277 insertions(+), 63 deletions(-)
 create mode 100644 packages/react-grab/src/utils/get-change-description.ts
 create mode 100644 packages/react-grab/src/utils/get-fiber-source.ts

diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index 6c12d51d3..d3597b8e9 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -144,7 +144,8 @@ export const SCAN_ACTION_ID = "scan";
 export const Z_INDEX_SCAN_CANVAS = Z_INDEX_OVERLAY_CANVAS - 1;
 export const SCAN_OUTLINE_DURATION_MS = 900;
 export const LONG_ANIMATION_FRAME_ENTRY_TYPE = "long-animation-frame";
-export const MAX_SCAN_TRACE_COMPONENTS = 100;
+export const MAX_SCAN_TRACE_COMMITS = 50;
+export const MAX_SCAN_TRACE_FIBERS_PER_COMMIT = 20;
 export const MAX_SCAN_TRACE_LOAF_ENTRIES = 100;
 export const MAX_SCAN_TRACE_LOAF_SCRIPTS = 10;
 export const SCAN_LABEL_TEXT_COLOR = "rgba(255, 255, 255, 0.95)";
diff --git a/packages/react-grab/src/core/scan-trace-recorder.ts b/packages/react-grab/src/core/scan-trace-recorder.ts
index 2b32842f7..d08bf671d 100644
--- a/packages/react-grab/src/core/scan-trace-recorder.ts
+++ b/packages/react-grab/src/core/scan-trace-recorder.ts
@@ -1,16 +1,20 @@
 import type { Fiber } from "bippy";
 import {
   LONG_ANIMATION_FRAME_ENTRY_TYPE,
-  MAX_SCAN_TRACE_COMPONENTS,
+  MAX_SCAN_TRACE_COMMITS,
+  MAX_SCAN_TRACE_FIBERS_PER_COMMIT,
   MAX_SCAN_TRACE_LOAF_ENTRIES,
   MAX_SCAN_TRACE_LOAF_SCRIPTS,
 } from "../constants.js";
 import type {
-  ScanComponentProfile,
+  ScanCommit,
   ScanLoafScript,
   ScanLongAnimationFrame,
+  ScanRenderedFiber,
   ScanTrace,
 } from "../types.js";
+import { getChangeDescription } from "../utils/get-change-description.js";
+import { getFiberSource } from "../utils/get-fiber-source.js";
 
 // The `long-animation-frame` entry shape is not yet in the DOM lib types, so
 // we model the fields we read off PerformanceObserver entries here.
@@ -29,11 +33,20 @@ interface LongAnimationFrameTiming extends PerformanceEntry {
   scripts?: LongAnimationFrameScriptTiming[];
 }
 
+interface CollectedFiber {
+  fiber: Fiber;
+  name: string;
+  actualDurationMs: number;
+  selfDurationMs: number;
+  parentRendered: boolean;
+}
+
 export interface ScanTraceRecorder {
   begin: () => void;
   end: () => void;
   beginCommit: (timestamp: number) => void;
-  recordFiber: (componentName: string, fiber: Fiber) => void;
+  collectFiber: (fiber: Fiber, name: string, parentRendered: boolean) => void;
+  endCommit: () => void;
   takeTrace: () => ScanTrace | null;
 }
 
@@ -41,16 +54,18 @@ const isLongAnimationFrameSupported = (): boolean =>
   typeof PerformanceObserver !== "undefined" &&
   Boolean(PerformanceObserver.supportedEntryTypes?.includes(LONG_ANIMATION_FRAME_ENTRY_TYPE));
 
-// Pure, DOM-free profiling model: accumulates per-component render cost and
-// long-animation-frame entries over a scan session. Kept separate from the
-// canvas scanner so it can be reasoned about and tested on its own.
+// Records what react-scan/lite records - per commit, the fibers that rendered
+// with their actualDuration, why they re-rendered (change description) and
+// where they live (source) - plus the long-animation-frames over the same
+// window, so an agent can attribute a slow frame to a commit and a component.
 export const createScanTraceRecorder = (): ScanTraceRecorder => {
-  const componentProfiles = new Map<string, ScanComponentProfile>();
+  const commits: ScanCommit[] = [];
   const longAnimationFrames: ScanLongAnimationFrame[] = [];
+  const collected: CollectedFiber[] = [];
   let commitCount = 0;
+  let currentCommitTimestamp = 0;
   let scanStartTimestamp = 0;
   let scanStartEpochMs = 0;
-  let currentCommitTimestamp = 0;
   let observer: PerformanceObserver | null = null;
 
   const recordLongAnimationFrames = (list: PerformanceObserverEntryList): void => {
@@ -80,8 +95,9 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
   };
 
   const begin = (): void => {
-    componentProfiles.clear();
+    commits.length = 0;
     longAnimationFrames.length = 0;
+    collected.length = 0;
     commitCount = 0;
     scanStartTimestamp = performance.now();
     scanStartEpochMs = Date.now();
@@ -102,49 +118,63 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
   const beginCommit = (timestamp: number): void => {
     currentCommitTimestamp = timestamp;
     commitCount += 1;
+    collected.length = 0;
+  };
+
+  const collectFiber = (fiber: Fiber, name: string, parentRendered: boolean): void => {
+    collected.push({
+      fiber,
+      name,
+      actualDurationMs: fiber.actualDuration ?? 0,
+      selfDurationMs: fiber.selfBaseDuration ?? 0,
+      parentRendered,
+    });
   };
 
-  const recordFiber = (componentName: string, fiber: Fiber): void => {
-    const actualDurationMs = fiber.actualDuration ?? 0;
-    const selfDurationMs = fiber.selfBaseDuration ?? 0;
-    const existingProfile = componentProfiles.get(componentName);
-    if (existingProfile) {
-      existingProfile.renderCount += 1;
-      existingProfile.totalActualDurationMs += actualDurationMs;
-      existingProfile.totalSelfDurationMs += selfDurationMs;
-      if (actualDurationMs > existingProfile.maxActualDurationMs) {
-        existingProfile.maxActualDurationMs = actualDurationMs;
+  // Finalizes the in-progress commit: keep the slowest fibers, and only for
+  // those compute the (relatively expensive) change description + source while
+  // the fibers are still the live alternates for this commit.
+  const endCommit = (): void => {
+    if (collected.length === 0) return;
+    collected.sort((first, second) => second.actualDurationMs - first.actualDurationMs);
+
+    let totalActualDurationMs = 0;
+    for (const entry of collected) {
+      if (entry.actualDurationMs > totalActualDurationMs) {
+        totalActualDurationMs = entry.actualDurationMs;
       }
-      existingProfile.lastRenderTimestamp = currentCommitTimestamp;
-    } else {
-      componentProfiles.set(componentName, {
-        componentName,
-        renderCount: 1,
-        totalActualDurationMs: actualDurationMs,
-        maxActualDurationMs: actualDurationMs,
-        totalSelfDurationMs: selfDurationMs,
-        lastRenderTimestamp: currentCommitTimestamp,
-      });
     }
+
+    const fibers: ScanRenderedFiber[] = collected
+      .slice(0, MAX_SCAN_TRACE_FIBERS_PER_COMMIT)
+      .map((entry) => ({
+        name: entry.name,
+        actualDurationMs: entry.actualDurationMs,
+        selfDurationMs: entry.selfDurationMs,
+        source: getFiberSource(entry.fiber),
+        change: getChangeDescription(entry.fiber, entry.parentRendered),
+      }));
+
+    commits.push({
+      timestampMs: currentCommitTimestamp,
+      totalActualDurationMs,
+      renderedFiberCount: collected.length,
+      fibers,
+    });
+    if (commits.length > MAX_SCAN_TRACE_COMMITS) commits.shift();
+    collected.length = 0;
   };
 
   const takeTrace = (): ScanTrace | null => {
-    if (componentProfiles.size === 0 && longAnimationFrames.length === 0) return null;
-    const components = Array.from(componentProfiles.values())
-      .sort(
-        (first, second) =>
-          second.totalActualDurationMs - first.totalActualDurationMs ||
-          second.renderCount - first.renderCount,
-      )
-      .slice(0, MAX_SCAN_TRACE_COMPONENTS);
+    if (commits.length === 0 && longAnimationFrames.length === 0) return null;
     return {
       startedAtEpochMs: scanStartEpochMs,
       durationMs: performance.now() - scanStartTimestamp,
       commitCount,
-      components,
+      commits: commits.slice(),
       longAnimationFrames: longAnimationFrames.slice(),
     };
   };
 
-  return { begin, end, beginCommit, recordFiber, takeTrace };
+  return { begin, end, beginCommit, collectFiber, endCommit, takeTrace };
 };
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index e8bede36e..6845ea17e 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -1,5 +1,6 @@
 import {
   instrument,
+  didFiberRender,
   getDisplayName,
   getNearestHostFiber,
   isCompositeFiber,
@@ -94,12 +95,21 @@ export const createScanner = (): ScannerController => {
   // instead of calling performance.now() inside the hot fiber walk.
   let currentCommitTimestamp = 0;
 
+  const didNearestCompositeAncestorRender = (fiber: Fiber): boolean => {
+    let ancestor = fiber.return;
+    while (ancestor) {
+      if (isCompositeFiber(ancestor)) return didFiberRender(ancestor);
+      ancestor = ancestor.return;
+    }
+    return false;
+  };
+
   const recordRenderedFiber = (fiber: Fiber): void => {
     if (!isCompositeFiber(fiber)) return;
     const componentName = getDisplayName(fiber.type);
     if (!componentName || !isUsefulComponentName(componentName)) return;
 
-    recorder.recordFiber(componentName, fiber);
+    recorder.collectFiber(fiber, componentName, didNearestCompositeAncestorRender(fiber));
 
     const hostFiber = getNearestHostFiber(fiber);
     const element = hostFiber?.stateNode;
@@ -126,6 +136,7 @@ export const createScanner = (): ScannerController => {
     currentCommitTimestamp = performance.now();
     recorder.beginCommit(currentCommitTimestamp);
     traverseRenderedFibers(root, recordRenderedFiber);
+    recorder.endCommit();
     scheduleFrame();
   };
 
diff --git a/packages/react-grab/src/types.ts b/packages/react-grab/src/types.ts
index d83add99b..40bb91bd1 100644
--- a/packages/react-grab/src/types.ts
+++ b/packages/react-grab/src/types.ts
@@ -606,20 +606,35 @@ export interface ScanLongAnimationFrame {
   scripts: ScanLoafScript[];
 }
 
-export interface ScanComponentProfile {
-  componentName: string;
-  renderCount: number;
+export interface ScanFiberChange {
+  isFirstMount: boolean;
+  props: string[] | null;
+  state: boolean;
+  context: boolean;
+  hooks: number[];
+  parent: boolean;
+}
+
+export interface ScanRenderedFiber {
+  name: string;
+  actualDurationMs: number;
+  selfDurationMs: number;
+  source: string | null;
+  change: ScanFiberChange | null;
+}
+
+export interface ScanCommit {
+  timestampMs: number;
   totalActualDurationMs: number;
-  maxActualDurationMs: number;
-  totalSelfDurationMs: number;
-  lastRenderTimestamp: number;
+  renderedFiberCount: number;
+  fibers: ScanRenderedFiber[];
 }
 
 export interface ScanTrace {
   startedAtEpochMs: number;
   durationMs: number;
   commitCount: number;
-  components: ScanComponentProfile[];
+  commits: ScanCommit[];
   longAnimationFrames: ScanLongAnimationFrame[];
 }
 
diff --git a/packages/react-grab/src/utils/get-change-description.ts b/packages/react-grab/src/utils/get-change-description.ts
new file mode 100644
index 000000000..f5d234a55
--- /dev/null
+++ b/packages/react-grab/src/utils/get-change-description.ts
@@ -0,0 +1,111 @@
+import {
+  ClassComponentTag,
+  type Fiber,
+  ForwardRefTag,
+  FunctionComponentTag,
+  MemoComponentTag,
+  SimpleMemoComponentTag,
+  traverseContexts,
+  traverseProps,
+  traverseState,
+} from "bippy";
+import type { ScanFiberChange } from "../types.js";
+
+const isCompositeTag = (tag: number): boolean =>
+  tag === FunctionComponentTag ||
+  tag === ClassComponentTag ||
+  tag === ForwardRefTag ||
+  tag === MemoComponentTag ||
+  tag === SimpleMemoComponentTag;
+
+const collectChangedProps = (fiber: Fiber): string[] => {
+  const changed: string[] = [];
+  traverseProps(fiber, (propName, nextValue, prevValue) => {
+    if (!Object.is(prevValue, nextValue)) changed.push(propName);
+  });
+  return changed;
+};
+
+const didAnyContextChange = (fiber: Fiber): boolean => {
+  let changed = false;
+  traverseContexts(fiber, (nextContext, prevContext) => {
+    if (!nextContext || !prevContext) return;
+    if (nextContext.context !== prevContext.context) {
+      changed = false;
+      return true;
+    }
+    if (!Object.is(prevContext.memoizedValue, nextContext.memoizedValue)) {
+      changed = true;
+      return true;
+    }
+  });
+  return changed;
+};
+
+const didAnyClassStateChange = (fiber: Fiber): boolean => {
+  const previousState = fiber.alternate?.memoizedState;
+  const nextState = fiber.memoizedState;
+  if (
+    !previousState ||
+    !nextState ||
+    typeof previousState !== "object" ||
+    typeof nextState !== "object"
+  ) {
+    return previousState !== nextState;
+  }
+  const previousObject = previousState as Record<string, unknown>;
+  const nextObject = nextState as Record<string, unknown>;
+  for (const key of new Set([...Object.keys(previousObject), ...Object.keys(nextObject)])) {
+    if (!Object.is(previousObject[key], nextObject[key])) return true;
+  }
+  return false;
+};
+
+// Indices of stateful hooks whose memoizedState changed by reference.
+// Approximate: conflates useState with useMemo/useCallback/useEffect deps.
+const collectChangedHookIndices = (fiber: Fiber): number[] => {
+  const indices: number[] = [];
+  let index = 0;
+  traverseState(fiber, (nextState, prevState) => {
+    if (nextState && prevState && !Object.is(prevState.memoizedState, nextState.memoizedState)) {
+      indices.push(index);
+    }
+    index++;
+  });
+  return indices;
+};
+
+// Why a fiber re-rendered, attributed to props / state / context / hooks, or
+// flagged as a first mount / parent cascade. Ported from react-scan/lite (which
+// ports react-devtools' getChangeDescription); `parentRendered` is supplied by
+// the caller, which already knows whether a composite ancestor rendered.
+export const getChangeDescription = (
+  fiber: Fiber,
+  parentRendered: boolean,
+): ScanFiberChange | null => {
+  if (!isCompositeTag(fiber.tag)) return null;
+
+  if (fiber.alternate === null) {
+    return { isFirstMount: true, props: null, state: false, context: false, hooks: [], parent: false };
+  }
+
+  if (fiber.tag === ClassComponentTag) {
+    return {
+      isFirstMount: false,
+      props: collectChangedProps(fiber),
+      state: didAnyClassStateChange(fiber),
+      context: didAnyContextChange(fiber),
+      hooks: [],
+      parent: parentRendered,
+    };
+  }
+
+  return {
+    isFirstMount: false,
+    props: collectChangedProps(fiber),
+    state: false,
+    context: didAnyContextChange(fiber),
+    hooks: collectChangedHookIndices(fiber),
+    parent: parentRendered,
+  };
+};
diff --git a/packages/react-grab/src/utils/get-fiber-source.ts b/packages/react-grab/src/utils/get-fiber-source.ts
new file mode 100644
index 000000000..f3d4b2eac
--- /dev/null
+++ b/packages/react-grab/src/utils/get-fiber-source.ts
@@ -0,0 +1,27 @@
+import type { Fiber } from "bippy";
+import { formatOwnerStack, hasDebugSource, hasDebugStack, parseStack } from "bippy/source";
+
+// The JSX call site of a fiber as a compact "file:line:col" string, or null.
+// Synchronous only: reads `_debugSource` (React 16-18 dev) or parses the first
+// frame of `_debugStack` (React 19+ dev). No source-map symbolication - bundled
+// URLs only. Ported (trimmed) from react-scan/lite's getFiberSource.
+export const getFiberSource = (fiber: Fiber): string | null => {
+  if (hasDebugSource(fiber)) {
+    const { fileName, lineNumber, columnNumber } = fiber._debugSource;
+    return `${fileName}:${lineNumber}:${columnNumber}`;
+  }
+
+  if (hasDebugStack(fiber)) {
+    try {
+      const ownerStack = formatOwnerStack(fiber._debugStack.stack);
+      if (ownerStack) {
+        const frame = parseStack(ownerStack)[0];
+        if (frame?.fileName) {
+          return `${frame.fileName}:${frame.lineNumber}:${frame.columnNumber}`;
+        }
+      }
+    } catch {}
+  }
+
+  return null;
+};
diff --git a/packages/react-grab/src/utils/serialize-scan-trace.ts b/packages/react-grab/src/utils/serialize-scan-trace.ts
index 25659c4a0..f6cc05d2b 100644
--- a/packages/react-grab/src/utils/serialize-scan-trace.ts
+++ b/packages/react-grab/src/utils/serialize-scan-trace.ts
@@ -1,34 +1,53 @@
-import type { ScanTrace } from "../types.js";
+import type { ScanFiberChange, ScanTrace } from "../types.js";
 
 const round1 = (value: number): number => Math.round(value * 10) / 10;
 
+// Compact "why did this fiber render" from a change description.
+const formatChange = (change: ScanFiberChange | null): string => {
+  if (!change) return "?";
+  if (change.isFirstMount) return "mount";
+  const parts: string[] = [];
+  if (change.props && change.props.length > 0) parts.push(`props:${change.props.join(",")}`);
+  if (change.state) parts.push("state");
+  if (change.hooks.length > 0) parts.push(`hooks:${change.hooks.join(",")}`);
+  if (change.context) parts.push("context");
+  if (change.parent) parts.push("parent");
+  return parts.length > 0 ? parts.join(" ") : "?";
+};
+
 // Renders a render-scan trace as a compact, token-efficient log (not JSON) for
-// pasting to a coding agent. Columns are positional with terse labels and a
-// per-section legend, mirroring the react-scan/lite + LoAF correlation model:
-// rank components by render cost, then list the long-animation-frames so an
-// agent can attribute jank to a component and the script that blocked the frame.
+// pasting to a coding agent - the same data react-scan/lite captures (per
+// commit, the fibers that rendered with actualDuration, why, and where) plus
+// the long-animation-frames over the same window. Commits are listed slowest
+// first so the worst offenders lead; "parent" on a fiber marks a cascade
+// (re-rendered because an ancestor did), not a root cause.
 export const serializeScanTrace = (trace: ScanTrace): string => {
   const lines: string[] = [];
 
   lines.push(
     `react-grab render scan: ${(trace.durationMs / 1000).toFixed(1)}s, ` +
-      `${trace.commitCount} commits, ${trace.components.length} components, ` +
-      `${trace.longAnimationFrames.length} long frames (>50ms)`,
+      `${trace.commitCount} commits, ${trace.longAnimationFrames.length} long frames (>50ms)`,
   );
 
   lines.push("");
-  lines.push("components — name total ×renders avg max self (render ms), worst first:");
-  if (trace.components.length === 0) {
+  lines.push("commits — @start totalMs (rendered); fibers: name selfMs why @source, slowest first:");
+  if (trace.commits.length === 0) {
     lines.push("  none");
   } else {
-    for (const component of trace.components) {
+    const commits = trace.commits
+      .slice()
+      .sort((first, second) => second.totalActualDurationMs - first.totalActualDurationMs);
+    for (const commit of commits) {
       lines.push(
-        `  ${component.componentName} ${round1(component.totalActualDurationMs)}` +
-          ` ×${component.renderCount}` +
-          ` avg${round1(component.totalActualDurationMs / component.renderCount)}` +
-          ` max${round1(component.maxActualDurationMs)}` +
-          ` self${round1(component.totalSelfDurationMs)}`,
+        `  @${round1(commit.timestampMs)} ${round1(commit.totalActualDurationMs)}ms` +
+          ` (${commit.renderedFiberCount} rendered)`,
       );
+      for (const fiber of commit.fibers) {
+        const source = fiber.source ? ` @${fiber.source}` : "";
+        lines.push(
+          `    ${fiber.name} ${round1(fiber.selfDurationMs)}ms ${formatChange(fiber.change)}${source}`,
+        );
+      }
     }
   }
 

From 78aa07a93c2046559fe4eca27e7936daa1119032 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 00:18:13 -0700
Subject: [PATCH 11/16] fix(react-grab): address thermo review findings on scan
 trace

- Stop the scan when React Grab is disabled/collapsed (forceDeactivateAll)
  so the canvas + per-commit fiber walk + LoAF observer can't keep running
  with no UI to stop them.
- Fix didAnyContextChange: skip diverged context slots instead of aborting
  and wiping a real change, so the trace's "why" column isn't under-reported.
- Use accurate per-fiber self time via bippy getTimings (was selfBaseDuration),
  and drop the redundant max loop (the slowest fiber after sort is the total).
- Install the commit hook via bippy secure() for prod/version guards + error
  isolation instead of raw instrument().
- Flush observer.takeRecords() on stop so trailing long-animation-frames
  aren't dropped.
- Keep the scan button visible while scanning (not just when available) so a
  restored scan is always stoppable.
- Remove dead trace fields (startedAtEpochMs, per-fiber actualDurationMs,
  renderStartMs) and unused API (ScannerController.toggle/dispose,
  ScanController.scanner); toggle() now composes stop().
---
 .../src/components/toolbar/index.tsx          |  2 +-
 packages/react-grab/src/core/index.tsx        |  3 ++
 .../react-grab/src/core/scan-controller.ts    | 13 ++---
 .../src/core/scan-trace-recorder.ts           | 48 +++++++------------
 packages/react-grab/src/core/scanner.ts       | 29 ++++++-----
 packages/react-grab/src/types.ts              |  3 --
 .../src/utils/get-change-description.ts       |  8 ++--
 7 files changed, 46 insertions(+), 60 deletions(-)

diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index f39133487..ae7478eaa 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -784,7 +784,7 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
               tooltipPosition={tooltipPosition()}
               tooltip="Style"
             />
-            <Show when={props.scanAvailable}>
+            <Show when={props.scanAvailable || props.isScanning}>
               <ToolbarActionButton
                 actionId={SCAN_ACTION_ID}
                 isToggle
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index ac43f160f..3f4e67729 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -1505,6 +1505,9 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       if (isActivated()) {
         deactivateRenderer();
       }
+      // Stop any live scan too - disabling React Grab must not leave the canvas
+      // and per-commit fiber walk running with no UI to stop them.
+      scanController.stop();
       clearCopyFeedbackCooldown();
     };
 
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
index 5b1c22900..d8844491f 100644
--- a/packages/react-grab/src/core/scan-controller.ts
+++ b/packages/react-grab/src/core/scan-controller.ts
@@ -3,12 +3,7 @@ import { FEEDBACK_DURATION_MS } from "../constants.js";
 import { copyContent } from "../utils/copy-content.js";
 import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
 import { loadScanActive, saveScanActive } from "../utils/scan-active-storage.js";
-import {
-  createScanner,
-  isScanAvailable,
-  onScanAvailable,
-  type ScannerController,
-} from "./scanner.js";
+import { createScanner, isScanAvailable, onScanAvailable } from "./scanner.js";
 
 interface ScanControllerOptions {
   // Whether there is a toolbar to stop the scan from; a persisted scan only
@@ -17,7 +12,6 @@ interface ScanControllerOptions {
 }
 
 export interface ScanController {
-  scanner: ScannerController;
   // Whether a React renderer is instrumented; the scan button hides when false.
   isScanAvailable: Accessor<boolean>;
   isScanning: Accessor<boolean>;
@@ -59,8 +53,7 @@ export const createScanController = (options: ScanControllerOptions): ScanContro
 
   const toggle = () => {
     if (scanner.isScanning()) {
-      scanner.stop();
-      setIsScanning(false);
+      stop();
       saveScanActive(false);
       const trace = scanner.takeTrace();
       if (trace && copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
@@ -94,5 +87,5 @@ export const createScanController = (options: ScanControllerOptions): ScanContro
     stop();
   });
 
-  return { scanner, isScanAvailable: scanAvailable, isScanning, scanCopiedToken, toggle, stop };
+  return { isScanAvailable: scanAvailable, isScanning, scanCopiedToken, toggle, stop };
 };
diff --git a/packages/react-grab/src/core/scan-trace-recorder.ts b/packages/react-grab/src/core/scan-trace-recorder.ts
index d08bf671d..594b32231 100644
--- a/packages/react-grab/src/core/scan-trace-recorder.ts
+++ b/packages/react-grab/src/core/scan-trace-recorder.ts
@@ -1,4 +1,4 @@
-import type { Fiber } from "bippy";
+import { type Fiber, getTimings } from "bippy";
 import {
   LONG_ANIMATION_FRAME_ENTRY_TYPE,
   MAX_SCAN_TRACE_COMMITS,
@@ -27,7 +27,6 @@ interface LongAnimationFrameScriptTiming {
 }
 
 interface LongAnimationFrameTiming extends PerformanceEntry {
-  renderStart?: number;
   blockingDuration?: number;
   firstUIEventTimestamp?: number;
   scripts?: LongAnimationFrameScriptTiming[];
@@ -37,7 +36,6 @@ interface CollectedFiber {
   fiber: Fiber;
   name: string;
   actualDurationMs: number;
-  selfDurationMs: number;
   parentRendered: boolean;
 }
 
@@ -65,14 +63,13 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
   let commitCount = 0;
   let currentCommitTimestamp = 0;
   let scanStartTimestamp = 0;
-  let scanStartEpochMs = 0;
   let observer: PerformanceObserver | null = null;
 
-  const recordLongAnimationFrames = (list: PerformanceObserverEntryList): void => {
-    for (const entry of list.getEntries()) {
+  const ingestLoafEntries = (entries: PerformanceEntryList): void => {
+    for (const entry of entries) {
       if (longAnimationFrames.length >= MAX_SCAN_TRACE_LOAF_ENTRIES) break;
-      // getEntries() is typed as the base PerformanceEntry; the runtime entry
-      // carries the long-animation-frame fields modeled above.
+      // The runtime entry carries the long-animation-frame fields modeled above
+      // that aren't in the base PerformanceEntry lib type.
       const loafEntry = entry as LongAnimationFrameTiming;
       const scripts: ScanLoafScript[] = (loafEntry.scripts ?? [])
         .slice(0, MAX_SCAN_TRACE_LOAF_SCRIPTS)
@@ -87,7 +84,6 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
         startTimeMs: loafEntry.startTime,
         durationMs: loafEntry.duration,
         blockingDurationMs: loafEntry.blockingDuration ?? 0,
-        renderStartMs: loafEntry.renderStart ?? 0,
         firstUIEventTimestampMs: loafEntry.firstUIEventTimestamp ?? 0,
         scripts,
       });
@@ -100,9 +96,8 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
     collected.length = 0;
     commitCount = 0;
     scanStartTimestamp = performance.now();
-    scanStartEpochMs = Date.now();
     if (!isLongAnimationFrameSupported()) return;
-    observer = new PerformanceObserver(recordLongAnimationFrames);
+    observer = new PerformanceObserver((list) => ingestLoafEntries(list.getEntries()));
     try {
       observer.observe({ type: LONG_ANIMATION_FRAME_ENTRY_TYPE, buffered: false });
     } catch {
@@ -111,7 +106,11 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
   };
 
   const end = (): void => {
-    observer?.disconnect();
+    if (!observer) return;
+    // Drain entries the observer buffered but hasn't delivered yet (delivery is
+    // async), so frames near the end of the scan aren't lost on disconnect.
+    ingestLoafEntries(observer.takeRecords());
+    observer.disconnect();
     observer = null;
   };
 
@@ -122,35 +121,25 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
   };
 
   const collectFiber = (fiber: Fiber, name: string, parentRendered: boolean): void => {
-    collected.push({
-      fiber,
-      name,
-      actualDurationMs: fiber.actualDuration ?? 0,
-      selfDurationMs: fiber.selfBaseDuration ?? 0,
-      parentRendered,
-    });
+    collected.push({ fiber, name, actualDurationMs: fiber.actualDuration ?? 0, parentRendered });
   };
 
   // Finalizes the in-progress commit: keep the slowest fibers, and only for
-  // those compute the (relatively expensive) change description + source while
-  // the fibers are still the live alternates for this commit.
+  // those compute the (relatively expensive) change description + source +
+  // self time while the fibers are still the live alternates for this commit.
   const endCommit = (): void => {
     if (collected.length === 0) return;
     collected.sort((first, second) => second.actualDurationMs - first.actualDurationMs);
 
-    let totalActualDurationMs = 0;
-    for (const entry of collected) {
-      if (entry.actualDurationMs > totalActualDurationMs) {
-        totalActualDurationMs = entry.actualDurationMs;
-      }
-    }
+    // actualDuration nests children, so the slowest fiber's duration is the
+    // commit's total render time.
+    const totalActualDurationMs = collected[0].actualDurationMs;
 
     const fibers: ScanRenderedFiber[] = collected
       .slice(0, MAX_SCAN_TRACE_FIBERS_PER_COMMIT)
       .map((entry) => ({
         name: entry.name,
-        actualDurationMs: entry.actualDurationMs,
-        selfDurationMs: entry.selfDurationMs,
+        selfDurationMs: getTimings(entry.fiber).selfTime,
         source: getFiberSource(entry.fiber),
         change: getChangeDescription(entry.fiber, entry.parentRendered),
       }));
@@ -168,7 +157,6 @@ export const createScanTraceRecorder = (): ScanTraceRecorder => {
   const takeTrace = (): ScanTrace | null => {
     if (commits.length === 0 && longAnimationFrames.length === 0) return null;
     return {
-      startedAtEpochMs: scanStartEpochMs,
       durationMs: performance.now() - scanStartTimestamp,
       commitCount,
       commits: commits.slice(),
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index 6845ea17e..cf15eaed1 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -1,5 +1,6 @@
 import {
   instrument,
+  secure,
   didFiberRender,
   getDisplayName,
   getNearestHostFiber,
@@ -41,10 +42,8 @@ interface ScanOutline {
 export interface ScannerController {
   start: () => void;
   stop: () => void;
-  toggle: () => void;
   isScanning: () => boolean;
   takeTrace: () => ScanTrace | null;
-  dispose: () => void;
 }
 
 let handleCommit: (rendererId: number, root: FiberRoot) => void = () => {};
@@ -69,14 +68,22 @@ export const onScanAvailable = (listener: () => void): (() => void) => {
 };
 
 if (typeof window !== "undefined") {
-  instrument({
-    name: "react-grab-scan",
-    onActive: markInstrumentationActive,
-    onCommitFiberRoot(_rendererId, root) {
-      markInstrumentationActive();
-      return handleCommit(_rendererId, root);
-    },
-  });
+  // secure() adds bippy's production/React-version guard and per-callback error
+  // isolation around the commit hook. Scanning needs dev-only profiling timings
+  // anyway, so we let it stay disabled on production React.
+  instrument(
+    secure(
+      {
+        name: "react-grab-scan",
+        onActive: markInstrumentationActive,
+        onCommitFiberRoot(_rendererId, root) {
+          markInstrumentationActive();
+          return handleCommit(_rendererId, root);
+        },
+      },
+      { onError: () => {} },
+    ),
+  );
 }
 
 export const createScanner = (): ScannerController => {
@@ -260,9 +267,7 @@ export const createScanner = (): ScannerController => {
   return {
     start,
     stop,
-    toggle: () => (isScanning ? stop() : start()),
     isScanning: () => isScanning,
     takeTrace: recorder.takeTrace,
-    dispose: stop,
   };
 };
diff --git a/packages/react-grab/src/types.ts b/packages/react-grab/src/types.ts
index 40bb91bd1..494f17f59 100644
--- a/packages/react-grab/src/types.ts
+++ b/packages/react-grab/src/types.ts
@@ -601,7 +601,6 @@ export interface ScanLongAnimationFrame {
   startTimeMs: number;
   durationMs: number;
   blockingDurationMs: number;
-  renderStartMs: number;
   firstUIEventTimestampMs: number;
   scripts: ScanLoafScript[];
 }
@@ -617,7 +616,6 @@ export interface ScanFiberChange {
 
 export interface ScanRenderedFiber {
   name: string;
-  actualDurationMs: number;
   selfDurationMs: number;
   source: string | null;
   change: ScanFiberChange | null;
@@ -631,7 +629,6 @@ export interface ScanCommit {
 }
 
 export interface ScanTrace {
-  startedAtEpochMs: number;
   durationMs: number;
   commitCount: number;
   commits: ScanCommit[];
diff --git a/packages/react-grab/src/utils/get-change-description.ts b/packages/react-grab/src/utils/get-change-description.ts
index f5d234a55..aaadddb87 100644
--- a/packages/react-grab/src/utils/get-change-description.ts
+++ b/packages/react-grab/src/utils/get-change-description.ts
@@ -30,10 +30,10 @@ const didAnyContextChange = (fiber: Fiber): boolean => {
   let changed = false;
   traverseContexts(fiber, (nextContext, prevContext) => {
     if (!nextContext || !prevContext) return;
-    if (nextContext.context !== prevContext.context) {
-      changed = false;
-      return true;
-    }
+    // A context-identity mismatch means the dependency lists diverged (e.g. a
+    // conditional context read); skip this slot rather than aborting, so a
+    // genuine value change in a later context is still detected.
+    if (nextContext.context !== prevContext.context) return;
     if (!Object.is(prevContext.memoizedValue, nextContext.memoizedValue)) {
       changed = true;
       return true;

From 1c8347a401908d60d41309e849b3c96694d6e0c3 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 00:44:38 -0700
Subject: [PATCH 12/16] fix

---
 packages/react-grab/src/core/scanner.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index cf15eaed1..940f6e45c 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -46,7 +46,7 @@ export interface ScannerController {
   takeTrace: () => ScanTrace | null;
 }
 
-let handleCommit: (rendererId: number, root: FiberRoot) => void = () => {};
+let handleCommit: (root: FiberRoot) => void = () => {};
 
 // Tracks whether bippy is instrumenting a React renderer. Scanning is
 // meaningless without one, so the toolbar hides the scan button until this
@@ -78,7 +78,7 @@ if (typeof window !== "undefined") {
         onActive: markInstrumentationActive,
         onCommitFiberRoot(_rendererId, root) {
           markInstrumentationActive();
-          return handleCommit(_rendererId, root);
+          return handleCommit(root);
         },
       },
       { onError: () => {} },
@@ -138,7 +138,7 @@ export const createScanner = (): ScannerController => {
     }
   };
 
-  handleCommit = (_rendererId: number, root: FiberRoot): void => {
+  handleCommit = (root: FiberRoot): void => {
     if (!isScanning) return;
     currentCommitTimestamp = performance.now();
     recorder.beginCommit(currentCommitTimestamp);

From cf358ba87ca53e99933a8dd4785c0bb6bc7e00b8 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 00:55:40 -0700
Subject: [PATCH 13/16] chore(react-grab): drop unused rendererId from scan
 commit handler; "Stop scanning" tooltip

handleCommit now takes only the FiberRoot. The scan button shows a
"Stop scanning" tooltip on hover while active (was suppressed).
---
 .../src/components/toolbar/index.tsx          |  4 ++--
 packages/react-grab/src/core/scanner.ts       | 21 +++++++------------
 2 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index ae7478eaa..694cbb49b 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -805,9 +805,9 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
                     <IconScan size={14} class={actionIconClass(false)} />
                   )
                 }
-                tooltipVisible={isTooltipVisible(SCAN_ACTION_ID) && !props.isScanning}
+                tooltipVisible={isTooltipVisible(SCAN_ACTION_ID)}
                 tooltipPosition={tooltipPosition()}
-                tooltip="Scan"
+                tooltip={props.isScanning ? "Stop scanning" : "Scan"}
               />
             </Show>
           </>
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index 940f6e45c..1b13d17ac 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -71,19 +71,14 @@ if (typeof window !== "undefined") {
   // secure() adds bippy's production/React-version guard and per-callback error
   // isolation around the commit hook. Scanning needs dev-only profiling timings
   // anyway, so we let it stay disabled on production React.
-  instrument(
-    secure(
-      {
-        name: "react-grab-scan",
-        onActive: markInstrumentationActive,
-        onCommitFiberRoot(_rendererId, root) {
-          markInstrumentationActive();
-          return handleCommit(root);
-        },
-      },
-      { onError: () => {} },
-    ),
-  );
+  instrument({
+    name: "react-grab",
+    onActive: markInstrumentationActive,
+    onCommitFiberRoot(_rendererId, root) {
+      markInstrumentationActive();
+      return handleCommit(root);
+    },
+  });
 }
 
 export const createScanner = (): ScannerController => {

From 1cc5e359f91d8d12184c8de94525f3c404bffe3d Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 00:55:40 -0700
Subject: [PATCH 14/16] feat(react-grab): drop scan sessionStorage persistence

Reloading no longer resumes a scan. Removes scan-active-storage and the
DOMContentLoaded restore path, so a scan is purely in-memory for the
session and toggled only by the user. Simplifies the controller (no
persistence options) and drops the now-moot reload-resume e2e test.
---
 .changeset/render-scan-trace.md               |  2 +-
 packages/react-grab/e2e/scan.spec.ts          | 33 -----------------
 packages/react-grab/src/core/index.tsx        |  5 +--
 packages/react-grab/src/core/plugins/scan.ts  |  2 +-
 .../react-grab/src/core/scan-controller.ts    | 37 ++-----------------
 .../src/utils/scan-active-storage.ts          | 21 -----------
 6 files changed, 7 insertions(+), 93 deletions(-)
 delete mode 100644 packages/react-grab/src/utils/scan-active-storage.ts

diff --git a/.changeset/render-scan-trace.md b/.changeset/render-scan-trace.md
index b2575be54..4feccb918 100644
--- a/.changeset/render-scan-trace.md
+++ b/.changeset/render-scan-trace.md
@@ -2,4 +2,4 @@
 "react-grab": minor
 ---
 
-Add a render scan that highlights re-rendering components on a canvas overlay, and copies an agent-readable performance trace (per-component render cost + long-animation-frames) to the clipboard when you stop scanning. The toolbar shows a "Copied" pill on stop, and the scan state persists across reloads via sessionStorage.
+Add a render scan that highlights re-rendering components on a canvas overlay, and copies an agent-readable performance trace (per-commit fiber detail with render reasons and source, plus long-animation-frames) to the clipboard when you stop scanning. The toolbar shows a "Copied" pill on stop.
diff --git a/packages/react-grab/e2e/scan.spec.ts b/packages/react-grab/e2e/scan.spec.ts
index ce9e41e7f..c07371b5d 100644
--- a/packages/react-grab/e2e/scan.spec.ts
+++ b/packages/react-grab/e2e/scan.spec.ts
@@ -2,7 +2,6 @@ import { test, expect, type ReactGrabPageObject } from "./fixtures.js";
 import type { Page } from "@playwright/test";
 
 const ATTRIBUTE_NAME = "data-react-grab";
-const SCAN_ACTIVE_STORAGE_KEY = "react-grab-scan-active";
 
 const waitForToolbar = async (reactGrab: ReactGrabPageObject) => {
   await expect.poll(() => reactGrab.isToolbarVisible(), { timeout: 2000 }).toBe(true);
@@ -31,9 +30,6 @@ const isScanCopiedVisible = (page: Page): Promise<boolean> =>
     return Boolean(root?.querySelector("[data-react-grab-scan-copied]"));
   }, ATTRIBUTE_NAME);
 
-const getStoredScanActive = (page: Page, key: string): Promise<string | null> =>
-  page.evaluate((storageKey) => window.sessionStorage.getItem(storageKey), key);
-
 test.describe("Render scan", () => {
   test("starts and stops the scan canvas from the toolbar", async ({ reactGrab }) => {
     await waitForToolbar(reactGrab);
@@ -47,35 +43,6 @@ test.describe("Render scan", () => {
     expect(await reactGrab.getToolbarActionPressed("scan")).toBe(false);
   });
 
-  test("persists the scanning flag to sessionStorage", async ({ reactGrab }) => {
-    await waitForToolbar(reactGrab);
-
-    await clickScanButton(reactGrab.page);
-    await expect
-      .poll(() => getStoredScanActive(reactGrab.page, SCAN_ACTIVE_STORAGE_KEY), { timeout: 2000 })
-      .toBe("true");
-
-    await clickScanButton(reactGrab.page);
-    await expect
-      .poll(() => getStoredScanActive(reactGrab.page, SCAN_ACTIVE_STORAGE_KEY), { timeout: 2000 })
-      .toBe(null);
-  });
-
-  test("resumes a persisted scan after reload", async ({ reactGrab }) => {
-    await waitForToolbar(reactGrab);
-
-    await clickScanButton(reactGrab.page);
-    await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(true);
-
-    await reactGrab.page.reload();
-    await waitForToolbar(reactGrab);
-
-    await expect.poll(() => isScanCanvasPresent(reactGrab.page), { timeout: 2000 }).toBe(true);
-    await expect
-      .poll(() => reactGrab.getToolbarActionPressed("scan"), { timeout: 2000 })
-      .toBe(true);
-  });
-
   test("copies a trace and shows the Copied toast on stop", async ({ reactGrab }) => {
     await waitForToolbar(reactGrab);
 
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 3f4e67729..8c1abd82c 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -1606,10 +1606,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       handleActivateAction(currentToolbarState()?.defaultAction ?? DEFAULT_ACTION_ID);
     };
 
-    const scanController = createScanController({
-      isToolbarEnabled: () =>
-        Boolean(pluginRegistry.store.theme.enabled && pluginRegistry.store.theme.toolbar.enabled),
-    });
+    const scanController = createScanController();
 
     const enterCommentModeForElement = (element: Element, positionX: number, positionY: number) => {
       actions.setPendingCommentMode(false);
diff --git a/packages/react-grab/src/core/plugins/scan.ts b/packages/react-grab/src/core/plugins/scan.ts
index 65757992e..0326227ee 100644
--- a/packages/react-grab/src/core/plugins/scan.ts
+++ b/packages/react-grab/src/core/plugins/scan.ts
@@ -2,7 +2,7 @@ import type { Plugin } from "../../types.js";
 import { SCAN_ACTION_ID } from "../../constants.js";
 
 // Receives the scan controller's synced stop (not the raw scanner) so plugin
-// teardown keeps the toolbar's isScanning state and sessionStorage in sync.
+// teardown keeps the toolbar's isScanning state in sync.
 export const createScanPlugin = (stopScan: () => void): Plugin => ({
   name: SCAN_ACTION_ID,
   setup: () => ({
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
index d8844491f..a424a7d00 100644
--- a/packages/react-grab/src/core/scan-controller.ts
+++ b/packages/react-grab/src/core/scan-controller.ts
@@ -2,15 +2,8 @@ import { createSignal, onCleanup, type Accessor } from "solid-js";
 import { FEEDBACK_DURATION_MS } from "../constants.js";
 import { copyContent } from "../utils/copy-content.js";
 import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
-import { loadScanActive, saveScanActive } from "../utils/scan-active-storage.js";
 import { createScanner, isScanAvailable, onScanAvailable } from "./scanner.js";
 
-interface ScanControllerOptions {
-  // Whether there is a toolbar to stop the scan from; a persisted scan only
-  // resumes when true, so it can never run with no way to turn it off.
-  isToolbarEnabled: () => boolean;
-}
-
 export interface ScanController {
   // Whether a React renderer is instrumented; the scan button hides when false.
   isScanAvailable: Accessor<boolean>;
@@ -22,10 +15,10 @@ export interface ScanController {
   stop: () => void;
 }
 
-// Owns the full scan lifecycle: the canvas scanner, the reactive scanning
-// state, clipboard copy of the trace on stop, the transient "copied" toast,
-// and persistence across reloads. Must run inside a reactive owner.
-export const createScanController = (options: ScanControllerOptions): ScanController => {
+// Owns the scan lifecycle: the canvas scanner, the reactive scanning state,
+// clipboard copy of the trace on stop, and the transient "copied" toast.
+// Must run inside a reactive owner.
+export const createScanController = (): ScanController => {
   const scanner = createScanner();
   const [scanAvailable, setScanAvailable] = createSignal(isScanAvailable());
   onCleanup(onScanAvailable(() => setScanAvailable(true)));
@@ -41,10 +34,6 @@ export const createScanController = (options: ScanControllerOptions): ScanContro
     scanCopiedTimeout = setTimeout(() => setScanCopiedToken(null), FEEDBACK_DURATION_MS);
   };
 
-  // Stops the scanner and syncs the in-memory flag, but never writes persisted
-  // intent. sessionStorage is written only by an explicit user toggle, so a
-  // scan survives teardown/reload and resumes on the next init - and teardown
-  // ordering can't leave the persisted state inconsistent.
   const stop = () => {
     if (!scanner.isScanning()) return;
     scanner.stop();
@@ -54,7 +43,6 @@ export const createScanController = (options: ScanControllerOptions): ScanContro
   const toggle = () => {
     if (scanner.isScanning()) {
       stop();
-      saveScanActive(false);
       const trace = scanner.takeTrace();
       if (trace && copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
         flashCopied();
@@ -63,25 +51,8 @@ export const createScanController = (options: ScanControllerOptions): ScanContro
     }
     scanner.start();
     setIsScanning(true);
-    saveScanActive(true);
   };
 
-  // Resume a persisted scan across reloads/HMR. Deferred to DOMContentLoaded so
-  // the scanner's canvas has a document.body to attach to.
-  const restore = () => {
-    if (!loadScanActive() || scanner.isScanning() || !options.isToolbarEnabled()) return;
-    scanner.start();
-    setIsScanning(true);
-  };
-  if (typeof document !== "undefined") {
-    if (document.readyState === "loading") {
-      document.addEventListener("DOMContentLoaded", restore, { once: true });
-      onCleanup(() => document.removeEventListener("DOMContentLoaded", restore));
-    } else {
-      restore();
-    }
-  }
-
   onCleanup(() => {
     clearTimeout(scanCopiedTimeout);
     stop();
diff --git a/packages/react-grab/src/utils/scan-active-storage.ts b/packages/react-grab/src/utils/scan-active-storage.ts
deleted file mode 100644
index a0dad47ea..000000000
--- a/packages/react-grab/src/utils/scan-active-storage.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-const SCAN_ACTIVE_STORAGE_KEY = "react-grab-scan-active";
-
-export const loadScanActive = (): boolean => {
-  if (typeof window === "undefined") return false;
-  try {
-    return window.sessionStorage.getItem(SCAN_ACTIVE_STORAGE_KEY) === "true";
-  } catch {
-    return false;
-  }
-};
-
-export const saveScanActive = (isActive: boolean): void => {
-  if (typeof window === "undefined") return;
-  try {
-    if (isActive) {
-      window.sessionStorage.setItem(SCAN_ACTIVE_STORAGE_KEY, "true");
-    } else {
-      window.sessionStorage.removeItem(SCAN_ACTIVE_STORAGE_KEY);
-    }
-  } catch {}
-};

From b35fdb8623de62ffcd0ac78b4873213b643528d1 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 00:58:16 -0700
Subject: [PATCH 15/16] chore(react-grab): drop unused secure import; fix stale
 comment on scan instrument

---
 packages/react-grab/src/core/scanner.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index 1b13d17ac..ee22a6e3c 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -1,6 +1,5 @@
 import {
   instrument,
-  secure,
   didFiberRender,
   getDisplayName,
   getNearestHostFiber,
@@ -68,9 +67,10 @@ export const onScanAvailable = (listener: () => void): (() => void) => {
 };
 
 if (typeof window !== "undefined") {
-  // secure() adds bippy's production/React-version guard and per-callback error
-  // isolation around the commit hook. Scanning needs dev-only profiling timings
-  // anyway, so we let it stay disabled on production React.
+  // Raw instrument() (not secure()): secure tears the commit hook down if a
+  // React renderer isn't detected within its ~100ms install-check window, which
+  // breaks scanning on apps that mount React after react-grab's script loads.
+  // React core already wraps onCommitFiberRoot in try/catch, so this is safe.
   instrument({
     name: "react-grab",
     onActive: markInstrumentationActive,

From a5cb5204a7334684ea2a2bbe7f05d78b1b26b25c Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Mon, 1 Jun 2026 10:33:56 -0700
Subject: [PATCH 16/16] refactor(react-grab): consolidate scan modules into
 scanner.ts; trim comments

Merges scan-controller and scan-trace-recorder into core/scanner.ts
(recorder -> scanner -> controller), shrinking the public surface to
createScanController/ScanController. Also trims the scan feature's
comments down to only non-obvious "why" notes per AGENTS.
---
 .../react-grab/src/components/copied-pill.tsx |   5 +-
 packages/react-grab/src/constants.ts          |   5 +-
 packages/react-grab/src/core/index.tsx        |   4 +-
 packages/react-grab/src/core/plugins/scan.ts  |   4 +-
 .../react-grab/src/core/scan-controller.ts    |  62 -----
 .../src/core/scan-trace-recorder.ts           | 168 ------------
 packages/react-grab/src/core/scanner.ts       | 257 ++++++++++++++++--
 packages/react-grab/src/styles.css            |   2 -
 .../src/utils/format-render-label.ts          |   6 +-
 .../src/utils/get-change-description.ts       |  11 +-
 .../react-grab/src/utils/get-fiber-source.ts  |   6 +-
 .../src/utils/serialize-scan-trace.ts         |   8 +-
 12 files changed, 247 insertions(+), 291 deletions(-)
 delete mode 100644 packages/react-grab/src/core/scan-controller.ts
 delete mode 100644 packages/react-grab/src/core/scan-trace-recorder.ts

diff --git a/packages/react-grab/src/components/copied-pill.tsx b/packages/react-grab/src/components/copied-pill.tsx
index 487830469..4026e9a71 100644
--- a/packages/react-grab/src/components/copied-pill.tsx
+++ b/packages/react-grab/src/components/copied-pill.tsx
@@ -6,10 +6,7 @@ interface CopiedPillProps {
   text: string;
 }
 
-// Static, non-interactive "copied" confirmation pill for passive confirmations
-// (e.g. the toolbar scan-trace toast). It appears instantly, holds, then fades
-// itself out over its final FADE_DURATION_MS - the same dismissal the selection
-// label uses - so the parent only needs to mount/unmount it.
+// Static "copied" pill that self-fades on a CSS animation; parent only mounts it.
 export const CopiedPill: Component<CopiedPillProps> = (props) => {
   return (
     <div
diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index d3597b8e9..0323c59a1 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -137,10 +137,7 @@ export const COMMENT_ACTION_ID = "comment";
 export const EDIT_ACTION_ID = "edit";
 export const SCAN_ACTION_ID = "scan";
 
-// Render-scan overlay (bippy-driven re-render outlines). Reuses the shared
-// overlay pink (OVERLAY_*_COLOR_DEFAULT) and rounded-rect drawing; the scan
-// canvas lives outside the overlay shadow root, so it sits one step below the
-// overlay canvas to keep the selection/toolbar layers visually on top.
+// One below the overlay canvas so selection/toolbar layers stay on top.
 export const Z_INDEX_SCAN_CANVAS = Z_INDEX_OVERLAY_CANVAS - 1;
 export const SCAN_OUTLINE_DURATION_MS = 900;
 export const LONG_ANIMATION_FRAME_ENTRY_TYPE = "long-animation-frame";
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 8c1abd82c..ad4f0ddfd 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -127,7 +127,7 @@ import { commentPlugin } from "./plugins/comment.js";
 import { editPlugin } from "./plugins/edit.js";
 import { openPlugin } from "./plugins/open.js";
 import { createScanPlugin } from "./plugins/scan.js";
-import { createScanController } from "./scan-controller.js";
+import { createScanController } from "./scanner.js";
 import {
   freezeAnimations,
   freezeAllAnimations,
@@ -1505,8 +1505,6 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       if (isActivated()) {
         deactivateRenderer();
       }
-      // Stop any live scan too - disabling React Grab must not leave the canvas
-      // and per-commit fiber walk running with no UI to stop them.
       scanController.stop();
       clearCopyFeedbackCooldown();
     };
diff --git a/packages/react-grab/src/core/plugins/scan.ts b/packages/react-grab/src/core/plugins/scan.ts
index 0326227ee..25b52614b 100644
--- a/packages/react-grab/src/core/plugins/scan.ts
+++ b/packages/react-grab/src/core/plugins/scan.ts
@@ -1,8 +1,8 @@
 import type { Plugin } from "../../types.js";
 import { SCAN_ACTION_ID } from "../../constants.js";
 
-// Receives the scan controller's synced stop (not the raw scanner) so plugin
-// teardown keeps the toolbar's isScanning state in sync.
+// Takes the controller's synced stop (not the raw scanner) so teardown keeps
+// isScanning in sync.
 export const createScanPlugin = (stopScan: () => void): Plugin => ({
   name: SCAN_ACTION_ID,
   setup: () => ({
diff --git a/packages/react-grab/src/core/scan-controller.ts b/packages/react-grab/src/core/scan-controller.ts
deleted file mode 100644
index a424a7d00..000000000
--- a/packages/react-grab/src/core/scan-controller.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import { createSignal, onCleanup, type Accessor } from "solid-js";
-import { FEEDBACK_DURATION_MS } from "../constants.js";
-import { copyContent } from "../utils/copy-content.js";
-import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
-import { createScanner, isScanAvailable, onScanAvailable } from "./scanner.js";
-
-export interface ScanController {
-  // Whether a React renderer is instrumented; the scan button hides when false.
-  isScanAvailable: Accessor<boolean>;
-  isScanning: Accessor<boolean>;
-  // A fresh token per successful copy (null when no toast). The toolbar keys
-  // its toast on this so each copy replays the fade, even back-to-back.
-  scanCopiedToken: Accessor<number | null>;
-  toggle: () => void;
-  stop: () => void;
-}
-
-// Owns the scan lifecycle: the canvas scanner, the reactive scanning state,
-// clipboard copy of the trace on stop, and the transient "copied" toast.
-// Must run inside a reactive owner.
-export const createScanController = (): ScanController => {
-  const scanner = createScanner();
-  const [scanAvailable, setScanAvailable] = createSignal(isScanAvailable());
-  onCleanup(onScanAvailable(() => setScanAvailable(true)));
-  const [isScanning, setIsScanning] = createSignal(false);
-  const [scanCopiedToken, setScanCopiedToken] = createSignal<number | null>(null);
-  let scanCopiedCount = 0;
-  let scanCopiedTimeout: ReturnType<typeof setTimeout> | undefined;
-
-  const flashCopied = () => {
-    scanCopiedCount += 1;
-    setScanCopiedToken(scanCopiedCount);
-    clearTimeout(scanCopiedTimeout);
-    scanCopiedTimeout = setTimeout(() => setScanCopiedToken(null), FEEDBACK_DURATION_MS);
-  };
-
-  const stop = () => {
-    if (!scanner.isScanning()) return;
-    scanner.stop();
-    setIsScanning(false);
-  };
-
-  const toggle = () => {
-    if (scanner.isScanning()) {
-      stop();
-      const trace = scanner.takeTrace();
-      if (trace && copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
-        flashCopied();
-      }
-      return;
-    }
-    scanner.start();
-    setIsScanning(true);
-  };
-
-  onCleanup(() => {
-    clearTimeout(scanCopiedTimeout);
-    stop();
-  });
-
-  return { isScanAvailable: scanAvailable, isScanning, scanCopiedToken, toggle, stop };
-};
diff --git a/packages/react-grab/src/core/scan-trace-recorder.ts b/packages/react-grab/src/core/scan-trace-recorder.ts
deleted file mode 100644
index 594b32231..000000000
--- a/packages/react-grab/src/core/scan-trace-recorder.ts
+++ /dev/null
@@ -1,168 +0,0 @@
-import { type Fiber, getTimings } from "bippy";
-import {
-  LONG_ANIMATION_FRAME_ENTRY_TYPE,
-  MAX_SCAN_TRACE_COMMITS,
-  MAX_SCAN_TRACE_FIBERS_PER_COMMIT,
-  MAX_SCAN_TRACE_LOAF_ENTRIES,
-  MAX_SCAN_TRACE_LOAF_SCRIPTS,
-} from "../constants.js";
-import type {
-  ScanCommit,
-  ScanLoafScript,
-  ScanLongAnimationFrame,
-  ScanRenderedFiber,
-  ScanTrace,
-} from "../types.js";
-import { getChangeDescription } from "../utils/get-change-description.js";
-import { getFiberSource } from "../utils/get-fiber-source.js";
-
-// The `long-animation-frame` entry shape is not yet in the DOM lib types, so
-// we model the fields we read off PerformanceObserver entries here.
-interface LongAnimationFrameScriptTiming {
-  sourceURL?: string;
-  sourceFunctionName?: string;
-  sourceCharPosition?: number;
-  duration?: number;
-  forcedStyleAndLayoutDuration?: number;
-}
-
-interface LongAnimationFrameTiming extends PerformanceEntry {
-  blockingDuration?: number;
-  firstUIEventTimestamp?: number;
-  scripts?: LongAnimationFrameScriptTiming[];
-}
-
-interface CollectedFiber {
-  fiber: Fiber;
-  name: string;
-  actualDurationMs: number;
-  parentRendered: boolean;
-}
-
-export interface ScanTraceRecorder {
-  begin: () => void;
-  end: () => void;
-  beginCommit: (timestamp: number) => void;
-  collectFiber: (fiber: Fiber, name: string, parentRendered: boolean) => void;
-  endCommit: () => void;
-  takeTrace: () => ScanTrace | null;
-}
-
-const isLongAnimationFrameSupported = (): boolean =>
-  typeof PerformanceObserver !== "undefined" &&
-  Boolean(PerformanceObserver.supportedEntryTypes?.includes(LONG_ANIMATION_FRAME_ENTRY_TYPE));
-
-// Records what react-scan/lite records - per commit, the fibers that rendered
-// with their actualDuration, why they re-rendered (change description) and
-// where they live (source) - plus the long-animation-frames over the same
-// window, so an agent can attribute a slow frame to a commit and a component.
-export const createScanTraceRecorder = (): ScanTraceRecorder => {
-  const commits: ScanCommit[] = [];
-  const longAnimationFrames: ScanLongAnimationFrame[] = [];
-  const collected: CollectedFiber[] = [];
-  let commitCount = 0;
-  let currentCommitTimestamp = 0;
-  let scanStartTimestamp = 0;
-  let observer: PerformanceObserver | null = null;
-
-  const ingestLoafEntries = (entries: PerformanceEntryList): void => {
-    for (const entry of entries) {
-      if (longAnimationFrames.length >= MAX_SCAN_TRACE_LOAF_ENTRIES) break;
-      // The runtime entry carries the long-animation-frame fields modeled above
-      // that aren't in the base PerformanceEntry lib type.
-      const loafEntry = entry as LongAnimationFrameTiming;
-      const scripts: ScanLoafScript[] = (loafEntry.scripts ?? [])
-        .slice(0, MAX_SCAN_TRACE_LOAF_SCRIPTS)
-        .map((script) => ({
-          sourceURL: script.sourceURL ?? "",
-          sourceFunctionName: script.sourceFunctionName ?? "",
-          sourceCharPosition: script.sourceCharPosition ?? 0,
-          durationMs: script.duration ?? 0,
-          forcedStyleAndLayoutDurationMs: script.forcedStyleAndLayoutDuration ?? 0,
-        }));
-      longAnimationFrames.push({
-        startTimeMs: loafEntry.startTime,
-        durationMs: loafEntry.duration,
-        blockingDurationMs: loafEntry.blockingDuration ?? 0,
-        firstUIEventTimestampMs: loafEntry.firstUIEventTimestamp ?? 0,
-        scripts,
-      });
-    }
-  };
-
-  const begin = (): void => {
-    commits.length = 0;
-    longAnimationFrames.length = 0;
-    collected.length = 0;
-    commitCount = 0;
-    scanStartTimestamp = performance.now();
-    if (!isLongAnimationFrameSupported()) return;
-    observer = new PerformanceObserver((list) => ingestLoafEntries(list.getEntries()));
-    try {
-      observer.observe({ type: LONG_ANIMATION_FRAME_ENTRY_TYPE, buffered: false });
-    } catch {
-      observer = null;
-    }
-  };
-
-  const end = (): void => {
-    if (!observer) return;
-    // Drain entries the observer buffered but hasn't delivered yet (delivery is
-    // async), so frames near the end of the scan aren't lost on disconnect.
-    ingestLoafEntries(observer.takeRecords());
-    observer.disconnect();
-    observer = null;
-  };
-
-  const beginCommit = (timestamp: number): void => {
-    currentCommitTimestamp = timestamp;
-    commitCount += 1;
-    collected.length = 0;
-  };
-
-  const collectFiber = (fiber: Fiber, name: string, parentRendered: boolean): void => {
-    collected.push({ fiber, name, actualDurationMs: fiber.actualDuration ?? 0, parentRendered });
-  };
-
-  // Finalizes the in-progress commit: keep the slowest fibers, and only for
-  // those compute the (relatively expensive) change description + source +
-  // self time while the fibers are still the live alternates for this commit.
-  const endCommit = (): void => {
-    if (collected.length === 0) return;
-    collected.sort((first, second) => second.actualDurationMs - first.actualDurationMs);
-
-    // actualDuration nests children, so the slowest fiber's duration is the
-    // commit's total render time.
-    const totalActualDurationMs = collected[0].actualDurationMs;
-
-    const fibers: ScanRenderedFiber[] = collected
-      .slice(0, MAX_SCAN_TRACE_FIBERS_PER_COMMIT)
-      .map((entry) => ({
-        name: entry.name,
-        selfDurationMs: getTimings(entry.fiber).selfTime,
-        source: getFiberSource(entry.fiber),
-        change: getChangeDescription(entry.fiber, entry.parentRendered),
-      }));
-
-    commits.push({
-      timestampMs: currentCommitTimestamp,
-      totalActualDurationMs,
-      renderedFiberCount: collected.length,
-      fibers,
-    });
-    if (commits.length > MAX_SCAN_TRACE_COMMITS) commits.shift();
-    collected.length = 0;
-  };
-
-  const takeTrace = (): ScanTrace | null => {
-    if (commits.length === 0 && longAnimationFrames.length === 0) return null;
-    return {
-      durationMs: performance.now() - scanStartTimestamp,
-      commitCount,
-      commits: commits.slice(),
-      longAnimationFrames: longAnimationFrames.slice(),
-    };
-  };
-
-  return { begin, end, beginCommit, collectFiber, endCommit, takeTrace };
-};
diff --git a/packages/react-grab/src/core/scanner.ts b/packages/react-grab/src/core/scanner.ts
index ee22a6e3c..06e504099 100644
--- a/packages/react-grab/src/core/scanner.ts
+++ b/packages/react-grab/src/core/scanner.ts
@@ -3,13 +3,21 @@ import {
   didFiberRender,
   getDisplayName,
   getNearestHostFiber,
+  getTimings,
   isCompositeFiber,
   isInstrumentationActive,
   traverseRenderedFibers,
   type Fiber,
   type FiberRoot,
 } from "bippy";
+import { createSignal, onCleanup, type Accessor } from "solid-js";
 import {
+  FEEDBACK_DURATION_MS,
+  LONG_ANIMATION_FRAME_ENTRY_TYPE,
+  MAX_SCAN_TRACE_COMMITS,
+  MAX_SCAN_TRACE_FIBERS_PER_COMMIT,
+  MAX_SCAN_TRACE_LOAF_ENTRIES,
+  MAX_SCAN_TRACE_LOAF_SCRIPTS,
   MIN_DEVICE_PIXEL_RATIO,
   OVERLAY_BORDER_COLOR_DEFAULT,
   OVERLAY_FILL_COLOR_DEFAULT,
@@ -20,25 +28,181 @@ import {
   SCAN_OUTLINE_DURATION_MS,
   Z_INDEX_SCAN_CANVAS,
 } from "../constants.js";
-import type { ScanTrace } from "../types.js";
-import { createScanTraceRecorder } from "./scan-trace-recorder.js";
-import { hideFromThirdParties } from "../utils/hide-from-third-parties.js";
-import { nativeCancelAnimationFrame, nativeRequestAnimationFrame } from "../utils/native-raf.js";
-import { isUsefulComponentName } from "../utils/is-useful-component-name.js";
+import type {
+  ScanCommit,
+  ScanLoafScript,
+  ScanLongAnimationFrame,
+  ScanRenderedFiber,
+  ScanTrace,
+} from "../types.js";
+import { copyContent } from "../utils/copy-content.js";
 import { createElementBounds } from "../utils/create-element-bounds.js";
 import { drawRoundedRectangle } from "../utils/draw-rounded-rectangle.js";
-import { parseBorderRadiusValue } from "../utils/parse-border-radius-value.js";
 import { formatRenderLabel } from "../utils/format-render-label.js";
+import { getChangeDescription } from "../utils/get-change-description.js";
+import { getFiberSource } from "../utils/get-fiber-source.js";
+import { hideFromThirdParties } from "../utils/hide-from-third-parties.js";
+import { isUsefulComponentName } from "../utils/is-useful-component-name.js";
+import { nativeCancelAnimationFrame, nativeRequestAnimationFrame } from "../utils/native-raf.js";
+import { parseBorderRadiusValue } from "../utils/parse-border-radius-value.js";
+import { serializeScanTrace } from "../utils/serialize-scan-trace.js";
+
+// ---------------------------------------------------------------------------
+// Trace recorder: per-commit fiber detail (actualDuration, why, where) + LoAFs.
+// ---------------------------------------------------------------------------
+
+// `long-animation-frame` fields aren't in the DOM lib types yet.
+interface LongAnimationFrameScriptTiming {
+  sourceURL?: string;
+  sourceFunctionName?: string;
+  sourceCharPosition?: number;
+  duration?: number;
+  forcedStyleAndLayoutDuration?: number;
+}
+
+interface LongAnimationFrameTiming extends PerformanceEntry {
+  blockingDuration?: number;
+  firstUIEventTimestamp?: number;
+  scripts?: LongAnimationFrameScriptTiming[];
+}
+
+interface CollectedFiber {
+  fiber: Fiber;
+  name: string;
+  actualDurationMs: number;
+  parentRendered: boolean;
+}
+
+interface ScanTraceRecorder {
+  begin: () => void;
+  end: () => void;
+  beginCommit: (timestamp: number) => void;
+  collectFiber: (fiber: Fiber, name: string, parentRendered: boolean) => void;
+  endCommit: () => void;
+  takeTrace: () => ScanTrace | null;
+}
+
+const isLongAnimationFrameSupported = (): boolean =>
+  typeof PerformanceObserver !== "undefined" &&
+  Boolean(PerformanceObserver.supportedEntryTypes?.includes(LONG_ANIMATION_FRAME_ENTRY_TYPE));
+
+const createScanTraceRecorder = (): ScanTraceRecorder => {
+  const commits: ScanCommit[] = [];
+  const longAnimationFrames: ScanLongAnimationFrame[] = [];
+  const collected: CollectedFiber[] = [];
+  let commitCount = 0;
+  let currentCommitTimestamp = 0;
+  let scanStartTimestamp = 0;
+  let observer: PerformanceObserver | null = null;
+
+  const ingestLoafEntries = (entries: PerformanceEntryList): void => {
+    for (const entry of entries) {
+      if (longAnimationFrames.length >= MAX_SCAN_TRACE_LOAF_ENTRIES) break;
+      const loafEntry = entry as LongAnimationFrameTiming;
+      const scripts: ScanLoafScript[] = (loafEntry.scripts ?? [])
+        .slice(0, MAX_SCAN_TRACE_LOAF_SCRIPTS)
+        .map((script) => ({
+          sourceURL: script.sourceURL ?? "",
+          sourceFunctionName: script.sourceFunctionName ?? "",
+          sourceCharPosition: script.sourceCharPosition ?? 0,
+          durationMs: script.duration ?? 0,
+          forcedStyleAndLayoutDurationMs: script.forcedStyleAndLayoutDuration ?? 0,
+        }));
+      longAnimationFrames.push({
+        startTimeMs: loafEntry.startTime,
+        durationMs: loafEntry.duration,
+        blockingDurationMs: loafEntry.blockingDuration ?? 0,
+        firstUIEventTimestampMs: loafEntry.firstUIEventTimestamp ?? 0,
+        scripts,
+      });
+    }
+  };
+
+  const begin = (): void => {
+    commits.length = 0;
+    longAnimationFrames.length = 0;
+    collected.length = 0;
+    commitCount = 0;
+    scanStartTimestamp = performance.now();
+    if (!isLongAnimationFrameSupported()) return;
+    observer = new PerformanceObserver((list) => ingestLoafEntries(list.getEntries()));
+    try {
+      observer.observe({ type: LONG_ANIMATION_FRAME_ENTRY_TYPE, buffered: false });
+    } catch {
+      observer = null;
+    }
+  };
+
+  const end = (): void => {
+    if (!observer) return;
+    // Drain buffered-but-undelivered entries (delivery is async) before disconnect.
+    ingestLoafEntries(observer.takeRecords());
+    observer.disconnect();
+    observer = null;
+  };
+
+  const beginCommit = (timestamp: number): void => {
+    currentCommitTimestamp = timestamp;
+    commitCount += 1;
+    collected.length = 0;
+  };
+
+  const collectFiber = (fiber: Fiber, name: string, parentRendered: boolean): void => {
+    collected.push({ fiber, name, actualDurationMs: fiber.actualDuration ?? 0, parentRendered });
+  };
+
+  const endCommit = (): void => {
+    if (collected.length === 0) return;
+    collected.sort((first, second) => second.actualDurationMs - first.actualDurationMs);
+
+    // actualDuration nests children, so the slowest fiber's is the commit total.
+    const totalActualDurationMs = collected[0].actualDurationMs;
+
+    // Enrich only the kept fibers, and now, while they're still this commit's
+    // live alternates.
+    const fibers: ScanRenderedFiber[] = collected
+      .slice(0, MAX_SCAN_TRACE_FIBERS_PER_COMMIT)
+      .map((entry) => ({
+        name: entry.name,
+        selfDurationMs: getTimings(entry.fiber).selfTime,
+        source: getFiberSource(entry.fiber),
+        change: getChangeDescription(entry.fiber, entry.parentRendered),
+      }));
+
+    commits.push({
+      timestampMs: currentCommitTimestamp,
+      totalActualDurationMs,
+      renderedFiberCount: collected.length,
+      fibers,
+    });
+    if (commits.length > MAX_SCAN_TRACE_COMMITS) commits.shift();
+    collected.length = 0;
+  };
+
+  const takeTrace = (): ScanTrace | null => {
+    if (commits.length === 0 && longAnimationFrames.length === 0) return null;
+    return {
+      durationMs: performance.now() - scanStartTimestamp,
+      commitCount,
+      commits: commits.slice(),
+      longAnimationFrames: longAnimationFrames.slice(),
+    };
+  };
+
+  return { begin, end, beginCommit, collectFiber, endCommit, takeTrace };
+};
+
+// ---------------------------------------------------------------------------
+// Scanner: a single global commit hook driving a canvas of re-render outlines.
+// ---------------------------------------------------------------------------
 
 interface ScanOutline {
   nameCounts: Map<string, number>;
-  // Cached label, recomputed only on commit (not per frame) to keep the
-  // render loop allocation-free.
   label: string;
   lastRenderTimestamp: number;
 }
 
-export interface ScannerController {
+interface ScannerController {
   start: () => void;
   stop: () => void;
   isScanning: () => boolean;
@@ -47,9 +211,6 @@ export interface ScannerController {
 
 let handleCommit: (root: FiberRoot) => void = () => {};
 
-// Tracks whether bippy is instrumenting a React renderer. Scanning is
-// meaningless without one, so the toolbar hides the scan button until this
-// flips true (on instrumentation activating or the first React commit).
 let hasActiveInstrumentation = isInstrumentationActive();
 const instrumentationListeners = new Set<() => void>();
 
@@ -59,18 +220,16 @@ const markInstrumentationActive = (): void => {
   for (const listener of instrumentationListeners) listener();
 };
 
-export const isScanAvailable = (): boolean => hasActiveInstrumentation;
+const isScanAvailable = (): boolean => hasActiveInstrumentation;
 
-export const onScanAvailable = (listener: () => void): (() => void) => {
+const onScanAvailable = (listener: () => void): (() => void) => {
   instrumentationListeners.add(listener);
   return () => instrumentationListeners.delete(listener);
 };
 
 if (typeof window !== "undefined") {
-  // Raw instrument() (not secure()): secure tears the commit hook down if a
-  // React renderer isn't detected within its ~100ms install-check window, which
-  // breaks scanning on apps that mount React after react-grab's script loads.
-  // React core already wraps onCommitFiberRoot in try/catch, so this is safe.
+  // Not secure(): it tears the hook down if React isn't detected within ~100ms,
+  // which breaks apps that mount React after react-grab's script loads.
   instrument({
     name: "react-grab",
     onActive: markInstrumentationActive,
@@ -81,7 +240,7 @@ if (typeof window !== "undefined") {
   });
 }
 
-export const createScanner = (): ScannerController => {
+const createScanner = (): ScannerController => {
   let isScanning = false;
   let canvas: HTMLCanvasElement | null = null;
   let context: CanvasRenderingContext2D | null = null;
@@ -93,8 +252,6 @@ export const createScanner = (): ScannerController => {
   const outlines = new Map<HTMLElement, ScanOutline>();
   const recorder = createScanTraceRecorder();
 
-  // Set once per commit so the per-fiber recorder reads a single clock value
-  // instead of calling performance.now() inside the hot fiber walk.
   let currentCommitTimestamp = 0;
 
   const didNearestCompositeAncestorRender = (fiber: Fiber): boolean => {
@@ -242,8 +399,6 @@ export const createScanner = (): ScannerController => {
     scheduleFrame();
   };
 
-  // The recorder's trace is intentionally preserved after stop() so the caller
-  // can read it via takeTrace(); the next start() clears it via recorder.begin().
   const stop = (): void => {
     if (!isScanning) return;
     isScanning = false;
@@ -266,3 +421,59 @@ export const createScanner = (): ScannerController => {
     takeTrace: recorder.takeTrace,
   };
 };
+
+// ---------------------------------------------------------------------------
+// Controller: reactive scan state, clipboard copy on stop, "copied" toast.
+// ---------------------------------------------------------------------------
+
+export interface ScanController {
+  isScanAvailable: Accessor<boolean>;
+  isScanning: Accessor<boolean>;
+  // Fresh token per copy so the toolbar can key (and replay) its toast.
+  scanCopiedToken: Accessor<number | null>;
+  toggle: () => void;
+  stop: () => void;
+}
+
+export const createScanController = (): ScanController => {
+  const scanner = createScanner();
+  const [scanAvailable, setScanAvailable] = createSignal(isScanAvailable());
+  onCleanup(onScanAvailable(() => setScanAvailable(true)));
+  const [isScanning, setIsScanning] = createSignal(false);
+  const [scanCopiedToken, setScanCopiedToken] = createSignal<number | null>(null);
+  let scanCopiedCount = 0;
+  let scanCopiedTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  const flashCopied = () => {
+    scanCopiedCount += 1;
+    setScanCopiedToken(scanCopiedCount);
+    clearTimeout(scanCopiedTimeout);
+    scanCopiedTimeout = setTimeout(() => setScanCopiedToken(null), FEEDBACK_DURATION_MS);
+  };
+
+  const stop = () => {
+    if (!scanner.isScanning()) return;
+    scanner.stop();
+    setIsScanning(false);
+  };
+
+  const toggle = () => {
+    if (scanner.isScanning()) {
+      stop();
+      const trace = scanner.takeTrace();
+      if (trace && copyContent(serializeScanTrace(trace), { componentName: "ReactGrabScan" })) {
+        flashCopied();
+      }
+      return;
+    }
+    scanner.start();
+    setIsScanning(true);
+  };
+
+  onCleanup(() => {
+    clearTimeout(scanCopiedTimeout);
+    stop();
+  });
+
+  return { isScanAvailable: scanAvailable, isScanning, scanCopiedToken, toggle, stop };
+};
diff --git a/packages/react-grab/src/styles.css b/packages/react-grab/src/styles.css
index f746e3393..c948b8ed7 100644
--- a/packages/react-grab/src/styles.css
+++ b/packages/react-grab/src/styles.css
@@ -337,8 +337,6 @@
   will-change: transform, opacity;
 }
 
-/* Hold, then fade+blur out - matches the selection label's dismissal. The
-   hold duration comes from the animation-delay set inline on the element. */
 @keyframes rg-copied-pill-out {
   from {
     opacity: 1;
diff --git a/packages/react-grab/src/utils/format-render-label.ts b/packages/react-grab/src/utils/format-render-label.ts
index 716e37987..291caa670 100644
--- a/packages/react-grab/src/utils/format-render-label.ts
+++ b/packages/react-grab/src/utils/format-render-label.ts
@@ -1,9 +1,7 @@
 import { SCAN_LABEL_MAX_CHARS, SCAN_LABEL_MAX_NAMES_PER_GROUP } from "../constants.js";
 
-// Builds the scan outline label from the component names that rendered into one
-// element. Names sharing a render count are grouped under a single `×count`
-// (e.g. "Row, Cell ×3, List ×1"), most-rendered first, and the whole label is
-// truncated with an ellipsis so a long name or many components can't overflow.
+// Outline label for an element: names grouped by render count (e.g.
+// "Row, Cell ×3, List ×1"), most first, ellipsis-truncated.
 export const formatRenderLabel = (nameCounts: Map<string, number>): string => {
   const namesByCount = new Map<number, string[]>();
   for (const [name, count] of nameCounts) {
diff --git a/packages/react-grab/src/utils/get-change-description.ts b/packages/react-grab/src/utils/get-change-description.ts
index aaadddb87..482b599e9 100644
--- a/packages/react-grab/src/utils/get-change-description.ts
+++ b/packages/react-grab/src/utils/get-change-description.ts
@@ -30,9 +30,7 @@ const didAnyContextChange = (fiber: Fiber): boolean => {
   let changed = false;
   traverseContexts(fiber, (nextContext, prevContext) => {
     if (!nextContext || !prevContext) return;
-    // A context-identity mismatch means the dependency lists diverged (e.g. a
-    // conditional context read); skip this slot rather than aborting, so a
-    // genuine value change in a later context is still detected.
+    // Diverged dependency lists (conditional context read): skip, don't abort.
     if (nextContext.context !== prevContext.context) return;
     if (!Object.is(prevContext.memoizedValue, nextContext.memoizedValue)) {
       changed = true;
@@ -61,7 +59,6 @@ const didAnyClassStateChange = (fiber: Fiber): boolean => {
   return false;
 };
 
-// Indices of stateful hooks whose memoizedState changed by reference.
 // Approximate: conflates useState with useMemo/useCallback/useEffect deps.
 const collectChangedHookIndices = (fiber: Fiber): number[] => {
   const indices: number[] = [];
@@ -75,10 +72,8 @@ const collectChangedHookIndices = (fiber: Fiber): number[] => {
   return indices;
 };
 
-// Why a fiber re-rendered, attributed to props / state / context / hooks, or
-// flagged as a first mount / parent cascade. Ported from react-scan/lite (which
-// ports react-devtools' getChangeDescription); `parentRendered` is supplied by
-// the caller, which already knows whether a composite ancestor rendered.
+// Why a fiber re-rendered (props/state/context/hooks/mount/parent-cascade).
+// Ported from react-scan/lite; `parentRendered` is supplied by the caller.
 export const getChangeDescription = (
   fiber: Fiber,
   parentRendered: boolean,
diff --git a/packages/react-grab/src/utils/get-fiber-source.ts b/packages/react-grab/src/utils/get-fiber-source.ts
index f3d4b2eac..4c3b36146 100644
--- a/packages/react-grab/src/utils/get-fiber-source.ts
+++ b/packages/react-grab/src/utils/get-fiber-source.ts
@@ -1,10 +1,8 @@
 import type { Fiber } from "bippy";
 import { formatOwnerStack, hasDebugSource, hasDebugStack, parseStack } from "bippy/source";
 
-// The JSX call site of a fiber as a compact "file:line:col" string, or null.
-// Synchronous only: reads `_debugSource` (React 16-18 dev) or parses the first
-// frame of `_debugStack` (React 19+ dev). No source-map symbolication - bundled
-// URLs only. Ported (trimmed) from react-scan/lite's getFiberSource.
+// JSX call site as "file:line:col", or null. Sync, dev-only, no symbolication:
+// `_debugSource` (React 16-18) or the first `_debugStack` frame (React 19+).
 export const getFiberSource = (fiber: Fiber): string | null => {
   if (hasDebugSource(fiber)) {
     const { fileName, lineNumber, columnNumber } = fiber._debugSource;
diff --git a/packages/react-grab/src/utils/serialize-scan-trace.ts b/packages/react-grab/src/utils/serialize-scan-trace.ts
index f6cc05d2b..3e5c380d2 100644
--- a/packages/react-grab/src/utils/serialize-scan-trace.ts
+++ b/packages/react-grab/src/utils/serialize-scan-trace.ts
@@ -2,7 +2,6 @@ import type { ScanFiberChange, ScanTrace } from "../types.js";
 
 const round1 = (value: number): number => Math.round(value * 10) / 10;
 
-// Compact "why did this fiber render" from a change description.
 const formatChange = (change: ScanFiberChange | null): string => {
   if (!change) return "?";
   if (change.isFirstMount) return "mount";
@@ -15,12 +14,7 @@ const formatChange = (change: ScanFiberChange | null): string => {
   return parts.length > 0 ? parts.join(" ") : "?";
 };
 
-// Renders a render-scan trace as a compact, token-efficient log (not JSON) for
-// pasting to a coding agent - the same data react-scan/lite captures (per
-// commit, the fibers that rendered with actualDuration, why, and where) plus
-// the long-animation-frames over the same window. Commits are listed slowest
-// first so the worst offenders lead; "parent" on a fiber marks a cascade
-// (re-rendered because an ancestor did), not a root cause.
+// Compact, token-efficient log (not JSON) of the trace for pasting to an agent.
 export const serializeScanTrace = (trace: ScanTrace): string => {
   const lines: string[] = [];