---
id: PLN-0014
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - Renderer Migration to Scene Viewport Cache
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---

## Objective

Migrate world rendering from direct canonical `SceneBank` consumption to `SceneViewportCache` consumption while preserving the accepted observable composition order.

## Background

`DEC-0013` makes `SceneViewportCache` the immediate source of copy data for world blits and preserves the visible order of world layers, interleaved sprites, and HUD. `PLN-0011` already removed the old canonical `TileLayer` / `ScrollableTileLayer` model and cleaned the bridge surface accordingly. This plan focuses on the renderer migration itself.

## Scope

### Included
- Remove direct world-layer map reads from the renderer hot path.
- Make world-layer composition consume cache-backed copy requests.
- Preserve sprite interleaving and HUD ordering.
- Keep V1 destructive `back` composition acceptable.

### Excluded
- scene domain model refactor
- cache structural implementation
- resolver movement logic
- non-world rendering systems beyond required integration points

## Execution Steps

### Step 1 - Identify and isolate direct canonical map consumption in the renderer

**What:**
Locate current renderer paths that read canonical scene/layer maps directly.

**How:**
- Replace any remaining direct `SceneBank` / `SceneLayer` / `TileMap` reads in [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs) with abstraction points prepared to accept cache-sourced copy requests.
- Keep the migration incremental enough to preserve buildability.

**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)

### Step 2 - Introduce world-layer copy paths driven by cache requests

**What:**
Teach the renderer to copy world content from `SceneViewportCache`.

**How:**
- Add renderer-facing entry points that consume per-layer copy instrumentation emitted by the resolver.
- Ensure the renderer treats the cache as the immediate world source for blit operations.
- Do not let the renderer re-own totem/drift/clamp policy.

**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
- Supporting cache/resolver integration modules

### Step 3 - Preserve accepted composition order

**What:**
Keep the visible ordering of layers, sprites, and HUD intact during migration.

**How:**
- Preserve composition order:
  - world layer 0
  - sprites
  - world layer 1
  - sprites
  - world layer 2
  - sprites
  - world layer 3
  - sprites
  - HUD
- Keep `HUD`, sprites, and fades outside the viewport-cache invalidation model.

**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)

### Step 4 - Preserve destructive `back` composition for V1

**What:**
Accept destructive composition while still benefiting from cache-backed world inputs.

**How:**
- Keep the first migrated renderer implementation destructive in `back`.
- Ensure the code path clearly separates:
  - canonical scene data
  - viewport cache data
  - final composition buffer
- Avoid mixing “cache update” with “final buffer copy” concerns in the renderer.

**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)

### Step 5 - Add renderer regression coverage

**What:**
Protect the migrated composition order and world rendering behavior.

**How:**
- Add tests or golden-style checks for:
  - world layers rendered from cache, not canonical maps
  - visible ordering of sprites between layers
  - HUD remaining on top
- Add probes or assertions preventing accidental fallback to direct canonical map reads.

**File(s):**
- Renderer tests in [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs) and adjacent test modules

## Test Requirements

### Unit Tests
- Cache-driven world copy code produces the same visible layer ordering as the prior renderer.

### Integration Tests
- Full `render_all()` path uses `SceneViewportCache` for world layers.
- Sprites/HUD/fades remain correctly ordered relative to world layers.

### Manual Verification
- Render representative scenes with multiple active layers and sprites to confirm no visible ordering regressions.

## Acceptance Criteria

- [ ] Renderer world composition no longer reads canonical `SceneBank` data directly in the hot path.
- [ ] World layers are copied from `SceneViewportCache`.
- [ ] Sprite interleaving and HUD ordering remain correct.
- [ ] V1 destructive composition still works end-to-end.
- [ ] Regression coverage protects the migrated path.

## Dependencies

- Depends on `PLN-0011`, `PLN-0012`, and `PLN-0013`.
- Source decision: `DEC-0013`

## Risks

- Renderer migration can accidentally duplicate world-copy work if cache and compositor responsibilities blur.
- Sprite ordering regressions are easy to introduce during world-layer refactoring.
- Temporary fallback paths can linger unless tests explicitly block them.