Implement ADV foreground transition lifecycle

docs/engine-ctx-reference.md

@@ -36,6 +36,7 @@ Struct `EngineCtx`, size `0xa1000`. Applied to the Ghidra `/v2` image (dispatch-
 | `0x6db28` | `coroutine_yield_b` | `void*` | op 0x7b yield-state save (op2 -> +ctxidx*4) |
 | `0x6dbc8` | `coroutine_runstate` | `int` | op 0x7c resume gate (run-state bit 0x2000000) |
 | `0x6dbcc` | `coroutine_resume_off` | `int` | op 0x7c resume PC offset |
+| `0x6dbd4` | `adv_read_skip_state` | `int` | current ADV read/click-skip service state; queried by op 0x1cc, maintained from ReadTextSkip + per-PC read history |
 | `0x9b24c` | `dispatch_table` | `void*` | opcode->handler table base [0x400]; handler(op) = *(0x9b24c + op*4) |
 | `0xa0cc0` | `screen_w` | `int` | screen width (640) |
 | `0xa0cc4` | `screen_h` | `int` | screen height (480) |

docs/engine-re.md

@@ -515,9 +515,10 @@ Op `0x234` is the independent rotation cycle above. Op `0x238` still configures
 ##### `label_1235a` animation-section boundary (2026-07-10)
 
 The section helper computes the maximum configured duration and arms it with `0x238`, then reads
-message-skip through `0x1c7` and ADV service state through `0x1cc`. Normal playback (both zero)
-executes `0x243` (reset the separate global animation-service clock) followed by `0x20c` present;
-the skip/service branch executes `0x21c` (set run-state bit `0x400`). Both branches finish with
+message-skip through `0x1c7` and ADV read/click-skip state through `0x1cc`. The raw `jcc` order matters:
+normal playback (both zero) branches to `0x21c` (set run-state bit `0x400`), while a nonzero skip/read
+state executes `0x243` (reset the separate global animation-service clock) followed by `0x20c` present.
+Both branches finish with
 `0x224`, which clears the native gfx command queue at `ctx+0x418`. These handlers are now named,
 commented, and saved in the Ghidra image.
 
@@ -805,8 +806,33 @@ into the target and ramps alpha 0→1. Its SC0000 site `0x129e7` passes `(handle
 handle+1,1,handle,1,G[0x6249f],G[0x624a0])`. It remains a render-target/transition slice dependency rather
 than being approximated in the affine object compositor.
 
+#### ADV foreground surface-transition lifecycle (2026-07-10)
+
+The completed native chain is `0x21d` snapshot -> `0x223` queue -> `label_1235a` skip queries ->
+`0x21c` normal yield or `0x20c` skip endpoint-present:
+
+- `gfx_object_clone` (`0x47e4f0`, op `0x21d` handler `0x423310`) copies the complete retained-object
+  record: exactly `0xb5` dwords / `0x2d4` bytes. SC0000 `0x128fc` clones the current CG handle to
+  `handle+1`; the loader then rebinds the source handle to the new CG, and `0x223 @ 0x129e7` uses
+  `handle+1` as old range A, the updated handle as new range B, and `handle+2` as the target presenter.
+- `0x1c7` is the `run_state_flags & 0x08000000` message-skip query. `0x1cc` reads
+  `ctx+0x6dbd4`, now named `adv_read_skip_state`; `adv_refresh_read_skip_state` (`0x406cd0`) and the
+  text/label/wait handlers maintain it from `message_ReadTextSkip` plus per-PC read history. It is not
+  surface-transition progress.
+- Zero OR-state is normal playback and reaches `0x21c`; run-state bit `0x400` parks interpreter
+  progression while the type-0 surface command advances from the frame clock. Nonzero skip/read state
+  reaches `0x243 + 0x20c`, exposing the completed endpoint without the normal wait.
+- Op `0x203` stores operand 2 at object `+0x30`. Transition sources use mode 2; their common
+  `0xffffffff` color is opaque identity modulation, not a solid-white tint. Negative alpha/RGB operands
+  separately preserve the corresponding byte(s) of current static color via the `FUN_0047f3e0` lookup.
+
+The port mirrors this with an explicit pending/start/progress/natural-or-forced-complete state. A click
+while `0x21c` is parked completes only the active foreground surface transition and is consumed; it does
+not pre-arm the following `wait-for-input`, and it does not complete independent retained rotation,
+matrix, spritesheet, or color-animation channels.
+
 **Still deferred:** `0x236` (`gfx_op_0x236` @`0x423ee0`) a
-**timed/animated-surface (movie-like) op**; plus the unclassified `0x21c/0x21d/0x224/0x242/0x23d/0x20a/0x20e/0x243`
+**timed/animated-surface (movie-like) op**; plus the unclassified `0x242/0x23d/0x20a/0x20e`
 tail (2-arg flags / inline). These stay GAP until a follow-up slice or are safe-noop'd if the opening tolerates it.
 
 ### Grey-background root cause — slot collision + tint-strength (2026-07-08, gfx-log)

docs/opcode-reference.md

@@ -79,15 +79,20 @@ Native handler sleep_op_0xc8 @0x420ec0 is NON-BLOCKING: it arms a timer (sleep_t
 - **grounding:** source=investigation, confidence=med
 - **evidence:** Ghidra: handler 0x4299c0 (dispatch ctx[0x9b74c]=0x4299c0; created+typed EngineCtx*+annotated; Kelebek u0041F9C0 = VA-drift). Writes gfx cmd-type 9; op2→local_204, op3→local_104, op4→local_208; (*DAT_005c6018)(8, ctx[0x54fe8], &local_210) → FUN_00425fb0(1,ret). DAT_005c6018: 6 xrefs all READ, no static writer; FUN_00405740 (screen-fade) calls it w/ cmd 3, branches on ret 1/2 = transition progress = native video service.
 
-### 0x1cc `get-adv-service-state` (get-adv-service-state, argc 1)
-- **summary:** (out) - copy native ADV service state ctx+0x6dbd4; label_1235a ORs it with message-skip to select its yield branch.
+### 0x1cc `get-adv-read-skip-state` (get-adv-read-skip-state, argc 1)
+- **summary:** (out) - copy the current ADV read/click-skip service state from ctx+0x6dbd4. label_1235a ORs it with 0x1c7's Ctrl/message-skip bit: zero takes 0x21c's normal transition/yield path; nonzero resets the animation service and presents the completed endpoint through 0x20c.
 - **grounding:** source=investigation, confidence=high
-- **evidence:** Ghidra handler 0x427330 calls vm_operand_write(1, ctx+0x6dbd4). Exact service-state producer remains outside this opcode.
+- **depended on by:** 0x20c, 0x20d, 0x21c, 0x223
+- **evidence:** Ghidra handler 0x427330 calls vm_operand_write(1, ctx+0x6dbd4). Producer recovered 2026-07-10: adv_update_read_text_skip_state@0x406cd0 and op 0x6e/0x71/0x72 maintain the field from message_ReadTextSkip plus current-PC read-history lookup; adv_interpreter_tick consumes it in click/read-skip control. It is not the 0x223 surface-transition progress flag.
 
 ### 0x21c `mark-frame-yield` (mark-frame-yield, argc 0)
-- **summary:** Set native run-state bit 0x400. Host-implicit: the port already offers a scheduler yield after every completed opcode.
-- **grounding:** source=investigation, confidence=high, noop_headless=True
-- **evidence:** Ghidra handler 0x417520 sets cmd-type 1 and ORs ctx+0xa0ce4 with 0x400. SC0000 label_1235a reaches it only when op 0x1c7 or 0x1cc is nonzero.
+- **summary:** Set native run-state bit 0x400; in normal ADV playback this is the queued foreground-transition yield/resume boundary.
+- **grounding:** source=investigation, confidence=high
+- **depends on:** 0x223, 0x1c7, 0x1cc
+- **depended on by:** 0x223
+- **evidence:** Ghidra handler 0x417520 sets cmd-type 1 and ORs ctx+0xa0ce4 with 0x400. SC0000 label_1235a's jcc reaches it when the OR of op 0x1c7/0x1cc is zero; synchronized port trace confirmed this is the normal path after 0x223.
+
+SC0000 label_1235a reaches this when the OR of 0x1c7 message-skip and 0x1cc read-skip state is zero (normal playback). Native run-state bit 0x400 yields the interpreter while the queued foreground presentation advances. The interactive port starts pending 0x223 commands here, parks only the VM thread while per-frame compositing continues, and resumes after natural or click-forced completion.
 
 ## draw
 
@@ -132,9 +137,9 @@ Native handler sleep_op_0xc8 @0x420ec0 is NON-BLOCKING: it arms a timer (sleep_t
 - **evidence:** Ghidra handler 0x4228d0 (dispatch ctx[0x26c93+0x202]); packs (alpha<<24|rgb) from operands 4/5, FUN_0047ea00(op1,op2,op3,packed).
 
 ### 0x203 `gfx-draw-color` (gfx-draw-color, argc 4)
-- **summary:** 0x203 (handle)(v)(alpha)(color) — gfx cmd-type 9. Handler gfx_op_0x203_draw_color @0x4229a0: worker gfx_op_0x203_worker_set_color @0x47e9b0 sets a STATIC color/alpha (obj+0x60), no anim bit; packs ARGB from alpha(op3)/color(op4). Sibling of 0x202 (one fewer positional arg). C# VM (2026-07-08 blend slice): routes through GfxState.SetObjectColor → compositor applies static alpha/tint (BlendKind.Alpha). See docs/engine-re.md §Blend & transparency.
+- **summary:** 0x203 (handle)(mode)(alpha)(color) — gfx cmd-type 9. Worker stores mode at obj+0x30 and STATIC packed color at obj+0x60. Negative alpha/RGB preserve current static bytes through FUN_0047f3e0. Mode 2 is the 0x223 transition-source alpha/identity path (0xffffffff = opaque identity, not solid white); mode 0 retains the established tint-strength behavior.
 - **grounding:** source=investigation, confidence=high
-- **evidence:** Ghidra handler 0x4229a0 (dispatch ctx[0x26c93+0x203]); packs color from operands 3/4, FUN_0047e9b0(op1,op2,packed).
+- **evidence:** Ghidra handler 0x4229a0 (dispatch ctx[0x26c93+0x203]); negative operands read current obj+0x60 via FUN_0047f3e0, then gfx_op_0x203_worker_set_color stores op2 at obj+0x30 and packed ARGB at obj+0x60. SC0000 transition setup uses mode 2 with -1/-1 before 0x21d/0x223; synchronized window pixels prove treating 0xffffffff as generic white tint is wrong.
 
 ### 0x208 `get-texture-size` (get-texture-size, argc 3)
 - **summary:** 0x208 (slot)(out_w)(out_h) — writes the loaded texture's width/height into two output globals; keystone for bytecode-computed sprite/bg geometry (SC0000 label_12649)
@@ -142,11 +147,13 @@ Native handler sleep_op_0xc8 @0x420ec0 is NON-BLOCKING: it arms a timer (sleep_t
 - **evidence:** SC0000 label_12649: set-texture(resId,slot) then 0x208(slot)->w,h feeds w/2 horizontal-center + foot-anchor subtraction into draw-texture dst; stubbing yields 0x0 sizes / off-center draws
 
 ### 0x20c `present-frame` (present-frame, argc 0)
-- **summary:** Present the composited frame (native gfx_render_frame). Host-implicit: our compositor presents every frame.
-- **grounding:** source=investigation, confidence=high, noop_headless=True
+- **summary:** Present the composited frame; label_1235a uses this on the read/message-skip branch to expose the completed foreground endpoint immediately.
+- **grounding:** source=investigation, confidence=high
+- **depends on:** 0x223, 0x1c7, 0x1cc
+- **depended on by:** 0x20d, 0x223
 - **evidence:** Ghidra: dispatch table FUN_00413860 param_1[0x26e9f]=gfx_op_0x20c_present_frame; 0x26e9f-0x26c93=0x20c. 2026-07-08.
 
-Native handler gfx_op_0x20c_present_frame (dispatch ctx[0x26c93+0x20c]) -> gfx_render_frame @0x4820b0 flips the composited buffers. Our Godot host runs a continuous per-frame compositor (Main.Recomposite in _Process), so an explicit present is redundant and the VM can skip it. noop_headless=true -> scene coverage classifies it safe-noop. Kelebek label u00416200 was VA-drift (unrelated fn); real handler resolved via the dispatch table.
+Native handler gfx_op_0x20c_present_frame (dispatch ctx[0x26c93+0x20c]) -> gfx_render_frame @0x4820b0. Godot composites continuously. In label_1235a the OR of 0x1c7/0x1cc is nonzero on the read/message-skip branch, which resets the animation service then presents; the port starts and snaps any pending 0x223 transition to its endpoint here. Normal zero-state playback branches to 0x21c, which owns wait/resume. Headless hosts remain non-blocking. Kelebek label u00416200 was VA-drift.
 
 ### 0x212 `set-gfx-field64` (set-gfx-field64, argc 2)
 - **summary:** 0x212 (obj_idx)(val) — gfx cmd-type 5. Handler gfx_op_0x212_set_field64 @0x4230c0: obj=[ctx+0x14d54 + obj_idx*4]; if obj: *(obj+0x64)=val. Sets one per-object field. See docs/engine-re.md gfx op-contract table.
@@ -188,6 +195,12 @@ Native handler gfx_op_0x20c_present_frame (dispatch ctx[0x26c93+0x20c]) -> gfx_r
 - **grounding:** source=investigation, confidence=high
 - **evidence:** Ghidra handler 0x42a1b0; FUN_0047f2e0(obj op1) + 3x→FUN_00425fb0(2/3/4). label_12649 site 0x00c86 handle=G[0x62457] → G[0x62498/9/a].
 
+### 0x21d `clone-gfx-object` (clone-gfx-object, argc 2)
+- **summary:** (source_handle)(destination_handle) - clone the complete retained gfx object record (0xb5 dwords / 0x2d4 bytes). SC0000 uses destination=source+1 as range A's old-frame snapshot immediately before 0x223 crossfades range B's updated source into target handle source+2.
+- **grounding:** source=investigation, confidence=high
+- **depends on:** 0x223
+- **evidence:** Ghidra handler 0x423310 -> gfx_object_clone@0x47e4f0. Worker requires source in ctx+0x408 map, creates destination, copies exactly 0xb5 dwords from source object record, then marks ctx+0xb558 dirty. SC0000 site 0x128fc passes current handle and handle+1 before queueing 0x223 at 0x129e7.
+
 ### 0x21e `set-anim-transform-norm` (set-anim-transform-norm, argc 6)
 - **summary:** (handle)(delay_ms)(duration_ms)(sx)(sy)(sz) — set the normalized SCALE-matrix channel (100=identity). Target obj+0xac is linearly sampled from current obj+0x6c by gfx_object_apply_transform_channels@0x472f00 on frame-time ctx+0xb550, after delay and for duration, then committed. Shares only start timestamp obj+0x34 with op 0x220; neither Z is opacity.
 - **grounding:** source=investigation, confidence=high
@@ -206,6 +219,8 @@ Native handler gfx_op_0x20c_present_frame (dispatch ctx[0x26c93+0x20c]) -> gfx_r
 ### 0x223 `queue-surface-alpha-transition` (queue-surface-alpha-transition, argc 8)
 - **summary:** (command_key)(target_slot)(range_a_start)(range_a_count)(range_b_start)(range_b_count)(delay_ms)(duration_ms) — queue a type-0 timed alpha transition command in the separate ctx+0x414 command map. This is render-target/surface presentation state, not an object affine matrix. The render frame composites the two handle ranges into target_slot and ramps alpha 0->1 after delay over duration.
 - **grounding:** source=investigation, confidence=high
+- **depends on:** 0x20c, 0x21c, 0x1c7, 0x1cc
+- **depended on by:** 0x20c, 0x21c, 0x21d
 - **evidence:** Ghidra handler 0x423620 -> gfx_queue_surface_alpha_transition@0x47f440. Record fields: type +0=0, start +4=0, delay +8=arg7, duration +0xc=arg8, slot +0x10=arg2, range A +0x14/+0x1c=args3/4, range B +0x18/+0x20=args5/6. gfx_render_frame@0x47fbc0 initializes start from ctx+0xb550 and consumes type 0 as an alpha ramp. SC0000 executes one shared-helper site at 0x129e7.
 
 ### 0x224 `clear-gfx-command-queue` (clear-gfx-command-queue, argc 0)
@@ -286,6 +301,7 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 ### 0x1c7 `get-message-skip` (get-message-skip, argc 1)
 - **summary:** (out) - write 1 iff ADV message-skip run-state bit 0x08000000 is set, otherwise 0.
 - **grounding:** source=investigation, confidence=high
+- **depended on by:** 0x20c, 0x20d, 0x21c, 0x223
 - **evidence:** Ghidra handler 0x4272b0 reads ctx+0xa0ce4 bit 0x08000000 and vm_operand_write(1, 1|0). SC0000 label_1235a ORs it with op 0x1cc.
 
 ## marker
@@ -988,6 +1004,7 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 ### 0x20d `u00420E10` (u00420E10, argc 1)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low
+- **depends on:** 0x20c, 0x1c7, 0x1cc
 
 ### 0x20e `u00416250` (u00416250, argc 0)
 - **summary:** —
@@ -997,10 +1014,6 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it "
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low
 
-### 0x21d `u00421410` (u00421410, argc 2)
-- **summary:** —
-- **grounding:** source=kelebek, confidence=low
-
 ### 0x222 `u004216C0` (u004216C0, argc 2)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

docs/phase-a-slice-plan.md

@@ -895,3 +895,47 @@ and composite call order; named useful parameters; saved `/v2`.
 apart from the pre-existing nullable warning and threaded `SELFTEST OK`; opcode tooling and focused Python
 tests clean; transform tool compiles; SC0000 coverage **81/129 handled (62.8%)**, 48 GAP ops / 602 GAP
 instructions; windowed affine capture clean. Final whitespace/diff validation is recorded with the handoff.
+
+### A2b — ADV foreground transition/click lifecycle ✅ DONE (2026-07-10)
+
+**Native recovery and control-flow correction.** `0x1c7` is the message-skip run-state query.
+`0x1cc` reads `ctx+0x6dbd4`, now `adv_read_skip_state`; `adv_refresh_read_skip_state@0x406cd0` plus the
+text/label/wait handlers maintain it from `message_ReadTextSkip` and the current-PC read-history lookup.
+It is not surface progress. The earlier reading of `label_1235a`'s branch was reversed: zero OR-state
+(normal playback) reaches `0x21c` and sets scheduler bit `0x400`; nonzero skip/read state reaches
+`0x243 + 0x20c` to present the endpoint. Synchronized execution caught and corrected this before validation.
+
+The executed missing producer for `0x223` range A was `0x21d`: `gfx_object_clone@0x47e4f0` copies the full
+`0x2d4`-byte retained-object record from the current CG handle to `handle+1`. SC0000 then rebinds the source
+handle to the new CG and queues `0x223` with old clone range A, new source range B, and target presenter
+`handle+2`. Op `0x203` mode 2 is the companion transition-source alpha/identity path; its `0xffffffff`
+is opaque identity, not generic solid-white tint, and negative alpha/RGB preserve current static bytes.
+
+**Port lifecycle.** `GfxState` owns explicit queue/start/wall-clock progress/natural-or-forced completion.
+Normal `0x21c` parks only the VM thread until the foreground command completes while Godot continues
+per-frame compositing. A click during that wait forces only the foreground transition to progress 1, is
+consumed, and resumes the VM; stable `wait-for-input` remains a separate gate. Tests verify that forcing a
+transition leaves an independent cyclic retained rotation active. The `0x20c` skip/read path starts and
+snaps a pending foreground transition to its endpoint without the normal wait.
+
+**Synchronized window evidence.** At normal speed, the second-to-third CG transition produced seven
+successive distinct PNG hashes while progress advanced `0.133, 0.297, 0.442, 0.592, 0.742, 0.891, 1.000`;
+the user independently observed that fade working in the live window. A timed click landed at progress
+`0.157`, the next frame was the endpoint, and the stable page count did not advance. The accelerated
+windowed run reached `BGM008 @ 0x1728` on frame 137 with non-white changing pixels (2,469 sampled colors at
+the sentinel) and continued; its earlier white interval was finite and released before that boundary.
+This is windowed pixel/object/timeline evidence, not the earlier headless reachability inference.
+
+The retained dialogue-text surface `0xe678` still has no pixels because native `draw-string 0x204` remains
+a separate GAP; the Godot `Label` shortcut remains outside this slice. Its create/erase events are explicit
+in the object timeline and are not being mistaken for foreground CG transition correctness.
+
+**Ghidra.** Renamed/commented `adv_refresh_read_skip_state` (`0x406cd0`),
+`op_0x1cc_get_adv_read_skip_state` (`0x427330`), `op_0x21d_clone_gfx_object` (`0x423310`), and
+`gfx_object_clone` (`0x47e4f0`); added `EngineCtx.adv_read_skip_state`; saved `/v2`.
+
+**Validation:** engine **102/102**; full sweep unchanged at **284 exit / 13 STEP-LIMIT**; Godot build clean
+apart from the pre-existing nullable warning and threaded `SELFTEST OK`; all six Python test scripts,
+opcode/ctx lint, 481-script decode validation, RECOVER, and Windows CR-aware `git diff --check` clean.
+The plain check reports only the generated reference's CRLF on its newly added row. SC0000 coverage is
+**85/129 handled (65.9%)**, 44 GAP ops / 598 GAP instructions. No commit was made.

docs/tools-reference.md

@@ -139,6 +139,7 @@ texture ops (no GPU context) — run windowed for real scenes. User args (after
 - `--gfx-log <file>` — **compositor + op diagnostic** (the tool that root-caused the grey background). Logs, per rendered frame, only the objects whose draw outcome **CHANGED** (drawn↔skip↔gone, resId, resolved file, `slot`, `src`/`dst`, `op`acity, `tintStr`ength) — quiet until something actually changes, so the exact frame a layer drops out (and why) stands out. Also traces every `set-texture`/`create-texture` **slot assignment** (via `GodotAdvHost.TraceOps`). Works live or with `--shot-sequence`. Use it before theorising about layering/blend/geometry: it showed the grey BG = the slot-selecting globals resolving to 0 → every texture collapsing into slot 0 (see engine-re.md §"Grey-background root cause"). e.g. `godot --path godot -- --boot --gfx-log out/gfx.log` then click to the bad page.
   Matrix-channel outcomes also include `base`, `anchor`, projected `dst`, sampled `scale`/`trans`, and
   one-shot-plus-cyclic `rot`ation angles. Parent directories are created automatically.
+- `--transition-click-ms <n>` — diagnostic-only input injector: after a foreground transition has been active for `n` virtual milliseconds, send one click through the real input lifecycle. The click completes/consumes the transition and does not advance a stable page. Use with `--timeline-log`, `--gfx-log`, and windowed `--shot-sequence`; omit for normal play.
 - `--timeline-log <jsonl>` — diagnostic-only synchronized event stream for a real Godot run. Records every
   executed script byte offset/opcode, virtual time/frame, VM state changes (`running`, `sleep`, `input-wait`,
   `halted`), BGM events, and changed visible-object compositor outcomes in one ordered JSONL file. Combine with