Diagnostic Overlay

diagnostic-overlayViewers

How a developer actually reaches the panel: right-click the face for Open diagnostics / Copy runtime report / Reset counters, or press Ctrl/Cmd+Shift+D. It owns everything `DiagnosticPanel` deliberately does not — whether the panel may be shown at all, the centered viewport modal, the per-viewer tab preference in guarded `localStorage`, Escape or an outside click to close, focus moving into the rail on open and back to the face on close, and the session's `open()`/`close()` lifecycle, which is what keeps a closed panel free on the audio thread. The modal portals into `document.body` and uses fixed positioning, so transforms, clipping, and stacking contexts inside a face cannot paint over it. Right-clicks keep their own menu on three kinds of target: text-editing islands, anything a module marked `[data-context-menu="browser"]`, and anything inside a module's own nested context menu — a diagnostics panel has no business shadowing cut/copy/paste. Visibility follows one rule, exported as `shouldShowDiagnostics` so hosts and tests assert on the same function: the policy must not be `"never"`, and then either the policy is `"always"`, or the host's build mode is development, or the connection is the dev runner, or there is no host at all (a standalone dev preview). A production plugin in a DAW gets nothing.

A module face

Right-click anywhere here, or press Ctrl/Cmd+Shift+D, to open the diagnostics modal, and Escape to close it. It stays centered in the viewport, moves focus into the rail on open, and returns it to the face on close. Click outside the panel to dismiss it.

Mounted with policy="always" so the docs page can show it; under the default "development" policy it appears only for a development build, the dev runner, or a face with no host at all.

Install

Copies the source into your project. Anything it depends on comes with it.

$ npx shadcn add @syntho-ui/diagnostic-overlay

Pulls in

diagnostic-paneluse-diagnostic-sessioncontrol-theme

First time? Add the registry to your components.json once:

components.json

{
  "registries": {
    "@syntho-ui": "https://engine.syntho.app/r/{name}.json"
  }
}

Usage

Controlled or uncontrolled, whichever suits the surrounding state.

example.tsx

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)

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 for the show rule — `identity.build.mode` and `connection` decide whether the overlay exists at all.
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	"codex.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 a blocked store is never worth failing a diagnostic panel over.
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.

All controls Start building