---
id: PLN-0015
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - API, Bank Integration, and Tests
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---

## Objective

Finish the scene/viewport-cache migration by aligning exposed APIs, bank-loading integration, and test coverage across HAL, drivers, and system entry points.

## Background

After core types, cache, resolver, and renderer migration exist, the remaining work is to align the surrounding surfaces so the new architecture is usable as the runtime’s operational model.

## Scope

### Included
- Update bridge APIs and exposed runtime surfaces.
- Align bank-loading/integration paths with scene-backed content.
- Remove stale tile-layer-era interfaces.
- Add cross-layer regression coverage.

### Excluded
- additional architectural redesign
- feature work beyond the accepted decision

## Execution Steps

### Step 1 - Update HAL and bridge surfaces

**What:**
Remove or replace public APIs still shaped around the old scrollable tile-layer model.

**How:**
- Update `GfxBridge` and adjacent bridge traits so they no longer expose obsolete canonical layer ownership assumptions.
- Introduce scene/cache/resolver-oriented access only where required by runtime consumers.

**File(s):**
- [crates/console/prometeu-hal/src/gfx_bridge.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/gfx_bridge.rs)
- Other bridge traits affected by scene model changes

### Step 2 - Align driver/hardware construction paths

**What:**
Ensure hardware and driver initialization paths can construct and own the new scene/cache/resolver model.

**How:**
- Update hardware bootstrap and driver ownership paths to instantiate the canonical scene and viewport-cache stack.
- Remove any remaining ownership assumptions tied to `ScrollableTileLayer`.

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

### Step 3 - Align asset/bank integration paths

**What:**
Make sure bank-loading and asset integration paths understand the scene-backed model at the operational layer.

**How:**
- Update asset-side or loader-side integration points so scene-backed content can be staged, installed, and referenced coherently.
- Keep the work scoped to the bank-loading path; do not reopen the canonical model here.

**File(s):**
- [crates/console/prometeu-drivers/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs)
- [crates/console/prometeu-drivers/src/memory_banks.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/memory_banks.rs)
- [crates/console/prometeu-hal/src/cartridge_loader.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/cartridge_loader.rs)
- Related asset/bank shared types

### Step 4 - Remove stale type and API remnants

**What:**
Clean out old interfaces that would leave the codebase in a dual-model state.

**How:**
- Remove obsolete references to:
  - `TileLayer`
  - `ScrollableTileLayer`
  - direct old-layer scroll ownership APIs
- Keep only the canonical scene model and the viewport-cache/render pipeline required by the decision.

**File(s):**
- HAL and driver modules touched by earlier plans

### Step 5 - Add full-stack regression coverage

**What:**
Add the minimum test family needed to execute the migration safely one plan at a time.

**How:**
- Add tests for:
  - canonical scene ownership
  - viewport-cache update behavior
  - resolver drift/hysteresis
  - renderer composition order
  - scene swap invalidation
  - absence of stale old-layer APIs
- Add at least one integration path that exercises:
  - scene load
  - cache population
  - resolver update
  - renderer world composition

**File(s):**
- Test modules across HAL, drivers, and system crates as needed

## Test Requirements

### Unit Tests
- Public/runtime-facing APIs no longer depend on `ScrollableTileLayer`.
- Cache, resolver, and renderer modules remain individually covered.

### Integration Tests
- End-to-end scene load -> cache update -> renderer composition path succeeds.
- Scene swap invalidates cache and repopulates correctly.

### Manual Verification
- Build the runtime and exercise representative world scenes to confirm no stale assumptions remain in construction or render flow.

## Acceptance Criteria

- [ ] Bridge and runtime-facing APIs align with the new scene/cache model.
- [ ] Hardware/driver construction paths instantiate the new architecture correctly.
- [ ] Asset/bank integration paths accept the scene-backed model.
- [ ] Stale old-layer APIs are removed.
- [ ] Full-stack regression coverage exists for the migration.

## Dependencies

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

## Risks

- API cleanup is where hidden dependencies on the old model are most likely to surface.
- Asset/bank integration can expand in scope if loader assumptions are too tightly coupled to current bank enums.
- If stale APIs are not removed aggressively, the codebase can get stuck in a fragile dual-model transition.