Add real-time diagnostics HUD for serve mode #2563

Mpdreamz · 2026-01-26T19:08:28Z

Summary

Adds a diagnostics heads-up display (HUD) to docs-builder serve that shows build errors, warnings, and hints in real-time
Streams diagnostics via Server-Sent Events (SSE) as the in-memory build runs in parallel with live reload
Provides an interactive pill button in the isolated header showing current status (building, error/warning/hint counts, or "All good!")
HUD panel at bottom of screen with filterable, scrollable list of diagnostics including file location and copy functionality

Features

Real-time streaming: Diagnostics appear as they're detected during build
Status pill: Color-coded segments showing error (red), warning (amber), and hint (blue) counts with animated gradients
Filter toggles: Show/hide errors, warnings, or hints independently
Copy support: One-click copy of diagnostic details (severity, file:line:column, message)
State persistence: HUD open/closed state persists across page reloads via sessionStorage
Smooth transitions: Header offset changes animate smoothly without layout shift on reload

cursorful-video-1769454422244.mp4

… initialization flow

Features: - Add segmented diagnostics pill in header showing [icon] [count] [name] per severity - Each segment has animated gradient background matching severity color - Segments with count 0 are automatically hidden - Add diagnostics HUD panel with filter toggle buttons for errors/warnings/hints - Add "All" button when any filter is inactive - Sort diagnostics by severity: errors > warnings > hints - Add copy button for each diagnostic row - Stream diagnostics via SSE with broadcast pattern for multiple clients - Run in-memory validation build in parallel with live reload - Optimize builds by reusing MockFileSystem and only regenerating OpenAPI when specs change - Add --skip-api flag to docs-builder command for faster builds

The logger was being created at module load time, which failed when other modules imported logging functions before the LoggerProvider was initialized. Changed to lazy initialization using a getter function. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

When the user has the diagnostics HUD open and the page reloads (via live reload or manual), the HUD now stays open instead of collapsing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Split initIsolatedHeader into two functions: - setInitialHeaderOffset(): Sets CSS variable immediately on script load - initIsolatedHeader(): Full init with scroll listener on DOMContentLoaded This prevents the visual jump where the header height changes after the page has already rendered. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Updated all experimental OpenTelemetry packages to 0.209.0 to ensure consistent versions across the dependency tree. The version mismatch between api-logs@0.208.0 and sdk-logs@0.209.0 was causing module initialization errors. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Added .no-transitions class that disables all transitions during initial page load to prevent visible animation when setting the header offset based on scroll position. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Moved the removal of no-transitions class from setInitialHeaderOffset to initIsolatedHeader, ensuring transitions stay disabled until after updateLayout sets the header element styles. This prevents the logo from animating on page load when scrolled down. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Adds cursor: pointer to all clickable elements in the diagnostics UI: - Diagnostic pill buttons in header (all states) - Filter buttons in HUD - Copy button on diagnostic rows - All/Close buttons in HUD header Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/Elastic.Documentation.Site/Assets/web-components/Diagnostics/DiagnosticsHud.tsx

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

src/tooling/docs-builder/Http/InMemoryBuildState.cs

+			foreach (var channel in _clientChannels)
+			{
+				if (!channel.Writer.TryWrite(buildEvent))
+				{
+					// Channel is full or closed, mark for removal
+					deadChannels.Add(channel);
+				}
+			}


src/tooling/docs-builder/Http/InMemoryBuildState.cs

+		catch (Exception ex)
+		{
+			_logger.LogError(ex, "Error during in-memory build: {Message}", ex.Message);
+			Status = BuildStatus.Complete;
+
+			// Emit build_complete with current counts even on error
+			await BroadcastEventAsync(new BuildEvent(
+				"build_complete",
+				DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+				Errors: ErrorCount,
+				Warnings: WarningCount,
+				Hints: HintCount
+			));
+		}


reakaleek

❤️ 🚀

LGTM

Not a blocker: But IMO it would be nice if we stick with EUI. But I can take a look at it when working on dev docs.

Mpdreamz · 2026-01-26T19:37:24Z

Not a blocker: But IMO it would be nice if we stick with EUI. But I can take a look at it when working on dev docs.

Agreed!

There are a few more things I want to do with diagnostics.

Ensure each diagnostics has a code, document all error/warnings/hints inluding a fix/remedy. And link to those from the HUD (and CLI output).

reakaleek · 2026-01-26T19:37:37Z

src/Elastic.Documentation.Site/Assets/web-components/Diagnostics/diagnostics.store.ts

+
+// SessionStorage key for persisting HUD open state
+const HUD_OPEN_KEY = 'diagnostics-hud-open'
+


In the ask ai store we are using zustand with the sessionStorage provider

Ahh here I am also using zustand for the diagnostics itself. Should this go into indexeddb?

it looks to me that the diagnotics stuff is fine for just in-memory zustand.

And small UI state also sounds good for the sessionStorage..

I used IndexedDB for the chat because it could potentially become huge, and there is virtually no storage limit. (the downside is that it is slower)

But for UI state, like flyout open/closed.. we are also using sessionStorage.

Mpdreamz and others added 11 commits January 26, 2026 18:48

Update header for isolated builds

7493945

format css js

83dd291

Refactor: Move isolated header logic to a dedicated module and update…

6657c70

… initialization flow

Persist HUD open state across page reloads using sessionStorage

8203d0d

When the user has the diagnostics HUD open and the page reloads (via live reload or manual), the HUD now stays open instead of collapsing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Disable CSS transitions during initial header offset setup

1466f28

Added .no-transitions class that disables all transitions during initial page load to prevent visible animation when setting the header offset based on scroll position. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Mpdreamz requested a review from a team as a code owner January 26, 2026 19:08

Mpdreamz added the feature label Jan 26, 2026

Mpdreamz self-assigned this Jan 26, 2026

Mpdreamz requested a review from cotti January 26, 2026 19:08

github-code-quality bot found potential problems Jan 26, 2026

View reviewed changes

src/Elastic.Documentation.Site/Assets/web-components/Diagnostics/DiagnosticsHud.tsx Fixed Show fixed Hide fixed

Mpdreamz and others added 2 commits January 26, 2026 20:10

Potential fix for pull request finding 'Unused variable, import, func…

2f1fb89

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

format css js

7056f6e

github-code-quality bot found potential problems Jan 26, 2026

View reviewed changes

fix linters

7153a79

reakaleek approved these changes Jan 26, 2026

View reviewed changes

Mpdreamz changed the title ~~feature/diagnostics heads up display~~ Add real-time diagnostics HUD for serve mode Jan 26, 2026

Mpdreamz enabled auto-merge (squash) January 26, 2026 19:37

reakaleek reviewed Jan 26, 2026

View reviewed changes

Mpdreamz merged commit 02b21f0 into main Jan 26, 2026
31 checks passed

Mpdreamz deleted the feature/diagnostics-heads-up-display branch January 26, 2026 19:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add real-time diagnostics HUD for serve mode #2563

Add real-time diagnostics HUD for serve mode #2563

Mpdreamz commented Jan 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

reakaleek left a comment

Uh oh!

Mpdreamz commented Jan 26, 2026

Uh oh!

reakaleek Jan 26, 2026

Uh oh!

Mpdreamz Jan 26, 2026

Uh oh!

reakaleek Jan 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		// SessionStorage key for persisting HUD open state
		const HUD_OPEN_KEY = 'diagnostics-hud-open'

Add real-time diagnostics HUD for serve mode #2563

Add real-time diagnostics HUD for serve mode #2563

Conversation

Mpdreamz commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Uh oh!

Uh oh!

reakaleek left a comment

Choose a reason for hiding this comment

Uh oh!

Mpdreamz commented Jan 26, 2026

Uh oh!

reakaleek Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Mpdreamz Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

reakaleek Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Mpdreamz commented Jan 26, 2026 •

edited

Loading

reakaleek Jan 26, 2026 •

edited

Loading