---
id: PLN-0075
ticket: render-frame-packet-boundary
title: RenderManager Core
status: done
created: 2026-05-25
ref_decisions: [DEC-0030]
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
---

## Briefing

Source decision: `DEC-0030`.

Add `RenderManager` as the runtime abstraction that closes domain buffers into typed submissions, tracks active app mode, owns transition coordination placeholders, and hands the latest complete submission to the render surface.

## Target

Runtime frame execution routes render closure through `RenderManager` without making it a host renderer or direct framebuffer writer.

## Scope

- Add the `RenderManager` module and public runtime API.
- Track active `AppMode` and frame id generation.
- Close the active domain buffer into a `RenderSubmission`.
- Enforce latest-complete-submission-wins rather than an unbounded queue.
- Add transition coordination placeholders owned by `RenderManager`.
- Provide a publication handoff to a render-surface abstraction.

## Out of Scope

- Full visual transition implementation.
- Host-specific presentation details.
- Domain buffer implementation beyond integration points.
- Render thread, GPU backend, or backend registry.

## Execution Sequence

1. Add a runtime render module that owns `RenderManager` and related state.
2. Wire `VirtualMachineRuntime` frame closure through `RenderManager`.
3. Add active app-mode routing and rejection for incoherent packet closure.
4. Add latest-complete-submission storage and replacement semantics.
5. Add a render-surface handoff interface without calling host-specific `present()` from producers.
6. Add explicit no-op transition hooks for future work.

## Acceptance Criteria

- Runtime has one frame closure authority for render submissions.
- Producers can mutate domain buffers before closure but cannot mutate the closed submission.
- `RenderManager` does not depend on desktop host types.
- Backpressure is latest-complete-submission-wins.
- App-mode routing is explicit and tested.

## Tests / Validation

- Add unit tests for frame id increment, latest submission replacement, app-mode routing, and no-op transition state.
- Add runtime integration coverage proving frame closure passes through `RenderManager`.
- Run affected crate tests.

## Risks

- Existing frame lifecycle code may assume immediate framebuffer mutation; isolate compatibility shims and remove them in later plans.
- Transition placeholders must not become hidden fade behavior.

## Affected Artifacts

- Runtime crate/modules under `crates/`
- Runtime tests