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

# Mechanism review — `e56aa511` (#376 + #388): native fullscreen mode switching + state-aware display apply

**Reviewer lens:** MECHANISM (does the machine do what it claims, on the
platform it runs on).
**Scope:** `src/AcDream.App/Settings/DisplayModeSwitching.cs` (new),
`src/AcDream.App/Settings/RuntimeSettingsTargets.cs`
(`SilkRuntimeDisplayWindowTarget.Apply` rework), and their live
surroundings.
**Date:** 2026-08-13. **Report only — no files were edited.**

Primary evidence for the Silk/GLFW claims below is IL read directly out of
the pinned packages
(`Silk.NET.GLFW 2.23.0`, `Silk.NET.Windowing.Glfw 2.23.0` under
`%USERPROFILE%\.nuget\packages`), not recollection. Where a claim rests on
IL, the decoded bytes are quoted.

---

## Verdict summary

| # | Question | Verdict |
|---|---|---|
| 1 | GLFW API correctness (`Glfw.GetApi()`, main thread) | **PASS** on both halves — but the error-handling contract built on top of it is broken (M1) |
| 2 | State-machine holes | **FAIL** — M2 (no idempotence → video-mode storm), M5 (persisted state diverges, one path silent). The `_windowedPosition` clobber the question asked about is correctly guarded. |
| 3 | Silk-vs-native `WindowState` desync | **PASS** — no desync exists; the getter is native-backed and no writer remains. Events fire on both paths. One latent trap (W3). |
| 4 | Exit path / remembered position | **PARTIAL FAIL** — M3: two switcher instances, so the startup-fullscreen → live-exit path never restores the remembered placement. True off-screen stranding is unlikely (W5). |
| 5 | Validation seam | **PARTIAL FAIL** — M4: catalog and switcher enumerate *different monitors*. The catalog-uninstalled (fixture/headless) case refuses cleanly rather than crashing — that half **PASSES**. |
| 6 | #377 regression surface (startup ordering) | **PASS on ordering** — the composition order is safe and the quiescence gate is reentrant. But the commit does not close #377's mechanism; it makes it reachable more often (W1). |

---

## MUST-FIX findings, ranked

### M1 — `catch (GlfwException)` is dead code on Windows: a failed native switch reports SUCCESS and arms a deferred crash

`DisplayModeSwitching.cs:103-109` (and `:135-139`) wrap the native calls in
`catch (GlfwException)`, and the interface doc at `:24-25` promises
"False (with a reason) instead of throwing on any failure". The commit
message repeats it: "every failure is a no-throw (bool, reason) result."

**On Windows that is false.** Silk's process-global GLFW error callback is
installed by `GlfwProvider::GetGlfw`
(`… callvirt Glfw::Init … call Glfw::get_ErrorCallback; callvirt
Glfw::SetErrorCallback`) and its body is `Glfw.<>c::<.cctor>b__143_0`.
Raw IL (51 bytes):

```
00: 72 3F160070      ldstr  "{0}: {1}"
05: 03 8C 11000002   ldarg.3 ; box            (error code)
0B: 02               ldarg.2                  (description)
0C: 28 4F00000A      call   String::Format
11: 73 9E000006      newobj GlfwException::.ctor
16: 25 03 6F A2..06  dup; ldarg.3; set_ErrorCode
1D: 0A               stloc.0                  (ex)
1E: 7E 40010004      ldsfld Glfw::_isWindows
23: 2C 02            brfalse.s -> 0x27
25: 06 7A            ldloc.0; THROW           <- non-Windows only
27: 7E 41010004      ldsfld Glfw::_exceptions
2C: 06 6F 5600000A   ldloc.0; callvirt List::Add   <- WINDOWS: DEFERRED
32: 2A               ret
```

i.e. `if (!_isWindows) throw ex; else Glfw._exceptions.Add(ex);`.

The drain is `Glfw.ThrowExceptions()`, and the only callers in the entire
Silk closure are seven `GlfwWindow` methods:

```
GlfwWindow::Create, CoreInitialize, CoreReset, RegisterCallbacks,
GlfwWindow::SetWindowIcon, set_Monitor, GetProcAddress
```

(verified by scanning `Silk.NET.Windowing.Glfw`, `Silk.NET.Input.Glfw`,
`Silk.NET.Windowing.Common`, `Silk.NET.Input.Common`, `Silk.NET.Core` —
the last four contain **zero** call sites). None of them is per-frame, and
none of them is on any path this commit takes. `ThrowExceptions` also never
clears the list — its 66-byte body contains `get_Count`, `get_Item(0)`,
`AggregateException`, `throw`, and no `Clear` — so a queued error is
re-raised at *every* later drain.

**Consequences, in order of severity:**

1. A failing `glfw.SetWindowMonitor` (`DisplayModeSwitching.cs:98`) — e.g.
   "Failed to set video mode: Graphics mode not supported", the exact #388
   error — returns normally. `TryEnterFullscreen` returns `true` and prints
   `display: fullscreen mode switch WxH@R` (`:99-100`) for a switch that did
   not happen. Every downstream consumer, including the §D5/§D6 gate script
   and the "live-verified" evidence line in the commit message, reads that
   log as proof of success. **The gate's own oracle can lie.**
2. The queued `GlfwException` detonates at the next `ThrowExceptions()`,
   which in this client is `GlfwWindow::CoreReset` — window close. A failed
   mode switch mid-session therefore surfaces as an unexplained crash *at
   shutdown*, which is exactly the path the project needs graceful for ACE
   session cleanup.
3. This also retro-explains #388's "first surfaced as a caught
   `settings: display save failed: PlatformError…`, then a second fired as
   an UNHANDLED exception": with a never-cleared static list, **the same
   exception instance is thrown twice** from two different drains. That
   pattern is a signature of this mechanism, not of two independent errors.

**Fix direction (no workaround):** do not rely on exceptions at all. Verify
the *post-condition* natively inside `TryEnterFullscreen` /
`TryLeaveFullscreen`: after `SetWindowMonitor`, re-read
`glfw.GetWindowMonitor(handle)` and `glfw.GetVideoMode(monitor)` and require
they match the request; return `false` with the observed state otherwise.
That is platform-independent, needs no knowledge of Silk's deferral, and
turns the log line into a measurement instead of an assumption. Draining
`Glfw.ThrowExceptions()` is a *second-choice* option only, and must account
for the never-cleared static list (a stale error from anywhere in the
process would be misattributed to the switch).

---

### M2 — No idempotence guard on the fullscreen branch: every Display-backed Config row re-issues a REAL video-mode change, once per slider drag tick

`RuntimeSettingsTargets.cs:116-130` — the fullscreen branch calls
`TryEnterFullscreen` **unconditionally**. The windowed branch immediately
below keeps its change guard (`:147`,
`if (haveResolution && (_window.Size.X != width || _window.Size.Y != height))`),
and the code this commit **deleted** had one too
(`if (_window.WindowState != desired) _window.WindowState = desired;`). The
idempotence that existed before this commit was removed on the fullscreen
side only.

Why that matters here specifically:

- Every Display-backed Config row funnels through the same apply:
  `ConfigOptionsPageController.cs:587, 643, 651, 659, 671, 678, 685, 693,
  738, 746, 754` → `bindings.SaveDisplay(...)` →
  `RuntimeSettingsController.SaveDisplay` (`:386-399`) →
  `ApplyDisplayWindowState` → `Apply`.
- `FloatOptionRow.SetCurrentValue` applies **live, on every drag tick, not
  on release** — stated verbatim in `OptionPageModel.cs:176-181` and relied
  on by the Chat tab's fade-while-dragging behaviour.

So, while fullscreen, dragging Field of View / Screen Brightness / Degrade
Distance / Graphics Performance issues one `glfwSetWindowMonitor`
(→ `ChangeDisplaySettingsEx`) **per mouse-move sample**, each one taking the
monitor through a real mode set + re-sync, each one re-entrantly firing
`FramebufferResize` + `Move` (see W1) and arming a swapchain recreate. Every
non-slider Display row (texture detail, filtering, degrades, quality preset,
VSync) does the same once per click.

Secondary cost on the same path: `Glfw.GetApi()` is called fresh on every
`IsFullscreen` read (`:60`) and every `Try*` entry (`:76`, `:124`), and
`Glfw::GetApi` is `newobj GlfwLibraryNameContainer → GetLibraryNames →
CreateDefaultContext → newobj Glfw` — a new `DefaultNativeContext` (and a
`LoadLibrary`/`dlopen` refcount) per call, never disposed. That is ~2–3 per
apply, i.e. per drag tick under this bug.

**Fix:** early-return when already fullscreen at the requested mode. That
needs a current-mode read on the seam (e.g.
`IDisplayModeSwitcher.TryGetCurrentMode(out int w, out int h)`), which the
fake can implement trivially — and a test asserting a same-state re-apply
issues zero `enter:` calls (`FakeModeSwitcher` already records them, so this
gap was one assertion away from being caught).

---

### M3 — Two `SilkRuntimeDisplayWindowTarget` instances: the remembered windowed placement is lost exactly on the startup-fullscreen → live-exit path

There are two production construction sites, each building its **own**
`GlfwDisplayModeSwitcher` with its own `_windowedPosition` field
(`DisplayModeSwitching.cs:47`, initial value `(60, 60)`):

- `src/AcDream.App/Rendering/GameWindow.cs:1296` — the **startup** target
  (`RuntimeSettingsStartupTargets`), which runs `ApplyDisplay` during
  composition phase 3.
- `src/AcDream.App/Composition/SessionPlayerComposition.cs:334` — the
  **live** target (`RuntimeSettingsTargets`), which runs
  `ApplyDisplayWindowState` on every Config save.

Sequence that breaks: `settings.json` has `fullscreen: true` → **instance A**
captures the real windowed position at `:90-96` and enters fullscreen →
user later unticks Full Screen in the Config tab → **instance B** runs
`TryLeaveFullscreen`, and its `_windowedPosition` has never been written, so
the window is placed at the `(60, 60)` literal.

On a single monitor that is merely wrong-but-harmless; on multi-monitor it
teleports the client to the **primary** monitor's top-left regardless of
where it was. It also makes the commit message's claim ("the windowed
placement is remembered for the exit path") and gate-script step §D5
("positioned where it was before entering fullscreen",
`docs/research/2026-08-13-display-block-test-script.md`) false for that
ordering — and *only* for that ordering, so a tester who toggles fullscreen
on and off within one session will not reproduce it. **The gate must
explicitly exercise launch-fullscreen → untick.**

**Fix:** one process-wide switcher (or hoist the remembered placement into a
single owner both targets borrow).

---

### M4 — Catalog and switcher enumerate DIFFERENT monitors, so "an offered mode is supported by construction" does not hold

The whole crash-class argument rests on the catalog and the switcher agreeing
about which display's mode list is authoritative. They do not:

- `DisplayModeCatalog.InstallFromWindow` (`Rendering/DisplayModeCatalog.cs:53`)
  enumerates **`window.Monitor`**. Silk's `GlfwWindow::get_Monitor` (IL:
  `GetWindowMonitor` → else walk `GlfwMonitorEnumerable` for the monitor whose
  bounds contain the window centre → else `GetPrimaryMonitor`) means at
  `OnLoad` this is *the monitor the window happens to be on*.
- `GlfwDisplayModeSwitcher.TryEnterFullscreen` (`:77`) enumerates and
  switches on **`GetPrimaryMonitor()`**.

Two failure shapes on a heterogeneous multi-monitor desktop:

1. A mode offered from the secondary's list is absent from the primary's →
   `TryFindRefreshRate` fails (`:84-88`) → fullscreen refused. The user ticks
   the box, nothing happens, `settings.json` says `fullscreen: true`
   (see M5).
2. Even on success, entering fullscreen moves the client to the *primary*
   monitor. That may be retail-faithful (`Device::ForceDisplayResolution`
   drove the primary display device, per the class doc), but it is a
   behavioural deviation from "fullscreen the window where it is" and is not
   in the divergence register.

**Fix:** pick one monitor authority and use it at both ends (catalog +
switcher). If "always primary" is kept as the retail-faithful choice, the
catalog must enumerate the primary too, and a
`docs/architecture/retail-divergence-register.md` row must record the
window-jumps-to-primary behaviour.

---

### M5 — Every fullscreen refusal/failure leaves `settings.json` inconsistent with reality; one path is entirely silent

`RuntimeSettingsController.SaveDisplay` **persists first, applies second**
(`:390` then `:392`). `Apply`'s three fullscreen exits never revert:

| Path | Line | Logged? | Persisted state after |
|---|---|---|---|
| Resolution unparseable | `:118-119` | **no log at all** | `fullscreen: true`, window windowed |
| Mode not offered | `:120-125` | yes (`refused — not an offered mode`) | `fullscreen: true`, window windowed |
| Switch failed | `:126-128` | yes (`failed (…) — staying windowed`) | `fullscreen: true`, window windowed |

The unparseable case is the one the review brief asked about, and it is the
worst of the three: it produces **no `display:` line whatsoever**, so the
gate script's "any refused/failed switch logs a `display: … failed/refused`
line" acceptance criterion (§D6 step 1) cannot be met and the tester has
nothing to read. The Config checkbox then reads `true` from storage forever
and every subsequent launch silently re-refuses.

A second accuracy defect lives at `:128`: when the *re-entry* attempt fails
while the window is **already fullscreen**, the message says "staying
windowed", which is factually wrong.

**Fix:** log the unparseable case; make the failure message report the actual
resulting state; and decide deliberately whether a refusal should revert the
persisted `Fullscreen` (retail has a confirmation flow — `SetConfirmChange`
— already noted as unported in `ConfigOptionsPageController.cs:623`).

---

## Per-question findings

### Q1 — GLFW API correctness

**`Glfw.GetApi()` is the right instance. PASS.** `Glfw::GetApi` IL is
`newobj GlfwLibraryNameContainer → SearchPathContainer::GetLibraryNames →
Glfw::CreateDefaultContext → newobj Glfw`: a *new managed wrapper* over the
*same native library*. GLFW's state (init flag, window list, monitor list,
error callback) lives in the native module, which the OS loader returns as
one instance per process — so a second wrapper drives the same GLFW.

The `GraphicalWindowBackendSelection.cs:135-138` comment ("A separate
`Glfw.GetApi()` instance would receive the hint but would not own the window
backend's process-global GLFW state") is about **init-hint ordering**, not
about later calls: `GlfwProvider.UninitializedGLFW` is itself literally
`new Lazy<Glfw>(Glfw.GetApi)` (`GlfwProvider::.cctor` → `<>O::<0>__GetApi`),
so it is the same kind of object. Using `GlfwProvider.UninitializedGLFW.Value`
there matters because Silk must later `Init()` *that* instance; it does not
imply later `GetApi()` calls are wrong. `GlfwCursorCache.TryCreate`
(`Rendering/GlfwCursorCache.cs:47`) already established this in production
(#348).

**Caveat (W4):** `GlfwCursorCache` caches its `Glfw` for the object's
lifetime; `GlfwDisplayModeSwitcher` calls `Glfw.GetApi()` on **every**
property read and method entry (`:60`, `:76`, `:124`). Each call allocates a
`Glfw` + `DefaultNativeContext` and takes a native-library refcount that is
never released (`NativeApiContainer.Dispose` is never called). Cache one
instance in the field, as the #348 precedent does.

**Thread: PASS.** `Program.cs` constructs `GameWindow` and calls
`window.Run()` on the process main thread (`Program.cs:142`);
`GameWindow.Run` calls `Window.Create` (`GameWindow.cs:761`) and
`_window.Run()` (`:785`) on that same thread; Silk's loop and all callbacks
(Load/Update/Render/FramebufferResize) run on the calling thread. Both the
startup `ApplyDisplay` (composition, inside `OnLoad`) and the live
`ApplyDisplayWindowState` (Config-tab click handling in the update phase)
therefore execute on the GLFW main thread. `glfwSetWindowMonitor`,
`glfwGetVideoModes` and `glfwGetWindowPos` are all main-thread-only, and all
three are satisfied.

### Q2 — State-machine hole enumeration

`haveResolution` = `TryParseResolution` succeeded (`:113-114`);
`offered` = `_isOfferedMode("{w}x{h}")`; `fs` = `_modeSwitcher.IsFullscreen`.

| # | target | fs | haveRes | offered | switcher result | Outcome | Assessment |
|---|---|---|---|---|---|---|---|
| 1 | FS | no | yes | yes | ok | enters fullscreen | correct |
| 2 | FS | no | yes | yes | fail | logs, stays windowed | correct **but see M1** (on Windows "fail" is not observable) |
| 3 | FS | no | yes | no | — | logs refusal, stays windowed | correct; **M5** (settings now lie) |
| 4 | FS | no | **no** | — | — | **silent return** | **M5** — no log, settings lie |
| 5 | FS | **yes** | yes | yes | ok | redundant real mode set | **M2** — storm |
| 6 | FS | **yes** | yes | yes | fail | logs "staying windowed" **while fullscreen** | **M5** (wrong message) |
| 7 | FS | **yes** | yes | no | — | logs refusal, remains fullscreen at old mode | acceptable; message is accurate |
| 8 | FS | **yes** | no | — | — | silent return, remains fullscreen | benign, but silent |
| 9 | win | yes | yes | — | ok | native exit at picked size + `_windowedPosition` | correct; **M3** (wrong position across instances), **W5** (size==desktop) |
| 10 | win | yes | yes | — | fail | logs, remains fullscreen | correct |
| 11 | win | yes | **no** | — | ok | exit at **current fullscreen size** (`:136-140` reads `_window.Size`, which under native fullscreen is the *mode* size) | window client = desktop size → frame overflows desktop (**W5**) |
| 12 | win | no | yes | — | — | size write iff changed (`:147`) | correct, guarded |
| 13 | win | no | no | — | — | no-op | correct |

**On the specific idempotency sub-question:** the guard at `:90-96` is
**correct**. `_windowedPosition` is only captured when
`glfw.GetWindowMonitor(handle) is null`, so re-entering fullscreen while
already fullscreen cannot clobber it with `(0,0)`. GLFW itself tolerates
`glfwSetWindowMonitor` with the same monitor (it re-applies the mode); the
problem is not correctness of a single repeat but the *rate* of repeats
(M2).

### Q3 — Silk-vs-native desync

**No desync exists. PASS.** `GlfwWindow::get_CoreWindowState` is
native-backed:

```
_glfw.GetWindowAttrib(_glfwWindow, Iconified)   -> Minimized
_glfw.GetWindowAttrib(_glfwWindow, Maximized)   -> Maximized
_glfw.GetWindowMonitor(_glfwWindow) != null     -> Fullscreen
else                                            -> Normal
```

So after a native `SetWindowMonitor`, `_window.WindowState` correctly reports
`Fullscreen`. Silk's `_extendedState`-style caching only applies before
`IsInitialized`.

**No readers to misbehave.** `grep` over `src/` and `tests/` finds **zero**
`WindowState =` writers left after this commit, and the only consumer is
`DisplayFramePacingController.OnWindowStateChanged(WindowState _)`
(`Rendering/DisplayFramePacingController.cs:132`), which discards the value
and calls `RefreshActiveMonitor()`. UI/picking read `IWindow.Size`
(`Composition/InteractionUiRuntimeSources.cs:559`) and the render path reads
`IWindow.FramebufferSize` (`Rendering/RetailPViewPassExecutor.cs:27`,
`Rendering/Gpu/Vk/VulkanGraphicsContext.cs:261, 406`) — both are live native
reads (`get_FramebufferSize` = `GetFramebufferSize`), both correct under
native fullscreen. There is no screenshot path that reads `WindowState`.

**Events fire on both paths, and directly.** Silk raises them straight from
the GLFW callback with **no queueing** —
`GlfwWindow::<RegisterCallbacks>b__94_2` is
`ldsfld FramebufferResize; newobj Vector2D<int>; callvirt Invoke`, and
`b__94_0` (pos) is `UpdatePosition; ldsfld Move; Invoke`. Since
`glfwSetWindowMonitor` calls `SetWindowPos`, the WM_SIZE / WM_MOVE handlers
run synchronously inside it, so `FramebufferResize` and `Move` are delivered
**re-entrantly**, on both enter and exit. (Confirmed safe: see W1/W8.)

**`StateChanged` does NOT fire** for a monitor change — `b__94_6`/`b__94_7`
are the iconify/maximize callbacks and are the only sites that call
`UpdateState` + raise `StateChanged`. `pacing.OnWindowStateChanged` therefore
never runs for our switch; `pacing.OnWindowMoved` covers it instead
(`SilkWindowCallbackBinding.cs:152`). No action needed — just do not build
anything new on `StateChanged`.

**W3 (latent trap):** `GlfwWindow::set_CoreWindowState` is the only writer of
Silk's `_nonFullscreenPosition` / `_nonFullscreenSize`. Bypassing it means
those stay stale forever. If any future code sets `WindowState = Normal`
while natively fullscreen, Silk calls `glfwRestoreWindow`, which for a
fullscreen window restores the *video mode on the same monitor* — it does
**not** leave fullscreen. Worth a one-line comment in
`DisplayModeSwitching.cs` so the next author does not reach for the Silk
setter as a "simpler" exit.

### Q4 — The exit path

- **`(60,60)` default:** reachable in production, via M3 (not via the
  "never captured" path the question hypothesised — startup entry *does*
  capture, just on the other instance).
- **Off-screen stranding proper:** unlikely. `glfwSetWindowMonitor(NULL, …)`
  restores the monitor's original video mode, so a position captured
  pre-fullscreen is still valid for the restored desktop. `(60,60)` is always
  on-screen on the primary.
- **W5 (real, milder):** the exit uses the *picked resolution* as the
  **client** size. The catalog's Defaults value **is the desktop mode**
  (`DisplayModeCatalog.cs:39-43`), so the common case produces a windowed
  client exactly the size of the desktop — its frame and title bar then
  overflow the work area, and row 11 of the Q2 table (unparseable resolution)
  produces the same via `_window.Size`. Recommend clamping the restored
  placement/size to the monitor work area
  (`glfwGetMonitorWorkarea`) on the exit path.
- **#390 interaction — confirmed, the UI clamp does NOT cover the OS
  window.** `RetailWindowLayoutPersistence.ClampAllToScreen`
  (`src/AcDream.App/UI/RetailWindowLayoutPersistence.cs:102-129`) clamps each
  attached retail-UI window into `ValidScreenSize()` — the client area — via
  `handle.MoveTo`. It never touches the native window. So #390 keeps the
  *panels* reachable inside whatever client rect exists; it cannot rescue a
  client rect that itself overflows the desktop. That is the right layering;
  it just means W5 needs its own fix rather than leaning on #390.

### Q5 — Validation seam

- **Are valid sub-desktop fullscreen modes wrongly refused?** Not by the
  curation itself. `DisplayModeCatalog.Curate` (`:94-144`) keeps any monitor
  mode that fits the desktop, is ≥1280 wide and is 16:9/16:10/21:9/32:9
  within ±2.5% — plus the desktop mode unconditionally. Those are all genuine
  fullscreen targets, and `TryFindRefreshRate` re-checks against the live
  GLFW mode list, so nothing supported-and-offered is refused **on a
  single-monitor machine**. On multi-monitor, **M4** breaks it.
- **Catalog-uninstalled (fixture/headless):** refuses cleanly, no crash.
  `DisplayModeCatalog.Resolutions` is `null`, and
  `RuntimeSettingsTargets.cs:83` is
  `spec => DisplayModeCatalog.Resolutions?.Contains(spec) == true` — a
  null-conditional whose `null == true` is `false`. Fullscreen entry is
  refused with a log; nothing dereferences null. **PASS.**
- **Nit (not blocking):** `Contains` is `Enumerable.Contains` over an
  `IReadOnlyList<string>` (ordinal, O(n≈10)) — fine. The spec string is
  rebuilt from the parsed ints (`$"{width}x{height}"`), so
  `"01920x1080"`-style input normalises before lookup. `TryParseResolution`
  splits on lowercase `'x'` only (`:165`) — pre-existing.
- **W7:** the catalog is captured once at `OnLoad`
  (`GameWindow.cs:1246`) and never refreshed; monitor hot-plug or a topology
  change leaves it stale, and (with M4) increasingly wrong.

### Q6 — #377 regression surface at startup

**The ordering is safe. PASS.** Verified chain inside `OnLoad`:

1. `AcquirePlatform()` → `VulkanGraphicsContext.Acquire` — swapchain created
   at the 1280x720 startup size (`GameWindow.cs:1219-1238`, `:752-757`).
2. `DisplayModeCatalog.InstallFromWindow(_window!)` — `GameWindow.cs:1246`,
   **before** the pipeline, so the startup fullscreen entry is validated
   against a real catalog.
3. Composition **phase 1** binds the framebuffer targets:
   `FramebufferResize.BindViewport` (`HostInputCameraComposition.cs:204`) and
   `BindCamera` (`:317`).
4. Composition **phase 3** runs `Settings.ApplyStartup`
   (`SettingsDevToolsComposition.cs:53`) → `ApplyDisplay` → native switch.

So the re-entrant `FramebufferResize` fired from inside
`glfwSetWindowMonitor` finds both targets bound —
`FramebufferResizeController.Resize` (`:109-129`) is null-conditional
throughout, and the Vulkan viewport target only **arms** a frame-boundary
swapchain recreate (`VulkanHostInputCameraCompositionFactory.cs:38, 122`)
rather than doing GPU work re-entrantly. Had step 4 preceded step 3, the
resize would have been silently dropped ("late binding never replays an
earlier resize transition", `FramebufferResizeController.cs:123-124`) and
the client would have rendered a 1280x720-aspect image stretched over the
fullscreen surface — the #387 symptom, resurrected at startup. **This
ordering is load-bearing and undocumented; it deserves a comment at
`GameWindow.cs:1246` or a boundary test.**

Re-entrancy itself cannot deadlock: `HostQuiescenceGate.Invoke` uses `lock`
(`Rendering/HostQuiescenceGate.cs:39, 49`), and `Monitor` is reentrant on the
same thread — the class doc already calls this out.

**W1 (the residual, and the honest answer to "could this resurrect the old
access violation"): yes, the mechanism is still reachable — more often than
before.** The re-entrant `Move` event runs
`pacing.OnWindowMoved` → `RefreshActiveMonitor()` →
`SilkDisplayFramePacingSurface.TryGetActiveMonitorRefreshHz` →
`_window.Monitor?.VideoMode.RefreshRate`
(`DisplayFramePacingController.cs:35, 121-128`) **from inside
`glfwSetWindowMonitor`, mid-mode-transition**. `GlfwWindow::get_Monitor`
resolves through `GetWindowMonitor` → `GetMonitors` → `new GlfwMonitor` and
`GlfwMonitor.VideoMode` → `GetVideoMode` — which is precisely #377's crash
site (`0xC0000005 in Glfw.GetVideoMode`, "reading a monitor
mid-mode-transition", `docs/ISSUES.md` §#377). Its `catch (GlfwException)`
guard (`:42-49`) does not help: per **M1** GLFW errors do not throw on
Windows, and an access violation is not a managed exception at all.

This is not a *new* class — Silk's own `WindowState = Fullscreen` setter also
called `SetWindowMonitor` — but before this commit the fullscreen write was
guarded by `if (_window.WindowState != desired)` and therefore rare. With
**M2**, it now runs on every Display-tab save and every slider drag tick.
Recommendation: suppress the pacing monitor refresh for the duration of a
deliberate mode switch (a re-entrancy latch around
`SetWindowMonitor`, then one explicit `RefreshActiveMonitor()` after it
returns) — that is a correctness fix for a re-entrancy hazard, not a
symptom-hiding guard.

---

## Test-coverage gaps (all five new tests pass on their own facts)

`tests/AcDream.App.Tests/Settings/RuntimeSettingsControllerTests.cs:157-288`
covers: validated switch / never-size-write, unoffered refusal, failed-switch
usability, native exit, plain windowed write. Missing, each one assertion
away with the existing `FakeModeSwitcher`:

1. `Fullscreen=true` while `IsFullscreen=true` **at the same mode** → expect
   `Assert.Empty(switcher.Calls)` (**M2**).
2. `Fullscreen=true` with an unparseable `Resolution` → currently a silent
   `return`; assert whatever the decided behaviour is (**M5**).
3. Enter-then-exit round trip on **one** switcher instance, asserting the
   position is round-tripped (would not catch **M3**, which is a composition
   fact — that one needs a construction-site assertion or a single-owner
   refactor).
4. `Fullscreen=false` while `IsFullscreen=true` with an unparseable
   resolution → asserts the row-11 fallback reads the surface size.

## Gate-script gaps

`docs/research/2026-08-13-display-block-test-script.md` §D4–§D6 is otherwise
well-shaped (the black-screen-risk flagging is right). Add:

- §D5 must include **launch fullscreen → untick Full Screen** as a distinct
  step from **tick → untick in one session**; only the former exposes **M3**.
- §D6 must include **drag a slider (Field of View) while fullscreen** — the
  **M2** storm.
- §D6's "any refused/failed switch logs a `display: … failed/refused` line"
  is not currently guaranteed (**M1** makes failure invisible, **M5** case 4
  logs nothing). Treat that acceptance line as unmet until M1/M5 land.

## Register / bookkeeping

- No `docs/architecture/retail-divergence-register.md` row accompanies this
  commit. At minimum the **always-switch-the-primary-monitor** behaviour
  (**M4**) is a deviation ("retail's `ForceDisplayResolution` drove the
  primary display device" is asserted in the class doc but the *window* also
  relocates), and the CLAUDE.md rule is that a deviation ships with its row
  in the same commit.
- On Wayland (`GraphicalDisplayProtocol.Wayland`), a client cannot change the
  display mode; `glfwSetWindowMonitor` will report success without switching.
  Slice L is parked, so this is documentation-only today — one line in the
  `GlfwDisplayModeSwitcher` class doc.