---
id: PLN-0043
ticket: internal-viewport-270p
title: Runtime 270p Core Migration
status: done
created: 2026-04-27
completed: 2026-04-27
tags: [gfx, runtime, viewport, resolution, frame-composer]
---

## Briefing

This plan executes the first mandatory slice of `DEC-0022`: migrate the canonical runtime resolution from `320x180` to `480x270` inside the core runtime path before any host-facing or documentation-only propagation.

This plan intentionally prioritizes runtime ownership, framebuffer sizing, `FrameComposer` baseline, resolver/cache sizing behavior, and runtime-local tests. It does not include host window/input propagation or specs/docs publication.

## Decisions de Origem

- `DEC-0022` - Internal Viewport 270p (480x270) as Canonical Runtime Contract

## Alvo

Make the runtime itself operate canonically at `480x270` RGB565 and preserve the existing scene/cache/resolver architecture under the new baseline.

## Escopo

- Update canonical runtime width/height constants.
- Propagate the new resolution through `Hardware`, `Gfx`, and `FrameComposer`.
- Preserve `SceneViewportResolver` and `SceneViewportCache` architecture while updating runtime assumptions and tests derived from the old baseline.
- Recompute runtime expectations that explicitly depended on `320x180`.

## Fora de Escopo

- Host desktop surface creation and pointer mapping.
- Host overlay RGBA fixtures.
- Specs and docs publication.
- Asset migrations or text/glyph content redesign.

## Plano de Execucao

### Step 1 - Promote runtime-wide canonical dimensions

**What:**
Change the runtime’s canonical internal framebuffer dimensions from `320x180` to `480x270`.

**How:**
Update the canonical constants and any runtime-local documentation/comments that still publish the old baseline, ensuring all `Gfx` and `FrameComposer` construction paths inherit the new dimensions from the same source of truth.

**File(s):**
- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-drivers/src/gfx.rs`

### Step 2 - Rebaseline frame composition and scene runtime sizing

**What:**
Make `FrameComposer` use `480x270` as the canonical viewport baseline for scene binding and scene-runtime construction.

**How:**
Keep the existing ownership split (`FrameComposer` -> `SceneViewportCache` + `SceneViewportResolver`) intact, but update construction-time expectations and tests that hardcode `320x180`. Preserve the current cache sizing algorithm and hysteresis derivation; do not introduce configurable dual-mode resolution.

**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`

### Step 3 - Rebaseline resolver expectations under 270p

**What:**
Update resolver tests and derived numeric expectations to the `480x270` viewport.

**How:**
Adjust test fixtures that currently instantiate `SceneViewportResolver::new(320, 180, 25, 16, 12, 20)` and recompute anchor, clamp, and refresh-region assertions from the 270p baseline. Preserve behavioral intent:
- anchor initialization;
- parallax propagation;
- hysteresis stability;
- edge clamping;
- incremental refresh behavior.

**File(s):**
- `crates/console/prometeu-hal/src/scene_viewport_resolver.rs`

### Step 4 - Rebaseline runtime integration tests

**What:**
Update runtime-level tests that validate compositor/runtime invariants using the old resolution.

**How:**
Migrate runtime integration assertions so they derive expected sizes from the new baseline or from the runtime constants. Keep scene-cache and sprite-order semantics unchanged; only the canonical viewport contract changes.

**File(s):**
- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- `crates/console/prometeu-drivers/src/gfx.rs`

## Criterios de Aceite

- `Hardware::W == 480` and `Hardware::H == 270`.
- Runtime-owned frame composition uses `480x270` as the canonical viewport.
- Runtime tests no longer hardcode `320x180` as the canonical internal resolution.
- Resolver/cache behavior remains architecturally unchanged apart from the dimensional baseline.
- No configurable `180p/270p` runtime mode is introduced.

## Tests / Validacao

### Unit Tests

- `cargo test` for:
  `prometeu-drivers`
  `prometeu-hal`

### Integration Tests

- Verify `FrameComposer` scene-binding/runtime tests under the new viewport.
- Verify resolver numeric assertions after updating the viewport baseline.

### Manual Verification

- Inspect runtime constants and constructor callsites to confirm a single canonical source of truth.
- Confirm no new runtime API for resolution selection was added.

## Riscos

- Resolver tests may fail with multiple derived-value changes at once, requiring careful recomputation rather than blind constant replacement.
- Some runtime assertions may accidentally embed old visible-framing assumptions instead of true contract checks.
- Runtime-only completion does not yet yield correct host presentation; that gap is intentional and deferred to the next plan.