Implement native ADV retained text

docs/engine-re.md

@@ -923,6 +923,45 @@ NOT the predicted coroutine yield (`0x140`/`~0x50f`); the oracle reports whateve
 surfaced an earlier state hole. **This is now the repeatable way to localize a mis-modeled op/state.**
 Phase-2 extension (deferred): effects-diff (global-bank / gfx-registry writes) for branchy scenes.
 
+### ADV retained text — ops `0x7a` / `0x204` and show-text publication (2026-07-10)
+
+The SC0000 textbox uses two related native paths under the text manager at `ctx+0x14940`:
+
+- **Op `0x7a` (`op_0x7a_handler@0x41eba0`) is `set-adv-text-cursor(layoutSlot,x,y)`.**
+  `adv_text_set_cursor@0x4530f0` treats slot 0 as the current slot at manager `+0x4c8`, resolves
+  `manager+0x414[slot]`, and `text_layout_set_cursor@0x452530` writes x/y to `+4/+8` of that
+  layout's last 20-byte record. SC0000 `0x9d3` and `0xbbf` set slot 1 to `(75,47)` for voiced
+  pages. The reset narration record is `(100,47,720,147,0)`.
+- **Op `0x204` (`op_0x204_handler@0x422a60`) is immediate `draw-string(surface,x,y,string)`.**
+  `draw_string_to_surface@0x450150` locks the numbered D3D surface, selects the uncached or cached/effect
+  raster worker, consumes CP932 characters through GDI `GetGlyphOutlineA`, blends the bitmap in
+  `text_blit_glyph_bitmap@0x458c80`, and unlocks. Font/color/effect state is retained around manager
+  `+0x450/+0x458/+0x4d0/+0x544/+0x558`; the observed ADV glyph is white with a one-pixel `0x606060`
+  outline and advances 25 pixels. At SC0000 `0x9b2`, surface 13 is 400x30 and receives `"魔王"` at
+  `(1,1)`; the following `0x1fb` binds it to retained object `0xe678` at `(74,444)`, so the name begins
+  at screen `(75,445)`.
+
+Show-text (`0x6e`) is the timed companion, not an immediate Label write. `adv_text_build_glyph_records`
+`@0x4576c0` measures and rasterizes the complete CP932 line into one 20-byte record per glyph. Layout slot
+1 has origin `(0,430)`, bounds `(720,147)`, reveal handle base `55000` (`0xd6d8`), and source surface
+`slot+0x14 = 21`. `adv_text_publish_next_glyph@0x451220` advances the reveal index and publishes each
+record with `gfx_object_bind_draw`. Native SC0000 records `ctx+0x14e9c = 50 ms`: page 1 builds 13 records
+at `0x834`, then publishes them one at a time before reaching wait `0x83c`. A click during reveal completes
+the remaining records and is consumed; the next click releases the stable wait.
+
+The port retains the SC0000-visible contract without exposing thousands of individual host glyph objects:
+surface strings remain associated with blank surface slots for later retained-object binding, while ADV
+lines retain cursor/origin, start time, visible-glyph count, and completion state. The compositor renders
+the surface-13 name at the bound `0xe678` transform and the dialogue at origin+cursor. `ShowText` parks the
+VM until the 50 ms/glyph service completes or a click forces completion, so the completion click cannot
+pre-arm the following `wait-for-input`. Local/global string-pointer operand tags (8/14) are now resolved by
+the VM, which is required for SC0000's `lookup-array local-string-ptr -> draw-string` name path.
+
+Matching evidence: `build/native-adv-text-trace.jsonl` and Godot timeline captures at `0x834`, `0x9b2`,
+`0x9d3`, and `0xa0d`. Windowed page-1 pixels place glyphs at x=100 and native y=477; voiced page 7 has
+non-overlapping name/dialogue bands at y=447–468, 478–500, and 507–530. A manual run progressed 14 pages:
+11 clicks completed active reveals and 14 later clicks released 14 distinct waits through `0xe0c`.
+
 ### Scene-entry state snapshot — auto-seeding single-scene runs (2026-07-09)
 
 **Problem the oracle surfaced:** single-scene VM runs diverge from the engine because they lack the

docs/opcode-reference.md

@@ -5,10 +5,15 @@
 
 ## adv
 
-### 0x7a `text-param?` (u0041AD70, argc 3)
-- **summary:** 3 args (imm/computed/imm); sub computes a value then 0x7a then show-text — text speed/wait/window param
-- **grounding:** source=inference, confidence=med
-- **evidence:** confirm via frida
+### 0x7a `set-adv-text-cursor` (set-adv-text-cursor, argc 3)
+- **summary:** (layout_slot)(x)(y) - set the cursor in the selected ADV text layout's last 20-byte record. Slot 0 selects the current layout.
+- **grounding:** source=investigation, confidence=high
+- **evidence:** Ghidra /v2: op_0x7a_handler@0x41eba0 fetches operands 3,2,1 and calls adv_text_set_cursor@0x4530f0 on text manager ctx+0x14940. Slot 0 resolves manager+0x4c8; manager+0x414[slot] selects the layout; text_layout_set_cursor@0x452530 writes x/y to +4/+8 of its last 0x14-byte record. SC0000 0x9d3 computes slot 1, x=75, y=47 before voiced show-text.
+
+### 0x204 `draw-string` (draw-string, argc 4)
+- **summary:** (surface_slot)(x)(y)(string) - rasterize a CP932 string immediately into a numbered graphics surface using current font/color/effect state.
+- **grounding:** source=investigation, confidence=high
+- **evidence:** Ghidra /v2: op_0x204_handler@0x422a60 resolves operand 4 as a string, fetches surface/x/y, then calls draw_string_to_surface@0x450150 on text manager ctx+0x14940. The worker validates and locks gfx-manager surface table +0xa590[slot], chooses text_raster_string_uncached@0x459d90 or cached/effect path @0x45b600, rasterizes GDI GetGlyphOutlineA bitmaps through text_blit_glyph_bitmap@0x458c80 using font/color state +0x4d0/+0x458, then unlocks. SC0000 0x9b2 draws the speaker name into 400x30 surface 0xd at (1,1); following 0x1fb binds it to retained object 0xe678 at (74,444).
 
 ## audio
 
@@ -981,10 +986,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
 
-### 0x204 `draw-string` (draw-string, argc 4)
-- **summary:** —
-- **grounding:** source=kelebek, confidence=med
-
 ### 0x205 `u00420A60` (u00420A60, argc 6)
 - **summary:** —
 - **grounding:** source=kelebek, confidence=low

docs/phase-a-slice-plan.md

@@ -1016,3 +1016,36 @@ threaded `SELFTEST OK`; all seven Python suites, opcode/ctx lint, 481-script dec
 Normal-speed windowed capture wrote 220 PNGs and progressed through the complete AE sequence; at the target
 frame, bind + mode-1 + `0x202` setup share one VM frame and the first published object state is mode 1.
 Ghidra `/v2` comments were updated and saved. This slice was committed as `85fc07d`.
+
+### A2b — native ADV retained text (`0x7a` / `0x204`) ✅ DONE (2026-07-10)
+
+The prerequisite input check passed before text work: the unmodified port reached page-1
+`wait-for-input@0x83c` in about 2.0 seconds and a manual run released 14 consecutive waits through page 15.
+Clicks were independently healthy, so no scheduler/input workaround was folded into this slice.
+
+Native `/v2` dispatch resolves `0x7a` to `op_0x7a_handler@0x41eba0` and `0x204` to
+`op_0x204_handler@0x422a60`. Op `0x7a` selects layout slot 1 and writes the last 20-byte record's cursor;
+SC0000 voiced pages compute `(75,47)`, while narration resets to `(100,47)`. Layout origin is `(0,430)`,
+bounds are `(720,147)`, retained glyph handles begin at `0xd6d8`, and glyph source surface is 21.
+Op `0x204` locks a numbered D3D surface and GDI-rasterizes its CP932 string with retained font/color/effect
+state. SC0000 `0x9b2` draws `"魔王"` to 400x30 surface 13 at `(1,1)`; `0x1fb@0x9bb` binds that surface to
+object `0xe678` at `(74,444)`. Show-text builds all glyph records, then publishes one every 50 ms; a click
+completes and consumes an active reveal before the VM can reach the following stable wait.
+
+The port now handles both opcodes and string-pointer types 8/14. Blank-surface text is retained by slot and
+drawn through the bound object's transform (the SC0000 speaker-name path), while ADV text retains cursor,
+origin, 50 ms/glyph progress, and forced completion. The prior top-left dev Label/status presentation is
+gone. Page-1 window pixels show the black 800x227 textbox with text at native `(100,477)`; voiced page 7
+has separate name/dialogue bands at y=447–468, 478–500, and 507–530. Final manual validation progressed
+14 pages, with 11 completion clicks consumed during reveal and 14 later clicks releasing 14 waits.
+
+Ghidra `/v2` was renamed/commented throughout the handler, layout, raster, surface-lock, and publication
+chain and saved. The new low-frequency `capture_adv_text_trace.py` records matching native offsets/state;
+an initial experimental version combining a D3D device scan with hot per-glyph/render hooks crashed in
+`frida-agent.dll` at teardown, so those hooks were removed and the safe narrowed rerun left AGE alive.
+
+**Validation:** engine **110/110**; corpus sweep unchanged at **284 exit / 13 STEP-LIMIT**; Godot build
+clean apart from the pre-existing nullable warning and threaded `SELFTEST OK`; all seven Python suites,
+opcode/ctx lint, 481-script decode, RECOVER, and `git diff --check` clean. SC0000 coverage rises from
+**85/129 to 87/129 handled (67.4%)**, with 42 GAP ops / 188 GAP instructions. Movie `0x236` and SFX remain
+separate slices. No implementation commit was made.

docs/tools-reference.md

@@ -178,6 +178,7 @@ texture ops (no GPU context) — run windowed for real scenes. User args (after
 | `tools/frida/capture_global_writes.py` | **Scene-entry state capture** → auto-seed for single-scene runs (`docs/engine-re.md` "Scene-entry state snapshot"). Hooks `vm_operand_write@0x425fb0` and logs `(codebase, index, PLAINTEXT value)` for global-ints (the helper sees the value before the obfuscated store — no de-obfuscation needed). **`--spawn` captures from boot** (packer-aware: polls until `0x425fb0` unpacks, then attaches; kills the spawned pid on setup failure so no suspended orphan). `--attach` = partial (misses pre-attach writes). Validated: a real boot→New-Game→SC0000 capture seeds the VM to match the engine's whole opening. | `py -3.11 -u -X utf8 tools/frida/capture_global_writes.py --spawn [secs]` | running/spawned game → `build/global-writes.jsonl` (raw) + `build/scene-entry-state.json` (GameSession snapshot) |
 
 | `tools/frida/capture_presentation_trace.py` | **Retained-state presentation trace:** correlates the current script offset with native draw/color writes, object composition, surface-command consumption, `gfx_render_frame`, queue clear, and D3D9 Present count. Read-only; distinguishes live retained state from state actually published to the window. | `py -3.11 -u -X utf8 tools/frida/capture_presentation_trace.py [secs] [pid\|AGE.EXE]` | native game → `build/native-presentation-trace.jsonl` |
+| `tools/frida/capture_adv_text_trace.py` | **ADV text trace:** correlates SC offsets with op `0x6e`/`0x7a`/`0x204`, layout cursor/origin and 20-byte record counts, CP932 strings, surface draw/bind, and timed glyph-record publication. Read-only and deliberately limited to low-frequency known handlers; the first experimental version's D3D scan plus hot per-glyph/render hooks crashed in `frida-agent.dll` during teardown and was removed. | `py -3.11 -u -X utf8 tools/frida/capture_adv_text_trace.py [secs] [pid\|AGE.EXE]` | native game → `build/native-adv-text-trace.jsonl` |
 
 *(Static disassembly of `build/engine-dump/range_00400000.bin` uses **capstone** — `py -3.11 -m pip install capstone`; VA `X` → file offset `X−0x400000`.)*