Implement legacy black surface fades

docs/engine-re.md

@@ -3193,10 +3193,14 @@ black/white scratch alpha to 255. Re-entry finalizes the named endpoint before s
 Himegari uses only the black pair: three `0x21` calls and eight `0x22` calls, all `(1,30)` and therefore
 about 480 ms. The scripts first select surface 1, clear it, publish a complete retained frame through
 `0x20c`, restore the backbuffer, then fade. `0x21` is the menu-entry reveal; `0x22` is the corresponding
-menu/scene exit to black. Together they close 11 of the 39 remaining skipped instructions across seven
-distinct scripts. Implementation should extend the existing `LegacyScreenTransition` host path with an
-explicit solid-color endpoint; treating a missing numbered surface as black is unsafe because the current
-mode-4 fallback snapshots the live retained frame.
+menu/scene exit to black.
+
+The port dispatches both opcodes through the existing blocking `LegacyScreenTransition` clock and terminal
+publication path. Its compositor already clears the whole frame to opaque black, so an empty source list
+models black-to-captured and an empty target list models captured-to-black without overloading the mode-4
+missing-surface fallback (which intentionally snapshots the live retained frame). This closes 11 formerly
+skipped instructions across seven distinct scripts and reduces the effectful-gap inventory from 18 to 16
+distinct opcodes / 28 instructions.
 
 The same manual pass exposed a resource-addressing issue after `0x6c` was fixed: ROOM did execute
 `play-voice`, but `GodotAdvHost` attempted only inferred SC-section resolution. ROOM's voice operands

docs/opcode-reference.md

@@ -658,12 +658,16 @@ SC0000 label_1235a reaches this when 0x1c7/0x1cc are zero. Native run-state bit
 - **depends on:** 0x20c, 0x20d
 - **evidence:** Ghidra /v2: dispatch slot 0x21 resolves to op_0x21_fade_surface_in_from_black@0x41cb00. First entry sets run-state bit 8, converts timing <=64 to interval=argument ms and alpha step=16 (otherwise interval=argument/16 and step=1), then starts screen_transition_begin@0x439da0 mode 0 with the operand surface. screen_transition_tick@0x43a7a0 draws that surface below an opaque-black scratch surface whose alpha falls 255->0; re-entry finalizes the operand surface. Corpus: 3 sites in EVOLVE, SELSTAGE, and STUDY, all (1,30), approximately 480 ms.
 
+Port status (2026-07-29): implemented through the blocking legacy full-frame transition host path. An explicit empty/black source endpoint is composited beneath the captured target; timing and terminal-frame publication share the op-0x25 lifecycle.
+
 ### 0x22 `fade-surface-out-to-black` (u00418920, argc 2)
 - **summary:** (surface_slot)(timing_argument) — block while fading a captured full-frame surface to black. Black remains the terminal frame.
 - **grounding:** source=investigation, confidence=high
 - **depends on:** 0x20c, 0x20d
 - **evidence:** Ghidra /v2: dispatch slot 0x22 resolves to op_0x22_fade_surface_out_to_black@0x41cbc0. It uses the same timer/alpha-step conversion as 0x21 and 0x25, then starts screen_transition_begin@0x439da0 mode 1. screen_transition_tick@0x43a7a0 keeps the operand surface opaque and raises the black scratch-surface alpha 0->255; re-entry finalizes a black endpoint. Corpus: 8 sites across ALCHEMY, CHMENU, EVOLVE, FORT, SELSTAGE, STUDY, and SUMMON, all (1,30), approximately 480 ms.
 
+Port status (2026-07-29): implemented through the blocking legacy full-frame transition host path. The captured source is composited beneath an explicit empty/black target endpoint; timing and terminal-frame publication share the op-0x25 lifecycle.
+
 ### 0x23 `fade-surface-in-from-white` (u004189D0, argc 2)
 - **summary:** (surface_slot)(timing_argument) — broader-AGE mode-2 sibling of 0x21: block while fading from white to a captured full-frame surface.
 - **grounding:** source=investigation, confidence=high

docs/phase-b-framework.md

@@ -828,9 +828,9 @@ native defaults, category isolation, getter/setter round trips, idempotent route
 selectors, native and redirected path resolution, CP932 INI preservation, and persistence. All 476 engine tests, the
 warning-free Godot build, opcode lint, and the Himegari-targeted threaded selftest pass.
 
-**Post-tranche rerank:** a fresh 481-script aggregate confirms exactly 18 effectful gaps totaling only
-39 instructions. The widest are unknown `0x22` (eight sites across seven scripts), unknown `0x230`
-(six sites across two scripts), then `0x21` and `0x1b2` (three sites each); every other gap has at most two
+**Post-tranche rerank:** a fresh 481-script aggregate found exactly 18 effectful gaps totaling only
+39 instructions. The widest were `0x22` (eight sites across seven scripts), `0x230`
+(six sites across two scripts), then `0x21` and `0x1b2` (three sites each); every other gap had at most two
 sites. CONFIG itself is now 1659/1665 instructions implemented, with four unrelated calls remaining
 (`0x142` twice, `0xb7`, and `0xb8`).
 
@@ -841,11 +841,19 @@ timer conversion and full-frame snapshot lifecycle. All 11 combined Himegari sit
 480 ms, across menu entry/exit paths. The existing `LegacyScreenTransition` host seam can own the pair,
 but it needs an explicit black endpoint rather than its mode-4 missing-surface fallback.
 
-The follow-up `0x230(handle)` is also decoded: it clears the retained object's cyclic active flag and five
+**Black-fade pair implemented (2026-07-29):** `0x21` and `0x22` now dispatch through the shared blocking
+full-frame transition path. The compositor represents the solid-black side explicitly as an empty captured
+object list over its normal opaque-black clear: source-empty for black-to-surface and target-empty for
+surface-to-black. This preserves mode-4 `0x25`'s separate missing-target fallback, shares the native timing
+conversion and exact terminal-frame publication, and closes all 11 sites. The remaining effectful inventory
+is 16 distinct opcodes / 28 instructions. All 477 engine tests, opcode build/lint, the zero-warning Godot
+build, and the Himegari-targeted threaded selftest pass.
+
+The follow-up `0x230(handle)` is decoded: it clears the retained object's cyclic active flag and five
 looping-channel start/period pairs without changing current/base transforms. Its six calls are five
 DEBUGADV effect demonstrations plus one FIELD movement setup.
 
-**NEXT:** implement `0x21` and `0x22` together as one black-fade slice, then implement `0x230`.
+**NEXT:** implement `0x230`.
 
 ## Later Phase B breadth