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

---
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.