acdream/docs/research/2026-08-13-376-388-blast-review.md

# Blast-radius review — `e56aa511` (#376 + #388: real fullscreen mode switching, state-aware display apply)

**Reviewer lens:** BLAST RADIUS (who else touches the changed surfaces, and who
read the values they used to write). Report only — no edits made.
**Date:** 2026-08-13
**Base:** `e56aa511`, worktree `.claude/worktrees/eloquent-hugle-42119e`,
branch `claude/latest-commits-cb0c8f`.

The commit is correct about the thing it set out to fix: a raw `Size` write
against a fullscreen GLFW window is genuinely gone, the mode switch is genuinely
native, and the failure paths are genuinely no-throw. Everything below is about
the *other* edges those two changes now sit on.

---

## Verdict summary

| # | Surface | Verdict |
|---|---|---|
| M1 | Every Config-tab display row re-runs the fullscreen switch; enter has no idempotence guard; sliders apply per drag tick | **MUST-FIX** |
| M2 | Validation source ≠ switch target (catalog monitor vs primary monitor; UI fallback vs validator fallback) | **MUST-FIX** |
| M3 | #388's *maximized* half is unfixed, and the only un-maximize in the codebase was deleted — but the issue is marked DONE | **MUST-FIX** |
| M4 | Refused/failed enter leaves `fullscreen: true` persisted + checkbox ticked, with no surface but a console line | **MUST-FIX** |
| M5 | Two `GlfwDisplayModeSwitcher` instances → the windowed-position memory is dead on the boot-fullscreen exit path (gate §D5.3 asserts the opposite) | **MUST-FIX** |
| M6 | No divergence-register row for the deviations this commit introduces | **MUST-FIX (process)** |
| W1 | Pacing monitor-refresh read happens *before* the switch, and `StateChanged` (the signal the deleted `WindowState` write used to fire) is now dead | WATCH |
| W2 | `IsFullscreen` is the one unguarded native call in a "never throws" class | WATCH |
| W3 | Windowed exit with no parseable resolution falls back to the *fullscreen* size | WATCH |
| W4 | `glfwSetWindowMonitor` dispatches Silk callbacks synchronously, inside the quiescence lock, inside the update phase | WATCH (verified safe, undocumented) |
| W5 | Hard-kill while fullscreen now leaves a real display-mode change to Windows to unwind | WATCH |
| W6 | `DisplayModeCatalog.InstallFromWindow` is unguarded, and a silent non-install disables fullscreen entirely | WATCH |
| A1 | Startup `ApplyDisplay` ordering vs `InstallFromWindow` | **CLEAN** |
| A2 | Readers of `_window.WindowState` across `src/` | **CLEAN** (there are none) |
| A3 | `RetailWindowLayoutPersistence` resolution key shared fullscreen/windowed | **CLEAN** (correct: same client extent) |
| A4 | #390 edge-detector sequence for enter and exit | **CLEAN** |
| A5 | Tests / `InspectingDisplayWindowTarget` | **CLEAN** |
| A6 | Headless / no-window hosts | **CLEAN** (never reach this code) |

---

## Axis 1 — callers of `SilkRuntimeDisplayWindowTarget` / `IRuntimeDisplayWindowTarget`

Exactly **two production construction sites**, both in `AcDream.App`, both
inside `GameWindow.OnLoad`'s single composition pipeline run:

| Site | Path | Instance lifetime |
|---|---|---|
| `src/AcDream.App/Rendering/GameWindow.cs:1296` | startup — `RuntimeSettingsStartupTargets` → `ApplyDisplay` | process |
| `src/AcDream.App/Composition/SessionPlayerComposition.cs:334` | live save — `RuntimeSettingsTargets` → `ApplyDisplayWindowState` | process (composition runs once at `OnLoad`, not per generation) |

Consumers of the interface: `RuntimeSettingsStartupTargets.ApplyDisplay`
(`RuntimeSettingsTargets.cs:194`) and
`RuntimeSettingsTargets.ApplyDisplayWindowState` (`RuntimeSettingsTargets.cs:424`).
No headless / no-window host reaches either — `AcDream.Headless` references only
`AcDream.Runtime`, and `SessionPlayerDependencies.Window` is a non-nullable
`IWindow` supplied only by `GameWindow` (`SessionPlayerComposition.cs:41`,
`GameWindow.cs:1445`). **CLEAN.**

### Callers relying on the OLD behaviour

- *"`Size` write while fullscreen persists a windowed size for later."* No
  consumer depended on this. A resolution pick while fullscreen is now a real
  mode switch, and the later windowed exit takes its size from
  `display.Resolution` (`RuntimeSettingsTargets.cs:141`), which is the same
  value the old `Size` write would have parked. **CLEAN.**
- *"`WindowState.Fullscreen` borderless."* Nothing in `src/` reads window state
  (see Axis 2). **CLEAN** — with one exception, the *maximized* case, which is
  M3 below.

### M5 — two switcher instances, one live position memory

`GlfwDisplayModeSwitcher._windowedPosition` (`DisplayModeSwitching.cs:47`) is
per-instance and defaults to `(60, 60)`. It is written only inside
`TryEnterFullscreen` (`DisplayModeSwitching.cs:90-96`).

Boot-fullscreen flow:

1. Phase 3 (`SettingsDevToolsComposition.cs:53` → `ApplyStartup` →
   `ApplyDisplay`) enters fullscreen through the **startup** target's switcher.
   That instance captures the real windowed position.
2. Phase 8 (`SessionPlayerComposition.cs:334`) builds the **live** target with a
   fresh switcher whose `_windowedPosition` is still `(60, 60)`.
3. User unticks Full Screen → live path → `TryLeaveFullscreen` restores to
   `(60, 60)` at the fullscreen resolution.

On a 1920×1080 desktop that is a 1920×1080 client area placed at (60,60) — title
bar and bottom edge off-screen. The gate script's own acceptance text for §D5
step 3 says the client must return "positioned where it was before entering
fullscreen"; for the §D4 boot-fullscreen path it will not.

Cheapest correct fix: one shared switcher (or one shared placement record) rather
than one per target instance.

---

## Axis 2 — readers of `_window.WindowState`

`grep '\.WindowState|WindowState\.'` over `src/**/*.cs` returns **zero** reads of
`IWindow.WindowState` outside the deleted lines. Nothing keys window chrome,
screenshots, input mapping, or the L1 capability probes off it:

- Screenshots: `PrivatePresentationRenderer.cs:81` takes `input.ViewportWidth/Height`,
  seeded from `_window.Size` at `GameWindow.cs:1575`. Size-driven, not state-driven.
- Input: cursor mode is driven by camera mode only
  (`CameraPointerInputController.cs:445-447`); nothing consults fullscreen.
- #348's native cursor cache takes the GLFW window handle
  (`GameWindow.cs:1026`), which `glfwSetWindowMonitor` does not change.
- L1 probes (`GraphicalHostPlatformServices`, the bindless/MDI/SSBO gates) read
  no window state.

**CLEAN** on the read side. The one consumer of the *event*:

### W1 — the `StateChanged` signal is now dead, and pacing reads the monitor too early

`SilkWindowCallbackBinding.cs:153` wires `IWindow.StateChanged` →
`DisplayFramePacingController.OnWindowStateChanged`
(`DisplayFramePacingController.cs:132`) → `RefreshActiveMonitor()`. Silk raises
`StateChanged` from its own `WindowState` setter and its iconify/maximize
callbacks; a native `glfwSetWindowMonitor` bypasses all of them. So the deleted
`_window.WindowState = Fullscreen` write was, incidentally, the thing that
re-read the active monitor's refresh rate after a fullscreen transition. That is
gone.

Compounding it, the startup path refreshes the monitor **before** the switch:

```
RuntimeSettingsTargets.cs:194-201
    _pacing.RefreshActiveMonitor();      // desktop mode, e.g. 60 Hz
    _pacing.ApplyPreference(display.VSync);
    _displayWindow.Apply(display);       // switches the display to 1920x1080@300
```

and the live path (`ApplyDisplayWindowState`, `RuntimeSettingsTargets.cs:424-434`)
never touches pacing at all. With VSync **off** and capped rendering,
`FramePacingPolicy.Resolve` (`FramePacingPolicy.cs:26-29`) caps the software
pacer at the cached Hz — which after a fullscreen enter is the pre-switch desktop
refresh. The only thing that rescues it is the incidental `Move` callback
(`SilkWindowCallbackBinding.cs:152`) firing because the window jumped to the
monitor origin — which does not fire if the window was already at that position.

Rated WATCH, not MUST-FIX, because VSync defaults on (`DisplaySettings.cs:92`)
and the VSync branch ignores the refresh value. Fix is one line: refresh the
active monitor *after* `_displayWindow.Apply`, on both paths.

### W2 — `IsFullscreen` can throw out of a "never throws" class

`DisplayModeSwitching.cs:54-62` calls `Glfw.GetApi().GetWindowMonitor(handle)`
with no `try`, while both `Try*` methods around it are wrapped. The class doc
promises "every failure is a no-throw (bool, reason) result". `Apply` calls
`IsFullscreen` on the windowed branch (`RuntimeSettingsTargets.cs:134`), which is
the branch that runs on every single Config-tab save. Low probability
(`glfwGetWindowMonitor` on a live handle does not error), but the contract is
stated and not honoured.

---

## Axis 3 — `DisplaySettings.Fullscreen` consumers

Complete reader set (`grep Fullscreen --include=*.cs src`):

| Reader | Site |
|---|---|
| Startup apply | `RuntimeSettingsTargets.cs:116` (via `ApplyDisplay`, `:199`) |
| Live apply | `RuntimeSettingsTargets.cs:116` (via `ApplyDisplayWindowState`, `:426`) |
| Config tab "Full Screen" row | `ConfigOptionsPageController.cs:650-651` |
| Persistence | `SettingsStore.cs:82` (read), `:640` (write) |

`RetailWindowLayoutPersistence` does **not** read it — see A3.

### Fullscreen boot path, end-to-end

1. `GameWindow.Run` creates the window unconditionally at 1280×720
   (`GameWindow.cs:752-754`).
2. `OnLoad` → `DisplayModeCatalog.InstallFromWindow(_window!)`
   (`GameWindow.cs:1246`).
3. Composition phase 3 builds `SilkRuntimeDisplayWindowTarget(_window!)`
   (`GameWindow.cs:1296`) and `SettingsDevToolsCompositionPhase.Compose` runs
   `ApplyStartup` (`SettingsDevToolsComposition.cs:53`) →
   `RuntimeSettingsController.ApplyStartup:216` → `ApplyDisplay` →
   `Apply(display)`.
4. Fullscreen branch → catalog check → `TryEnterFullscreen` →
   `glfwSetWindowMonitor`.
5. GLFW dispatches the framebuffer-size callback synchronously; the viewport
   target arms `VulkanGraphicsContext.RequestRecreate`
   (`VulkanHostInputCameraCompositionFactory.cs:136`) and the camera aspect
   updates (`FramebufferResizeController.cs:125-127`). Both targets are already
   bound by phase 2, so the mid-`OnLoad` event lands on live owners.

Functionally sound. The problem is what happens when step 4 says no.

### M4 — flag/reality divergence has no surface

The Config toggle persists first, applies second
(`ConfigOptionsPageController.cs:651` → `RuntimeSettingsController.cs:386-392`).
Both refusal paths (`RuntimeSettingsTargets.cs:120-125` "not an offered mode",
`:126-128` "failed") only `Console.WriteLine`. Consequences:

- `settings.json` keeps `fullscreen: true` while the client is windowed.
- The checkbox reads `bindings.LoadDisplay().Fullscreen`
  (`ConfigOptionsPageController.cs:650`) → renders **ticked** against a windowed
  client.
- Every subsequent launch refuses again. The client boots windowed forever with
  the box ticked and no visible explanation. The user's only feedback is a
  console line they will not see in a normal launch.

This matters because the refusal is *reachable in ordinary use*, not just in
pathological setups — see M2. At minimum the refusal should reset the persisted
flag (or the row should read live state rather than the stored flag) so that what
the panel shows is what the client is.

Note the interaction with #377's documented recovery ("hand-edit settings.json
back to false"): the new refusal path re-creates exactly that stuck-flag shape,
minus the crash.

---

## Axis 4 — the #390 interaction (`2153bee2`)

`RetailUiRuntime.Draw` (`RetailUiRuntime.cs:620-652`) is a two-step edge detector
on the per-frame screen size. That size is `_window.Size`, captured once per
render at `GameWindow.cs:1575` and threaded through
`RenderFrameInput.ViewportWidth/Height` →
`PrivatePresentationRenderer.cs:72-76` → `RetainedGameplayUiFrame.Render` →
`Draw`.

**Enter (1280×720 → 1920×1080).** The toggle is handled in the *update* phase
(this is the same seam the #389 review deliberately chose over the render-phase
preview seam — `RuntimeSettingsTargets.cs:427-433`), so the native switch
completes before the frame's render:

- frame N render: `_window.Size` = 1920×1080 ≠ `_lastScreenSize` → one
  `ClampAllToScreen()` (`RetailWindowLayoutPersistence.cs:102-129`, no store I/O,
  `_restoring` suppresses per-move saves), `_screenSizeSettling = true`.
- frame N+1: size repeats → one `RestoreAll(saveBack: false)` for key
  `"1920x1080"`.

One clamp, one reload, no transient size (the intermediate 1280×720 frame never
renders — the switch is synchronous within the update). **CLEAN.**

**Exit.** `TryLeaveFullscreen` is called with the *same* `display.Resolution`
(`RuntimeSettingsTargets.cs:141`) — unticking Full Screen does not change the
resolution setting. So the screen size does not change, the edge detector sees
nothing, and there is no clamp/reload. Correct, and consistent: the layout key is
unchanged. **CLEAN.**

**A3 — the shared layout key.** `ResolutionKey` is `"{W}x{H}"` with no fullscreen
discriminator (`RetailWindowLayoutPersistence.cs:304-305`). Fullscreen 1920×1080
and windowed 1920×1080 have the *same client extent*, so sharing the key is the
right answer, not a collision. **CLEAN.**

**No storm risk from the detector itself** — but see M1, which can produce a
native-call storm upstream of it.

---

## Axis 5 — tests

- No test in `tests/` asserts the old `WindowState` write. The only `WindowState`
  hits are `ChatWindowState`, `RetainedWindowState`, `CreateWindowState`, and
  `DisplayFramePacingControllerTests.cs:65`'s `OnWindowStateChanged(default)`
  smoke call — none coupled to the display apply.
- `InspectingDisplayWindowTarget`
  (`tests/AcDream.App.Tests/Settings/RuntimeSettingsControllerTests.cs:1072`) is a
  fake `IRuntimeDisplayWindowTarget`; the interface is unchanged, so all 7 uses
  stay valid.
- `GameWindowSlice8BoundaryTests.cs:298/331` asserts on `GameWindow.cs` source
  text only — unaffected.
- The 5 new state-machine facts
  (`RuntimeSettingsControllerTests.cs:191-283`) cover exactly the five branches
  and are honest tests (they assert `surface.Writes == 0` on the fullscreen paths,
  which is the real invariant).

**CLEAN.** Two gaps worth noting rather than fixing-as-bugs:

- No test pins the **idempotence** of a repeated fullscreen apply (M1). A
  `FakeModeSwitcher` already records `Calls`; asserting `["enter:1920x1080"]`
  after two identical applies would have caught it.
- No test covers `Fullscreen = true` + unparseable resolution
  (`RuntimeSettingsTargets.cs:118-119`, silent return).

---

## Axis 6 — the catalog dependency and construction order

**A1 — ordering: CLEAN.** Two facts make it safe:

1. The offered-mode check is a **lazy** lambda, not a captured snapshot:
   `spec => Rendering.DisplayModeCatalog.Resolutions?.Contains(spec) == true`
   (`RuntimeSettingsTargets.cs:83`). Construction order relative to
   `InstallFromWindow` is therefore irrelevant; only *apply* order matters.
2. `DisplayModeCatalog.InstallFromWindow(_window!)` is at `GameWindow.cs:1246`,
   before `GameWindowCompositionPipeline.Run` at `:1249`; the startup apply is
   phase 3 (`SettingsDevToolsComposition.cs:53`). Install strictly precedes apply.

A legitimate fullscreen boot is **not** refused for ordering reasons. But it can
be refused for two other reasons, which is the real finding:

### M2 — "an offered mode is supported by construction" is false along two axes

The commit's central safety claim is that validating against `DisplayModeCatalog`
makes the unsupported-mode crash class unreachable. That holds only if the
offered set is a subset of the *switch target's* mode list. Two ways it isn't:

**(a) Different monitors.** The catalog is curated from `window.Monitor` — the
monitor the window currently sits on (`DisplayModeCatalog.cs:53`). The switch
targets `glfwGetPrimaryMonitor()` (`DisplayModeSwitching.cs:77`), and the refresh
lookup enumerates *that* monitor's modes (`DisplayModeSwitching.cs:144-156`). On a
multi-monitor machine with the client on a secondary display, a mode that is
offered (secondary supports it) can be absent from the primary's list →
`"mode WxH is not in the monitor's mode list"` → silent refusal (M4). It fails
safe rather than crashing, but the invariant the design leans on is not there.

**(b) Different fallbacks at the two seams.** When no catalog installs
(`window.Monitor` null, or `Curate` returns empty — `DisplayModeCatalog.cs:54,68`):

- the dropdown falls back to the 6-entry static ladder
  (`RetailUiRuntime.cs:2429` → `ConfigOptionsPageController.cs:641`
  `availableResolutions ?? DisplaySettings.AvailableResolutions`), so the user
  sees six selectable resolutions;
- the validator falls back to **nothing offered**
  (`RuntimeSettingsTargets.cs:83`, `Resolutions?.Contains(...) == true` on null →
  `false`).

So on any host where the catalog does not install, the Full Screen checkbox is a
permanent silent no-op while the dropdown still advertises six modes. The two
seams must share one fallback.

**(c) The likely everyday case.** `DisplaySettings.Default.Resolution` is
`"1280x720"` (`DisplaySettings.cs:90`). If the monitor does not enumerate a
1280×720 mode (common on high-refresh panels that expose a short mode list), a
fresh user who simply ticks Full Screen at the default resolution gets nothing —
no fullscreen, no message. Likewise any settings.json carrying a pre-#391
resolution (`800x600`, `1024x768` — both selectable in earlier builds, per the
OP6 note at `ConfigOptionsPageController.cs:625-633`) now boots windowed forever
with the flag ticked.

---

## M1 — the fullscreen enter is not idempotent, and every Config row re-runs it

This is the highest-blast-radius finding, because it comes in through a surface
the commit never looked at.

`storeOnly` on the Config rows is **only a caption-dim marker**
(`ConfigOptionsPageController.cs:136-152`) — it does not suppress the apply.
Every Graphics row's `apply:` lambda calls `bindings.SaveDisplay(...)`
(`ConfigOptionsPageController.cs:587, 643, 651, 659, 671, 678, 685, 693, 738,
746, 754, 766, 774, 780`), which routes
`RuntimeSettingsController.SaveDisplay:386-392` →
`ApplyDisplayWindowState` → `SilkRuntimeDisplayWindowTarget.Apply`.

And `Apply`'s fullscreen branch has **no idempotence guard**
(`RuntimeSettingsTargets.cs:116-129`) — unlike the windowed branch, which still
has `if (haveResolution && (_window.Size.X != width || ...))` at `:147`. The old
code had `if (_window.WindowState != desired)` at the deleted `:83`; that guard
was removed with the rest of the block and nothing replaced it.

So, while `fullscreen: true`:

- toggling *any* store-only graphics row (MultiPassAlpha, BuildingDetailTextures,
  LandscapeDrawDistance, TextureFiltering, …) fires a full
  `glfwSetWindowMonitor(handle, primary, 0, 0, W, H, refresh)`;
- **dragging a slider** does it *per drag tick*. `FloatOptionRow.SetCurrentValue`
  is documented as "the drag-tick entry point… applies it live IMMEDIATELY"
  (`OptionPageModel.cs:232-240`), and `slider.ScalarChanged` calls it directly
  (`ConfigOptionsPageController.cs:1044`). Field of View (`:587`), Screen
  Brightness (`:671`) and Degrade Distance (`:693`) are all sliders on this tab.

Per drag tick that means: a full `glfwGetVideoModes` enumeration
(`DisplayModeSwitching.cs:148`), a `glfwSetWindowMonitor`, and one
`display: fullscreen mode switch WxH@R` console line
(`DisplayModeSwitching.cs:99-100`) — a permanent evidence line turned into a
per-frame log storm.

What saves it from being a visible mode-change storm on Windows is GLFW's
*internal* early-out (`setVideoModeWin32` returns before `ChangeDisplaySettingsEx`
when the chosen mode equals the current one). Correctness of a user-visible
behaviour should not rest on an undocumented internal of a third-party library —
especially on the exact path whose failure mode was "the client dies mid-session".

The gate script's own §D6 step 1 tells the user to "drag sliders in between"
while fullscreen, so this is directly in the acceptance path.

**Fix shape:** guard the enter the way the windowed branch guards its write —
remember the last applied `(W, H, monitor)` or query the current window monitor +
mode, and return early when the request already holds.

---

## M3 — #388's maximized half is unfixed, and the only un-maximize was deleted

#388's own title and filing include the maximized case: *"fullscreen/maximized
windows silently ignore resolution picks"*, with the evidence being five
consecutive picks producing no framebuffer event at `window was 2056x1290`
(`docs/ISSUES.md:126, 158-165`). The commit marks #388 **DONE**
(`docs/ISSUES.md:127`) having addressed only the fullscreen half.

Worse, the deleted block was the codebase's *only* write of `WindowState`
(Axis 2: there is now zero). Under the new `Apply`, a maximized window takes the
`_modeSwitcher.IsFullscreen == false` path (a maximized window has no attached
monitor) and receives a plain `_window.Size = ...`
(`RuntimeSettingsTargets.cs:147-154`) — precisely the write the issue documents
as silently ignored. Nothing anywhere restores the window to `Normal` first.

So: resolution picks on a maximized window are now permanently a no-op, with the
issue closed. Either restore-then-resize in the windowed branch, or reopen the
maximized half of #388 with the evidence carried forward.

---

## M6 — missing divergence-register rows (process)

`git show e56aa511 --stat` touches no register file. CLAUDE.md's rule is binding:
*"Any commit that introduces a deviation adds its register row IN THE SAME
COMMIT."* At least two deviations ship here, both acknowledged in the code's own
comments:

1. **Refresh-rate selection.** `TryFindRefreshRate` picks the monitor's
   *highest* refresh for the requested WxH (`DisplayModeSwitching.cs:142-156`),
   while the class doc states "retail passed the device's mode as-is"
   (`DisplayModeSwitching.cs:37-38`). Entering fullscreen therefore changes the
   panel's refresh rate as a side effect of a *resolution* pick (the live run
   went to 300 Hz).
2. **Silent refusal.** Retail surfaced "Graphics mode not supported"; acdream
   refuses to a console line and leaves the preference inconsistent (M4).

Arguably a third: primary-monitor-only targeting (`DisplayModeSwitching.cs:77`),
which the doc justifies against retail's primary display device — that one is
probably a citation rather than a deviation, but it is the assumption M2(a)
breaks, so it deserves to be written down somewhere auditable.

IA-22 (#391's curated list) is the natural neighbour row; these are separate
deviations and need their own.

---

## Remaining WATCH items

**W3 — windowed exit with no parseable resolution uses the fullscreen size.**
`RuntimeSettingsTargets.cs:136-140`: when `display.Resolution` does not parse, the
exit falls back to `_window.Size` — which, while fullscreen, *is* the fullscreen
extent. The window then leaves fullscreen as a desktop-sized window at
`(60, 60)`. Narrow (requires a corrupt/blank resolution string), but the fallback
reads "current windowed size" and means "current fullscreen size".

**W4 — synchronous native dispatch inside the quiescence lock.** On Win32,
`glfwSetWindowMonitor` dispatches `WM_SIZE`/`WM_MOVE` synchronously, so
`FramebufferResize` and `Move` re-enter `HostQuiescenceGate.Invoke`
(`SilkWindowCallbackBinding.cs:152-154`) on the same thread while the update
callback already holds `_sync`. This is **safe** — `Monitor` is re-entrant
(`HostQuiescenceGate.cs:36-54`) — and the Vulkan side only *arms* recreation
(`VulkanHostInputCameraCompositionFactory.cs:136`), never recreating mid-frame.
Both are load-bearing invariants that nothing records; a comment at the
`SetWindowMonitor` call site would keep a future change from breaking them.

Also thread-affinity: `glfwSetWindowMonitor` and `glfwGetVideoModes` are
main-thread-only. Both call paths (composition `OnLoad`, update-phase save) are
main-thread today; nothing enforces it.

**W5 — hard kill while fullscreen.** The project's documented launch workflow
falls back to `Stop-Process -Force` when `CloseMainWindow` times out (CLAUDE.md,
"Logout-before-reconnect"). Previously that left a borderless window behind;
now it abandons a real `ChangeDisplaySettingsEx` mode change for Windows to
unwind. Low risk (CDS_FULLSCREEN changes are process-scoped and revert on exit),
but worth one line in the gate script's black-screen-risk note.

**W6 — `InstallFromWindow` is unguarded and fails silently.**
`GameWindow.cs:1246` has no `try`, while `SilkDisplayFramePacingSurface` already
documents that `window.Monitor` can throw `GlfwException` during an RDP/console
display-topology handoff (`DisplayFramePacingController.cs:42-49`). A throw there
kills `OnLoad`; a silent early-return (`DisplayModeCatalog.cs:54-69`) now also
silently disables fullscreen entirely (M2b). The two failure modes deserve
different treatment, and neither is currently distinguishable in a log.

---

## Ranked must-fixes

1. **M1** — guard the fullscreen enter against a no-change request.
   `src/AcDream.App/Settings/RuntimeSettingsTargets.cs:116-129`; drivers at
   `src/AcDream.App/UI/Layout/OptionPageModel.cs:232-240` and
   `src/AcDream.App/UI/Layout/ConfigOptionsPageController.cs:587,671,693`.
2. **M2** — make the offered set and the switch target agree: same monitor
   (`DisplayModeCatalog.cs:53` vs `DisplayModeSwitching.cs:77`) and same fallback
   (`RuntimeSettingsTargets.cs:83` vs `RetailUiRuntime.cs:2429` →
   `ConfigOptionsPageController.cs:641`).
3. **M3** — either fix the maximized half of #388 (restore-to-`Normal` before the
   windowed size write, `RuntimeSettingsTargets.cs:147-154`) or reopen it;
   `docs/ISSUES.md:126-127` currently claims it closed.
4. **M4** — give a refused/failed enter a surface: reset the persisted flag, or
   have the Config row read live state.
   `RuntimeSettingsTargets.cs:120-128`, `ConfigOptionsPageController.cs:650-651`.
5. **M5** — share one windowed-placement record between the startup and live
   switchers. `DisplayModeSwitching.cs:47`, `GameWindow.cs:1296`,
   `SessionPlayerComposition.cs:334`.
6. **M6** — add the divergence-register rows (refresh-rate selection; silent
   refusal), `docs/architecture/retail-divergence-register.md`.