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 map 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. 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 layer maps directly.

How:

• Replace direct 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 scene maps 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.