docs: handoff — fold in retail teleport-anim (TAS) flow + acdream gap analysis for the teleport-flow feature

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/research/2026-06-21-teleport-issues-handoff.md

@@ -62,12 +62,44 @@ input + camera, **waits for the world to load**, then exits/places the player. U
 faithful retail teleport flow (anim + input/camera lock + **hold-until-loaded** + single exit point) fixes the
 float, the timing, the input-lock, **and very likely Work item A.** This is the keystone.
 
-**This is a FEATURE → start with `superpowers:brainstorming`** (the user is the retail oracle on look/feel).
+**This is a FEATURE → resume `superpowers:brainstorming`** (user is the retail oracle on look/feel). The
-**Research first:** grep `docs/research/named-retail/acclient_2013_pseudo_c.txt` for the portal/teleport flow
+3-agent research (workflow `wf_61501a7a-1d4`) is DONE — findings below. **Extend acdream's machinery, don't
-— the teleport animation, the loading hold, the PortalSpace exit condition, and the unified path for
+rebuild.**
-login/logout/death/portal. **Extend, don't rebuild:** acdream already has `PlayerState.PortalSpace`,
+
-`TeleportArrivalController`, and `TeleportArrivalRules.Decide` (`src/AcDream.App/World/` + `GameWindow`); the
+### RETAIL flow (decomp-verified) — `gmSmartBoxUI` teleport **animation state machine**
-flow should slot the anim + hold-until-loaded into that machinery.
+
+`TeleportAnimState` enum (`acclient.h:6871`): the client plays a **fade + portal-tunnel animation that COVERS
+the world-load wait** — used by ALL of login / logout / death / portal:
+
+```
+TAS_OFF(0) → WORLD_FADE_OUT(1, ~1s) → TUNNEL_FADE_IN(2, ~1s) → TUNNEL(3 = HOLD for world load)
+          → TUNNEL_CONTINUE(4, min ~2s) → TUNNEL_FADE_OUT(5, ~1s) → WORLD_FADE_IN(6, ~1s) → OFF
+```
+- State machine: `gmSmartBoxUI::UseTime` (pc 219400); begin `BeginTeleportAnimation` (218888); end `EndTeleportAnimation` (218994).
+- **The world-load HOLD** is `TAS_TUNNEL(3)`, gated on `SmartBox::teleport_in_progress` (pc 90815) = `(player != 0) && (position_update_complete == 0)`; `position_update_complete` flips to 1 when the **DDD interrogation / position update** completes → animation advances. **This is the "exit when the world has loaded" the user wants.**
+- **Input lock:** `PlayerModule::SetLockUI` sets bit `0x1000000` in `options2_` (pc 486713) for the whole animation; cleared at `TAS_OFF`.
+- **Unification:** **death + logout share** the flow via `logOffRequested`; **login** enters via `RecvNotice_BeginEnterWorld`; **portal** starts directly at `TAS_TUNNEL` (skips the fade-out). Sounds: `Sound_UI_EnterPortal`(0x6A) / `ExitPortal`(0x6B). Exit callback `SendLoginCompleteNotification` (pc 367516).
+- Missing from decomp: exact `TELEPORT_ANIM_FADE_TIME` / `MIN_CONTINUE_TIME` constants; the DDD code that sets `position_update_complete`.
+
+### acdream TODAY — what exists, what's missing
+
+acdream ALREADY has the *skeleton*: `PlayerState.PortalSpace` **input lock** (`PlayerMovementController.cs:840-854`)
++ a **hold-until-readiness** controller (`TeleportArrivalController.cs:56-105`; `GameWindow.OnTeleportStarted`
+:5487, `OnLivePositionUpdated`/`BeginArrival` :5394, `PlaceTeleportArrival` :5443-5478, readiness :5419-5439).
+
+**The gaps (the actual work):**
+1. **NO animation / visual cover.** During the hold the camera is frozen at the OLD spot, then `PlaceTeleportArrival` **snaps** both cameras (`:5464-5469`, no fade/lerp). That snap + the world streaming in *is* the "floating" the user dislikes. → **Build a client teleport-anim state machine (TAS-shaped: fade-out → tunnel/hold → fade-in) that covers the wait.**
+2. **Readiness gate is too weak → this is the #145 residual.** Outdoor readiness gates on `SampleTerrainZ != null` (`:5436`) — terrain heightmap can sample BEFORE the collision **landblock cells** load, so the player is placed onto a `branch=NO-LANDBLOCK` world → the unstreamed-arrival cascade + Z free-fall (Work item A). → **Gate on the full landblock being loaded** (`teleport_in_progress`-equivalent). **Fixing this likely closes Work item A.**
+3. **`yaw` still updates during the hold** (`MouseLook` not frozen, gotcha) — lock it too.
+4. **Login / logout / death NOT unified.** Login uses inline auto-entry guards (`:1036-1065`) that DUPLICATE teleport's readiness (`:5419-5439`) + recenter (`:2874-2881` vs `:5364-5370`). **Logout does not exist; death only feeds `Chat.OnPlayerKilled` (`:2569`), no game effect.** → Route all four through one arrival/anim controller; de-dupe readiness + recenter.
+
+### Design direction (for the brainstorm)
+
+Build a **client-side teleport animation + arrival controller** (port the TAS state machine shape) layered on
+the existing PortalSpace lock + TeleportArrivalController hold: (a) a fade/tunnel **visual cover** over the
+world-load wait (kills the float); (b) **strengthen the readiness gate** to the full landblock (kills the #145
+residual + the Z free-fall); (c) **unify** login/logout/death/portal entry points + de-dupe the readiness/recenter
+logic; (d) tune timing so it doesn't feel longer than retail (the current 600-frame/10s timeout is the worst case).
 
 ---