acdream/docs/research/2026-06-05-viewer-cell-flicker-rootcause-and-fix-plan-handoff.md

# Handoff — Indoor flicker/void ROOT CAUSE confirmed (decomp + live cdb); 3-part retail-faithful fix planned — 2026-06-05 (PM)

> **Canonical pickup for the next (fix) session. Read this FIRST.** This session did the diagnosis
> the previous "core inside render (R1)" handoff asked for, and it landed somewhere different than that
> handoff predicted. The indoor **bluish void + grey/texture flicker** is NOT a missing per-cell flood
> port — R1's per-cell `DrawInside` is built and the cellar/ceiling seal correctly. The residual is
> **camera/viewer-cell instability at cell boundaries**, confirmed by both the named-retail decomp AND a
> live cdb capture of retail. The fix is a **3-part retail-faithful port** (camera boom stability +
> viewer-cell dead-zone + w-space portal clip), de-risked and ready to plan + implement.
> Branch `claude/thirsty-goldberg-51bb9b`. PowerShell on Windows; launch logs are UTF-16.

---

## 0. TL;DR

- **The premise we started with was stale.** "Cellar floor drops / R1 incomplete" — actually R1's per-cell
  `DrawInside` + binary inversion already exist (commit `c4fd711`, 2026-06-02) and the cellar **is sealed**
  (user visual-verified T1 this session). The flood reaches the cellar; the shell draws.
- **The real bug is two faces of ONE root cause — visibility metastability at cell boundaries:**
  1. **Flicker (grey↔texture) at a "stationary" position** = the **viewer (camera) cell flips per-frame**
     `0170↔0171` because the 3rd-person camera **boom drifts** (`desiredBack 3.11→3.07` while the player
     stands still), walking the eye across a portal plane, and acdream re-resolves the viewer cell fresh
     each frame with **no hysteresis**. The render roots at the viewer cell, so it redraws two different
     solves → flicker.
  2. **Stable bluish void** = when the eye is firmly in/at a thin/transition cell, the portal flood
     **degenerates** because acdream projects-to-NDC-then-2D-clips instead of clipping in clip-space, so a
     close/grazing portal drops (`proj=0`) → no terrain / neighbour not flooded → grey.
- **CONFIRMED by live cdb on retail** (this is the payoff): retail's `viewer_cell` is **rock-stable** at
  the same Holtburg-cottage boundary — clean single monotonic transitions, **zero oscillation** across
  4,916 samples; retail rests the camera in the *substantial* cell, never lingering in the thin doorway
  cell. acdream's `[flap-sweep]` flips `0170↔0171` at the same spot. Retail is stable, acdream is not —
  exactly as the decomp predicted.
- **The fix (3 parts, prioritized) is retail-faithful and anchored to specific decomp functions.** §4.
- **Two partial fixes shipped this session** (`5f596f2` NDC frustum side-plane clip — keep;
  `9f95252` eye-in-portal flood — band-aid, likely superseded → reassess/revert). §3.
- **Test baseline:** App **183 pass / 0 fail** (179 + 4 new). Core **1326 pass / 4 fail (documented) /
  1 skip**. Branch HEAD after this handoff commit. Build green.

---

## 1. The session arc (so you don't repeat it)

1. Read the "core inside render (R1)" handoff. **Discovered R1's inversion + per-cell `DrawInside` already
   exist and are live** (`c4fd711`/`4b75c68`/`cf85ea4`, 2026-06-02; not reverted). So this was a *debug*
   task, not a *port* task.
2. **Visual gate (user):** the cellar (T1) is **sealed**. The real symptoms are at **transitions**: a
   bluish **void flap** exiting the building (screenshot), a **grey flash** cellar→room, **outdoor
   content through the ground** looking out, and a **stationary flicker** (textures alternate grey↔texture
   while standing still).
3. **Evidence-first (probes `ACDREAM_PROBE_FLAP/_VIS/_SHELL/_CELL`):**
   - Refuted the prior handoff's hypothesis ("flood doesn't reach the cellar") — rooted at the room, the
     flood **does** reach the cellar (`[vis] root=0171 ids=[...,0174]`).
   - Found the void is `terrain=Skip` / `proj=0` on exit/interior portals when the eye is close
     (`[flap] p->0xFFFF D=-0.28 proj=4 clip=0`; later `p1->0x0171 D=0.16 proj=0`).
   - Found the **flicker** is the **viewer cell flipping** at a knife-edge boundary: in a held pose the
     `[flap-sweep] viewerCell` flips `0170↔0171` as `D` crosses `0.00`, while the **player stands still**
     and the boom **drifts** (`desiredBack 3.11→3.07`).
4. **Decomp spike (3 parallel agents + 1 verified-myself crux):** mapped how retail stays stable. §2.
5. **Live cdb on retail** (matching v11.4186 binary, PDB-paired): captured retail's `viewer_cell` across
   the same crossings → **clean, no oscillation**. §2.4. Confirms the fix direction.

---

## 2. ROOT CAUSE — retail stays stable via THREE mechanisms; acdream diverges on each

### 2.1 Camera boom is a stable spring (Q3) — `CameraManager::UpdateCamera`
- Retail's boom vector `CameraManager::viewer_offset` (default `y = -2.5 m`) is **fixed** (changes only on
  zoom keys). `UpdateCamera` (≈`0x00456660`, lerp body `0x00456d0d`) lerps the camera *position* toward
  `pivot + viewer_offset` with stiffness, and **snaps to the current position when within 0.0004 m** → holds
  a constant fixed point at rest.
- **The collided eye is firewalled from the desired position:** `set_viewer(…, arg3=0)` (the normal success
  path, `update_viewer` pc≈92870) writes `this->viewer` (rendered eye) but **NOT** `viewer_sought_position`.
  So the collision result never feeds back into the desired boom.
- `PlayerPhysicsUpdatedCallback` (`0x00452d60`, pc:91836) computes `viewer_sought_position = UpdateCamera(current_viewer)`.
- **acdream diverges:** `RetailChaseCamera` desired boom **drifts at rest** (`desiredBack 3.11→3.07`).
  Hypotheses (verify in code): the collided eye is fed back into the desired (no firewall), and/or no
  convergence snap. **This drift is the flicker trigger** (walks the eye across the boundary).

### 2.2 Viewer cell is sticky via a 0.2 mm dead-zone (Q1) — VERIFIED MYSELF
- `SmartBox::update_viewer` (`0x00453ce0`, pc:92761): `viewer_cell = sphere_path.curr_cell` after the
  collision sweep, which **starts from the stable player cell** each frame (`cell_1` = player cell or
  `AdjustPosition`-seated).
- `SPHEREPATH::init_path` (`0x0050ce20`, pc:274370): `curr_cell = arg2` (the start cell).
- The sweep updates the cell only on a **definite** crossing: `check_other_cells` (`0x0050ae50`, pc:272717)
  → `find_cell_list` → `check_cell`; `validate_transition` (`0x0050aa70`) promotes `curr_cell = check_cell`
  (pc:272608) only when the cell/pos actually changed, else **restores `curr_cell`**.
- **The dead-zone (VERIFIED at pc:325513/325522):** `BSPNODE::point_inside_cell_bsp` (`0x0053c1f0`) uses
  `0.000199999995f` (≈0.2 mm) symmetrically — a point within ±0.2 mm of a splitting plane belongs to
  **neither** cell, so at a boundary graze `check_cell` is null and `curr_cell` stays at the start cell.
- **acdream diverges:** `RetailChaseCamera.ViewerCellId = swept.ViewerCellId` is re-resolved fresh **every
  frame** with **no dead-zone** ("graph-tracked, deterministic, NO grace frames" — the comment) → flips at
  the boundary.

### 2.3 Portal clip is homogeneous (w-space), before the divide (Q2) — `GetClip`/`polyClipFinish`
- `PView::GetClip` (`0x005a4320`, pc:432344) projects the portal then calls `ACRender::polyClipFinish`
  (`0x006b6d00`, pc:702749), which **clips against the near plane (w=0) in clip-space, generating synthetic
  edge vertices, BEFORE the perspective divide** — so a close portal never blows up to garbage NDC.
- `PView::InitCell` (`0x005a4b70`, pc:432896) **side-test culls** in-plane/back-facing portals (same 0.2 mm
  band, pc≈432936) before any projection.
- The flood is substantially **root-invariant** for adjacent cells (both seeded full-screen; side-test is
  symmetric).
- **acdream diverges:** projects-to-NDC then 2D-clips → degenerates at grazing/close angles (`proj=0` →
  portal dropped → grey void / neighbour not flooded). This session's commit `5f596f2` added the eye-plane
  + side-plane clip (partial); the missing piece is the **w=0 near-plane clip with synthetic verts** + the
  side-test dead-band.

### 2.4 LIVE CDB CONFIRMATION (retail v11.4186, PDB-paired) — the payoff
Captured `SmartBox::viewer_cell` (`viewer.objcell_id`) at the Holtburg cottage while passing inside↔outside
+ the stairs + standing still. Run-length-encoded camera-cell sequence (4,916 samples):
```
0xa9b40032 ×3360 → 0031 ×173 → 0170 ×8 → 0171 ×134 → 0170 ×14 → 0031 ×129
→ 0170 ×7 → 0171 ×139 → 0170 ×15 → 0031 ×110 → 0170 ×7 → 0171 ×167 → … (clean repeats)
```
- **Every crossing is a clean, single, monotonic pass** (outside `0031/0032` → vestibule `0170` brief
  7–15-sample pass-through → room `0171`, and back). **ZERO `0170↔0171` oscillation** anywhere.
- Standing still, retail rests in the **substantial** cells (room `0171` ×134–197, outside long runs),
  **never lingering in the thin vestibule `0170`**.
- **Contrast acdream:** `[flap-sweep] viewerCell` flips `0170↔0171` per-frame at the same boundary.
- **Conclusion:** retail's viewer cell is stable (boom holds + 0.2 mm dead-zone + sweep-from-player-cell);
  acdream's is not. No surprises — the fix is de-risked.

---

## 3. What shipped this session (committed; partial)

| SHA | What | Keep? |
|---|---|---|
| `5f596f2` | `PortalProjection.ProjectToNdc` clips eye + 4 frustum **side planes** in clip-space before the divide (replaces the 2026-06-03 `MinW`-only workaround). Bounds NDC to the screen. | **KEEP.** Real correctness, retail-consistent (partial of §2.3). |
| `9f95252` | `PortalVisibilityBuilder` floods the neighbour when the eye **stands in** an interior portal (`EyeInsidePortalOpening`). Fixed the cellar **ceiling** (visual-verified). | **REASSESS / likely REVERT.** A coverage band-aid for the thin-cell-root case; the §4 boom + dead-zone keep the camera out of thin cells, and the w=0 clip handles close portals — this may become unnecessary or over-include. Easy `git revert 9f95252`. |

Neither is the flicker fix. Both green (App 183), Core baseline held (1326/4/1).

---

## 4. THE FIX — 3-part retail-faithful port (prioritized). Plan, then implement TDD.

### Part 1 (HIGHEST leverage) — Camera boom stability  → kills the flicker trigger
- **Goal:** acdream's desired boom settles and **holds** at rest (no drift). Match `UpdateCamera`: desired
  position derived each frame from a **fixed** boom offset + the player pivot; **firewall the collided eye**
  out of the desired chain; add the **convergence snap** (return current when within ~0.0004 m).
- **acdream targets:** `src/AcDream.App/Rendering/RetailChaseCamera.cs` (the `_dampedEye` / `desiredBack` /
  the lerp + where the collided `swept.Eye` is consumed). Verify whether `swept.Eye` feeds the next-frame
  desired (the drift hypothesis) and whether a snap exists.
- **Anchors:** `CameraManager::UpdateCamera` `0x00456660` (snap ~`0x00456d0d` region), `PlayerPhysicsUpdatedCallback`
  `0x00452d60` (pc:91836), `set_viewer` arg3=0 firewall (`update_viewer` pc≈92870).
- **Verify:** with the boom stable, the `[flap-sweep] eyeBack/desiredBack` is flat at rest and the eye stops
  grazing the boundary.

### Part 2 — Viewer-cell dead-zone hysteresis  → belt-and-suspenders for the flicker
- **Goal:** acdream's camera-sweep viewer-cell resolution doesn't flip on a sub-mm/boundary graze. Port the
  retail dead-zone: a point within ±0.2 mm of a portal plane belongs to neither cell → keep the prior/start
  (player) cell.
- **acdream targets:** `src/AcDream.App/Rendering/PhysicsCameraCollisionProbe.cs` (`SweepEye`) and the
  Core cell-resolution it calls (`CellTransit.FindVisibleChildCell` / the point-in-cell test). Ensure the
  sweep starts from the player cell and only changes `viewer_cell` on a definite crossing.
- **Anchors:** `point_inside_cell_bsp` `0x0053c1f0` (0.000199999995f, pc:325513/325522), `init_path` pc:274370,
  `validate_transition` pc:272608, `check_other_cells` pc:272717.

### Part 3 — w-space portal clip robustness  → kills the *stable* grey void
- **Goal:** extend `5f596f2` to a true **near-plane (w=0) clip with synthetic edge vertices before the
  divide** + the **InitCell side-test dead-band** that culls in-plane/back-facing portals before projection.
- **acdream targets:** `src/AcDream.App/Rendering/PortalProjection.cs` + `PortalVisibilityBuilder.cs`
  (the side test `CameraOnInteriorSide`). After this, **reassess `9f95252`** (the eye-in-portal flood may be
  redundant → revert).
- **Anchors:** `GetClip` `0x005a4320` (pc:432344), `polyClipFinish` `0x006b6d00` (pc:702749, the w=0 clip),
  `InitCell` `0x005a4b70` (pc:432896 side-test).

**Order:** Part 1 → visual gate → Part 2 → Part 3 → reassess `9f95252`. Each is independently verifiable.

---

## 5. KEEP / DON'T

**KEEP:**
- R1 per-cell `DrawInside` + the binary inversion (`c4fd711`) — built and correct; the cellar seals.
- Residual A (camera collision, `update_viewer` port) — the viewer cell is *accurate*; we're stabilizing it,
  not removing it.
- Commit `5f596f2` (NDC side-plane clip).
- The two-camera-ish reality: eye drives projection; the fix makes the *viewer cell* stable (boom + dead-zone),
  matching retail (`is_player_outside` decides; `DrawInside(viewer_cell)` roots).

**DON'T:**
- Don't re-attempt "the flood doesn't reach the cellar" — refuted (`[vis]` shows it does).
- Don't add a render-side debounce/grace-period for the flicker — it's a **membership/visibility stability**
  bug; fix the *input* (boom + dead-zone), not the render (memory: render-downstream-of-membership).
- Don't switch the render root to the *player* cell — retail roots `DrawInside` at the *viewer* cell; the
  fix is to make the viewer cell *stable*, not to change which cell roots.
- Don't put a `;` inside a cdb `$$` comment (it splits into a command — bit me this session; use `*` comments).

---

## 6. APPARATUS (committed / ready)

- **Probes** (all live): `ACDREAM_PROBE_FLAP` (`[flap]`/`[flap-cam]`/`[flap-sweep]`), `ACDREAM_PROBE_VIS`
  (`[vis]`), `ACDREAM_PROBE_SHELL` (`[shell]`), `ACDREAM_PROBE_CELL` (`[cell-transit]`).
- **cdb script** `tools/cdb/retail-viewer-cell.cdb` — samples retail `SmartBox::viewer_cell` ~6/sec,
  auto-`.detach` after 6000 hits. Binary verified MATCH via `tools/pdb-extract/check_exe_pdb.py`.
  Re-run pattern + RLE analysis are in this session's transcript (PowerShell `Select-String` on
  `retail-viewer-cell.log`). **Lesson:** per-frame bp + `dt`/`.printf` is heavy but survived here (retail
  intact); keep samples sparse. `qd` is ignored in bp actions — use `.detach`.
- **TTD** is available (`tools/ttd-record.ps1` / `tools/ttd-query.ps1`) if a lower-overhead capture is needed.

---

## 7. STATE
- Branch `claude/thirsty-goldberg-51bb9b`. HEAD: this handoff's docs commit (after `9f95252`). No push (ask first).
- Build green. App **183 / 0**. Core **1326 / 4 (documented: 2× DoorBugTrajectoryReplay LiveCompare,
  BSPStepUpTests.D4, DoorCollisionApparatus) / 1 skip**.
- Running the client: see CLAUDE.md "Running the client"; `+Acdream` spawns in the Holtburg cottage.

---

## 8. KICKOFF PROMPT (copy-paste for the next session)

```
Continue acdream M1.5 indoor render: fix the boundary FLICKER + stable bluish VOID with the 3-part
retail-faithful port that the 2026-06-05 spike confirmed. ROOT CAUSE (decomp + live cdb, both done):
the indoor flicker/void is VISIBILITY METASTABILITY at cell boundaries, not a missing flood — R1's
per-cell DrawInside is built and the cellar seals. Retail stays stable via three mechanisms; acdream
diverges on each. Branch claude/thirsty-goldberg-51bb9b (do NOT branch/worktree; do NOT push without
asking; NEVER git stash/gc). PowerShell on Windows; launch logs are UTF-16.

READ FIRST (in order):
1. docs/research/2026-06-05-viewer-cell-flicker-rootcause-and-fix-plan-handoff.md  (THIS handoff — root
   cause §2, cdb confirmation §2.4, the 3-part fix §4, KEEP/DON'T §5).
2. memory: reference_render_pipeline_state.md, feedback_render_downstream_of_membership.md,
   feedback_render_one_gate.md, project_camera_visibility_coupling.md.
3. The decomp anchors cited in §2/§4 (named-retail) for each part you implement.

THE FIX (plan first, then implement TDD; each part independently visual-verified):
  Part 1 (highest leverage) — Camera boom stability (RetailChaseCamera): desired boom settles + HOLDS at
    rest; firewall the collided eye out of the desired chain; add the convergence snap. Anchors:
    CameraManager::UpdateCamera 0x00456660, PlayerPhysicsUpdatedCallback 0x00452d60, set_viewer arg3=0.
  Part 2 — Viewer-cell dead-zone (PhysicsCameraCollisionProbe.SweepEye / Core cell resolution): ±0.2 mm
    dead-zone so a graze keeps the player/start cell. Anchors: point_inside_cell_bsp 0x0053c1f0
    (0.000199999995f), validate_transition pc:272608, init_path pc:274370.
  Part 3 — w-space portal clip (PortalProjection/PortalVisibilityBuilder): near-plane (w=0) clip with
    synthetic verts before the divide + InitCell side-test dead-band; then reassess/revert the
    eye-in-portal flood band-aid (commit 9f95252). Anchors: GetClip 0x005a4320, polyClipFinish 0x006b6d00,
    InitCell 0x005a4b70.

START by using superpowers:writing-plans (or brainstorming if a part's shape is unclear) to turn §4 into a
step plan with per-part acceptance + visual gates, THEN implement Part 1 first via TDD.

DON'T (§5): no render-side debounce for the flicker (fix the boom/cell input); don't switch the render
root to the player cell (retail roots DrawInside at the viewer cell — stabilize it instead); don't reopen
"flood doesn't reach the cellar" (refuted).

TEST BASELINE: App 183 pass / 0 fail. Core 1326 pass / 4 fail (documented) / 1 skip. Build green.
This session committed 5f596f2 (NDC side-plane clip — KEEP) + 9f95252 (eye-in-portal flood — reassess).
```