prometeu-runtime/discussion/workflow/plans/PLN-0014-renderer-migration-to-scene-viewport-cache.md

id	ticket	title	status	created	completed	tags
PLN-0014	scene-bank-and-viewport-cache-refactor	Plan - Renderer Migration to Scene Viewport Cache	accepted	2026-04-13		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 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

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
• 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

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

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 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.