# Phase U.4c — flap FIXED (root visibility at the player's cell) + residuals handoff (2026-05-31)

## TL;DR

The **U.4c doorway "flap" is fixed.** Root cause (converged on live evidence, after two wrong
turns): indoor portal visibility was rooted at the **3rd-person camera EYE**, which drifts out of
the player's cell (through interior walls into AABB gaps); `FindCameraCell` then returned a **stale
cell for 3 grace frames**, and from that stale root the doorway portal was culled as "behind" the
eye → the exit cell + terrain + building shells all dropped → grey-void collapse. **Fix
(`0ee328a`):** root indoor visibility (cell resolution + portal-side test) at the **PLAYER's cell**
(retail `CellManager::ChangePosition` tracks `curr_cell` by the player; acdream already roots
lighting at the player for the same chase-cam reason). The eye still drives the per-frame projection.

Visual gate (2026-05-31): the user confirmed **"flap seems gone."** But the gate also revealed the
indoor pipeline is **not yet seamless** — three **separate, largely-known** residuals remain (terrain
not gated inside #78, camera-displacement / camera-collision, U.5). Those are a **broader new scope**
than the flap; user chose to **checkpoint + hand off**. M1.5 "indoor world feels right" needs them.

## The fix that shipped (`0ee328a`)

`GameWindow.OnRender`: introduce `visRootPos = (_playerMode && _playerController is not null) ?
_playerController.Position : camPos`, and feed it to BOTH `_cellVisibility.ComputeVisibility(...)`
and `PortalVisibilityBuilder.Build(clipRoot, visRootPos, …)`. The camera eye (`camPos` /
`envCellViewProj`) still drives the per-frame projection and `_envCellRenderer.PrepareRenderBatches`
frustum/render cull. Removed the earlier synthetic builder flap test (it modeled the disproven
side-test hypothesis; the fix is integration-level). App tests 151/151. Two-stage Opus review: clean
(no Critical/Important; downstream-consumer audit — sky/weather/fog/sun/entity-cull/cache — all
internally consistent under player-rooting; `cameraInsideCell` is now a harmless misnomer →
cosmetic rename suggested as a follow-up).

## The hypothesis journey (DO NOT re-walk these — all evidence-disproven)

- **H1 (PVS / stab_list grounding)** — the spec's leading hypothesis. The live evidence showed the
  flap is a *root* problem, not a *set-membership* problem; force-keeping cells would diverge from
  retail's walk-reached `cell_draw_list`. The Layer-1 data (`LoadedCell.VisibleCells` + `SeenOutside`,
  `639f20f`) was plumbed and is harmless/available but is NOT what fixed the flap.
- **H2 (port the dat `PortalSide` into the side test)** — I pivoted here on a raw 0/1 anti-correlation
  in `A8CellAudit`. **DISPROVEN** (`b5f2bf2`): under the `(Flags&2)==0` boolean convention + our normal
  winding, the dat `PortalSide` sense is **byte-identical** to our centroid `InsideSide` at every pose
  — the swap is a literal no-op. The implementer subagent caught this via the real-data validation
  loop and refused to ship the no-op.
- **"eye crosses the plane while inside the cell"** — **REFUTED** (`8941d1e`): `0171`'s local AABB is
  y∈[-7.65,1.15]; the `0171→0170` portal plane is at y=-7.65 (the cell's *min* boundary), so an eye
  genuinely inside `0171` always has side-test D≤0 → always traverses. The eye must be *outside* the
  cell for the cull — i.e. a ROOT problem (grace-stale), confirmed by the moving capture.

The decisive apparatus was `ACDREAM_PROBE_FLAP` (per-frame `[flap]`/`[flap-cam]` lines): flap frames
were uniformly `res=Grace eyeInRoot=n terrain=Skip`; good frames `eyeInRoot=Y`. See
`docs/research/2026-05-31-u4c-flap-characterization.md` (top banner = the converged reading).

## Residuals revealed at the visual gate (the NEXT work — NOT the flap)

User observations (inside a Holtburg cottage, this session's cells `0xA9B40162/0174/0175`) mapped to cause:

1. **"Floor shows outdoor ground / cellar floor transparent / I see the world from below."**
   → **Issue #78 family** (already known; CLAUDE.md flags it: *"outdoor terrain mesh visible inside
   cottage cellars … indoor-cell visibility culling not gating outdoor terrain"*). Terrain isn't
   occluded by the interior. The flap fix made it MORE visible because terrain now draws again (it
   was Skipped during the flap). **Fix direction:** gate outdoor terrain by indoor-cell visibility
   when the camera/player is in a cell — port retail `CEnvCell::find_visible_child_cell`
   (`acclient_2013_pseudo_c.txt:311397`) / the `seen_outside` landscape-keep logic; relate #78, #100
   secondary finding.

2. **"Outer walls transparent when looking out."** → the per-frame clip is projected from the
   **displaced eye** (outside the player's cell **79%** of frames: 3049 `eyeInRoot=n` vs 795 `=Y`).
   The OutsideView over-includes (scissor AABB fallback fired 320×; portals project far off-screen
   e.g. `ndc=(-9.8,0.7)(-9.4,-10.5)`) → terrain bleeds past the window opening. **Fix direction:**
   camera collision — retail `SmartBox::update_viewer` keeps the viewer inside the cell so the clip
   stays consistent (`eyeInRoot` ≈ always Y). Reopens the parked camera scope.

3. **"On the stairs: everything grey, I see doors/NPCs/particles from all around (other houses')."**
   → transition-zone cell resolution on the stairwell (player straddling cells) + the displaced eye
   seeing un-occluded entities. Same camera-displacement + terrain-gating family. (Stairs/cellar is
   the #98-saga area — complex geometry.)

4. **"Outside looking in: no interior walls."** → **U.5** (outdoor-camera → building-interior
   peering), already deferred.

**Net:** M1.5 "indoor world feels right" needs THREE more pieces beyond the flap — **#78 terrain
gating inside**, **camera collision (keep the eye in the player's cell)**, and **U.5**. The
camera-displacement root (residuals 2+3) is the highest-leverage: with the eye constrained to the
player's cell, the eye-projected clips become consistent and both 2 and much of 3 resolve.

## Apparatus (kept — gated/inert when off; available for the residual work)

- **`ACDREAM_PROBE_FLAP=1`** (`RenderingDiagnostics.ProbeFlapEnabled`) — per-frame `[flap]` (root,
  eye, localEye, per-portal D/side/proj/clip/NDC, outPolys, vis) + `[flap-cam]` (res, eyeInRoot,
  eye, player, terrain mode, outdoorVisible). `CellVisibility.LastCameraCellResolution` +
  `CameraCellResolution` enum added. Per-frame (not cell-change-throttled) so it catches flicker at a
  stable root. Throwaway — strip when the residual indoor work is done.
- **`tools/A8CellAudit/Program.cs` `portals` subcommand** — per-portal plane / centroid-`InsideSide`
  / dat `PortalSide` / local AABB / swept-pose O-vs-A-vs-B sense comparison. The tool that disproved
  H2. `PortalFlags.PortalSide = 0x2`, `ExactMatch = 0x1`.

## Commit list (all on `claude/thirsty-goldberg-51bb9b`, UNPUSHED)

```
0ee328a fix(render): U.4c — root indoor visibility at the player's cell (THE FLAP FIX)
8941d1e research: refute eye-crosses-plane; correct stale H2 note (+ AABB dump)
b5f2bf2 research: DISPROVE the side-test fix (PortalSide port is a no-op)
13d58ca research: characterize the flap on real dat evidence
+ probe commits (ProbeFlapEnabled, NDC/clip probe), the spec (31f265d) + plan (211350b),
  Layer-1 data plumbing (639f20f), the RED-apparatus (cd3ffe3, removed in 0ee328a).
```
(Plus the converged-note update + this handoff.)

## Git state
- Branch `claude/thirsty-goldberg-51bb9b`, **UNPUSHED** (push decision pending with the user).
- Two `git stash` entries preserved (#98/#101 WIP) — do NOT drop.

## Next-session pickup prompt
```
U.4c doorway flap is FIXED (commit 0ee328a — root indoor visibility at the player's cell, not the
camera eye; reviewed clean). READ docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md
FIRST. The visual gate revealed three SEPARATE residuals (NOT the flap): (1) #78-family — outdoor
terrain not gated inside (floor shows ground / see world from below); (2) camera displacement —
the chase eye is outside the player's cell 79% of frames so the eye-projected clip over-includes
(transparent outer walls), fixed by camera collision (retail SmartBox::update_viewer keeping the
eye in the cell); (3) U.5 outside-looking-in (deferred). Highest leverage = camera collision (fixes
2 and much of 3). Apparatus ACDREAM_PROBE_FLAP + A8CellAudit are committed + ready. Brainstorm the
camera-collision-vs-terrain-gating ordering before coding. Do NOT re-try H1 (PVS grounding) or H2
(PortalSide side-test) — both evidence-disproven (see the handoff). NO workarounds.
```