Debugging and troubleshooting

First record the host commit, plugin commit, .uproject, engine version and launch flags. 0.57.0-dev alone cannot distinguish the known-broken baseline inspector from the repair candidate. See version notes.

Baseline: rendering works, native inspector does not

At published host 91fd772c282098157c4e7cded0263844f076e9fb / plugin 933db5171161ac5966e3b9bca3fd3a965f5399cc, Tools > Quartz UI > Open DevTools opens a target-specific inspector, but CEF rejects the browser WebSocket Origin http://127.0.0.1:9222. Elements and Console remain empty/disconnected. Earlier independent baseline testing reproduced this failure. A separate direct protocol read proved the live page existed; it did not make the native menu pass.

Treat this as the known baseline defect. Do not add wildcard Origin flags, strip Origin headers or expose the debugging port. The baseline quickstart's success is visible rendering plus bridge/app readiness, not inspection.

Candidate: one-click live inspection, with remaining review limits

Plugin e7ab5dcc0069ade3393cc0e033e4541a78eaae3b is a repair candidate that invokes Chrome's native remote Inspect action for the exact live target. It adds a Node launcher and version-sensitive Chrome adapter. Node 22+ and a compatible Chrome are required; independent evidence used Node 22.23.2 and Chrome 153.0.8010.53 with UE's bundled CEF 128.0.6613.138. Edge discovery exists in source but Edge and other Chrome versions have not been validated.

When an authorized candidate checkout is ready:

Start PIE and wait for the live reference UI.
Release mouse capture when needed, then use Tools > Quartz UI > Open DevTools. One page opens directly. Multiple pages use an Editor title/URL picker.
Confirm Elements is populated and Console can evaluate document.URL, expecting https://reference.quartzui.test/index.html for the host fixture.
Arm the element selector and click SERVERS or SHOP in the Unreal viewport. The corresponding DOM node should be selected without navigating the app. After inspection ends, ordinary clicks should navigate again.
Verify preview selection separately, then close/reopen the inspector and stop/restart PIE to check cleanup and target replacement.

Independent candidate QA passed the two viewport reproductions, ordinary-click restoration, preview selection and lifecycle. The physical captured-mouse Shift+F1 hardware-input step remains unverified; synthetic key delivery reached an Editor shortcut and is not proof that human input is broken. Multi-page picker evidence is from prior candidate acfea46445f8400e19181d580df9c9844ec6cd84, not a repeated e7ab5dcc test. This evidence does not establish a released fix or an updated reference-host pin.

The preview contains the Chromium UI document, not the Unreal world or desktop. Candidate QA observed lossless PNG at 939 x 376 after panel resizing and 210 delivered frames in five seconds with the inspector focused. This is a measured fixture result, not a resolution or frame-rate guarantee. The candidate temporarily exempts the Editor from background CPU throttling while its live inspector is active and restores normal behavior on close/PIE teardown; it does not change the global preference.

Settings and logs

Project policy lives under Project Settings > Plugins > QuartzUI; machine tooling lives under Editor Preferences > Plugins > QuartzUI. The project must permit Editor DevTools. Restart the Editor after a debug port/startup-option change because CEF is already initialized. Candidate settings include Node Executable and optional Inspector Browser Executable. Missing tools produce a bounded failure; nothing is installed automatically.

The candidate uses an isolated profile under Saved/QuartzUI/DevTools/<editor-pid>/BrowserProfile. Close its windows normally. Launcher output uses LogQuartzUIEditor; inspect the host's Editor log and cef3.log as well. The browser may remain open after Editor exit; do not terminate unrelated Chrome sessions. The Editor module and its automatic debug setup do not run in packaged game executables.

Diagnose the first failing boundary

Symptom	Check and next step
Private clone or submodule authentication fails	Confirm authorized access to host and plugin separately through local login. Use the repository URLs supplied with preview access.
App asset is a text file beginning with an LFS pointer	Hydrate Git LFS in an agreed baseline checkout; verify the hash in installation.
Plugin missing or Editor module mismatch	Inspect actual submodule SHA and `QuartzUI.uplugin`; build the correct host Editor target with the exact engine. Preserve caches.
Build cannot locate a compiler/SDK	Check VS C++ tools and Windows SDK; the tested versions are environment evidence, not a substitute for provisioning.
`npm.ps1` is blocked by PowerShell execution policy	For an existing Node installation use `npm.cmd` for npm commands. Do not change machine policy to inspect its version.
No reference UI after Play	Check Default App, Automatic startup, hydrated app asset, Entry map, output files and initial shader progress. Look for stable QuartzUI failure codes before recreating assets.
Page draws but readiness fails	Compare the selected app's generated contract and `quartzui.build.manifest`; rebuild its bundle. A loaded HTML page is not a successful handshake.
`client.unavailable` in a desktop browser	The standalone browser has no native `window.ue.quartzui` gateway. Test the bridge inside Unreal.
`client.receiver-owned`	More than one client owns the same document. Retain one client and use subscription cleanup.
`quartzui.action.not-registered`	Register the action on that exact player's shell and validate its name/lifetime; a visible web button does not register native behavior.
Reference logs `bridge.endpoint-not-found`	The fixture can request an absent optional demo endpoint. Distinguish its rendering/readiness from an actual required gameplay provider.
DevTools reports no inspectable page	Start a live PIE/UI view and retry; do not reuse a stopped PIE target.
Empty DevTools with browser-Origin rejection	Check the baseline SHA. It is a known defect there; do not interpret passing discovery automation as a connection test.
Candidate inspector fails after Chrome update	Capture browser/Node versions and launcher log; revalidate the version-sensitive adapter. Keep Origin enforcement.
Audit passes but shipping behavior is unknown	Audit validates resource policy. A cook/package and launched packaged runtime remain separate untested gates.

Source anchors in the plugin: Documentation/EditorTools.md:1, Source/QuartzUIEditor/Public/QuartzUIEditorSettings.h, Source/QuartzUIEditor/Private/QuartzUIEditorModule.cpp, and Resources/Client/quartzui.mjs:45. Native execution claims come from earlier independent baseline and candidate testing. The subsequent documentation review checked their consistency; it did not execute a new Editor session.