# Phase U — Unified retail-faithful render pipeline (design spec)

**Status:** design approved 2026-05-30 (brainstorm). Supersedes the abandoned A8/A8.F
two-pipe approach (issue #103).
**Milestone:** M1.5 — "Indoor world feels right."
**Decision context:** [`docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md`](../../research/2026-05-30-unified-render-pipeline-decision-and-handoff.md)

---

## 1. The decision (recap)

acdream inherited a **two-pipe** render structure from WorldBuilder: a normal outdoor
draw plus a separate flat `RenderInsideOut` stencil pass toggled on `cameraInsideBuilding`.
That split is the root cause of every indoor/outdoor seam bug — the "flap", missing /
transparent walls, terrain bleeding into interiors — and it **cannot** be made seamless
(you cannot hand off two pipes cleanly at a doorway). The A8.F effort tried to graft
retail's recursive portal clip *on top of* the two-pipe stencil and failed its visual gate
(#103): the CPU clip math was unit-test-correct, but the integration (one global NDC mask
gating ALL outdoor geometry, with an else-branch that floods terrain when the mask is
empty) is inherently fragile.

**Retail has no such split.** It renders through one portal-visibility traversal (`PView`):
from whatever cell the camera occupies, walk the portal graph, build a screen-space convex
clip region per opening, and draw every visible cell — indoor *and* outdoor — gated by that
region. The camera being indoors vs outdoors selects only *which cell is the root*; the draw
machinery is identical. Seamless **by construction**.

**Phase U builds that.** Modern code, retail behavior.

### Settled design decisions (brainstorm 2026-05-30)

| # | Decision | Choice |
|---|----------|--------|
| Scope | First spec covers how much of `PView` | **Full Phase U in one spec** (indoor BFS + outdoor-camera building peering + dungeon-scale fixpoint termination + distance-priority ordering + reciprocal `OtherPortalClip`). Implemented in staged tasks U.1–U.6 with review/visual checkpoints. |
| Clip gate | How a modern GPU enforces "draw only inside this region" | **Hardware clip planes (`gl_ClipDistance`)** for the exact gate + **scissor AABB** as a cheap broad-phase pre-reject. Mirrors retail's two-level structure (it stores both a per-edge `Plane` and an `xmin/xmax/ymin/ymax` box). Structurally immune to the #103 global-mask-flood. Stencil-per-cell is the documented fallback if clip planes prove insufficient. |
| Terrain | How terrain + outdoor scenery fit | **Separate path, gated (retail-faithful).** `TerrainModernRenderer` stays as-is; when indoors, the whole terrain + outdoor-scenery batch is gated to the `OutsideView` clip planes (empty ⇒ no terrain). Terrain never enters the cell graph. Diverges intentionally from the handoff's "terrain as cells" sketch, which is *not* what retail does. |
| Salvage | Reuse vs fresh-port the A8.F pieces | **Reuse the clip math, rewrite the builder, delete the stencil + orchestration.** Keep `PortalView` / `ScreenPolygonClip` / `PortalProjection` (pure, GL-free, ~36 passing tests). Rework `PortalVisibilityBuilder` (wrong termination, wrong queue, no `OtherPortalClip`, #103 under-production). Delete `IndoorCellStencilPipeline`, `portal_stencil.*`, and the GameWindow two-pipe orchestration. |

---

## 2. Goal & non-goals

**Goal.** One render path. The camera's current cell is the root of a per-frame
portal-visibility traversal that yields *(ordered visible cells, per-cell screen-space clip
region, an `OutsideView` region for the outdoors)*. A single draw pass renders all visible
geometry (indoor cells, indoor statics, server entities, terrain, scenery) gated by clip
planes derived from those regions. No `cameraInsideBuilding` branch. No `RenderInsideOut`
stencil pass. No outdoor-vs-indoor toggle in the draw orchestration — only root selection.

**Non-goals (this phase).**
- Re-porting the WB mesh/dat pipeline. `ObjectMeshManager` / `WbMeshAdapter` /
  `WbDrawDispatcher` / `TerrainModernRenderer` / `LandblockMesh` / `DatCollection` / texture
  decode all stay. Phase U is **visibility + draw orchestration**, not mesh extraction.
- The 2026-05-30 camera-collision + physics work (`PhysicsCameraCollisionProbe`,
  `RetailChaseCamera`, the viewer/sight 30-step bypass). Kept verbatim.
- Per-instance highlight / selection blink, alpha-blend mode subpasses, and other
  rendering-quality items not on the seam-fix critical path.

---

## 3. The retail oracle

The thing we port. All line numbers are in
`docs/research/named-retail/acclient_2013_pseudo_c.txt`; struct lines in
`docs/research/named-retail/acclient.h`.

### 3.1 Top-level dispatch — `SmartBox::RenderNormalMode` (~92649)

Branches on `viewer_cell->seen_outside`:
- **Indoors** (`seen_outside == 0`, camera in a pure-indoor cell): `RenderDevice::DrawInside(viewer_cell)` → `PView::DrawInside(indoor_pview, viewer_cell)`. The BFS is rooted at the camera's `CEnvCell`.
- **Outdoors**: `LScape::draw(lscape)` draws terrain + landblock geometry (including building shells). Building interiors are peered into *from within that path* (§3.4).

`seen_outside` is set on a `CEnvCell` in `CEnvCell::find_cell_list` (~311044); it means "this
interior cell has at least one open portal to the exterior" (cellar windows, inn doorways).
It keeps the landscape loaded and sunlight injected for hybrid cells.

### 3.2 The clip region is a screen-space convex polygon — NOT scissor/stencil

Retail stores a cell's clip region as `view_type` (acclient.h:32338): a set of `view_poly`
(32465) entries, each a convex polygon of `view_vertex` (32483). **Each `view_vertex` carries
a `Plane`** for Sutherland-Hodgman edge clipping, plus the polygon's `xmin/xmax/ymin/ymax` box
for fast rejection. Retail clips **every polygon in software** against the active region
(`Render::set_view` 343750 installs it; the rasterizer's clipper reads it). We cannot do
per-polygon software clipping on a modern GPU — the per-edge `Plane` is exactly what maps to
`gl_ClipDistance` (§5.2).

### 3.3 Indoor BFS — `PView::ConstructView(CEnvCell*, uint16_t)` (433750)

1. Reset `outside_view.view_count = 0`; bump `master_timestamp` (the frame counter that drives
   the fixpoint).
2. `PView::InitCell` (432896) — classify the root cell's front-facing portals.
3. `PView::InsCellTodoList` (433183) — seed a **distance-sorted priority queue** (`cell_todo_list`).
4. **Closest-first BFS:** dequeue nearest cell → append to `cell_draw_list` →
   `PView::ClipPortals` (433572): for each `seen && !inflag` portal, project + intersect with
   the current clip region (`PView::GetClip` 432344) and, when non-empty, propagate into the
   neighbour's `portal_view_type` via `Render::copy_view` (344784). `PView::OtherPortalClip`
   (433524) additionally clips against the neighbour's matching (reciprocal) portal.
   `PView::AddViewToPortals` (433446) enqueues grown neighbours; `update_count` vs
   `master_timestamp` is the convergence watermark. A portal with `other_cell_id == 0xFFFF`
   accumulates into `PView::outside_view` (the landscape window).
5. `PView::DrawCells` (432709) consumes `cell_draw_list`: draws landscape through
   `outside_view` (if non-empty), then each cell's geometry gated by its stored region
   (`CEnvCell::setup_view` → `set_view`).

### 3.4 Outdoor → building-interior peering

`outdoor_pview` (a second `PView` instance, landscape-draw OFF) handles seeing *into* a
building from outside. `RenderDeviceD3D::DrawBuilding` primes
`outdoor_pview->outdoor_portal_list = building->portals` before drawing the shell. The shell's
BSP traversal hits portal nodes (`BSPPORTAL::portal_draw_portals_only` ~326881), which call
`RenderDeviceD3D::DrawPortal` (427852) → `PView::ConstructView(CBldPortal*, CPolygon*, …)`
(433827, the **recursive** overload). That tests viewer sidedness against the building portal,
clips the opening, resolves the destination `CEnvCell`, and **recurses into the CEnvCell BFS**
(§3.3) rooted at the destination cell. `CBldPortal` (acclient.h:32094) fields: `portal_side`,
`other_cell_id`, `other_portal_id`, `exact_match`, `num_stabs`, `stab_list`.

**Seamlessness:** both roots draw the same geometry from opposite sides of the same portal —
outdoor root peers *in* through the door; indoor root peers *out* through it
(`0xFFFF → outside_view → landscape`). Same clip machinery, same convergence. The threshold
crossing only swaps which cell is the root.

### 3.5 Terrain is its own path

`RenderDeviceD3D::DrawBlock` (430027) / `DrawLandCell` is the landblock render path,
visibility-tested in `LScape::draw_check_blocks` against the portal-derived clip polygon
(`Render::PortalList = pview`). Terrain is **never** enrolled into the cell graph; it is gated
by the single `outside_view` region when indoors and drawn normally when outdoors.

---

## 4. Architecture

```
   camera pos ─► CellVisibility.FindCameraCell(pos)
                     │  cell → INDOOR root        null → OUTDOOR root
                     ▼
   PortalViewBuilder.Build(root, camPos, viewProj, lookup)        [GL-free, CPU]
     • closest-first BFS through portals (distance-priority queue)
     • per-cell convex NDC clip region (ScreenPolygonClip + OtherPortalClip)
     • timestamp/update-count fixpoint termination
     • 0xFFFF exit portals → OutsideView
                     ▼
   ClipPlaneSet.From(region)                                      [GL-free, CPU]
     • each NDC edge (a→b) → clip-space plane (nx,ny,0,d)
     • merge near-collinear; cap at 8; AABB-scissor fallback when over budget
                     ▼
   upload: per-cell plane SSBO (binding=2, keyed by CellId); terrain uniform planes
                     ▼
   ONE draw pass (depth buffer on):
     sky               (ungated, no depth write)
     terrain + scenery (gated → OutsideView planes; outdoor root = ungated)
     indoor cells      EnvCellRenderer.Render(visibleCells)  (gated per-cell, SSBO)
     entities          WbDrawDispatcher.Draw                 (gated per-cell, SSBO)
     particles / weather (ungated)
                     ▼
   ACDREAM_PROBE_VIS  [vis] line on cell change
```

Two invariant properties:
- **No two-pipe seam.** Indoor vs outdoor changes only the BFS root, not the draw pass.
- **Per-cell gating at draw time, never a global mask.** Each draw carries its own region's
  planes (looked up by `CellId`); an empty region = zero planes pass = nothing drawn. The
  #103 flood-on-empty failure mode is structurally impossible.

---

## 5. Components

Each is independently testable; interfaces are the contract.

### 5.1 `PortalViewBuilder` — GL-free visibility core (reworked)

Reworks the existing `PortalVisibilityBuilder`. Reuses `PortalView` (`ViewPolygon`/`CellView`),
`ScreenPolygonClip`, `PortalProjection` unchanged.

```csharp
public sealed class PortalViewFrame
{
    public IReadOnlyList<uint> OrderedVisibleCells { get; }      // closest-first
    public IReadOnlyDictionary<uint, CellView> CellClipRegions { get; }
    public CellView OutsideView { get; }                          // 0xFFFF exits, clipped
}

public static class PortalViewBuilder
{
    // Indoor root.
    public static PortalViewFrame Build(
        LoadedCell rootCell, Vector3 cameraPos, Matrix4x4 viewProj,
        Func<uint, LoadedCell?> lookup);

    // Outdoor-peering root (U.5): root at a building-exterior portal.
    public static PortalViewFrame BuildFromBuildingPortal(
        BuildingExteriorPortal portal, Vector3 cameraPos, Matrix4x4 viewProj,
        Func<uint, LoadedCell?> lookup);
}
```

Changes from the #103 builder:
- **Distance-priority queue** (retail `InsCellTodoList` 433183) replacing the plain FIFO →
  correct front-to-back order + early-out.
- **Timestamp/update-count fixpoint** (retail `master_timestamp` + `update_count`,
  `AddViewToPortals` 433446) replacing the `MaxReprocessPerCell = 4` hard cap → converges on
  cyclic dungeon graphs (closes the #102 fast-follow, relates #95). A cell re-enqueues only
  when its accumulated region genuinely grows, tracked by a real watermark (the current
  near-no-op grow-guard is removed).
- **Reciprocal `OtherPortalClip`** (retail 433524) — also clip the portal against the
  neighbour's matching portal polygon → prevents over-inclusion through skewed openings.
- Emits per-cell `CellView`s + `OutsideView` (the existing builder already does the
  `OutsideView`; this generalises to all cells).

`LoadedCell` already supplies everything needed (`CellVisibility.cs:24`): `CellId`,
`WorldTransform`, `InverseWorldTransform`, `LocalBoundsMin/Max`, `Portals`
(`CellPortalInfo{ OtherCellId, PolygonId, Flags }`; `OtherCellId == 0xFFFF` = exit),
`ClipPlanes` (`PortalClipPlane{ Normal, D, InsideSide }`), `PortalPolygons` (`List<Vector3[]>`),
`BuildingId`.

### 5.2 `ClipPlaneSet` — edge → clip-plane extractor (GL-free)

```csharp
public readonly struct ClipPlaneSet
{
    public int Count { get; }                 // 0..8
    public ReadOnlySpan<Vector4> Planes { get; }   // clip-space (nx,ny,0,d)
    public bool UseScissorFallback { get; }   // true ⇒ region exceeded 8 edges; use AABB
    public Vector4 ScissorAabb { get; }       // NDC xmin,ymin,xmax,ymax

    public static ClipPlaneSet From(CellView region);
}
```

Each NDC edge from `(ax,ay)` to `(bx,by)` becomes the half-space "inside the edge". With
`NDC = clip.xy / clip.w` (and `w > 0` for visible geometry), the screen-space line
`nx·x + ny·y + d = 0` lifts to a clip-space plane via multiply-through-by-`w`:

```
gl_ClipDistance = nx·clip.x + ny·clip.y + d·clip.w     // ≥ 0 ⇒ inside
```

so no un-projection is needed — the 2D edge directly yields a `vec4(nx, ny, 0, d)` applied to
`gl_Position`. Sign convention is fixed by the builder's CCW winding (`EnsureCcw`). The 8-plane
cap (GL guarantees `GL_MAX_CLIP_DISTANCES ≥ 8`) is handled by: (1) merge near-collinear edges
(retail `copy_view` dedups within ~1px); (2) if still > 8, set `UseScissorFallback` and gate by
the AABB box instead — conservative (slight corner over-draw, never hides geometry).

### 5.3 GPU gate — shaders + buffers

- **`mesh_modern.vert`** (indoor cells, indoor statics, server entities all share it): new SSBO
  at `binding=2`: `struct CellClip { uint count; uint _pad0,_pad1,_pad2; vec4 planes[8]; }
  buffer ClipBuf { CellClip cells[]; };` indexed by a per-cell slot derived from
  `InstanceData.CellId`. The shader writes `gl_ClipDistance[i] = dot4(planes[i], gl_Position)`
  for `i < count`. **Does not break MDI batching** — `gl_ClipDistance` is a per-vertex built-in,
  not per-draw state, so the single `glMultiDrawElementsIndirect` per group is preserved.
  Existing bindings (`binding=0` instance mat4, `binding=1` batch tuple) are untouched.
- **`terrain_modern.vert`**: a small uniform block `{ int count; vec4 planes[8]; }` for the
  `OutsideView`; writes `gl_ClipDistance`. `count = 0` when outdoors (ungated).
- **CPU**: `glEnable(GL_CLIP_DISTANCE0 + i)` for `i < maxActiveCount` (and disable the rest);
  upload the per-cell SSBO + terrain uniforms each frame after the builder runs. An "outdoor /
  no-clip" sentinel slot (count 0) for entities outside any gated cell.

A per-frame **CellId → SSBO slot** map is built alongside `CellClipRegions` (visible cells get
slots 0..N; everything else maps to the no-clip sentinel).

### 5.4 Draw orchestrator — the GameWindow restructure

Replaces the deleted two-pipe branch (GameWindow.cs ~7342–7715) with the §4 sequence. Wires in
the **currently-orphaned** `EnvCellRenderer.Render(visibleCells)` (today only the two-pipe
methods call it — outdoors you see shells + floating furniture but no cell walls). Keeps every
audited retail-faithful fix (§7). The default outdoor draw — today
`_wbDrawDispatcher.Draw(set: EntitySet.All)` at GameWindow.cs:7704–7715 — becomes the
outdoor-root case of the unified sequence.

### 5.5 `ACDREAM_PROBE_VIS` — runtime visibility probe

One `[vis]` line per frame on cell change: root cell id, `OrderedVisibleCells` count + ids,
`OutsideView` poly count + extracted plane count, per-cell plane counts, and any 8-plane-cap
scissor fallbacks. Owned by `PhysicsDiagnostics`-style diagnostic owner (per Code Structure
Rule 5), runtime-toggleable via the DebugPanel. **This is the apparatus #103 lacked at runtime**
— built in U.2, used to validate the builder against live frames before any GL work.

---

## 6. Data flow, two roots, error handling

### 6.1 Per-frame (see §4 diagram)

Opaque correctness rides the depth buffer; the BFS front-to-back order is for early-Z and alpha
sorting, not a correctness crutch (retail needed draw-order because its software clip path had no
per-pixel depth test; we have one). Clip planes do exactly one job: keep each thing inside its
portal-framed NDC region so nothing bleeds across an opening.

### 6.2 Indoor root (dominant, ships first — U.4)

Camera in a `CEnvCell`. BFS from that cell; `0xFFFF` exits union into `OutsideView`; terrain
gated to `OutsideView`. Fixes the cellar/inn bleed.

### 6.3 Outdoor-peering root (U.5)

Camera outdoors. Terrain + shells draw normally. To peer into a building, root the builder at the
building's camera-facing exterior portal and recurse into its cells (retail `outdoor_pview` /
`DrawBuilding` / `DrawPortal` / `ConstructView(CBldPortal)`). **Dependency to confirm during
U.5:** the render-side `BuildingExteriorPortal` (polygon + destination cell id + side). We carry
`BldPortalInfo` on the physics side (`BuildingPhysics` / `CheckBuildingTransit`); U.5 surfaces it
to the render layer (or reads the same dat structure). If the data is not readily available, U.5
is the place to add it — the spec flags it as the one open data dependency.

### 6.4 Error handling / fallbacks

- **8-plane cap:** merge near-collinear edges; else AABB scissor fallback (conservative). Logged.
- **Empty-region semantics (the #103 inversion):** empty `CellView` ⇒ cell not visible ⇒ not
  drawn; empty `OutsideView` ⇒ no outdoors visible ⇒ terrain not drawn. The correct reading of
  empty.
- **Dungeon termination:** the timestamp/update-count fixpoint (§5.1) guarantees convergence on
  cyclic graphs.
- **#103 under-production — tracked, not inherited:** the builder does not ship until
  `ACDREAM_PROBE_VIS` shows a non-empty, *narrowing* `OutsideView` at the cellar window on a live
  capture. Suspects to verify in U.2: exit-portal (`0xFFFF`) polygons actually populated in
  `PortalPolygons` at cell hydration; portal-side test not over-culling.
- **Degenerate portals:** `< 3` verts after near-plane clip ⇒ skip (already in `PortalProjection`).
- **Camera-cell miss:** existing 3-frame grace + brute-force fallback in `FindCameraCell`; worst
  case briefly renders as outdoor root (no crash, no flood).

---

## 7. Delete / keep audit (Task 1, surgical)

**Delete (two-pipe machinery only):**

| Target | Location |
|--------|----------|
| `IndoorCellStencilPipeline.cs` (792 LOC) + `portal_stencil.vert/.frag` | `src/AcDream.App/Rendering/` |
| `RenderInsideOutAcdream` | `GameWindow.cs:11007–11319` |
| `RenderOutsideInAcdream` | `GameWindow.cs:213–325` |
| A8-perf instrumentation (`_a8Perf*`, `MaybeFlushA8Perf`, probe emit methods) | `GameWindow.cs:7134–7177`, `11321–11609` |
| `cameraInsideBuilding` / `a8IndoorBranchEnabled` / `ACDREAM_A8_INDOOR_BRANCH` branch | `GameWindow.cs:7342–7523`, `7613–7715`, `7825–7831` |
| `_indoorStencilPipeline` field / ctor / dispose | `GameWindow.cs:172`, `1941–1944`, `11690` |
| `PortalVisibilityBuilder.Build` call site | `GameWindow.cs:11040` (replaced by the new orchestration) |

**Rework, don't delete:** `PortalVisibilityBuilder.cs` → `PortalViewBuilder` (§5.1).

**Keep (referenced beyond the two-pipe path):** `EnvCellRenderer.cs`, `Building.cs`,
`BuildingLoader.cs`, `BuildingRegistry.cs`, `CellVisibility.cs`, and the clip-math trio
`PortalView.cs` / `ScreenPolygonClip.cs` / `PortalProjection.cs` (+ their ~36 tests).

**Keep these real bug-fixes (NOT visibility machinery) through the delete:**

| Commit | Fix |
|--------|-----|
| `9559726` | `EnvCellRenderer` pool aliasing (list clear, `PostPreparePoolIndex` cursor, nested `isSetup`) |
| `0fc6003` | `BuildingId` stamping + `GetCellsForLandblock` (cell lookup by landblock) |
| `5dc4140` | `EnvCellRenderer` SSBO stride (64B mat4), FrontFace(CW)+per-batch CullMode via MDI, `EntitySet` partition |
| `d5deeb3`, `0940d79`, `9ee42d4` | `EnvCellRenderer` GL-state correctness (cull state, cache invalidation at `Render` entry) |
| `aae5300` + camera family | `PhysicsCameraCollisionProbe` / `RetailChaseCamera` spring-arm |

Note: the `EntitySet` values introduced specifically for the two-pipe split (`IndoorPass`,
`OutdoorScenery`, `BuildingShells`) get re-evaluated against the unified draw sequence in U.4 —
the partition mechanism stays; some specific draw-call sites collapse.

---

## 8. Testing strategy

- **Unit (GL-free):** `PortalViewBuilder` on synthetic graphs — a cottage chain (visible set,
  ordering, `OutsideView` narrowing) and a cyclic dungeon hub (fixpoint termination, no
  duplicate-accumulation blowup, `visibleCells` bounded). `ClipPlaneSet` on hand-worked polygons
  (edge→plane sign, 8-cap merge, scissor fallback). Reuse the existing ~36 clip-math tests.
- **The real gate is visual + the runtime probe** — unit tests on synthetic data did **not**
  catch #103. We assert "`OutsideView` non-empty and narrowing at the cellar window" on a live
  `ACDREAM_PROBE_VIS` capture before claiming the builder works, then:
  - Cottage → cellar → out the door: no flap, walls solid, no terrain bleed, seamless threshold
    from any camera angle/zoom.
  - Holtburg Inn: no outdoor stabs/terrain through floor/walls (closes #78).
  - Dungeon via Town Network portal: `visibleCells` ~4–15, no foreign-dungeon geometry
    (closes/relates #95).
  - Zero regression to the outdoor default (today's working game).

---

## 9. Implementation staging

The spec covers all of Phase U; the plan (writing-plans) details each task. Build + test green at
every stage.

| Stage | Deliverable | Gate |
|-------|-------------|------|
| **U.1** | Delete two-pipe surgically (§7); keep all audited fixes. Default path visibly unchanged. | Build/test green; "deck cleared" |
| **U.2** | GL-free core: `PortalViewBuilder` (priority queue, fixpoint, `OtherPortalClip`) + `ClipPlaneSet` + `ACDREAM_PROBE_VIS`. Fully unit-tested. No GL. | Tests + probe validates live `OutsideView` |
| **U.3** | GPU gate: clip-plane SSBO + `gl_ClipDistance` in `mesh_modern.vert`; terrain uniform planes in `terrain_modern.vert`; upload + slot-map infra. | Build green; clip visibly works on a test draw |
| **U.4** | Indoor-root orchestration: wire `EnvCellRenderer.Render` + gated terrain into the unified pass. Cellar/inn bug fix. | **Visual gate #1** |
| **U.5** | Outdoor-peering root: `BuildingExteriorPortal` root; seamless threshold from outside. (Confirms the §6.3 data dependency.) | **Visual gate #2** |
| **U.6** | Dungeon-scale validation; close/relate #95 + #102; confirm `visibleCells` sane + perf. | **Visual gate #3** |

---

## 10. Risks

- **Outdoor-peering data dependency (§6.3).** Medium. Render-side building-exterior-portal
  geometry may need surfacing from the physics-side `BldPortalInfo`. Isolated to U.5; the indoor
  bug fix (U.4) does not depend on it.
- **#103 under-production recurrence.** Medium, mitigated. The reworked builder + the runtime
  probe + the empty-region inversion attack the exact failure; the probe makes recurrence
  falsifiable on live frames before GL work.
- **8-plane cap on deep portal chains.** Low. M1.5 scenes are short chains; merge + scissor
  fallback covers the rest. Revisit only if a dungeon shows corner over-draw.
- **MDI batching vs per-cell gating.** Low — resolved by the per-vertex `gl_ClipDistance` +
  CellId-indexed SSBO (no per-cell draws, batching preserved).

---

## 11. Reference index

- **Decision / handoff:** [`docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md`](../../research/2026-05-30-unified-render-pipeline-decision-and-handoff.md)
- **#103 failure detail:** [`docs/research/2026-05-29-a8f-visual-gate-failure-handoff.md`](../../research/2026-05-29-a8f-visual-gate-failure-handoff.md)
- **Why WB can't express per-portal clipping:** project memory `indoor-portal-visibility-wb-vs-retail`
- **Retail decomp:** `docs/research/named-retail/acclient_2013_pseudo_c.txt` — `SmartBox::RenderNormalMode` 92649; `PView::ConstructView` 433750 (CEnvCell) / 433827 (CBldPortal); `ClipPortals` 433572; `GetClip` 432344; `DrawCells` 432709; `InitCell` 432896; `AddViewToPortals` 433446; `InsCellTodoList` 433183; `OtherPortalClip` 433524; `copy_view` 344784; `set_view` 343750; `DrawInside` 433793; `DrawPortal` 427852; `DrawBlock` 430027; `find_visible_child_cell` 311397; `GetVisible` 311378; `grab_visible_cells` 311878. Structs (acclient.h): `PView` 45934; `portal_view_type` 32346; `view_type` 32338; `view_poly` 32465; `view_vertex` 32483; `CCellPortal` 32300; `CBldPortal` 32094.
- **acdream anchors:** `CellVisibility.cs` (`LoadedCell` :24, `FindCameraCell` :301, `PointInCell` :367, `GetVisibleCells` :426, `ComputeVisibility` :272); `EnvCellRenderer.cs` (MDI draw :876/:1058, `RegisterCell` :246); `TerrainModernRenderer.cs` (`Draw` :191, MDI :263); shaders `mesh_modern.vert`, `terrain_modern.vert`; clip-math `PortalView.cs` / `ScreenPolygonClip.cs` / `PortalProjection.cs`.
- **Related issues:** #103 (this supersedes the A8.F arc), #78 (inn through-floor bleed — U.4), #95 (dungeon portal-graph blowup — U.6), #102 (builder fixpoint fast-follow — U.2/U.6).