Diagnostic Overlay
diagnostic-overlayViewersRight-click a module face to open its diagnostics, and only where that is allowed.
$ pnpm dlx shadcn@latest add @pluginui/core-diagnostic-overlayInstall
Copies the source into your project. Anything it depends on comes with it. Run this in your React project with shadcn initialized; no registry configuration is needed.
Pulls in
Install using the registry URL
$ pnpm dlx shadcn@latest add https://pluginui.com/r/core-diagnostic-overlay.jsonUsage
Connect the documented props to your application or host.
import { DiagnosticOverlay } from "@/components/ui/diagnostic-overlay"
// Wrap the face. HostedModuleFace already does this for every packaged face.
<DiagnosticOverlay session={session} snapshot={snapshot}>
<ModuleFace {...faceProps} />
</DiagnosticOverlay>
// Force it on for a docs page or a support build.
<DiagnosticOverlay session={session} snapshot={snapshot} policy="always">
<ModuleFace {...faceProps} />
</DiagnosticOverlay>
// Ask the rule directly, without mounting anything.
shouldShowDiagnostics("development", snapshot)About Diagnostic Overlay
Right-click the face for Open diagnostics, Copy runtime report or Reset counters, or press Ctrl/Cmd+Shift+D to open the panel. This overlay owns everything `DiagnosticPanel` deliberately leaves to its host: whether the panel may appear, the centered viewport modal, the per-viewer tab preference in guarded `localStorage`, closing on Escape or outside click, focus entering the rail on open and returning to the face on close, and the session's `open()` / `close()` lifecycle that keeps a closed panel free on the audio thread. It portals into `document.body` and uses fixed positioning, so transforms, clipping and stacking contexts inside a face cannot cover it. Right-clicks retain their own menu on text-editing islands, targets marked `[data-context-menu="browser"]`, and anything inside a module's nested context menu. A diagnostics panel should not shadow cut, copy or paste. Visibility follows the exported `shouldShowDiagnostics` rule, shared by hosts and tests: the policy must not be “never”, and either it is “always”, the host build is development, the connection is the dev runner, or no host exists (a standalone dev preview). Production plugins in a DAW get nothing.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| session | DiagnosticSession | — | Opened when the drawer becomes visible and closed when it hides or unmounts, so feeds stream only while someone is looking. |
| snapshot | DiagnosticSnapshot | — | Passed through to the panel and read by the show rule. `identity.build.mode` and `connection` determine whether the overlay exists. |
| policy | "development" | "always" | "never" | "development" | Bundle-level policy, mirroring `plugin.config.json` `ui.diagnostics`. `"never"` mounts nothing and renders the children bare; the generated bundle template passes the overlay component explicitly so a `"never"` build carries no overlay chunk at all. |
| storageKey | string | "maru.diagnostics" | Prefix for the remembered tab, dock side and drawer size, so two faces on one page keep separate preferences. Every read and write is wrapped. A private window or blocked store should never make a diagnostics panel fail. |
| children | ReactNode | — | The face the overlay wraps and whose right-click it handles. |
Interaction
- Right-click Opens the diagnostics menu, except on editable, browser-menu or nested-menu targets.
- Ctrl/Cmd+Shift+D Toggles the drawer.
- Escape Closes the drawer.
- Drag the inner edge Resizes the drawer, floored at 360px.