---
id: AGD-0101
ticket: pbs-composer-blitable
title: PBS Composer-facing Blitable Contract
status: open
created: 2026-11-04
resolved:
decision:
tags: [compiler, pbs, sdk, composer, drawing]
---

## Problema

Discutir uma abstração de desenho sobre o composer, candidata ao nome
`Blitable`, sem acoplar o fechamento de `Sprite` e `Animator` a essa API.

**Worker:** Agenda Worker. **Domínio owner:** `compiler/pbs`, subdomínio
SDK/composição. **Discussão:** DSC-0099. **Estado:** agenda aberta.

O usuário pediu explicitamente separar o tema da
[AGD-0100 / DSC-0098](AGD-0100-pbs-core-sprite-and-animation.md) em 2026-11-04.
Quando o contrato amadurecer, `Sprite` e `Animator` poderão implementá-lo;
essa possibilidade não exige implementação nem antecipação do contrato agora.

## Contexto

1. `SpriteView`, na discussão de origem, oferece banco/glyph da representação
   corrente sem emitir comandos nem avançar animação.
2. `Blitable` foi proposta como trait de emissão: quem a implementa sabe chamar
   o composer com a representação e os inputs de desenho.
3. O usuário explicitou que `Composer` é SDK e não conhece `Sprite`. O desenho
   de alto nível deve chamar sua API existente externamente.
4. A Game stdlib `1` expõe em `@sdk:composer`:
   `emit_sprite(glyph_id: int, palette_id: int, x: int, y: int, layer: int,
   bank_id: int, flip_x: bool, flip_y: bool, priority: int) -> int`, com identidade
   host `("composer", "emit_sprite", 1)` e capability `composer`.
5. Posição e paleta são inputs externos na discussão de origem. Um método de
   desenho não pode introduzir armazenamento implícito desses inputs nos tipos.
6. PBS representa traits por `declare contract`/`implements`. Implementações
   pertencem ao módulo que declara o tipo concreto. O desenho não pode presumir
   extensão arbitrária de tipos por um módulo terceiro.

## Escopo e fronteiras

- Fechar responsabilidade, assinatura, resultado e composição de `Blitable`,
  ou escolher uma operação externa de desenho como alternativa.
- Preservar a independência entre consulta visual, avanço e emissão.
- Identificar módulos e direção de dependências: implementar uma operação que
  chama `Composer` cria uma dependência de execução do SDK.
- Avaliar a relação com um futuro gerenciador de draw de sprites sem incluir
  automaticamente sua implementação, filas, ordenação ou batching.
- Não alterar o contrato host, criar um novo syscall ou reabrir o modelo de
  animação como consequência implícita desta agenda.

`compiler/pbs` é owner da API PBS. `compiler` participa se houver impacto no
pipeline comum. `vm-arch`/runtime participam somente se uma proposta concreta
demonstrar necessidade de mudança de execução. Nenhuma escrita no runtime é
prevista ou autorizada por esta agenda.

## Opções e tradeoffs

| Opção | Abordagem | Benefícios | Custos e manutenção |
| --- | --- | --- | --- |
| A — Contract `Blitable` | Tipos implementam uma operação `blit` que recebe inputs de desenho e emite pelo composer. `Sprite` e `Animator` podem aderir posteriormente. | Chamador pode desenhar diferentes tipos pelo mesmo contract; cada tipo controla como obter e emitir sua representação. | Implementações assumem efeitos, dependência do SDK e preservação do resultado da emissão. Ownership PBS pode exigir mudanças nos módulos que declaram os tipos. |
| B — Operação externa que consome `SpriteView` | Uma função ou serviço de desenho consulta banco/glyph e chama a API existente do composer. | Centraliza parâmetros e tratamento de emissão, mantendo consulta e dados independentes do SDK de composição. | Cobre diretamente representações de um banco/glyph. Objetos que emitam várias imagens exigiriam outro contrato explícito. |

A diferenciação útil é entre conhecer uma representação e saber emiti-la.
Implementar as duas traits no mesmo tipo não as torna equivalentes. A escolha
deve ser demonstrada com exemplos de consumo e com a direção de dependências,
sem exigir duas abstrações que ofereçam apenas conveniências idênticas.

## Recomendação para debate

Manter `SpriteView` como consulta na discussão de origem e amadurecer esta
abstração na camada de composição. Antes de escolher A ou B, comparar chamadas
de sprite estático e animator com os mesmos parâmetros e erros do composer.

Se a intenção for que objetos saibam emitir seu próprio conteúdo, preferir A,
explicitando dependências e ownership das implementações. Se a necessidade
continuar sendo emitir um único banco/glyph consultado, B fornece um caminho
centralizado com menos obrigações nos tipos de dados. A escolha permanece aberta.

## Perguntas em aberto

- [ ] `Blitable` representa emissão de uma imagem ou pode emitir vários comandos?
  Esse escopo deve preceder o desenho de qualquer gerenciador.
- [ ] Quais parâmetros recebe: posição, paleta, layer, flips e priority
  individualmente ou por uma representação de inputs? Como manter seus custos
  e defaults explícitos?
- [ ] Como preservar o resultado `int` e os erros da emissão existente? Se houver
  múltiplos comandos, qual resultado e política para emissão parcial?
- [ ] Qual relação com `SpriteView`: uso interno opcional, dependência explícita
  ou contratos independentes? Emissão continua sem avanço de animação.
- [ ] Onde declarar o contract e implementar sua adesão, respeitando ownership
  PBS e dependências? Como evitar ciclos entre módulos?
- [ ] Como documentar e propagar a capability `composer` pelo caminho de desenho?
- [ ] Qual é o escopo de uma futura integração de `Sprite`/`Animator` e quais
  exemplos e testes comprovam a conveniência do contrato?

## Evidências para convergir

Comparar emissão de um sprite e de um animator sem avançá-lo, emissão repetida
no mesmo tick, troca de paleta/posição sem persistência e falha do composer.
Comprovar imports/exports, ownership de implements e ausência de ciclos de
dependência em compilação real antes de propor um plan de implementação.

## Referências

- [AGD-0100 — PBS Core Sprite and Animation](AGD-0100-pbs-core-sprite-and-animation.md).
- [Composer empacotado](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/composer/main.pbs).
- [PBS 5 — Manifest, Stdlib, and SDK Resolution](../../../docs/specs/compiler-languages/pbs/5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md).
- [Compiler 18 — Standard Library Surface](../../../docs/specs/compiler/18.%20Standard%20Library%20Surface%20Specification.md).

## Próximo passo sugerido

Retomar quando a discussão de composição amadurecer. Fechar escopo de emissão,
comparar A/B com exemplos e então definir assinatura, ownership e propagação.
Esta agenda não bloqueia a conclusão da AGD-0100.

## Resolução

Em aberto. O tema foi separado por solicitação do usuário; não houve escolha
final de API, transição para decision ou autorização de implementação.
