---
id: PLN-0055
ticket: studio-frame-composer-syscall-and-sprite-alignment
title: Repository Fixtures, Examples, and Cleanup for Composer Sprite Migration
status: review
created: 2026-04-18
completed:
tags:
  - studio
  - examples
  - fixtures
  - lsp
  - composer
  - sprites
---

## Objective

Remove repository-visible usage of `Gfx.set_sprite` and migrate examples, fixtures, and supporting tests to the new `@sdk:composer` sprite path.

## Background

`DEC-0027` requires broad propagation across tests, fixtures, and examples, with no compatibility path. Even after stdlib/spec/compiler work lands, stale sample code or support fixtures would continue teaching the retired API and could hide incomplete migration.

## Scope

### Included
- Migrate repository sample projects that still call `Gfx.set_sprite`.
- Update LSP or support fixtures that rely on reserved SDK import examples where the new module is more appropriate.
- Sweep repository-owned callsites for stale references to the old sprite path.
- Add or update verification to ensure no repository-visible `Gfx.set_sprite` usage remains.

### Excluded
- Third-party or external downstream projects outside this repository.
- Runtime test suites in `../runtime`.
- New scene/camera composer scenarios.

## Execution Steps

### Step 1 - Migrate sample projects to `@sdk:composer`

**What:**
Rewrite repository examples that still use the old sprite path.

**How:**
Update `test-projects/main` to import `Composer` from `@sdk:composer` and replace all `Gfx.set_sprite(...)` calls with `Composer.emit_sprite(...)`. Keep `Gfx` imports only for the remaining primitive calls such as `clear(...)`. Review `test-projects/fragments` and migrate only if it contains sprite-composition examples or should demonstrate the new reserved module inventory.

**File(s):**
- `test-projects/main/src/main.pbs`
- `test-projects/fragments/src/main.pbs`

### Step 2 - Update LSP/import fixtures where the reserved SDK inventory is exercised

**What:**
Keep non-compiler support tests aligned with the new reserved-module set.

**How:**
Review LSP fixtures that use `@sdk:gfx` imports as representative SDK examples. Leave primitive-oriented examples intact when they are still valid, but add or switch coverage where the test should reflect the new reserved `@sdk:composer` module being part of the environment.

**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/LspServiceImplTest.java`

### Step 3 - Run a repository sweep for stale public sprite references

**What:**
Ensure the old API is not still visible in repository-owned artifacts.

**How:**
Search for `Gfx.set_sprite`, `LowGfx.set_sprite`, and sprite-specific `@sdk:gfx` examples. Remove or migrate every repository-owned occurrence that is part of the normative surface, examples, fixtures, or tests. Keep pure `@sdk:gfx` primitive usage where it remains valid.

**File(s):**
- `docs/**`
- `prometeu-compiler/**`
- `prometeu-lsp/**`
- `test-projects/**`

### Step 4 - Add final regression verification for no-compat policy

**What:**
Create a final gate that makes legacy leakage easy to detect.

**How:**
Add or document a repository grep-based verification step in the execution notes or test workflow so implementation can confirm there are no remaining repository-owned `Gfx.set_sprite` references once the migration is complete.

**File(s):**
- Verification notes in the implementation PR or relevant test documentation

## Test Requirements

### Unit Tests

- Any support or fixture tests touched by the migration must continue to pass with the new imports.

### Integration Tests

- Repository sample projects used by compiler or integration flows must build/analyze successfully after migration.

### Manual Verification

- Run a repository-wide search for `Gfx.set_sprite` and verify zero remaining repository-owned hits.
- Run a repository-wide search for sprite-specific `@sdk:gfx` examples and verify they were either migrated or intentionally retained only for primitive usage.

## Acceptance Criteria

- [ ] Repository sample code no longer uses `Gfx.set_sprite`.
- [ ] No repository-owned fixture or example teaches the retired public sprite API.
- [ ] Any retained `@sdk:gfx` usage is primitive/overlay-oriented rather than sprite-composition-oriented.
- [ ] A repeatable verification step exists to confirm no-compat cleanup.

## Dependencies

- Depends on `PLN-0053` for the final stdlib surface.
- Depends on `PLN-0054` for compiler/frontend acceptance of the new imports and calls.
- Depends directly on `DEC-0027`.

## Risks

- Repository examples may mix primitive and sprite usage, making partial migration easy to miss.
- LSP fixtures may not strictly require composer coverage, so the cleanup can be under-scoped unless reviewed deliberately.
- Without a final sweep, legacy references can survive in docs or examples even after tests pass.