feat: surface specific changed prop/state/hook keys in profiling output (#32)

* feat: surface changed prop/state/hook keys in profiling output

Add ChangedKeys type carrying specific changed keys (props, state,
hooks) alongside cause type strings. This makes profiling output more
actionable by showing *which* props/state/hooks changed, not just
*that* they changed.

- Add ChangedKeys interface and changedKeys field to ComponentRenderReport
- Add extractChangedKeys helper and aggregate keys across commits in Profiler
- Include changedKeys in CommitDetail components
- Add formatChangedKeys helper and display keys in all profiling formatters
- Add tests for key aggregation, deduplication, and display

* chore: add changeset for changed keys feature

* docs: update profiling output examples with changed keys

Author: piotrski

.changeset/surface-changed-keys.md

@@ -0,0 +1,12 @@
+---
+"agent-react-devtools": minor
+---
+
+Surface specific changed prop/state/hook keys in profiling output
+
+Profiling reports and commit details now show *which* props, state keys, and hooks changed, not just *that* they changed.
+
+- `profile report` and `profile slow` append `changed: props: onClick, className  state: count` lines
+- `profile rerenders` and `profile commit` include the same detail per component
+- Keys are deduplicated across commits in aggregate reports
+- Empty keys produce no extra output (backward-compatible)

README.md

@@ -97,8 +97,8 @@ agent-react-devtools profile slow
 
 ```
 Slowest (by avg render time):
-  @c5 [fn] TodoList  avg:4.2ms  max:8.1ms  renders:6  causes:props-changed
-  @c4 [fn] SearchBar  avg:2.1ms  max:3.4ms  renders:12  causes:hooks-changed
+  @c5 [fn] TodoList  avg:4.2ms  max:8.1ms  renders:6  causes:props-changed  changed: props: items, onDelete
+  @c4 [fn] SearchBar  avg:2.1ms  max:3.4ms  renders:12  causes:hooks-changed  changed: hooks: #0
   @c2 [fn] Header  avg:0.8ms  max:1.2ms  renders:3  causes:parent-rendered
 ```
 

packages/agent-react-devtools/skills/react-devtools/SKILL.md

@@ -89,12 +89,14 @@ hooks:
 
 ```
 Slowest (by avg render time):
-  @c3 [fn] ExpensiveList  avg:12.3ms  max:18.1ms  renders:47  causes:props-changed
-  @c4 [fn] TodoItem  avg:2.1ms  max:5.0ms  renders:94  causes:parent-rendered, props-changed
+  @c3 [fn] ExpensiveList  avg:12.3ms  max:18.1ms  renders:47  causes:props-changed  changed: props: items, filter
+  @c4 [fn] TodoItem  avg:2.1ms  max:5.0ms  renders:94  causes:parent-rendered, props-changed  changed: props: onToggle
 ```
 
 Render causes: `props-changed`, `state-changed`, `hooks-changed`, `parent-rendered`, `force-update`, `first-mount`.
 
+When specific changed keys are available, a `changed:` suffix shows exactly which props, state keys, or hooks triggered the render (e.g. `changed: props: onClick, className  state: count  hooks: #0`).
+
 ## Common Patterns
 
 ### Wait for the app to connect after a reload

packages/agent-react-devtools/skills/react-devtools/references/commands.md

@@ -65,21 +65,31 @@ Stop profiling and collect data from React. Shows a summary with duration, commi
 ### `agent-react-devtools profile slow [--limit N]`
 Rank components by average render duration (slowest first). Default limit: 10.
 
-Output columns: label, type tag, component name, avg duration, max duration, render count, all causes.
+Output columns: label, type tag, component name, avg duration, max duration, render count, all causes, changed keys.
 
 ### `agent-react-devtools profile rerenders [--limit N]`
 Rank components by render count (most re-renders first). Default limit: 10.
 
-Output columns: label, type tag, component name, render count, all causes.
+Output columns: label, type tag, component name, render count, all causes, changed keys.
 
 ### `agent-react-devtools profile report <@cN | id>`
-Detailed render report for a single component: render count, avg/max/total duration, all render causes.
+Detailed render report for a single component: render count, avg/max/total duration, all render causes, changed keys.
 
 ### `agent-react-devtools profile timeline [--limit N]`
 Chronological list of React commits during the profiling session. Each entry: index, duration, component count.
 
 ### `agent-react-devtools profile commit <N | #N> [--limit N]`
-Detail for a specific commit by index. Shows per-component self/total duration and render causes.
+Detail for a specific commit by index. Shows per-component self/total duration, render causes, and changed keys.
+
+### Changed Keys
+
+When React DevTools reports which specific props, state keys, or hooks triggered a re-render, profiling commands append a `changed:` suffix:
+
+```
+changed: props: onClick, className  state: count  hooks: #0
+```
+
+Categories with no changes are omitted. Keys are deduplicated across commits in aggregate reports (`profile slow`, `profile rerenders`, `profile report`).
 
 ## Setup
 

packages/agent-react-devtools/skills/react-devtools/references/profiling-guide.md

@@ -59,15 +59,15 @@ Once you identify a suspect, get its full render report:
 agent-react-devtools profile report @c12
 ```
 
-This shows all render causes. Common patterns:
+This shows all render causes and the specific changed keys (e.g. `changed: props: onClick, className  state: count`). Use the changed keys to pinpoint exactly what to stabilize or investigate. Common patterns:
 
-| Cause | Meaning | Typical Fix |
-|-------|---------|-------------|
-| `parent-rendered` | Parent re-rendered, child has no bailout | Wrap child in `React.memo()` |
-| `props-changed` | Received new prop references | Stabilize with `useMemo`/`useCallback` in parent |
-| `state-changed` | Component's own state changed | Check if state update is necessary |
-| `hooks-changed` | A hook dependency changed | Review hook dependencies |
-| `first-mount` | Initial render | Normal — not a problem |
+| Cause | Changed keys example | Meaning | Typical Fix |
+|-------|---------------------|---------|-------------|
+| `parent-rendered` | _(none)_ | Parent re-rendered, child has no bailout | Wrap child in `React.memo()` |
+| `props-changed` | `props: onClick, style` | Received new prop references | Stabilize the listed props with `useMemo`/`useCallback` in parent |
+| `state-changed` | `state: count, filter` | Component's own state changed | Check if the listed state updates are necessary |
+| `hooks-changed` | `hooks: #0, #2` | A hook dependency changed | Review deps of the listed hooks (by index) |
+| `first-mount` | _(none)_ | Initial render | Normal — not a problem |
 
 ### 5. Inspect the Component
 
@@ -101,7 +101,7 @@ Compare render counts and durations to confirm improvement.
 A parent component re-renders (e.g., from a timer or context change) and all children re-render because none use `React.memo`. Look for high re-render counts with `parent-rendered` cause.
 
 ### Unstable prop references
-Parent passes `onClick={() => ...}` or `style={{...}}` inline — creates new references every render, defeating `memo()`. The child shows `props-changed` as the cause even though the values are semantically identical.
+Parent passes `onClick={() => ...}` or `style={{...}}` inline — creates new references every render, defeating `memo()`. The child shows `props-changed` as the cause even though the values are semantically identical. The `changed:` output tells you exactly which props are the culprits (e.g. `changed: props: onClick, style`).
 
 ### Expensive computations without memoization
 A component does heavy work (filtering, sorting, formatting) on every render. Shows up as high avg render time. Fix with `useMemo`.

packages/agent-react-devtools/src/__tests__/formatters.test.ts

@@ -12,9 +12,10 @@ import {
   formatRerenders,
   formatTimeline,
   formatCommitDetail,
+  formatChangedKeys,
 } from '../formatters.js';
 import type { TreeNode } from '../component-tree.js';
-import type { InspectedElement, StatusInfo, ComponentRenderReport, ConnectionHealth } from '../types.js';
+import type { InspectedElement, StatusInfo, ComponentRenderReport, ConnectionHealth, ChangedKeys } from '../types.js';
 import type { ProfileSummary, TimelineEntry, CommitDetail } from '../profiler.js';
 
 describe('formatTree', () => {
@@ -252,7 +253,7 @@ describe('formatProfileSummary', () => {
 });
 
 describe('formatProfileReport', () => {
-  it('should format a render report with type tag', () => {
+  it('should format a render report with changed keys', () => {
     const report: ComponentRenderReport = {
       id: 5,
       displayName: 'UserProfile',
@@ -263,6 +264,7 @@ describe('formatProfileReport', () => {
       avgDuration: 45,
       maxDuration: 120,
       causes: ['props-changed', 'state-changed'],
+      changedKeys: { props: ['userId', 'theme'], state: ['isEditing'], hooks: [] },
     };
 
     const result = formatProfileReport(report);
@@ -271,6 +273,23 @@ describe('formatProfileReport', () => {
     expect(result).toContain('avg:45.0ms');
     expect(result).toContain('max:120.0ms');
     expect(result).toContain('props-changed');
+    expect(result).toContain('changed: props: userId, theme  state: isEditing');
+  });
+
+  it('should omit changed line when keys are empty', () => {
+    const report: ComponentRenderReport = {
+      id: 5,
+      displayName: 'UserProfile',
+      renderCount: 1,
+      totalDuration: 10,
+      avgDuration: 10,
+      maxDuration: 10,
+      causes: ['first-mount'],
+      changedKeys: { props: [], state: [], hooks: [] },
+    };
+
+    const result = formatProfileReport(report, '@c5');
+    expect(result).not.toContain('changed:');
   });
 
   it('should prefer explicit label param over report.label', () => {
@@ -296,31 +315,42 @@ describe('formatSlowest', () => {
     expect(formatSlowest([])).toContain('No profiling data');
   });
 
-  it('should format slowest components with labels and all causes', () => {
+  it('should format slowest components with labels and changed keys', () => {
     const reports: ComponentRenderReport[] = [
-      { id: 1, displayName: 'SlowComp', label: '@c1', type: 'function', renderCount: 5, totalDuration: 250, avgDuration: 50, maxDuration: 100, causes: ['props-changed', 'state-changed'] },
-      { id: 2, displayName: 'FastComp', label: '@c2', type: 'memo', renderCount: 10, totalDuration: 100, avgDuration: 10, maxDuration: 20, causes: ['state-changed'] },
+      { id: 1, displayName: 'SlowComp', label: '@c1', type: 'function', renderCount: 5, totalDuration: 250, avgDuration: 50, maxDuration: 100, causes: ['props-changed', 'state-changed'], changedKeys: { props: ['data'], state: ['count'], hooks: [] } },
+      { id: 2, displayName: 'FastComp', label: '@c2', type: 'memo', renderCount: 10, totalDuration: 100, avgDuration: 10, maxDuration: 20, causes: ['state-changed'], changedKeys: { props: [], state: ['count'], hooks: [] } },
     ];
 
     const result = formatSlowest(reports);
     expect(result).toContain('Slowest');
     expect(result).toContain('@c1 [fn] SlowComp');
     expect(result).toContain('@c2 [memo] FastComp');
     expect(result).toContain('causes:props-changed, state-changed');
-    expect(result).toContain('causes:state-changed');
+    expect(result).toContain('changed: props: data  state: count');
+    expect(result).toContain('changed: state: count');
   });
 });
 
 describe('formatRerenders', () => {
-  it('should format rerender data with labels and all causes', () => {
+  it('should format rerender data with labels and changed keys', () => {
     const reports: ComponentRenderReport[] = [
-      { id: 1, displayName: 'Chatty', label: '@c1', type: 'function', renderCount: 50, totalDuration: 100, avgDuration: 2, maxDuration: 5, causes: ['parent-rendered', 'props-changed'] },
+      { id: 1, displayName: 'Chatty', label: '@c1', type: 'function', renderCount: 50, totalDuration: 100, avgDuration: 2, maxDuration: 5, causes: ['parent-rendered', 'props-changed'], changedKeys: { props: ['value'], state: [], hooks: [] } },
     ];
 
     const result = formatRerenders(reports);
     expect(result).toContain('50 renders');
     expect(result).toContain('@c1 [fn] Chatty');
     expect(result).toContain('causes:parent-rendered, props-changed');
+    expect(result).toContain('changed: props: value');
+  });
+
+  it('should omit changed line when keys are empty', () => {
+    const reports: ComponentRenderReport[] = [
+      { id: 1, displayName: 'Chatty', label: '@c1', type: 'function', renderCount: 50, totalDuration: 100, avgDuration: 2, maxDuration: 5, causes: ['parent-rendered'], changedKeys: { props: [], state: [], hooks: [] } },
+    ];
+
+    const result = formatRerenders(reports);
+    expect(result).not.toContain('changed:');
   });
 });
 
@@ -340,14 +370,14 @@ describe('formatTimeline', () => {
 });
 
 describe('formatCommitDetail', () => {
-  it('should format commit detail with labels and types', () => {
+  it('should format commit detail with labels, types, and changed keys', () => {
     const detail: CommitDetail = {
       index: 0,
       timestamp: 1000,
       duration: 15.5,
       components: [
-        { id: 1, displayName: 'App', label: '@c1', type: 'function', actualDuration: 15.5, selfDuration: 5.2, causes: ['state-changed'] },
-        { id: 2, displayName: 'Header', label: '@c2', type: 'memo', actualDuration: 10.3, selfDuration: 10.3, causes: ['props-changed', 'hooks-changed'] },
+        { id: 1, displayName: 'App', label: '@c1', type: 'function', actualDuration: 15.5, selfDuration: 5.2, causes: ['state-changed'], changedKeys: { props: [], state: ['count'], hooks: [] } },
+        { id: 2, displayName: 'Header', label: '@c2', type: 'memo', actualDuration: 10.3, selfDuration: 10.3, causes: ['props-changed', 'hooks-changed'], changedKeys: { props: ['onClick', 'className'], state: [], hooks: [0] } },
       ],
       totalComponents: 2,
     };
@@ -360,8 +390,10 @@ describe('formatCommitDetail', () => {
     expect(result).toContain('self:5.2ms');
     expect(result).toContain('total:15.5ms');
     expect(result).toContain('causes:state-changed');
+    expect(result).toContain('changed: state: count');
     expect(result).toContain('@c2 [memo] Header');
     expect(result).toContain('causes:props-changed, hooks-changed');
+    expect(result).toContain('changed: props: onClick, className  hooks: #0');
   });
 
   it('should show hidden count', () => {
@@ -370,12 +402,45 @@ describe('formatCommitDetail', () => {
       timestamp: 2000,
       duration: 10,
       components: [
-        { id: 1, displayName: 'App', label: '@c1', type: 'function', actualDuration: 10, selfDuration: 10, causes: [] },
+        { id: 1, displayName: 'App', label: '@c1', type: 'function', actualDuration: 10, selfDuration: 10, causes: [], changedKeys: { props: [], state: [], hooks: [] } },
       ],
       totalComponents: 5,
     };
 
     const result = formatCommitDetail(detail);
     expect(result).toContain('... 4 more');
   });
+
+  it('should omit changed keys when empty', () => {
+    const detail: CommitDetail = {
+      index: 0,
+      timestamp: 1000,
+      duration: 5,
+      components: [
+        { id: 1, displayName: 'App', label: '@c1', type: 'function', actualDuration: 5, selfDuration: 5, causes: ['first-mount'], changedKeys: { props: [], state: [], hooks: [] } },
+      ],
+      totalComponents: 1,
+    };
+
+    const result = formatCommitDetail(detail);
+    expect(result).toContain('App');
+    expect(result).not.toContain('changed:');
+  });
+});
+
+describe('formatChangedKeys', () => {
+  it('should format all key categories', () => {
+    const keys: ChangedKeys = { props: ['onClick', 'className'], state: ['count'], hooks: [0, 3] };
+    expect(formatChangedKeys(keys)).toBe('props: onClick, className  state: count  hooks: #0, #3');
+  });
+
+  it('should return empty string when no keys', () => {
+    const keys: ChangedKeys = { props: [], state: [], hooks: [] };
+    expect(formatChangedKeys(keys)).toBe('');
+  });
+
+  it('should omit empty categories', () => {
+    const keys: ChangedKeys = { props: ['theme'], state: [], hooks: [] };
+    expect(formatChangedKeys(keys)).toBe('props: theme');
+  });
 });

packages/agent-react-devtools/src/__tests__/profiler.test.ts

@@ -140,6 +140,44 @@ describe('Profiler', () => {
     expect(report!.maxDuration).toBe(20);
     expect(report!.causes).toContain('props-changed');
     expect(report!.causes).toContain('hooks-changed');
+    expect(report!.changedKeys!.props).toEqual(['theme']);
+    expect(report!.changedKeys!.state).toEqual([]);
+    expect(report!.changedKeys!.hooks).toEqual([]);
+  });
+
+  it('should deduplicate changed keys across commits', () => {
+    profiler.start('test');
+
+    profiler.processProfilingData({
+      commitData: [
+        {
+          timestamp: 1000,
+          duration: 5,
+          fiberActualDurations: [1, 5],
+          fiberSelfDurations: [1, 5],
+          changeDescriptions: [
+            [1, { props: ['onClick', 'className'], state: ['count'], isFirstMount: false }],
+          ],
+        },
+        {
+          timestamp: 2000,
+          duration: 5,
+          fiberActualDurations: [1, 5],
+          fiberSelfDurations: [1, 5],
+          changeDescriptions: [
+            [1, { props: ['className', 'theme'], state: ['count'], hooks: [0, 2], isFirstMount: false }],
+          ],
+        },
+      ],
+    });
+
+    const report = profiler.getReport(1, tree);
+    expect(report).not.toBeNull();
+    expect(report!.changedKeys!.props).toEqual(expect.arrayContaining(['onClick', 'className', 'theme']));
+    expect(report!.changedKeys!.props).toHaveLength(3);
+    expect(report!.changedKeys!.state).toEqual(['count']);
+    expect(report!.changedKeys!.hooks).toEqual(expect.arrayContaining([0, 2]));
+    expect(report!.changedKeys!.hooks).toHaveLength(2);
   });
 
   it('should find slowest components', () => {