docs: prove a safe EditorWindow capture path and replace draft tooling screenshots

[wallstop]

Problem

PLAN.md WS-7.3 is the last open editor-tooling convergence item. The inspector-overlay screenshot manifest and guide still mark the current images as draft/stale because the Linux-devcontainer-to-Windows-host MCP topology has no proven first-class EditorWindow capture path.

Previous experiments established important safety boundaries:

• Do not call UnityEditorInternal.InternalEditorUtility.ReadScreenPixel.
• Do not automate native PrintWindow capture.
• Do not switch Unity editor skins programmatically during capture.
• Start from a Personal/light editor, record the actual skin, inspect every image, and clean the host state after capture.
• Scene View and camera capture tools do not prove EditorWindow or Inspector rendering.

Desired outcome

Establish a repeatable, visually verified capture workflow for the package-owned Inspector, Project Settings, Message Monitor, and Flow Graph surfaces, then replace the draft/stale screenshot set with images of the shipped UI.

Acceptance criteria

• Document one capture method that works from the configured Windows host editor without blocked native screen-reading primitives.
• Prove the method on the Inspector and at least one package-owned EditorWindow before replacing any manifest entry.
• Capture on Personal/light and record the Unity version and skin with each artifact.
• Visually inspect each image for clipping, stale prototype UI, duplicate windows, incorrect theme classes, and sensitive project data.
• Update docs/guides/inspector-overlay.md and the screenshot manifest together.
• Remove every draft/stale marker only when its corresponding image has been replaced and reviewed.
• Leave the host with no temporary scenes, windows, imported prototype assets, or changed skin preferences.
• Keep scripts/__tests__/design-system-dumps.test.js green, including the bans on ReadScreenPixel and PrintWindow automation.
• Run the relevant EditMode editor-tool contract fixtures through Unity MCP after the documentation update.

Related

• PLAN.md WS-7.3 / D9
• docs/images/inspector-overlay/README.md
• docs/guides/inspector-overlay.md

[wallstop]

Capture-path update from session 177:

I proved a desktop-independent path in Unity 6000.4.6f1 on both acceptance surfaces:

• a real Message Monitor using the shipped view and current data;
• a real Inspector containing MessagingComponentEditor and the current Message subscriptions section.

The method lays out and repaints the real Editor panel into a temporary linear RenderTexture, then reads only that render target. It does not use ReadScreenPixel, PrintWindow, desktop/GDI capture, onscreen window movement, or a programmatic skin switch.

Color correctness mattered: this project uses linear color. An sRGB target washed out the UI; RenderTextureReadWrite.Linear, GL.sRGBWrite = false, and a linear Texture2D visually matched the real dark panels and amber borders. All render state is restored in cleanup.

Post-capture state was clean: temporary windows/objects removed, selection cleared, editor idle, and Console empty.

The host currently reports Pro/dark (EditorGUIUtility.isProSkin == true, UserSkin == 1), so these are mechanism proofs, not shippable documentation images. The remaining acceptance work is to select Personal/light through the Unity UI, repeat the two captures, visually inspect them, and update the docs/manifest.

I also found and fixed a contract gap locally: the existing blocked-capture test rejected ReadScreenPixel but not PrintWindow. A mutation probe proved the new PrintWindow guard red, and removal restored the targeted test to 3/3 green. This will be carried in the repository's existing PR per the one-PR rule.

[wallstop]

Two additional acceptance constraints from the manifest audit:

• The manifest requests Unity 2022.3 LTS, while the configured host is 6000.4.6f1. We must use a 2022.3 host or explicitly revise that requirement before final capture.
• tools-menu-rescan.png is a native menu cascade, and the worked examples require combined Hierarchy/Inspector framing. Those remain manual host captures unless their scope is explicitly revised.

All ten tracked images remain draft/stale; the two dark captures prove only the EditorPanel mechanism.

[wallstop]

Evidence clarification: the safe RenderTexture probes were inspected in memory. The two saved dark PNGs in the local artifact folder came from Unity's internal ScreenShots API; after checking UnityCsReference, that API was rejected because it delegates to InternalEditorUtility.ReadScreenPixel. Those saved PNGs are only historical staging evidence and do not count toward the safe capture proof or final acceptance.

[wallstop]

The safe RenderTexture proof is now saved and visually inspected at native resolution:

• Monitor: .artifacts/design-system-screens/session-177/monitor-rendertexture-linear-dark-proof.png, 720x520, SHA-256 05648b02b622abef71be100b1ca8e200d9dd4bb0ea71eba109468fb0ec1cca3d
• Inspector: .artifacts/design-system-screens/session-177/inspector-rendertexture-linear-dark-proof.png, 1000x700, SHA-256 2f32ef372817523014816b201eb083cef47181bc851d102a0f376e55082e1453

The Monitor shows the real shipped view/current component data. The Inspector shows the real Enemy Drone Inspector, MessagingComponentEditor, and current Message subscriptions section. Both are correctly oriented, color-correct for the unchanged dark host, and contain no desktop content or sensitive data.

Postflight is clean: Unity idle, selection empty, exactly the seven standard windows, and a fresh Console error query returned zero entries. These still are dark mechanism proofs, not final Personal/light documentation assets.

[wallstop]

Final session-177 correction and acceptance status:

• The desktop-independent RenderTexture mechanism is cleanly proven for Message Monitor.
• The saved Inspector proof is visually correct, but its IMGUI body emitted EditorGUIUtility.AddCursorRect called outside an editor OnGUI. The Console was later cleared, so the subsequent zero-error query is not acceptance evidence. The final workflow must compare diagnostics without clearing user logs.
• Both saved RenderTexture PNGs are RGBA/color type 6, while the manifest requires RGB24/color type 2.
• No reusable capture helper is retained yet. It must be implemented and validated on Project Settings and Flow Graph as well as Monitor and Inspector.
• The host is still Unity 6000.4.6f1 Pro/dark, while the manifest requests Unity 2022.3 Personal/light.
• Native menu cascades and combined Hierarchy/Inspector frames remain manual captures or require an explicit scope revision.

Accordingly, all artifacts remain staging evidence. None of the draft/stale markers should be removed yet. The repository note and manifest now record these constraints and require docs/guides/inspector-overlay.md plus the manifest to be updated together after accepted captures.

[wallstop]

Mechanism done (#323); artwork still open

The first two acceptance criteria are met, and the capture method is now retained code rather than a documented experiment.

Tests/Editor/EditorSurfaceCapture.cs renders a real shipped surface into an offscreen linear RenderTexture, crops to the surface's own worldBound, and writes RGB24 after verifying PNG color type 2. It restores the render target and GL.sRGBWrite, destroys everything it made on both paths, and reports EditorGUIUtility.isProSkin and the Unity version with each capture instead of switching skins. Eight tests in EditorSurfaceCaptureTests pin it, and design-system-dumps.test.js stays green including the blocked-primitive bans.

Proven on Unity 6000.4.6f1: MessageAwareComponentInspectorView renders to a 720x63 RGB24 crop with no window chrome, no clipping, and a complete 4-side border; the full editor assembly is 557/0; the Console gains no entry from a capture; the host is left with only its seven standard windows and an unchanged skin.

Three findings are recorded in docs/images/inspector-overlay/README.md so they are not rediscovered: a never-shown window has no panel to render, omitting the Repaint step between ValidateLayout and Render yields a valid PNG of a blank frame, and a full-canvas readback frames the host window's tab strip.

The AddCursorRect diagnostic from the 2026-07-30 experiment does not apply here. It came from driving a whole live Inspector with an IMGUI body; the overlay images this issue asks for are crops of the package-owned UI Toolkit view, which renders directly and emits nothing.

What is left

Nothing in the capture mechanism. Two host-side decisions block the artwork, and neither can be automated:

1. Skin. The configured host is Pro/dark (isProSkin=True, UserSkin=1). The manifest requires Personal/light and this issue bans programmatic skin switching, so the final captures need a host that already starts in Personal/light.
2. Unity version. The manifest requests 2022.3 LTS; the configured host is 6000.4.6f1. Either capture on a matching host or revise the requirement explicitly.

Once a correctly configured host is available, the remaining work is running the helper per capture-list entry, visually reviewing each image, and updating docs/guides/inspector-overlay.md and the manifest's capture list together. Native menu cascades (tools-menu-rescan.png) and combined Hierarchy/Inspector frames (worked-example-before/after.png) still need manual host capture or an explicit scope change, because they frame Unity chrome this helper deliberately never reads.

No tracked screenshot has been replaced.