prometeu-studio/discussion/workflow/plans/PLN-0055-composer-fixtures-examples-and-repo-cleanup.md

id	ticket	title	status	created	completed	tags
PLN-0055	studio-frame-composer-syscall-and-sprite-alignment	Repository Fixtures, Examples, and Cleanup for Composer Sprite Migration	review	2026-04-18		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.