From 74eb85304cbf3ed91e75e0bb3926d11a387530cc Mon Sep 17 00:00:00 2001 From: erKam Date: Sat, 7 Nov 2026 17:34:26 +0000 Subject: [PATCH 1/2] fix(components): say why a page could not start a cd recording A page that answers record-change-detection start with supported: false was not counted as an answer, so the tool waited out its 3 seconds and then guessed "an Angular version without the profiler (Angular 20+)", even for a page whose capability report says it has the profiler hook. The start now treats an unsupported report as the page's answer and passes on cdUnsupportedText from that page's capability report: the version it runs, or a hook the recording could not attach to yet. A silent page no longer gets the version guess. Refs #366 --- apps/docs/src/content/agents/tools.md | 2 +- packages/devtools/CHANGELOG.md | 1 + .../__tests__/cd-record-unsupported.test.ts | 78 +++++++++++++++++++ packages/devtools/src/devframe.ts | 1 + packages/devtools/src/rpc/cd-record-tool.ts | 32 ++++++-- 5 files changed, 106 insertions(+), 8 deletions(-) create mode 100644 packages/devtools/src/__tests__/cd-record-unsupported.test.ts diff --git a/apps/docs/src/content/agents/tools.md b/apps/docs/src/content/agents/tools.md index c4d2fb14..7163ba63 100644 --- a/apps/docs/src/content/agents/tools.md +++ b/apps/docs/src/content/agents/tools.md @@ -339,7 +339,7 @@ Starts, stops or clears a change detection recording, and turns the live views o | `track` | no | `true` writes each component check, lifecycle hook and output listener to a **Pangular** track in the Chrome Performance panel. `false` turns it off. | | `angularProfiling` | no | `true` calls `ng.enableProfiling()` for Angular's own Performance panel track. It stays on until the page reloads, so `false` is refused. | -Pass `record`, a view or both. Without `page`, `record` goes to every connected page (`stop` only to the pages that record). `record` waits up to 3 seconds for each page to confirm and names the pages that did; when none does, or no page is connected, it refuses with `isError`. Call it with `record: "start"`, use the app, then call `change-detection`. +Pass `record`, a view or both. Without `page`, `record` goes to every connected page (`stop` only to the pages that record). `record` waits up to 3 seconds for each page to confirm and names the pages that did; when none does, or no page is connected, it refuses with `isError`. A page that answers a start with no recording says why: its Angular version lacks the profiler, with the version it runs, or it has the profiler but the recording could not attach yet. Call it with `record: "start"`, use the app, then call `change-detection`. `flash`, `track` and `angularProfiling` go to the page in `page`, or to every connected page. An [Angular Native](../getting-started/angular-native.md) or [NativeScript](../getting-started/nativescript.md) app has no live views. The tool says there is no DOM when `page` names such an app, or when `page` is left out and every page that reports is one. `record` works on these apps as on a browser page. They are the **Live views** toggles of the panel; see [Watch checks live](../inspectors/components.md#watch-checks-live). With `agent.readOnly` the tool is not registered, so start the recording from the panel. diff --git a/packages/devtools/CHANGELOG.md b/packages/devtools/CHANGELOG.md index 034683a0..0cb8552b 100644 --- a/packages/devtools/CHANGELOG.md +++ b/packages/devtools/CHANGELOG.md @@ -229,6 +229,7 @@ What remains: `/config` exports `DEFAULT_POPUP_HOTKEY`, `PANGULAR_ACTIONS`, `PAN - The **Pipes** tab no longer marks two `| async` usages of a Promise, a Subject, an `asObservable()` view of one or an NgRx store select as duplicates, since their subscribers share one execution (#369). Any other source that two `| async` usages subscribe to shows as **possible duplicate subscription**, and `explain-pipe` says **Possible duplicate subscriptions**, because the page can't see `share()` or `shareReplay()` in a pipe. - Browser DevTools show the app's own line as the caller of a `console` call again. The browser entries ship source maps that list the console tap in `x_google_ignoreList`, so its wrapper frame is skipped (#369). - The Angular Native overlay gates the injector profiler like the NativeScript overlay: in a development build with no `window`, importing it defines one until Angular publishes its debug utilities, so the **Providers** lists fill (#371). +- `record-change-detection` with `record: "start"` passes on why a page that answered could not record, from its capability report: the Angular version it runs, or a profiler hook the recording could not attach to yet. It no longer waits out the 3 seconds and blames the Angular version (#366). ### Docs diff --git a/packages/devtools/src/__tests__/cd-record-unsupported.test.ts b/packages/devtools/src/__tests__/cd-record-unsupported.test.ts new file mode 100644 index 00000000..8fc2bfd2 --- /dev/null +++ b/packages/devtools/src/__tests__/cd-record-unsupported.test.ts @@ -0,0 +1,78 @@ +import { describe, expect, it } from 'vitest'; +import type { AngularPageInfo } from '../config.ts'; +import { cdRecordAnswer } from '../rpc/cd-record-tool.ts'; +import type { CdPage } from '../rpc/cd-tools.ts'; +import { createPushAcks } from '../rpc/push-acks.ts'; + +const report = (pageId: string, fields: Partial) => + ({ pageId, recording: false, supported: true, cycles: [], ...fields }) as unknown as CdPage; + +/** + * Starts a recording on `pages`. Each page answers the start with the report + * `answers` gives it, the way the overlay pushes right after + * `change-detection-record`. + */ +async function start( + pages: string[], + answers: Record>, + angular: Record = {}, +) { + const acks = createPushAcks(); + return cdRecordAnswer({ + record: 'start', + connected: pages, + recording: [], + acks, + ms: 1000, + angularOf: (id) => angular[id], + send: () => { + for (const [id, fields] of Object.entries(answers)) acks.notify(id, report(id, fields)); + }, + }); +} + +describe('record-change-detection start on a page that cannot record', () => { + it('passes on why a page with the profiler hook could not attach, without a version guess', async () => { + const answer = await start( + ['p1'], + { p1: { supported: false } }, + { p1: { version: '21.0.1', capabilities: { profiler: true } } }, + ); + expect(answer).toHaveProperty('refused', true); + expect(answer.markdown).toContain('could not attach to it yet'); + expect(answer.markdown).not.toContain('did not confirm'); + expect(answer.markdown).not.toContain('Angular 20'); + }); + + it('names the Angular version a page without the profiler hook runs', async () => { + const answer = await start( + ['p1'], + { p1: { supported: false } }, + { p1: { version: '18.2.0', capabilities: { profiler: false } } }, + ); + expect(answer).toHaveProperty('refused', true); + expect(answer.markdown).toContain('Unsupported on this Angular version'); + expect(answer.markdown).toContain('18.2'); + expect(answer.markdown).not.toContain('did not confirm'); + }); + + it('reports the pages that started apart from the ones that answered unsupported', async () => { + const answer = await start( + ['p1', 'p2', 'p3'], + { p1: { recording: true }, p2: { supported: false } }, + { p2: { capabilities: { profiler: true } } }, + ); + expect(answer).not.toHaveProperty('refused'); + expect(answer.markdown).toContain('Recording started on page `p1`.'); + expect(answer.markdown).toContain('Page `p3` did not confirm'); + expect(answer.markdown).toContain('Page `p2` has Angular'); + expect(answer.markdown).not.toContain('`p2` did not confirm'); + }); + + it('no longer blames the Angular version when a page stays silent', async () => { + const answer = await start(['p1'], {}); + expect(answer).toHaveProperty('refused', true); + expect(answer.markdown).toContain('`p1` did not confirm within 1s'); + expect(answer.markdown).not.toContain('Angular 20'); + }); +}); diff --git a/packages/devtools/src/devframe.ts b/packages/devtools/src/devframe.ts index b42bb213..973e9077 100644 --- a/packages/devtools/src/devframe.ts +++ b/packages/devtools/src/devframe.ts @@ -3427,6 +3427,7 @@ const pangular = defineDevframe({ clear: record === 'clear', }), acks: cdAcks, + angularOf: angularPages.get, }); if ('refused' in answer) return answer; const next = answer.markdown; diff --git a/packages/devtools/src/rpc/cd-record-tool.ts b/packages/devtools/src/rpc/cd-record-tool.ts index ce3d9857..b1c6c018 100644 --- a/packages/devtools/src/rpc/cd-record-tool.ts +++ b/packages/devtools/src/rpc/cd-record-tool.ts @@ -1,4 +1,5 @@ -import type { CdPage } from './cd-tools.ts'; +import type { AngularPageInfo } from '../config.ts'; +import { cdUnsupportedText, type CdPage } from './cd-tools.ts'; import { code } from './forms-tools.ts'; import type { PushAcks } from './push-acks.ts'; import { PUSH_ACK_MS } from './push-acks.ts'; @@ -18,6 +19,8 @@ export interface CdRecordInput { send: () => void; acks: PushAcks; ms?: number; + /** The page's capability report, so a page that answered unsupported is told why. */ + angularOf?: (pageId: string) => AngularPageInfo | undefined; } const VERB: Record = { @@ -51,26 +54,41 @@ export async function cdRecordAnswer(input: CdRecordInput) { : `No page reports change detection, so no recording was ${VERB[record]}. Open the app in a browser with the overlay loaded, through the server that runs it.`, ); } - const accept = (report: CdPage) => - record === 'start' + // A start the page answered with `supported: false` is an answer too: the + // page says why, instead of the tool waiting out the timeout and guessing a version. + const unsupported = new Set(); + const accept = (report: CdPage) => { + if (record === 'start' && report.supported === false) { + unsupported.add(report.pageId); + return true; + } + if (record === 'start') unsupported.delete(report.pageId); + return record === 'start' ? report.recording === true : record === 'stop' ? report.recording === false : report.cycles.length === 0; + }; const confirmed = input.acks.wait(targets, accept, input.ms); input.send(); - const done = await confirmed; + const answered = await confirmed; + const done = answered.filter((id) => !unsupported.has(id)); + const refusedBy = answered.filter((id) => unsupported.has(id)); + const why = refusedBy.map((id) => cdUnsupportedText(id, input.angularOf?.(id))).join('\n\n'); const seconds = Math.round((input.ms ?? PUSH_ACK_MS) / 1000); + const silent = targets.filter((id) => !answered.includes(id)); if (!done.length) { + const quiet = silent.length + ? `${silent.length === 1 ? 'page' : 'pages'} ${pageList(silent)} did not confirm within ${seconds}s. The tab may be in the background, closed or reloading.` + : ''; return refusedAnswer( - `Recording was not ${VERB[record]}: ${targets.length === 1 ? 'page' : 'pages'} ${pageList(targets)} did not confirm within ${seconds}s. The tab may be in the background, closed, or on an Angular version without the profiler (Angular 20+, dev build).`, + `Recording was not ${VERB[record]}${quiet ? `: ${quiet}` : '.'}${why ? `\n\n${why}` : ''}`, ); } - const silent = targets.filter((id) => !done.includes(id)); const missing = silent.length ? ` ${silent.length === 1 ? 'Page' : 'Pages'} ${pageList(silent)} did not confirm within ${seconds}s.` : ''; return { - markdown: `Recording ${VERB[record]} on ${done.length === 1 ? 'page' : 'pages'} ${pageList(done)}.${missing}${NEXT[record]}`, + markdown: `Recording ${VERB[record]} on ${done.length === 1 ? 'page' : 'pages'} ${pageList(done)}.${missing}${NEXT[record]}${why ? `\n\n${why}` : ''}`, }; } From 03bb770cfec6d794dbcfcfdeddc98996ad070610 Mon Sep 17 00:00:00 2001 From: erKam Date: Sat, 7 Nov 2026 17:34:45 +0000 Subject: [PATCH 2/2] fix(http): name a hydration mismatch as a node unless its class is known explain-ssr-request printed every mismatch as "Mismatch in `x`", so a node name such as `app-card` or `#text` read like a component class. The scan already sets isClass when ng.getComponent names the host. The agent text now says "Mismatch in component `ProductCard`" only for a class, and "Mismatch at element ``" or "at a `#text` node" otherwise, as the panel and hub messages already do. Refs #366 --- apps/docs/src/content/agents/tools.md | 2 +- packages/devtools/CHANGELOG.md | 1 + .../src/__tests__/ssr-requests.test.ts | 25 +++++++++++++++++++ packages/devtools/src/rpc/ssr-tools.ts | 17 ++++++++++--- 4 files changed, 41 insertions(+), 4 deletions(-) diff --git a/apps/docs/src/content/agents/tools.md b/apps/docs/src/content/agents/tools.md index 7163ba63..02995d3d 100644 --- a/apps/docs/src/content/agents/tools.md +++ b/apps/docs/src/content/agents/tools.md @@ -855,7 +855,7 @@ These tools read the HttpClient calls that `withPangular()` recorded and the SSR | `explain-ssr-request` | One request end to end: timings, kept response headers, the router's guard and resolver times, each server call with its transfer cache outcome, then the browser page with its hydration result and the calls the browser made again. | `id`, `url` | | `list-http-calls` | The HttpClient calls of one tab and the server render that served it, newest first: side (SSR or client), method, URL, status, duration, and flags for mocked, faulted, cancelled, redirected, transfer cache hit and the matched rule. With `preview`, the masked response body, for failed calls too. With `view: "waterfall"`, the tab's client calls as a waterfall instead. | `url`, `failed`, `limit`, `preview`, `headers`, `view` | -`explain-ssr-request` picks the request by `id`, else the newest one for `url`, else the newest one. +`explain-ssr-request` picks the request by `id`, else the newest one for `url`, else the newest one. It names each hydration mismatch by the component class the node hosts when the page could read one, else by the element (``) or text node (`#text`). `list-http-calls` lists one tab and the server calls of the SSR request that served it: the tab `page` names, or the default page. With no tab connected, it lists the server calls. `url` keeps calls whose URL contains the text. `failed` keeps calls with a status of 400 or more, no response, an error, or a cancel. `limit` defaults to 30 (at most 200). `preview` adds each call's response preview, including the body a failed call got back, such as a validation message or `problem+json`. `headers` adds each call's request and response headers. Secrets in URLs, errors, previews and headers are masked, and `url` matches the masked URL. diff --git a/packages/devtools/CHANGELOG.md b/packages/devtools/CHANGELOG.md index 0cb8552b..9c5fb7bb 100644 --- a/packages/devtools/CHANGELOG.md +++ b/packages/devtools/CHANGELOG.md @@ -230,6 +230,7 @@ What remains: `/config` exports `DEFAULT_POPUP_HOTKEY`, `PANGULAR_ACTIONS`, `PAN - Browser DevTools show the app's own line as the caller of a `console` call again. The browser entries ship source maps that list the console tap in `x_google_ignoreList`, so its wrapper frame is skipped (#369). - The Angular Native overlay gates the injector profiler like the NativeScript overlay: in a development build with no `window`, importing it defines one until Angular publishes its debug utilities, so the **Providers** lists fill (#371). - `record-change-detection` with `record: "start"` passes on why a page that answered could not record, from its capability report: the Angular version it runs, or a profiler hook the recording could not attach to yet. It no longer waits out the 3 seconds and blames the Angular version (#366). +- `explain-ssr-request` names a hydration mismatch as a component only when the page read its class, and as an element (``) or text node (`#text`) otherwise (#366). ### Docs diff --git a/packages/devtools/src/__tests__/ssr-requests.test.ts b/packages/devtools/src/__tests__/ssr-requests.test.ts index c054b378..dbe6520b 100644 --- a/packages/devtools/src/__tests__/ssr-requests.test.ts +++ b/packages/devtools/src/__tests__/ssr-requests.test.ts @@ -361,6 +361,31 @@ describe('ssrRequestStory', () => { expect(text).toContain('POST `/api/quote`'); }); + it('names a mismatch by its component class only when the page read one', () => { + const pages = [ + page({ + hydration: { + enabled: true, + nodes: { hydrated: 4, skipped: 0, mismatched: 3 }, + mismatches: [ + { component: 'ProductCard', isClass: true }, + { component: 'app-card' }, + { component: '#text' }, + ], + skipHydrationHosts: [], + warnings: [], + warningsCaptured: true, + }, + }), + ]; + const text = explainSsrRequestText([ssrRequest()], [], pages, {}); + expect(text).toContain('Mismatch in component `ProductCard`'); + expect(text).toContain('Mismatch at element ``'); + expect(text).toContain('Mismatch at a `#text` node'); + expect(text).not.toContain('Mismatch in `app-card`'); + expect(text).not.toContain('Mismatch in `#text`'); + }); + it('explains an unknown id and an empty list', () => { expect(explainSsrRequestText([], [], [], {})).toContain('devtools.ssrMiddleware'); expect(explainSsrRequestText([ssrRequest()], [], [], { id: 'nope' })).toContain( diff --git a/packages/devtools/src/rpc/ssr-tools.ts b/packages/devtools/src/rpc/ssr-tools.ts index 9a67c3a4..3fc90be6 100644 --- a/packages/devtools/src/rpc/ssr-tools.ts +++ b/packages/devtools/src/rpc/ssr-tools.ts @@ -193,6 +193,19 @@ export function ssrRequestStory( return { request, serverCalls: own, page, refetched }; } +/** + * One hydration mismatch for the agent text. The page names it by the + * component class its node hosts when it could read one (`isClass`); otherwise + * `component` is the node name (`app-card`, `#text`), so it is shown as a node, + * not as a component. + */ +export function mismatchLine(m: { component: string; isClass?: boolean }): string { + if (m.isClass) return `Mismatch in component ${code(m.component)}`; + return m.component.startsWith('#') + ? `Mismatch at a ${code(m.component)} node` + : `Mismatch at element ${code(`<${m.component}>`)}`; +} + function ms(value: number): string { return `${value} ms`; } @@ -348,9 +361,7 @@ export function explainSsrRequestText( : `${h.nodes?.skipped ?? 0} nodes skipped` }.`, ); - for (const m of h.mismatches.slice(0, 10)) { - lines.push(` - Mismatch in ${code(m.component)}`); - } + for (const m of h.mismatches.slice(0, 10)) lines.push(` - ${mismatchLine(m)}`); for (const w of h.warnings.slice(0, 5)) lines.push(` - ${code(w)}`); } if (h?.stableMs !== undefined) {