---
id: PLN-0101
ticket: real-render-worker-establishment
title: Remove Immediate Gfx2D and GfxUI Syscall Rendering
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, gfx, syscalls, renderer]
---

## Objective

Make `gfx2d.*` and `gfxui.*` syscalls buffer commands only, without mutating the framebuffer immediately.

## Background

`DEC-0032` requires framebuffer mutation to occur through render submission consumption/publication, not inside VM syscall dispatch. This is required before render can run independently.

## Scope

### Included

- Remove `hw.gfx_mut().*` immediate draw calls from VM dispatch for `gfx2d` and `gfxui`.
- Add regression tests for `gfx2d.clear` and `gfx2d.draw_text`.
- Update tests that assumed immediate pixel mutation.

### Excluded

- Do not remove `GfxBridge`.
- Do not migrate composer in this plan.
- Do not implement worker.

## Execution Steps

### Step 1 - Remove immediate Game gfx writes

**What:** Delete direct `hw.gfx_mut()` rendering in `Gfx*` syscall handlers.
**How:** Keep command buffering into `gfx2d_commands`.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.

### Step 2 - Remove immediate Shell UI writes

**What:** Delete direct `hw.gfx_mut()` rendering in `GfxUi*` syscall handlers.
**How:** Keep command buffering into `gfxui_commands`.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.

### Step 3 - Add regression tests

**What:** Prove syscalls do not affect pixels until publication.
**How:** Tests for `gfx2d.clear` and `gfx2d.draw_text` should inspect command buffers and frame publication.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`.

## Test Requirements

### Unit Tests

- `gfx2d.clear` buffers only.
- `gfx2d.draw_text` buffers only.
- Shell UI commands buffer only.

### Integration Tests

- Stress cartridge still renders after frame publication.

### Manual Verification

- `rg "gfx_mut\\(\\).*draw|gfx_mut\\(\\).*clear|gfx_mut\\(\\).*fill" dispatch.rs` returns no immediate render calls.

## Acceptance Criteria

- [ ] Gfx syscalls no longer mutate framebuffer immediately.
- [ ] Pixels change only after render submission publication.
- [ ] Tests updated to the new contract.

## Dependencies

- `PLN-0100`.

## Risks

- Debug workflows may have relied on immediate drawing. Tests must make the new frame boundary explicit.