XCEngine/docs/plan/NewEditor_LiveResizeJitterRootCleanupPlan_2026-04-22.md

NewEditor Live Resize Jitter Root Cleanup Plan

Date: 2026-04-22 Status: In Progress

1. Objective

Clean up the remaining new_editor live-resize jitter without weakening the already-restored anti-deformation contract.

The target contract remains:

1. host-driven borderless resize must still be able to present target-size content before the native window visibly adopts that size
2. Win32 lifecycle handling must not reintroduce stretched stale content
3. resize-time rendering policy must stay centralized and structurally clean instead of being spread across message handlers and chrome code

2. Confirmed Root Cause

The current jitter is caused by two structural problems acting together:

1. live borderless resize still drives a real swap-chain resize on each pointer step
2. that resize path still performs a hard D3D12 synchronization before touching swap-chain buffers
3. the same resize step can then be rendered again from WM_SIZE, WM_PAINT, and the steady-state main loop

So the root issue is not the custom title bar design. The custom title bar is the mechanism that preserves anti-deformation. The remaining problem is the host-side resize / present execution strategy under it.

3. Red Lines

This cleanup must not:

1. remove the custom title-bar-driven anti-deformation flow
2. move resize / present ownership into the Editor UI content layer
3. add scattered if (interactiveResize) patches across unrelated code
4. create a second parallel frame executor beside the existing frame driver
5. weaken D3D12 lifetime safety by blindly deleting resize synchronization without replacing it with a narrower correct rule

4. Target End State

After the cleanup:

1. immediate resize-time frames still go through one shared frame-driving entry point
2. predicted borderless resize transitions present at most one intentional immediate frame per interaction step
3. WM_SIZE only acknowledges a predicted resize that was already presented and does not redundantly render it again
4. the next steady-state app-loop frame is skipped once after an already-presented immediate resize frame
5. live resize waits only for tracked in-flight frame retirement instead of forcing a fresh queue-wide idle synchronization each step

5. Implementation Plan

Phase A. Re-centralize immediate resize-time frame execution

1. add an explicit immediate-frame path on top of EditorWindowFrameDriver
2. route borderless predicted transitions through that shared driver instead of calling RenderFrame(...) directly
3. keep transfer-request handling ownership unchanged

Phase B. Add predicted-presentation acknowledgement state

1. extend host runtime state so predicted client size can remember whether it has already been presented
2. let borderless predicted transitions mark the prediction as presented only after the immediate frame path runs
3. teach WM_SIZE handling to consume that acknowledgement and skip its redundant render when the incoming size is only the native echo of an already-presented prediction

Phase C. Eliminate the immediate-frame / steady-state double render

1. add one-shot state that skips the next steady-state frame after an immediate synchronous frame already presented the same window
2. consume that skip only inside EditorWindowHostRuntime::RenderAllWindows(...)
3. keep normal steady-state rendering unchanged for all other cases

Phase D. Narrow D3D12 live-resize synchronization

1. add a host-device helper that waits only for tracked submitted frame slots to retire
2. use that narrower helper from live swap-chain resize
3. keep full WaitForGpuIdle() for shutdown / destruction paths where full teardown semantics are still required

6. Validation Requirements

Before completion:

1. XCUIEditorApp must build successfully after the cleanup
2. borderless live resize must still avoid content deformation
3. redundant WM_SIZE + steady-state resize-time frame duplication must be structurally removed from the new code path
4. no unrelated docking / detach / utility-window behavior may regress

7. Completion Criteria

This work is complete only when:

1. live resize keeps the anti-deformation contract
2. one resize interaction no longer fans out into multiple avoidable frame executions
3. D3D12 live-resize synchronization is reduced from queue-wide idle to tracked frame retirement
4. the resulting code remains a mainline host/render lifecycle cleanup instead of a symptom patch