Skip to content

Commit 445934c

Browse files
committed
fix(components): point recording hints at record-change-detection and wait for the page
#433 moved `record` from `change-detection` to `record-change-detection` and refuses the old argument, but several answers still told agents to call `change-detection` with `record: "start"`, and the recording tool pointed back at itself. Every hint and the docs now name the right tool, and a test keeps the old wording out. The panel announced "Recording started." as soon as the request reached the server, and a stop that got no report still announced a total. It now waits for the page to report that recording is on or off, and says the page did not confirm when no report comes within 3 seconds. Refs #366
1 parent b10969d commit 445934c

11 files changed

Lines changed: 233 additions & 47 deletions

File tree

‎app/src/__tests__/cd-recording-status.test.ts‎

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,13 @@ describe('CdRecording status', () => {
7474
pageId: 'p1',
7575
on: true,
7676
});
77-
expect(live()).toBe('Recording started.');
77+
// The server took the request; the page has not said it records yet.
78+
expect(live()).not.toContain('started');
79+
expect(visible()).toBe('Starting…');
7880

7981
await show(true, 3);
8082
expect(live()).toBe('Recording started.');
83+
expect(visible()).toBe('Recording. 3 cycles so far.');
8184

8285
await click('Stop recording');
8386
// The page's last report still brings cycles: the total waits for it.
@@ -89,20 +92,51 @@ describe('CdRecording status', () => {
8992
expect(live()).toBe('Cleared the recorded cycles.');
9093
});
9194

92-
it('announces the count it has when the last report does not come', async () => {
93-
await show(true, 2);
95+
/** Clicks with fake timers, so the confirmation wait can run out. */
96+
async function clickAndWait(text: string, ms: number) {
9497
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
9598
try {
96-
button('Stop recording').click();
99+
button(text).click();
97100
await vi.advanceTimersByTimeAsync(0);
98101
fixture.detectChanges();
99-
expect(live()).not.toContain('stopped');
100-
await vi.advanceTimersByTimeAsync(3000);
102+
const before = live();
103+
await vi.advanceTimersByTimeAsync(ms);
101104
fixture.detectChanges();
102-
expect(live()).toBe('Recording stopped. 2 cycles recorded.');
105+
return before;
103106
} finally {
104107
vi.useRealTimers();
105108
}
109+
}
110+
111+
it('says the page did not confirm when no report shows the recording on', async () => {
112+
const before = await clickAndWait('Record', 3000);
113+
expect(before).not.toContain('started');
114+
const failed =
115+
'The page did not confirm that the recording started. The tab may be in the background, closed or reloading.';
116+
expect(live()).toBe(failed);
117+
expect(visible()).toBe(failed);
118+
// The page still reports no recording, so the button still offers Record.
119+
expect(button('Record')).toBeTruthy();
120+
expect(button('Stop recording')).toBeUndefined();
121+
});
122+
123+
it('announces the start once a late report confirms it', async () => {
124+
await clickAndWait('Record', 3000);
125+
expect(live()).toContain('did not confirm');
126+
await show(true, 1);
127+
expect(live()).toBe('Recording started.');
128+
expect(visible()).toBe('Recording. 1 cycle so far.');
129+
expect(button('Stop recording')).toBeTruthy();
130+
});
131+
132+
it('says the page did not confirm when the report after Stop does not come', async () => {
133+
await show(true, 2);
134+
const before = await clickAndWait('Stop recording', 3000);
135+
expect(before).not.toContain('stopped');
136+
expect(live()).toBe(
137+
'The page did not confirm that the recording stopped. The tab may be in the background, closed or reloading.',
138+
);
139+
expect(button('Stop recording')).toBeTruthy();
106140
});
107141

108142
it('announces a repeated message again', async () => {

‎app/src/pages/cd-recording.ts‎

Lines changed: 51 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,11 @@ export type {
3434
CdCycle,
3535
} from '@pangular-inspector/devtools/internal/config';
3636

37-
/** How long Stop waits for the page's last report before it announces the count it has. */
38-
const STOP_REPORT_WAIT_MS = 3000;
37+
/**
38+
* How long Record and Stop wait for the page's report that says the recording is on or off
39+
* before they say the page did not confirm. The same wait as `record-change-detection`.
40+
*/
41+
const CONFIRM_WAIT_MS = 3000;
3942
/** One page's recording, as the page reports it. */
4043
export type CdPage = CdReport;
4144

@@ -541,38 +544,60 @@ export class CdRecording {
541544
return cdCauseText(cause);
542545
}
543546

544-
/** Set after Stop: the total is announced once the page's last report says it stopped. */
545-
private readonly stopping = signal(false);
546-
private stopTimer: ReturnType<typeof setTimeout> | undefined;
547+
/**
548+
* Set after Record (`true`) or Stop (`false`) reached the server: the result is announced
549+
* once the page reports the recording on or off. Stop's report also brings the last cycles.
550+
*/
551+
private readonly confirming = signal<boolean | null>(null);
552+
private confirmTimer: ReturnType<typeof setTimeout> | undefined;
547553

548554
constructor() {
549555
effect(() => {
550-
if (!this.stopping() || this.livePage()?.recording === true) return;
551-
untracked(() => this.announceStopped());
556+
const on = this.confirming();
557+
if (on === null) return;
558+
const recording = this.livePage()?.recording === true;
559+
if (recording !== on) return;
560+
untracked(() => this.confirmed(on));
552561
});
553-
inject(DestroyRef).onDestroy(() => clearTimeout(this.stopTimer));
562+
inject(DestroyRef).onDestroy(() => clearTimeout(this.confirmTimer));
554563
}
555564

556-
private announceStopped() {
557-
clearTimeout(this.stopTimer);
558-
this.stopping.set(false);
565+
private confirmed(on: boolean) {
566+
clearTimeout(this.confirmTimer);
567+
this.confirming.set(null);
568+
this.message.set('');
559569
const count = this.livePage()?.cycles.length ?? 0;
560-
this.announce(`Recording stopped. ${count} ${count === 1 ? 'cycle' : 'cycles'} recorded.`);
570+
this.announce(
571+
on
572+
? 'Recording started.'
573+
: `Recording stopped. ${count} ${count === 1 ? 'cycle' : 'cycles'} recorded.`,
574+
);
575+
}
576+
577+
/** No report confirmed in time: the button keeps the state the page last reported. */
578+
private unconfirmed(on: boolean) {
579+
const failed = `The page did not confirm that the recording ${on ? 'started' : 'stopped'}. The tab may be in the background, closed or reloading.`;
580+
this.message.set(failed);
581+
this.announce(failed);
561582
}
562583

563584
async toggle() {
564-
if (this.recording()) {
565-
const sent = await this.send({ on: false }, '', () => '', 'request-change-detection-record', {
566-
quiet: true,
567-
});
568-
if (!sent) return;
569-
// The page sends its last cycles with the report that says it stopped.
570-
this.stopping.set(true);
571-
clearTimeout(this.stopTimer);
572-
this.stopTimer = setTimeout(() => this.announceStopped(), STOP_REPORT_WAIT_MS);
573-
} else {
574-
await this.send({ on: true }, 'Starting…', () => 'Recording started.');
575-
}
585+
const on = !this.recording();
586+
clearTimeout(this.confirmTimer);
587+
this.confirming.set(null);
588+
const sent = await this.send(
589+
{ on },
590+
on ? 'Starting…' : 'Stopping…',
591+
() => '',
592+
'request-change-detection-record',
593+
{ quiet: true, keepPending: true },
594+
);
595+
if (!sent) return;
596+
this.confirming.set(on);
597+
// A report that comes after the wait still confirms, and replaces the note.
598+
this.confirmTimer = setTimeout(() => {
599+
if (this.confirming() === on) this.unconfirmed(on);
600+
}, CONFIRM_WAIT_MS);
576601
}
577602

578603
showImport(file: CdImported) {
@@ -621,7 +646,7 @@ export class CdRecording {
621646
pending: string,
622647
done: () => string,
623648
rpc = 'request-change-detection-record',
624-
{ quiet = false } = {},
649+
{ quiet = false, keepPending = false } = {},
625650
): Promise<boolean> {
626651
this.message.set(pending);
627652
try {
@@ -630,7 +655,7 @@ export class CdRecording {
630655
pageId: this.pageId(),
631656
...request,
632657
});
633-
this.message.set('');
658+
if (!keepPending) this.message.set('');
634659
if (!quiet) this.announce(done());
635660
return true;
636661
} catch {

‎apps/docs/src/content/guides/inspect-fix-verify.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Call `list-pages`. If more than one tab reports, pass its id as `page` to every
5757
The audit reads what the inspectors already hold. Errors, hydration, router, form and HTTP findings are there as soon as the page reports. Change detection numbers need a recording:
5858

5959
```json
60-
{"tool": "pangular:change-detection", "arguments": {"record": "start", "page": "k3x9"}}
60+
{"tool": "pangular:record-change-detection", "arguments": {"record": "start", "page": "k3x9"}}
6161
```
6262

6363
Then use the app: open the screens and click what the change is about. Subscriptions after destroy need tracking, so call `track-subscriptions` with `action: "start"` too if leaks matter to the change.
@@ -104,7 +104,7 @@ Call `open-in-panel` with `tab: "audit"` to give the user a link to the same lis
104104
## Gotchas
105105

106106
<ngmd-callout type="warning" title="Read-only agents">
107-
With <code>agent.readOnly</code>, <code>audit</code> has no <code>axe</code> argument and <code>change-detection</code> can't record. Run axe and the recording from the panel, and the agent's audit reads them.
107+
With <code>agent.readOnly</code>, <code>audit</code> has no <code>axe</code> argument and <code>record-change-detection</code> is not registered. Run axe and the recording from the panel, and the agent's audit reads them.
108108
</ngmd-callout>
109109

110110
- Findings are matched by area, rule and subject, not by position. A renamed component or route counts as one finding resolved and one new.

‎apps/docs/src/content/inspectors/components.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,18 @@ Set [`actions.components`](../getting-started/configuration.md#actions) to `fals
143143

144144
When the page renders `@defer` blocks, a **Defer blocks** list follows the tree. Each row shows the component whose template holds the block, its state (`placeholder`, `loading`, `complete` or `error`) and its triggers. With [incremental hydration](https://angular.dev/guide/incremental-hydration), a row also shows `dehydrated` or `hydrated`, and a **hydrate never** flag marks a block that stays as server HTML.
145145

146-
Hover or focus a row to highlight the block in the page. Click it to select the component that holds it. The list is hidden when the page renders no defer blocks, or when its Angular version has no util to read them.
146+
A row also carries the notes the [`defer-blocks`](../agents/tools.md#defer-blocks) tool prints. Hover a note to read it in full.
147+
148+
| Badge | Meaning |
149+
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
150+
| **failed** | The block failed to load. |
151+
| **stuck** _N_ s | The block has been on its placeholder for 10 seconds or more. |
152+
| **waiting** _N_ s | The same, for a block whose triggers only wait for the user (`on viewport`, `on interaction` or `on hover`). |
153+
| **&#64;error block** | The block has an `@error` block. |
154+
155+
When the block sets times, the row lists them, such as `placeholder min 500ms · loading after 100ms, min 1s`. Ages are counted on the page's clock, so a page on another device with its clock set wrong still shows the right age.
156+
157+
Hover or focus a row to highlight the block in the page. A block with several root elements gets one box around all of them. Click it to select the component that holds it. The list is hidden when the page renders no defer blocks, or when its Angular version has no util to read them.
147158

148159
The list holds the first 500 blocks of a page. When the page has more, the count reads **500+**.
149160

@@ -178,7 +189,7 @@ The list needs Angular 22.0 or later in a development build. On an older Angular
178189

179190
### Change detection
180191

181-
Below the tree and the defer blocks, the **Change detection** section records change detection cycles with Angular's profiler. Click **Record**, use the app, then click **Stop recording**. A check is a component whose template Angular ran. A clean OnPush component that Angular only walked past is not a check, and neither is the second pass that development builds run to catch `ExpressionChangedAfterItHasBeenChecked` errors. The flash overlay and the Performance panel track count the same way. **Clear** empties the recording. Each new recording starts empty, but a start sent while the page records, such as an agent's `record: "start"`, keeps the cycles recorded so far.
192+
Below the tree and the defer blocks, the **Change detection** section records change detection cycles with Angular's profiler. Click **Record**, use the app, then click **Stop recording**. A check is a component whose template Angular ran. A clean OnPush component that Angular only walked past is not a check, and neither is the second pass that development builds run to catch `ExpressionChangedAfterItHasBeenChecked` errors. The flash overlay and the Performance panel track count the same way. **Clear** empties the recording. Each new recording starts empty, but a start sent while the page records, such as an agent's `record-change-detection` call with `record: "start"`, keeps the cycles recorded so far. **Record** and **Stop recording** wait up to 3 seconds for the page to report the recording on or off before they announce it. If no report comes, the status says the page did not confirm, and the button keeps the state the page last reported.
182193

183194
- **Cycles**: a bar chart with one bar per recorded cycle, its height the cycle's duration. A line marks the 16.6 ms frame budget (one frame at 60 frames per second). A cycle over the budget has a striped bar, a triangle under it, and says "over budget" in its tooltip and in the table. Hover or focus a bar to see the cycle number, duration, output trigger, checks and its three slowest components.
184195
- **Spans in the picked cycles**: when the page reports timed spans, a flame graph of the picked cycles. Time runs left to right, cycle after cycle with the idle time between them left out, and a span nested in another sits one row lower. Each span is a component check (solid), a lifecycle hook (stripes), an `afterRender` callback (dots) or the output listener that triggered the cycle (lines, drawn before the cycle's start), with a key under the graph. Hover or focus a span to read its total and self time. The arrow keys move along a row, **Up** goes to the enclosing span and **Down** to the first nested one. **Enter** or a click on a component, hook or output selects that component in the tree. **Show the spans as a table** lists the same spans. The graph shows at most 30 cycles; pick a smaller range when more are picked.

‎packages/devtools/CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,15 +185,19 @@ What remains: `/config` exports `DEFAULT_POPUP_HOTKEY`, `PANGULAR_ACTIONS`, `PAN
185185
- Fixes from the audit of every inspector, the panel shell, the hub, the extension and the native overlays (#361, #362, #363, #364), the follow-ups in #418, and the release blockers found by the test campaign (#432).
186186
- One malformed component report no longer breaks the agent tools for every page. Reports are checked when they reach the server.
187187
- Change detection counts only template runs, not skipped children or the `checkNoChanges` pass.
188+
- The change detection answers with no recording, the audit note and the `record-change-detection` result send agents to `record-change-detection`, not to `change-detection` with `record`, which that tool refuses.
189+
- The panel announces **Record** and **Stop recording** once the page reports the recording on or off. If no report comes within 3 seconds, it says the page did not confirm and keeps the button state the page last reported.
188190
- The forms tools answer with the forms of the tab they were asked about.
189191
- Signal graph edges name their nodes instead of positions.
192+
- `inspect-signals` reads the graph of a component the page is not showing: a `component` the component tree knows, or a component host matched by the new `selector` argument (CSS). A selector that matches no component host is refused at once (#367).
190193
- A `Store` provided in a route is found, and the DI tools keep each signal store's name instead of `SignalStore`.
191194
- The SSR hydration count is right, and a request is no longer reported as a transfer cache hit when it was not.
192195
- A failed write answers with `isError: true`, and a failing call keeps its response body.
193196
- The Express hub turns itself off with a warning on a Node.js that can't load it, instead of crashing the server.
194197
- `@pangular-inspector/devtools/devframe` (and the package root) load Devframe from `node_modules` when imported, as the hub entry does, so an Angular 20 server bundle that imports them no longer fails with `Identifier 'createRequire' has already been declared` (#427).
195198
- Picking works inside shadow roots and `ShadowDom` components.
196199
- Analog server calls link only to the request they ran under (#405).
200+
- The Analog page chain includes pages in named outlets and sibling child routes, not only the first child. The primary chain comes first, and each other page names its outlet in the **Routes** tab and in `analog-inspect-page` (#369).
197201
- Signal Forms checkboxes, radios and selects are written in user mode (#360).
198202
- Live counts in **Timeline**, **Errors** and **Audit** speak only after a filter change, so they no longer flood screen readers.
199203
- Control outlines and **Signals** graph edges meet 3:1 contrast in both themes, and status pills keep their contrast on selected rows.
@@ -202,7 +206,13 @@ What remains: `/config` exports `DEFAULT_POPUP_HOTKEY`, `PANGULAR_ACTIONS`, `PAN
202206
- `explain-invalid-forms` no longer says no field has an error when the failing field is past the forms collector's limit of 100 fields per group. A cut group carries `truncatedInvalid` with the invalid fields it left out, `explain-invalid-forms` and `explain-submit` name them, and `inspect-forms` says which group was cut and how many fields it left out, or that a group past the 8-level depth limit was not read (#423).
203207
- `scan-signals` and `scan-components` cap their answer at 200 items or 20,000 characters, say how many items they left out, and take `filter`, `offset` and `limit` to read the rest. A list that fits is still the JSON array alone. One item longer than the cap is cut, with a note (#429).
204208
- The panel switches tabs when only the `#tab=` hash changes after load (#425).
209+
- The `defer-blocks` tool and the **Defer blocks** list count how long a block sat on its placeholder on the page's clock. The component report carries the page clock (`pageNow`) and the server keeps the offset as `clockOffset`, so a page whose clock runs ahead or behind no longer reads as stuck, or never stuck (#366).
210+
- The **Defer blocks** list shows the notes the `defer-blocks` tool prints (**failed**, **stuck** _N_ s, **waiting** _N_ s, **dehydrated**), an **&#64;error block** flag and the `@placeholder` and `@loading` times (#366).
211+
- Highlighting a `@defer` block draws one box around all of its root elements instead of the first one. `request-page-highlight` takes `ids` for several elements next to `id` (#366).
212+
- The **SSR & HTTP** hydration mismatches name the component class, such as `ProductCard`, instead of the DOM node name (#366).
205213
- At narrow widths the **Components** toolbar fits on two rows, with its tree actions as icons, and a cut off component name shows its full text on hover and focus (#421).
214+
- The **Forms** tab lists WebMCP tools that are not linked to a form under **Other WebMCP tools**, with the same parts as a form's **WebMCP tool** block (#368).
215+
- The **Forms** tab shows the forms setup errors Angular logs on the page, such as `NG01203`, in a notice above the list (#368).
206216

207217
### Docs
208218

0 commit comments

Comments
 (0)