feat(render): Phase U.4 — unified gated draw pass (indoor root)

Wire the portal-visibility result through the clip pipeline: build a per-frame
ClipFrame (slot 0 no-clip, slot 1 OutsideView, slot 2..N per visible cell) +
cellIdToSlot from PortalVisibilityBuilder; call the (previously dormant)
EnvCellRenderer.Render for cell shells inside the clip bracket; assign per-instance
clip slots in WbDrawDispatcher (live-dynamic unclipped per retail, cell statics to
their cell slot, outdoor scenery to OutsideView, non-visible culled); gate/scissor/
skip terrain per OutsideView (empty ⇒ no terrain — the bleed fix). Emit ACDREAM_PROBE_VIS.

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

src/AcDream.App/Rendering/ClipFrameAssembler.cs

@@ -0,0 +1,222 @@
+// ClipFrameAssembler.cs
+//
+// Phase U.4: assemble a per-frame ClipFrame (the GPU-side shared clip data) +
+// a cellId→slot map from a PortalVisibilityFrame. This is the CPU policy that
+// turns the portal-visibility BFS result into the slot indices the mesh shader
+// (binding=2 CellClip + binding=3 per-instance slot) and the terrain UBO read.
+//
+// GL-free: ClipFrame's CPU byte-packing (AppendSlot / SetTerrainClip) runs here;
+// the GL upload (ClipFrame.UploadShared) happens at the call site. That keeps the
+// whole slot/gate policy unit-testable without a GPU context — see
+// ClipFrameAssemblerTests.
+//
+// === The slot/gate policy (implemented EXACTLY as the U.4 spec dictates) ======
+// slot 0 = no-clip (count 0). ALWAYS present (ClipFrame.NoClip seeds it).
+//
+// Per visible interior cell (PortalVisibilityFrame.OrderedVisibleCells):
+//   ClipPlaneSet.From(CellView) has THREE Count==0 meanings (see ClipPlaneSet):
+//     • IsNothingVisible  ⇒ DO NOT map the cell. Its instances/shell won't draw
+//                           (the cull is deliberate — retail culls it too).
+//     • Count > 0         ⇒ append a real planes slot; cellIdToSlot[cell] = slot.
+//     • UseScissorFallback⇒ cellIdToSlot[cell] = 0 (no-clip / over-include).
+//                           Per-cell glScissor would break MDI batching, and
+//                           over-inclusion is the SAFE direction; counted in
+//                           ScissorFallbacks for the probe.
+//
+// OutsideView feeds TWO consumers:
+//   • mesh "outdoor slot" (outdoor scenery / building shells drawn while the
+//     camera is indoors): Count>0 ⇒ planes slot (OutdoorSlot); scissor ⇒ slot 0
+//     (no-clip, counted); IsNothingVisible ⇒ OutdoorVisible=false (CULL these
+//     instances — the camera can't see outdoors through any portal chain).
+//   • terrain UBO: Count>0 ⇒ SetTerrainClip(planes); scissor ⇒ TerrainScissor
+//     (the call site sets glScissor around ONLY the terrain draw) + UBO count 0;
+//     IsNothingVisible ⇒ SKIP the terrain draw entirely (THIS is the bleed fix).
+//
+// Outdoor root (pvFrame == null) is handled by the caller, not here: terrain
+// draws normally (UBO count 0, no scissor), every instance is slot 0. The caller
+// only invokes Assemble when there IS an indoor root.
+using System.Collections.Generic;
+using System.Numerics;
+
+namespace AcDream.App.Rendering;
+
+/// <summary>
+/// How the terrain (single OutsideView region) should be drawn this frame.
+/// </summary>
+public enum TerrainClipMode
+{
+    /// <summary>OutsideView reduced to convex planes — terrain gated via the UBO
+    /// (<see cref="ClipFrame.SetTerrainClip"/> already applied by the assembler).</summary>
+    Planes,
+
+    /// <summary>OutsideView exceeded the convex budget — the call site sets a
+    /// glScissor to <see cref="ClipFrameAssembly.TerrainScissorNdcAabb"/> around ONLY
+    /// the terrain draw; the UBO is left at count 0 (ungated).</summary>
+    Scissor,
+
+    /// <summary>OutsideView is empty (no exit portal visible through any chain) —
+    /// the call site SKIPS the terrain draw entirely. This is the bleed fix: an
+    /// interior with no view outdoors draws no terrain.</summary>
+    Skip,
+}
+
+/// <summary>
+/// Result of <see cref="ClipFrameAssembler.Assemble"/>: the populated
+/// <see cref="ClipFrame"/> (CPU bytes ready; caller does <c>UploadShared</c>) plus
+/// the per-instance routing data the renderers + the terrain draw consume.
+/// </summary>
+public sealed class ClipFrameAssembly
+{
+    /// <summary>The per-frame clip data. Caller uploads it via
+    /// <see cref="ClipFrame.UploadShared"/> then hands its
+    /// <see cref="ClipFrame.RegionSsbo"/> / <see cref="ClipFrame.TerrainUbo"/> to the
+    /// renderers.</summary>
+    public required ClipFrame Frame { get; init; }
+
+    /// <summary>Maps a visible cell id to its CellClip slot index. A cell that is
+    /// NOT a key (IsNothingVisible, or never visible) must NOT be drawn — its mesh
+    /// instances / shell are culled. A scissor-fallback cell maps to slot 0.</summary>
+    public required Dictionary<uint, int> CellIdToSlot { get; init; }
+
+    /// <summary>Slot for outdoor scenery / building-shell instances (ParentCellId
+    /// == null) while the camera is indoors. Meaningful only when
+    /// <see cref="OutdoorVisible"/> is true. 0 ⇒ no-clip (scissor fallback or trivial).</summary>
+    public required int OutdoorSlot { get; init; }
+
+    /// <summary>False ⇒ the OutsideView is empty; outdoor scenery / shells are
+    /// CULLED this frame (camera sees no outdoors through any portal chain).</summary>
+    public required bool OutdoorVisible { get; init; }
+
+    /// <summary>How to draw terrain (planes already applied to the UBO / scissor /
+    /// skip). See <see cref="TerrainClipMode"/>.</summary>
+    public required TerrainClipMode TerrainMode { get; init; }
+
+    /// <summary>NDC AABB (minX,minY,maxX,maxY) for the terrain glScissor when
+    /// <see cref="TerrainMode"/> is <see cref="TerrainClipMode.Scissor"/>. Unused otherwise.</summary>
+    public required Vector4 TerrainScissorNdcAabb { get; init; }
+
+    // ---- Probe data (ACDREAM_PROBE_VIS / RenderingDiagnostics.EmitVis) --------
+
+    /// <summary>Plane count the OutsideView reduced to (0 ⇒ scissor or empty).</summary>
+    public required int OutsidePlaneCount { get; init; }
+
+    /// <summary>Per-cell clip-plane count (cell id → plane count) for the probe.
+    /// A scissor-fallback cell records 0 here (it maps to slot 0).</summary>
+    public required Dictionary<uint, int> PerCellPlaneCounts { get; init; }
+
+    /// <summary>Number of regions (cells + OutsideView) that fell back to a scissor
+    /// AABB → no-clip this frame.</summary>
+    public required int ScissorFallbacks { get; init; }
+}
+
+/// <summary>
+/// Builds a <see cref="ClipFrameAssembly"/> from a <see cref="PortalVisibilityFrame"/>.
+/// Pure CPU; no GL. The single entry point <see cref="Assemble"/> implements the U.4
+/// slot/gate policy (file header).
+/// </summary>
+public static class ClipFrameAssembler
+{
+    /// <summary>
+    /// Assemble the per-frame clip data + routing from a portal-visibility frame
+    /// INTO an existing <see cref="ClipFrame"/> — the long-lived GameWindow frame is
+    /// <see cref="ClipFrame.Reset"/>-and-repacked here every frame so its GL buffers
+    /// are reused (no per-frame buffer churn). The returned assembly's
+    /// <see cref="ClipFrameAssembly.Frame"/> is the same instance passed in.
+    /// </summary>
+    public static ClipFrameAssembly Assemble(ClipFrame frame, PortalVisibilityFrame pvFrame)
+    {
+        System.ArgumentNullException.ThrowIfNull(frame);
+        System.ArgumentNullException.ThrowIfNull(pvFrame);
+
+        frame.Reset();                               // slot 0 = no-clip
+        var cellIdToSlot = new Dictionary<uint, int>();
+        var perCellPlaneCounts = new Dictionary<uint, int>();
+        int scissorFallbacks = 0;
+
+        // ── Interior cells ───────────────────────────────────────────────────
+        foreach (uint cellId in pvFrame.OrderedVisibleCells)
+        {
+            if (!pvFrame.CellViews.TryGetValue(cellId, out var view))
+                continue; // defensive — OrderedVisibleCells is derived from CellViews
+
+            var cps = ClipPlaneSet.From(view);
+
+            if (cps.IsNothingVisible)
+            {
+                // Cell culled — do NOT map it; its instances/shell won't draw.
+                continue;
+            }
+            if (cps.Count > 0)
+            {
+                int slot = frame.AppendSlot(cps);
+                cellIdToSlot[cellId] = slot;
+                perCellPlaneCounts[cellId] = cps.Count;
+            }
+            else // UseScissorFallback (Count == 0, not nothing-visible)
+            {
+                // Over-include via no-clip (slot 0). Per-cell glScissor would break
+                // MDI batching; over-inclusion is the safe direction for M1.5.
+                cellIdToSlot[cellId] = 0;
+                perCellPlaneCounts[cellId] = 0;
+                scissorFallbacks++;
+            }
+        }
+
+        // ── OutsideView ──────────────────────────────────────────────────────
+        var ov = ClipPlaneSet.From(pvFrame.OutsideView);
+
+        int outdoorSlot;
+        bool outdoorVisible;
+        TerrainClipMode terrainMode;
+        Vector4 terrainScissor = Vector4.Zero;
+
+        if (ov.IsNothingVisible)
+        {
+            // No outdoors visible through any portal chain.
+            outdoorSlot = 0;
+            outdoorVisible = false;     // mesh: CULL outdoor scenery / shells.
+            terrainMode = TerrainClipMode.Skip; // terrain: the bleed fix.
+        }
+        else if (ov.Count > 0)
+        {
+            // Convex planes — gate both the outdoor mesh slot and the terrain UBO.
+            outdoorSlot = frame.AppendSlot(ov);
+            outdoorVisible = true;
+            frame.SetTerrainClip(ToPlaneSpan(ov));
+            terrainMode = TerrainClipMode.Planes;
+        }
+        else // UseScissorFallback
+        {
+            // Mesh: no-clip over-include (slot 0), still visible. Terrain: scissor
+            // around the single terrain batch + UBO ungated (count 0 left as-is).
+            outdoorSlot = 0;
+            outdoorVisible = true;
+            terrainMode = TerrainClipMode.Scissor;
+            terrainScissor = ov.ScissorNdcAabb;
+            scissorFallbacks++;
+        }
+
+        return new ClipFrameAssembly
+        {
+            Frame = frame,
+            CellIdToSlot = cellIdToSlot,
+            OutdoorSlot = outdoorSlot,
+            OutdoorVisible = outdoorVisible,
+            TerrainMode = terrainMode,
+            TerrainScissorNdcAabb = terrainScissor,
+            OutsidePlaneCount = ov.Count,
+            PerCellPlaneCounts = perCellPlaneCounts,
+            ScissorFallbacks = scissorFallbacks,
+        };
+    }
+
+    // Copy a ClipPlaneSet's planes into a heap array for SetTerrainClip's span
+    // parameter (the set exposes IReadOnlyList, not a contiguous span).
+    private static Vector4[] ToPlaneSpan(ClipPlaneSet set)
+    {
+        int n = set.Count;
+        var planes = new Vector4[n];
+        for (int i = 0; i < n; i++) planes[i] = set.Planes[i];
+        return planes;
+    }
+}