fix(render): clip portal projection against frustum side planes (clip-space)

ProjectToNdc clipped only the eye half-space (w>MinW, a 2026-06-03 workaround) and left the 4 frustum side planes to the 2D ScreenPolygonClip. When the eye is within a portal's near plane, small-w verts explode under the perspective divide (probe saw NDC (10.2,-67.4)); the 2D clip then collapses to empty -> OutsideView empty -> terrain Skip -> the bluish doorway void. Clip the eye plane + 4 side planes (homogeneous Sutherland-Hodgman) before the divide so NDC is bounded to the screen by construction, matching retail GetClip -> polyClipFinish (clip in clip-space before the divide; pc:432344).

Partial: NOT the full flicker fix. The dominant cause (camera boom drift + viewer-cell flip at boundaries + missing w=0 near-plane clip) is identified and deferred to the next session per the handoff. 2 RED->GREEN tests.

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

src/AcDream.App/Rendering/PortalProjection.cs

@@ -1,9 +1,11 @@
 // PortalProjection.cs
 //
-// Phase A8.F: project a cell-local portal polygon to NDC screen space, clipping against the
+// Phase A8.F: project a cell-local portal polygon to NDC screen space. Homogeneous frustum clip
-// IN-FRONT-OF-EYE half-space (keep where w > MinW) so a portal straddling the camera does not
+// in CLIP SPACE (before the perspective divide): first the IN-FRONT-OF-EYE half-space (keep where
-// invert under the perspective divide, and the divide stays bounded away from the w=0 eye
+// w > MinW) so a portal straddling the camera does not invert under the divide and the divide
-// singularity.
+// stays bounded away from the w=0 eye singularity, then the 4 SIDE planes (x,y within ±w) so every
+// surviving vertex lands on the screen [-1,1] by construction. The side-plane clip is the R1
+// void-flap fix (2026-06-05) — see ProjectToNdc.
 //
 // The clip is NEAR-INDEPENDENT on purpose. We only use the projected x/y for the visibility clip
 // REGION, so a vertex in front of the eye is meaningful even if it is closer than the projection's
@@ -38,10 +40,24 @@ public static class PortalProjection
         foreach (var lp in localPoly)
             clip.Add(Vector4.Transform(new Vector4(lp, 1f), m));
 
-        // Clip against the in-front-of-eye half-space (keep where w > MinW). Near-independent:
+        // Homogeneous frustum clip in CLIP SPACE, before the perspective divide. First the
-        // see the file header — clipping at the projection's near plane culls portals the camera
+        // in-front-of-eye half-space (w > MinW) — near-INDEPENDENT, so a portal the camera is
-        // is standing in (the doorway "void").
+        // standing in still projects (see header); then the 4 SIDE planes (x,y within ±w). The
-        clip = ClipBehindEye(clip);
+        // side clip is the R1 void-flap fix (2026-06-05): without it, a portal WITHIN the near
+        // plane projected small-w verts to wildly off-screen NDC (the probe saw (10.2,-67.4)),
+        // which corrupted the downstream 2D ScreenPolygonClip into an EMPTY region -> OutsideView
+        // empty -> terrain Skip -> the bluish doorway "void". Clipping the side planes here bounds
+        // every surviving vertex to the screen [-1,1] by construction, so a screen-covering doorway
+        // clips to the screen (non-empty) instead of collapsing. The eye plane is clipped FIRST so
+        // all survivors have w > 0, making the side-plane functionals (w ± x, w ± y) well defined.
+        // Near/far are intentionally NOT clipped (near-independence). Retail PView::GetClip
+        // (decomp:0x005a4320) projects + frustum-clips the portal poly likewise (research doc A §3.5).
+        clip = ClipPlane(clip, v => v.W - MinW);   // in front of eye (near-independent)
+        if (clip.Count < 3) return System.Array.Empty<Vector2>();
+        clip = ClipPlane(clip, v => v.W + v.X);    // left:   x/w >= -1  <=>  w + x >= 0
+        clip = ClipPlane(clip, v => v.W - v.X);    // right:  x/w <=  1  <=>  w - x >= 0
+        clip = ClipPlane(clip, v => v.W + v.Y);    // bottom: y/w >= -1  <=>  w + y >= 0
+        clip = ClipPlane(clip, v => v.W - v.Y);    // top:    y/w <=  1  <=>  w - y >= 0
         if (clip.Count < 3) return System.Array.Empty<Vector2>();
 
         // Perspective divide → NDC xy.
@@ -60,16 +76,20 @@ public static class PortalProjection
     // standing in still projects and the cell behind it stays visible. See the file header.
     private const float MinW = 0.05f;
 
-    // Sutherland-Hodgman against the in-front-of-eye half-space: keep where w > MinW.
+    // Sutherland-Hodgman against one half-space of the homogeneous view frustum, in CLIP SPACE.
-    private static List<Vector4> ClipBehindEye(List<Vector4> poly)
+    // `dist` is the signed plane functional (>= 0 keeps the vertex); crossings are interpolated in
+    // homogeneous coords (perspective-correct). Callers apply the eye plane first so every survivor
+    // has w > 0, making the side-plane functionals (w ± x, w ± y) well defined.
+    private static List<Vector4> ClipPlane(List<Vector4> poly, System.Func<Vector4, float> dist)
     {
+        if (poly.Count == 0) return poly;
         var result = new List<Vector4>(poly.Count + 1);
         for (int i = 0; i < poly.Count; i++)
         {
             Vector4 cur = poly[i];
             Vector4 prev = poly[(i + poly.Count - 1) % poly.Count];
-            float dCur = cur.W - MinW;
+            float dCur = dist(cur);
-            float dPrev = prev.W - MinW;
+            float dPrev = dist(prev);
             bool curIn = dCur >= 0f;
             bool prevIn = dPrev >= 0f;
 

tests/AcDream.App.Tests/Rendering/PortalProjectionTests.cs

@@ -86,6 +86,59 @@ public class PortalProjectionTests
         }
     }
 
+    [Fact]
+    public void Project_QuadStraddlingCamera_NdcStaysWithinScreen()
+    {
+        // R1 void-flap fix (2026-06-05): the eye-plane-only clip (w>MinW) let small-w verts
+        // explode under the perspective divide (~±37 NDC). Those off-screen NDC then corrupted
+        // the downstream 2D ScreenPolygonClip, which at glancing/close angles collapsed to EMPTY
+        // -> OutsideView empty -> terrain Skip -> the bluish "void" at the cottage doorway.
+        // Clipping the 4 frustum SIDE planes in clip space (homogeneous, before the divide)
+        // bounds every projected vertex to the screen [-1,1] by construction. RED before the fix.
+        var poly = new[]
+        {
+            new Vector3(-1, -1, 2), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, 2),
+        };
+        var r = PortalProjection.ProjectToNdc(poly, Matrix4x4.Identity, ViewProj());
+        Assert.True(r.Length >= 3);
+        foreach (var v in r)
+        {
+            Assert.InRange(v.X, -1.001f, 1.001f); // bounded to the screen — no off-screen explosion
+            Assert.InRange(v.Y, -1.001f, 1.001f);
+        }
+    }
+
+    [Fact]
+    public void Project_CloseDoorway_NdcStaysWithinScreen_AndCoversScreen()
+    {
+        // The probe-confirmed void frame (2026-06-05): the chase eye is ~0.28 m from the front-door
+        // EXIT portal — well inside RetailChaseCamera's 1.0 m near plane — and looking through it.
+        // The door subtends the whole screen, but the old clip produced NDC like (10.2,-67.4) and
+        // ScreenPolygonClip reduced it to clip=0 (the void). After the homogeneous side-plane clip
+        // the NDC stays on-screen AND the door still covers the viewport (non-empty), not the void.
+        var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY);
+        var proj = Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 1.0f, 5000f); // RetailChaseCamera
+        var viewProj = view * proj;
+
+        // A 2 m x 2 m doorway 0.28 m in front of the eye, facing it.
+        var doorway = new[]
+        {
+            new Vector3(-1f, -1f, -0.28f), new Vector3(1f, -1f, -0.28f),
+            new Vector3(1f,  1f, -0.28f),  new Vector3(-1f, 1f, -0.28f),
+        };
+        var projected = PortalProjection.ProjectToNdc(doorway, Matrix4x4.Identity, viewProj);
+        Assert.True(projected.Length >= 3);
+        foreach (var v in projected)
+        {
+            Assert.InRange(v.X, -1.001f, 1.001f);
+            Assert.InRange(v.Y, -1.001f, 1.001f);
+        }
+
+        var viewport = CellView.FullScreen().Polygons[0].Vertices;
+        var onScreen = ScreenPolygonClip.Intersect(projected, viewport);
+        Assert.True(onScreen.Length >= 3, "a doorway the eye looks through must cover the screen, not collapse to the void");
+    }
+
     [Fact]
     public void Project_PortalEyeIsAlmostTouching_StaysVisibleOnScreen()
     {