prometeu-runtime/discussion/workflow/plans/PLN-0019-scene-binding-camera-and-scene-status.md

id	ticket	title	status	created	completed	tags
PLN-0019	render-all-scene-cache-and-camera-integration	Plan - Scene Binding, Camera, and Scene Status	accepted	2026-04-14		gfx runtime render scene camera frame-composer

Objective

Implement the FrameComposer scene-binding contract, minimal camera state, and explicit scene-availability status without yet completing the cache-refresh render path.

Background

DEC-0014 locks scene activation around bind_scene(scene_bank_id) with SceneBankPoolAccess, pointer-based access only, and scene_bank_id + Arc<SceneBank> retained inside FrameComposer.

Scope

Included

• scene bind/unbind contract
• active scene identity and shared reference storage
• scene availability status
• minimal camera state (i32, top-left viewport)

Excluded

• applying cache refreshes
• full render-path migration
• HUD behavior

Execution Steps

Step 1 - Add scene binding state to FrameComposer

What: Implement the canonical bind/unbind surface.

How:

• Add bind_scene(scene_bank_id) and unbind_scene().
• Resolve scenes from SceneBankPoolAccess.
• Store both:
  • scene_bank_id
  • Arc<SceneBank>
• Replace prior scene binding completely on a new bind.

File(s):

• crates/console/prometeu-drivers/src/frame_composer.rs
• crates/console/prometeu-drivers/src/memory_banks.rs

Step 2 - Add explicit scene status

What: Expose scene availability through status, not just implicit option checks.

How:

• Define a scene status enum or equivalent status object.
• Distinguish at least:
  • no scene bound
  • bound and available
  • bound but not renderable if such intermediate state is needed
• Ensure no-scene rendering remains valid.

File(s):

• crates/console/prometeu-drivers/src/frame_composer.rs
• optional HAL-facing status surface if needed later

Step 3 - Add camera contract

What: Implement the V1 camera ownership inside FrameComposer.

How:

• Add set_camera(x, y).
• Store camera coordinates as i32.
• Treat them as top-left viewport coordinates in world space.
• Keep all advanced camera behavior out of scope.

File(s):

• crates/console/prometeu-drivers/src/frame_composer.rs

Step 4 - Tie cache/resolver lifetime to scene binding

What: Align cache/resolver lifetime with the active scene contract.

How:

• Cache and resolver remain None / absent when no scene is bound.
• On bind:
  • create or reinitialize cache/resolver.
• On unbind:
  • discard cache/resolver and invalidate the world path.

File(s):

• crates/console/prometeu-drivers/src/frame_composer.rs

Test Requirements

Unit Tests

• bind stores scene_bank_id + Arc<SceneBank>.
• unbind clears active scene and cache.
• scene status reflects no-scene and active-scene states.
• camera coordinates are stored as top-left pixel-space values.

Integration Tests

• FrameComposer can resolve a scene from the pool and survive no-scene operation.

Manual Verification

• Confirm scene access remains pointer-based and no scene copies are introduced.

Acceptance Criteria

• FrameComposer binds scenes by bank id through SceneBankPoolAccess.
• Active binding stores both scene id and shared scene reference.
• Scene status is explicit.
• Camera contract is implemented as i32 top-left viewport coordinates.
• Cache/resolver lifetime follows scene bind/unbind.

Dependencies

• Depends on PLN-0017
• Source decision: DEC-0014

Risks

• Weak scene-status semantics can make no-scene behavior ambiguous in later render integration.
• If cache/resolver lifetime is not tied cleanly to binding, stale world state can leak across scene transitions.