acdream/docs/research/2026-06-08-indoor-flap-edgeon-vs-camera-position-handoff.md

HANDOFF — Indoor crossing flap: MEASURED vs HYPOTHESIS vs OPEN (read before ANY code)

Date: 2026-06-08 (late). Branch: claude/thirsty-goldberg-51bb9b. HEAD: the docs(render): plan status commit (after c7069cf). Working tree clean.

---

⚠️ 0. CALIBRATION NOTE — read this first

This session's diagnosis of the indoor flap shifted four times as measurements came in: per-building → camera-jitter (R-A4) → camera swept/published eye → flood edge-on. Each "confident" claim was refuted by the NEXT measurement, in the same session. The author (me) also stated a final scoreboard ("conclusively pinned / camera ruled out") with more confidence than the data earns.

So this handoff is structured to prevent the next session from inheriting an overclaim:

• §2 = MEASURED (high confidence, with the data + file refs).
• §3 = LEADING HYPOTHESIS (medium — explicitly NOT isolated).
• §4 = ALTERNATIVE NOT RULED OUT (a real competing explanation I waved away).
• §5 = WHAT TO VERIFY FIRST — do this BEFORE building anything. Do not trust §3 until §5 confirms it.
• §6 = DO-NOT (genuinely refuted, high confidence — safe to not re-try).

The honest one-liner: the flap is a motion-time grey-flash at openings; eye-jitter-at-rest is ruled out (measured); but whether the cause is the clip math at edge-on (§3) or the camera not pulling the eye in like retail (§4) is NOT yet disambiguated — the one "clean" pass wasn't clean enough (it had back-and-forth). Disambiguate (§5) before choosing the fix.

---

1. What SHIPPED this session (all green, visual-confirmed by the user)

Commit	What	Verified
7fe9809	R-A1 — canonicalize outdoor root on LoadedCell.IsOutdoorNode (behavior-preserving)	tests
c62663d	R-A2 — per-building floods (ConstructViewBuilding; OutdoorCellNode portal-less; per-building merge in RetailPViewRenderer.DrawInside)	user: outside-looking-in flap GONE
2ec189c	R-A2 seam fix — flood null-BuildingId cells (don't drop)	user: missing textures GONE
3c178b2	tools/cdb/flap-cam-measure.cdb — retail eye + CameraManager capture	apparatus
c7069cf	[flap-sweep] probe: F6 in=(desiredEye) / out=(eye)	apparatus
docs…	plan-doc STATUS note (R-A4 ruled out)	docs

Test baseline: App ~Rendering 207, Core PlayerMovementControllerTests 14. Build green. Plan: docs/superpowers/plans/2026-06-08-full-retail-render-port-option-a.md.

The user's remaining symptom (verbatim): "grey background color flapping entrances between rooms and cellar entrance and when going outside." I.e., the clear/background color flashes through openings during MOTION; at rest it does not flap.

---

2. MEASURED FACTS (high confidence — data + file refs)

2.1 acdream eye at REST ≈ 1 µm stable (NOT a jitter problem)

flap-cam-measure.log (acdream run, user held completely still, 768 samples). Last 150 frames: in (desiredEye) Y range 0.000 mm (1 distinct value); out (eye) Y range 0.001 mm (2 distinct); pulledIn=0. → The convergence snap (RetailChaseCamera.ApplyConvergenceSnap, SnapEpsilon 0.0004) holds; there is no at-rest jitter. (acdream at rest is actually steadier than retail's settled eye.)

2.2 The earlier "~1.3 mm jitter at rest" was MOTION misread as rest

launch-flap-pin2.log [pv-input] showed ~1.3 mm; that was during the crossing. The F2-precision print rounded sub-cm walking to "d=0", which I mis-analyzed as a static eye. The flap is motion-time only.

2.3 On a (mostly) one-way pass: eye SMOOTH, but visible-cell count OSCILLATES

launch-camprobe.log, the clean-pass tail (~25.7k sweep frames):

• Eye: 3D path = 34.1 m, net = 8.2 m (ratio 4.2×), direction reversals X=3, Y=18 (i.e. few large direction changes — the motion is smooth, not jittery).
• Visible cells ([flap] vis=): oscillated 414× between 1 and 6; 648 clip=0 events. Distribution 1:4084 2:6300 3:3860 4:10634 5:439 6:427. Roots: 0171 (room) 21396, 0031 (outdoor) 4084, others tiny.
• ⚠️ CAVEAT (why this is NOT isolated): ratio 4.2× means the pass was not purely one-way — it had back-and-forth + indoor↔outdoor. The 414 oscillations therefore mix (a) indoor-flood oscillation (root 0171, vis 2↔6) AND (b) indoor↔outdoor root swaps (0171↔0031, the "going outside" grey; the 4084 vis=1 frames are root 0031 = legitimately just the outdoor node). These were not separated. So "smooth eye + oscillating vis ⇒ flood bug" is indicated but not proven — some of the oscillation is the back-and-forth and the root-swap.

2.4 Retail eye at the cottage doorway: COLLIDED 93%, settled jitter ~tens of µm

flap-cam-measure.log (retail, acclient.exe, PDB MATCH refs/acclient.pdb), 768 samples:

• pub != sought 716/768 = 93% COLLIDED — retail's boom hits the cottage; the eye is pulled toward the player (a more head-on view of the doorway, not floating 3 m back).
• Settled jitter (quarters Q2–Q4) ≈ 93 µm; Q1's 1.4 mm was the user walking up (settling motion), verified by the quarter split.
• Offsets: CameraManager.t_stiffness@+0x08, r_stiffness@+0x0c, viewer_offset@+0x48; SmartBox.camera_manager@+0xa0. acdream's damping already matches retail's formula (alpha = clamp(stiffness·dt·10,0,1), stiffness 0.45) — RetailChaseCamera.ComputeDampingAlpha.

---

3. LEADING HYPOTHESIS (medium confidence — NOT isolated; see §2.3 caveat)

The flood/clip's "is the room behind this opening visible?" decision is non-monotonic near a doorway's EDGE-ON angle. The portal projects to an on-screen area that hovers at ~zero (coin-on-edge); small smooth eye steps flip the clip 0↔nonzero → the cell behind drops → grey flash. This matches the "grey at room↔room / cellar entrances." Mechanism candidates inside this hypothesis: ProjectToClip / ClipToRegion collapsing at edge-on (PortalProjection.cs), and/or the band-aids MaxReprocessPerCell (D4) + EyeInsidePortalOpening (D5) re-processing differently frame-to-frame during motion.

---

4. ALTERNATIVE NOT RULED OUT (a real competing explanation)

The edge-on viewing might be a CONSEQUENCE of the camera not pulling the eye in like retail. §2.4: retail's eye is collided 93% (head-on); acdream's [flap-sweep] showed it uncollided much more often (floats free, 3 m back → edge-on view of the doorway). A doorway viewed edge-on is exactly when the clip collapses. So the root cause could be camera collision / eye position (acdream's spring-arm not pulling in where retail's does), NOT the clip math.

• What IS ruled out: eye-jitter / wobble / at-rest instability (§2.1, §2.3 — smooth + 1 µm).
• What is NOT ruled out: eye position (collision pull-in). These are different. I conflated them in the scoreboard. Disambiguate in §5.2.
• Separately, the "going outside" grey is the root 0171↔0031 wholesale swap (§2.3) — likely a distinct sub-issue (indoor↔outdoor root transition), not the same as the room↔room edge-on flap.

---

5. VERIFY FIRST — before building ANY fix (this is the anti-overclaim gate)

1. Isolate pure indoor-flood oscillation. Do a genuinely one-way, slow walk through ONE interior doorway (room→room), no going outside, no back-and-forth, camera fixed. Capture ACDREAM_PROBE_FLAP=1. Confirm whether vis (root 0171 only) oscillates 2↔6 for a monotonic eye (check [flap-sweep] out= is monotonic — ratio ≈ 1, ~0 reversals). If it does NOT oscillate when the eye is truly monotonic → the flap was the back-and-forth / root-swap, not a flood bug (then §3 is wrong). The clean pass in §2.3 had ratio 4.2× — not clean enough to conclude.
2. Disambiguate clip-math (§3) vs camera-position (§4). At the SAME interior doorway, measure acdream's eye-to-doorway angle vs retail's (collided) — is acdream viewing it edge-on where retail views it head-on (because retail's eye is pulled in)? Add the doorway-plane signed distance + the collide state to [flap-sweep]. If acdream floats edge-on where retail pulls in → the fix is the camera collision, not the flood.
3. Read retail's edge-on clip handling (the fix ORACLE — do NOT guess the fix without this): PView::GetClip (0x5a4320, decomp ~:432344), PView::ClipPortals (0x5a5520, :433572), ACRender::polyClipFinish (the w=0 clip, :702749). Questions: does retail's clip collapse to zero at edge-on like ours, or stay robust? Does retail keep a flooded cell once added? Cross-check PortalProjection.cs (our port — handoff says it's faithful; verify at edge-on specifically).

---

6. DO-NOT RETRY (genuinely refuted this session — high confidence)

• Camera eye-JITTER / R-A4 stiffness change. Eye is smooth (3/18 reversals) + 1 µm at rest (§2.1, §2.3). acdream's damping already matches retail's stiffness 0.45. Do not "reduce jitter."
• RenderPosition rest-snap (cd974b2, reverted). The eye isn't the jitter source; at rest it's 1 µm.
• "1.3 mm jitter at rest" — it was MOTION (§2.2).
• A robust-MEMBERSHIP scheme retail lacks. Retail's flood is clip-driven too — PView::add_views (0x5a5210) only pre-pushes view slices onto the stab_list cells via curr_view_push; it does NOT ground cell_draw_list membership. So the robustness must live in the clip's edge-on behavior (§3) or the camera position (§4), NOT a stab_list membership-grounding.
• Two-pipe inside/outside split; bounded-propagation/churn; byte-stable eye — all refuted earlier (see the 2026-06-08 OPTION-A handoff §7).

---

7. The fix (R-A2b) — GATED on §5

Do NOT design until §5 disambiguates. Two branches:

• If §5.1 + §5.3 show the clip collapses at edge-on (clip-math): port retail's edge-on clip robustness into PortalProjection / PortalVisibilityBuilder; conformance-test "smooth monotonic eye through a doorway ⇒ monotonic vis (no oscillation)"; visual-gate.
• If §5.2 shows acdream's eye floats edge-on where retail pulls in (camera-position): the fix is the camera collision (PhysicsCameraCollisionProbe.SweepEye / RetailChaseCamera) — make the eye pull in like retail (93% collided at the doorway). This is the camera position, distinct from the ruled-out eye-jitter.
• The "going outside" grey (§4, root 0171↔0031 swap) is likely a separate, smaller task.

---

8. Apparatus (reuse — don't rebuild)

• acdream probes (gated in AcDream.Core.Rendering.RenderingDiagnostics):
  • ACDREAM_PROBE_FLAP=1 → [flap] (per-portal D/side-test TRV/CULL/clip= vertex count, vis=), [flap-sweep] (camera sweep: pulledIn, and in=(desiredEye) / out=(eye) at F6 — added c7069cf), [flap-cam]. HEAVY (per-frame per-portal) — short captures only.
  • ACDREAM_PROBE_PVINPUT=1 → [pv-input] (eye/player/rawPlayer F6 + flood count). Lighter.
• cdb on retail: tools/cdb/flap-cam-measure.cdb (eye origin per frame pub+sought raw float hex + CameraManager/SmartBox type dumps). Attach: Get-Process acclient → pid; cdb.exe -p <pid> -cf tools\cdb\flap-cam-measure.cdb. Exit code 5 is expected (clean detach). PDB refs/acclient.pdb — verify with py tools/pdb-extract/check_exe_pdb.py "C:/Turbine/Asheron's Call/acclient.exe" (MATCH).
• Logs (UNTRACKED, large — gitignore/delete): launch-camprobe.log, launch-flap-pin2.log, flap-cam-measure.log, launch-ra2.log.
• Launch: CLAUDE.md "Running the client" env block + $env:ACDREAM_PROBE_FLAP="1".
• Build-while-client-running gotcha: the running client locks the DLLs → build fails MSB3027. Close the client (graceful CloseMainWindow) before building.

---

9. Exact pickup (next session)

1. Read this doc top-to-bottom, then memory project_indoor_flap_rootcause (2026-06-08 late CORRECTION).
2. git log --oneline -8 (HEAD = the plan-status docs commit). dotnet build green; App ~Rendering 207 / Core PlayerMovementControllerTests 14 green.
3. Do §5 FIRST (isolate indoor-flood vs camera-position vs root-swap). Do NOT write a fix until §5 tells you which of §3 / §4 is real. This is the whole point of the calibration note.
4. Then §5.3 (retail clip oracle) → design the gated fix (§7) → conformance-test PRE-gate → visual-gate.
5. Strip the throwaway probes after the visual gate; update memory + the plan + milestones.

---

10. One-paragraph version (for when you're tired)

Outside-flap and seams are FIXED and confirmed. The indoor flap is a motion-time grey-flash at openings. We MEASURED that it's not eye-jitter (eye is smooth + 1 µm at rest). We did NOT prove it's the clip math: the one "clean" pass had back-and-forth (ratio 4.2×) so the 414 oscillations mix flood-edge-on, back-and-forth, and indoor↔outdoor root-swaps. And we did NOT rule out the camera position (retail's eye is pulled-in/head-on 93% at the doorway; ours floats edge-on). So: isolate a truly one-way single interior-doorway pass, compare acdream's vs retail's eye angle at that doorway, and read retail's edge-on clip code — THEN choose between the clip-math fix and the camera-position fix. Don't pick one until those three are done.