--- id: PLN-0053 ticket: studio-frame-composer-syscall-and-sprite-alignment title: Composer Spec and Stdlib Surface for Sprite Emission status: review created: 2026-04-18 completed: tags: - studio - compiler - pbs - stdlib - specs - composer - sprites --- ## Objective Introduce the canonical `@sdk:composer` sprite-emission surface and remove `Gfx.set_sprite` from the normative stdlib/spec contract, exactly as required by `DEC-0027`. ## Background The runtime already moved public frame composition ownership to `composer.*` and removed the legacy public `gfx.set_sprite` path. This repository still teaches and packages sprite composition through `@sdk:gfx`, which creates ABI drift between runtime ownership and Studio-facing source surfaces. `DEC-0027` locks the following requirements for this wave: - `@sdk:composer` is the canonical Studio-side module for sprite composition. - The source shape must mirror the existing `@sdk:gfx` pattern: `LowComposer` plus public `Composer`. - `composer.emit_sprite` keeps a raw `int` return for now. - `Gfx.set_sprite` must be removed completely. - `bind_scene`, `unbind_scene`, and `set_camera` remain out of scope. ## Scope ### Included - Add `stdlib/1/sdk/composer/main.pbs`. - Add `stdlib/1/sdk/composer/mod.barrel`. - Remove `set_sprite` from `stdlib/1/sdk/gfx/main.pbs`. - Update stdlib/spec documentation to name `@sdk:composer` as the canonical sprite-composition surface. - Document that scene/camera composer calls are deferred and not part of this wave. ### Excluded - Compiler implementation changes beyond what is necessary to consume the new stdlib files. - Test fixture migration outside of spec/stdlib-focused assertions. - Runtime changes in `../runtime`. - Scene binding, scene unbinding, camera APIs, and scene-bank work. ## Execution Steps ### Step 1 - Add the reserved `@sdk:composer` module **What:** Create the reserved stdlib module for sprite emission. **How:** Add a new `sdk/composer` directory that follows the established reserved-module layout. Define `LowComposer.emit_sprite(...)` with canonical host metadata `Host(module = "composer", name = "emit_sprite", version = 1)` and the canonical capability metadata. Define a public `Composer.emit_sprite(...)` service method that forwards to `LowComposer`. **File(s):** - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/composer/main.pbs` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/composer/mod.barrel` ### Step 2 - Remove the old public sprite path from `@sdk:gfx` **What:** Delete the legacy `set_sprite` public path from the GFX stdlib module. **How:** Remove the `LowGfx.set_sprite(...)` host declaration, remove the `Gfx.set_sprite(...)` service method, and leave the remaining primitive/overlay-oriented GFX surface intact. **File(s):** - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/gfx/main.pbs` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/gfx/mod.barrel` if export adjustments become necessary ### Step 3 - Update PBS stdlib and host-binding specs **What:** Rewrite the normative docs so they stop teaching sprite composition through `@sdk:gfx`. **How:** Update the PBS specs that describe reserved stdlib modules, interface-module examples, host-binding examples, and logical stdlib mapping. Add `@sdk:composer` to the reserved-module inventory and update examples that currently import `Gfx` for host-backed illustration when those examples are used to explain sprite composition or SDK host ownership. Document that this wave covers only sprite emission, while scene/camera composer members are deferred. **File(s):** - `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` - `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md` - `docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md` - `docs/specs/compiler/18. Standard Library Surface Specification.md` - Any additional compiler/PBS spec file whose examples currently name `Gfx.set_sprite` as canonical ### Step 4 - Align syntax/interface examples with the new owner **What:** Remove spec examples that preserve the old mental model for sprite composition. **How:** Review interface-module and host-declaration examples in the PBS syntax/spec set. Keep `gfx` examples where they demonstrate primitives generically, but change any sprite-composition-oriented illustration to `composer` so the docs no longer imply that `gfx` owns frame-composition policy. **File(s):** - `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md` - `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` - `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md` ## Test Requirements ### Unit Tests - Add or update stdlib-loading tests so `@sdk:composer` resolves successfully. - Add or update PBS SDK-interface tests so `LowComposer` and `Composer.emit_sprite(...)` are part of the reserved stdlib contract. ### Integration Tests - Existing compiler/frontend integration tests that load the stdlib must pass with the new module present and the old sprite path removed. ### Manual Verification - Inspect the generated stdlib resource tree and confirm `sdk/composer` is present and `sdk/gfx` no longer exposes `set_sprite`. - Read the updated spec sections and confirm they document only sprite emission for this wave and explicitly defer scene/camera composer calls. ## Acceptance Criteria - [ ] `@sdk:composer` exists under stdlib line `1` with `LowComposer` and `Composer`. - [ ] `Composer.emit_sprite(...)` uses canonical host metadata for `("composer", "emit_sprite", 1)`. - [ ] `@sdk:gfx` no longer exposes `set_sprite`. - [ ] PBS/compiler specs name `@sdk:composer` as the canonical sprite-composition surface. - [ ] Specs do not claim that `bind_scene`, `unbind_scene`, or `set_camera` are part of this wave. ## Dependencies - Depends directly on `DEC-0027`. - Should complete before broad compiler/test/example migration so downstream work can reference the final stdlib surface. ## Risks - Spec examples may accidentally over-generalize `composer` and imply that deferred scene/camera members are already available. - Removing `set_sprite` from `@sdk:gfx` may break more frontend tests than expected if hidden fixtures still import the old API. - If capability metadata or parameter shape drifts from runtime expectations, later compiler/test work will encode the wrong ABI under a new module name.