prometeu-runtime/discussion/workflow/plans/PLN-0043-runtime-270p-core-migration.md

id	ticket	title	status	created	completed	tags
PLN-0043	internal-viewport-270p	Runtime 270p Core Migration	done	2026-04-27	2026-04-27	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.