prometeu-studio/discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md

id	ticket	title	status	created	completed	tags
PLN-0053	studio-frame-composer-syscall-and-sprite-alignment	Composer Spec and Stdlib Surface for Sprite Emission	review	2026-04-18		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.