Internal Viewport 270p (480x270)

This commit is contained in:
2026-04-27 06:40:04 +01:00
parent b0762c776a
commit d10d5aa7db
6 changed files with 598 additions and 1 deletions
@@ -0,0 +1,123 @@
---
id: PLN-0043
ticket: internal-viewport-270p
title: Runtime 270p Core Migration
status: review
created: 2026-04-27
completed:
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.
@@ -0,0 +1,120 @@
---
id: PLN-0044
ticket: internal-viewport-270p
title: Host and Test Propagation for 270p
status: review
created: 2026-04-27
completed:
tags: [host, tests, viewport, resolution, touch, overlay]
---
## Briefing
This plan executes the second mandatory slice of `DEC-0022`: propagate the accepted `480x270` runtime contract into host presentation, absolute pointer mapping, host-side overlay/test fixtures, and any remaining test surfaces that still assume `320x180`.
This plan depends on `PLN-0043` completing first. It must not redefine the runtime contract; it only propagates the already-accepted 270p baseline into host-owned behavior and validation surfaces.
## Decisions de Origem
- `DEC-0022` - Internal Viewport 270p (480x270) as Canonical Runtime Contract
## Alvo
Make the desktop host and test surface faithfully consume the new canonical runtime resolution and touch domain.
## Escopo
- Update host framebuffer/surface creation to `480x270`.
- Update absolute pointer/touch mapping to the new canonical domain.
- Update host overlay fixtures and tests that still allocate or draw against `320x180`.
- Sweep remaining test hardcodes outside the core runtime step.
## Fora de Escopo
- Core runtime ownership changes already covered by `PLN-0043`.
- Specs and docs publication.
- Post-migration visual redesign or typography/layout tuning beyond strict propagation.
## Plano de Execucao
### Step 1 - Rebaseline host presentation surface
**What:**
Make the desktop host create and present its base `Pixels` surface using the new canonical runtime dimensions.
**How:**
Update host initialization and redraw flow so `PixelsBuilder`, frame copy, and overlay composition all consume `Hardware::W/H` after the runtime constants move to `480x270`.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/utilities.rs`
### Step 2 - Rebaseline absolute input mapping
**What:**
Align pointer/touch translation with the new canonical framebuffer domain.
**How:**
Update `window_to_fb()` and any clamping logic to map window coordinates into `[0, 479] x [0, 269]` through the canonical `Hardware::W/H` path.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/input.rs`
### Step 3 - Update host overlay fixtures and tests
**What:**
Remove host overlay hardcodes that still allocate or draw a `320x180` RGBA buffer.
**How:**
Update overlay tests and any host-owned fixtures so they use `480x270` or derive from the canonical hardware constants where appropriate. Preserve overlay semantics; do not redesign the overlay in this plan.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
### Step 4 - Sweep remaining non-doc resolution assertions
**What:**
Capture and update any remaining code or tests outside specs/docs that still depend on the old baseline.
**How:**
Search for `320x180`, `320, 180`, and equivalent fixed-size assumptions under host/runtime test surfaces and migrate them to the accepted 270p contract or to canonical constants.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/*`
- any remaining test modules under `crates/console/*`
## Criterios de Aceite
- The desktop host creates its base surface from the `480x270` canonical runtime dimensions.
- Absolute pointer/touch mapping uses the new framebuffer domain.
- Host overlay tests no longer hardcode `320x180`.
- No host-owned code path reintroduces the old baseline as an implicit contract.
## Tests / Validacao
### Unit Tests
- `cargo test` for:
`prometeu-host-desktop-winit`
any directly impacted console crates
### Integration Tests
- Verify runtime frame copy still lands correctly in the host RGBA surface.
- Verify pointer mapping clamps to the new canonical framebuffer bounds.
### Manual Verification
- Launch the desktop host and confirm the window presents a `480x270` logical framebuffer.
- Confirm overlay still renders and aligns within the new frame domain.
- Confirm pointer/touch interaction reaches the expected screen edges.
## Riscos
- Host visual regressions may appear only at runtime even when tests pass.
- Overlay layout may become visually awkward at 270p even if functionally correct; cosmetic tuning is intentionally deferred.
- Partial migration risks mismatch between runtime dimensions and host test fixtures if `PLN-0043` is not completed first.
## Dependencies
- `PLN-0043` MUST complete first.
@@ -0,0 +1,105 @@
---
id: PLN-0045
ticket: internal-viewport-270p
title: Specs and Docs Publication for 270p
status: review
created: 2026-04-27
completed:
tags: [specs, docs, runtime, viewport, resolution]
---
## Briefing
This plan executes the final mandatory slice of `DEC-0022`: publish the accepted `480x270` console contract in canonical specs and supporting documentation after runtime and host propagation are already in place.
This plan must run last. It exists to prevent public documentation from getting ahead of executable reality.
## Decisions de Origem
- `DEC-0022` - Internal Viewport 270p (480x270) as Canonical Runtime Contract
## Alvo
Update canonical published documentation so the repository describes Prometeu as a `480x270` console with matching framebuffer and touch coordinate semantics.
## Escopo
- Update runtime specs that explicitly publish `320x180`.
- Update any nearby prose that describes visual behavior in a way that now depends on the new baseline.
- Update related README/index material if it repeats the old resolution as canonical fact.
## Fora de Escopo
- Runtime or host code changes.
- Asset migration.
- Any broader narrative cleanup unrelated to the 270p contract.
## Plano de Execucao
### Step 1 - Update framebuffer and graphics specs
**What:**
Publish `480x270` as the canonical graphics/framebuffer resolution in the runtime graphics spec.
**How:**
Update the base-resolution and related descriptive sections so they state the new canonical resolution without ambiguity. Any prose that references `320x180` as a defining visual baseline must be revised to stay accurate.
**File(s):**
- `docs/specs/runtime/04-gfx-peripheral.md`
### Step 2 - Update touch coordinate contract
**What:**
Publish the new absolute touch domain that matches the 270p framebuffer.
**How:**
Update the touch spec so resolution, coordinate ranges, and any coordinate-space examples reflect `[0, 479] x [0, 269]`.
**File(s):**
- `docs/specs/runtime/07-touch-peripheral.md`
### Step 3 - Sweep remaining resolution references in runtime docs
**What:**
Remove remaining canonical `320x180` references from runtime docs and supporting material where they now contradict `DEC-0022`.
**How:**
Search runtime specs and adjacent docs for explicit resolution references and update only the ones that are part of the public console contract. Do not rewrite unrelated prose that merely mentions resolution in a different context unless it becomes incorrect after the migration.
**File(s):**
- `docs/specs/runtime/*.md`
- `docs/specs/runtime/README.md`
- any other directly affected docs under `docs/`
## Criterios de Aceite
- Canonical runtime docs publish `480x270` as the official internal resolution.
- Touch docs publish coordinate ranges consistent with `480x270`.
- No remaining public spec text describes `320x180` as the canonical console baseline.
- Documentation order reflects executable truth: runtime/host migration is already completed before docs close.
## Tests / Validacao
### Unit Tests
- No code unit tests are required for documentation-only changes.
### Integration Tests
- Re-run any repository validation or doc-linked checks that are already part of the normal workflow if available.
### Manual Verification
- Read the updated specs end-to-end for `gfx` and `touch` to confirm they agree with `DEC-0022`.
- Confirm no public-facing contradiction remains between docs and the implemented runtime baseline.
## Riscos
- Publishing docs before code would create a contract/execution mismatch; this is why this plan must remain last.
- Resolution references can hide in explanatory prose and examples, not only in obvious headings.
- Over-editing adjacent docs can accidentally turn a narrowly scoped publication task into a broad editorial rewrite.
## Dependencies
- `PLN-0043` MUST complete first.
- `PLN-0044` SHOULD complete first, and MUST complete first if any host-facing docs mention live desktop behavior.