121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
---
|
|
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.
|