prometeu-studio/discussion/workflow/agendas/AGD-0029-studio-scene-workspace.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0029	studio-scene-workspace	Scene Workspace for SCENE Authoring	abandoned	2026-04-14	2026-04-14	DEC-0026	studio workspace scene tilemap asset runtime-alignment

Pain

O Studio ainda nao possui um workspace dedicado para autoria e inspecao de scenes.

Sem esse workspace:

• o Studio nao oferece uma experiencia autoral propria para scenes como dominio editorial;
• a equipe fica sem uma superficie visual para editar o artefato intermediario de scene que depois alimenta o asset SCENE;
• o Studio perde a chance de ensinar o modelo correto de scene como asset versionado, com quatro layers e contrato proprio;
• a futura expansao para camera bounds, lights, AABB e outros aspectos acaba sem composicao clara desde a primeira wave.

Context

Domain owner: studio

Owner documental esperado:

• docs/specs/studio

Cross-domain impact:

• ../runtime para o contrato canonico de SCENE, SceneBank e SceneLayer;
• Assets workspace apenas na fronteira de criacao/descoberta do asset SCENE.

Rastro relevante ja existente:

• o runtime ja convergiu para SCENE como payload binario versionado;
• SceneBank e o modelo canonico carregado no runtime possuem exatamente 4 layers;
• cada SceneLayer possui seu proprio TileMap, com dimensoes independentes;
• viewport cache, camera movement e renderer nao fazem parte do modelo canonico de authoring do scene;
• o Assets workspace ja define o padrao de navegador customizado, asset-first e path-aware, que deve inspirar a navegacao do Scene Workspace sem virar um file explorer generico.

Escopo inicial solicitado pelo usuario:

• novo workspace chamado Scene Workspace;
• navegador de scenes na lateral esquerda, similar ao Assets workspace;
• o Scene Workspace trabalha com scenes como scenes, nao como assets;
• a scene editada no workspace vira um artefato intermediario de autoria;
• o Scene Workspace pode criar uma scene nova e, ao fazer isso, criar tambem o asset SCENE correspondente;
• o Assets workspace pode criar um asset SCENE, mas nao pinta mapa nem faz configuracoes editoriais da scene;
• depois de criado, o trabalho de conteudo e configuracao da scene fica delegado ao Scene Workspace;
• cada scene como mapa de 4 layers;
• cada layer com largura e altura independentes, em estilo similar ao Tiled;
• faixa superior com abas de aspectos da ferramenta;
• primeira aba: Tilemap;
• aba Tilemap com mapa no centro;
• painel superior direito com dimensoes e detalhes do tilemap;
• painel inferior direito com aquarela/paleta de tiles para selecao e pintura;
• tileset vindo de assets, com suporte a selecionar qualquer glyph bank ou marcar glyph banks como tileset apenas no Studio;
• outras abas futuras previstas: camera boundaries, lights, AABB, etc., mas fora da primeira wave.

Open Questions

• O Scene Workspace deve abrir scenes apenas por seu catalogo proprio, ou tambem aceitar handoff contextual quando um asset SCENE for criado no Assets?
• Qual identidade o navegador da esquerda deve priorizar: scene authoring artifact, path do projeto, ou algum catalogo editorial proprio do Scene Workspace?
• O Studio deve tratar a edicao de scene como staged editing com apply/reset, ou como documento editavel com save integrado?
• Como o Studio relaciona uma scene autoral com o asset SCENE correspondente: referencia por path, UUID proprio do artefato intermediario, ou binding mediado por metadata do Studio?
• Como o Studio seleciona o glyph bank usado como tileset em cada layer ou scene: referencia editorial na scene ou vinculacao resolvida pelo proprio Scene Workspace?
• O contrato do runtime ja determina metadados suficientes por layer para authoring inicial, ou o Studio precisara propor extensoes antes da implementacao do workspace?
• Como representar tiles vazios, brush, fill e selecao sem colidir com a semantica canonica de tile vazio ja aceita no runtime?
• A primeira wave deve permitir apenas pintura bruta por tile, ou ja precisa incluir ferramentais como marquee, bucket, eyedropper e multi-layer visibility/lock?
• As abas futuras devem ser somente placeholders estruturais agora, ou a wave inicial deve expor apenas a aba Tilemap para nao sugerir suporte inexistente?

Options

Option A - Scene Workspace como workspace dedicado no shell

• Approach: Criar um workspace proprio de Scene Workspace, com navegador de scenes na esquerda, header com tabs de aspecto e composicao interna especializada por aba.
• Pro: Da visibilidade de primeira classe a SCENE, cria uma arquitetura clara para expansao futura por aspectos e preserva a fronteira entre shell e detalhe operacional do workspace.
• Con: Introduz mais uma entrada no shell e exige decidir como ele se relaciona com a descoberta de assets no fluxo ja existente.
• Maintainability: Strong, porque estabiliza ownership e composicao desde a primeira wave.

Option B - editor especializado dentro do Assets workspace

• Approach: Manter tanto o asset SCENE quanto a edicao do artefato intermediario dentro do Assets, usando a selecao do asset como ponto de entrada do editor.
• Pro: Reaproveita navegacao asset-first existente e concentra toda a historia de scene em um unico lugar.
• Con: Colapsa duas naturezas diferentes em uma mesma superficie: gerenciamento de asset packer-facing e authoring de scene como conteudo editorial.
• Maintainability: Weak, porque incentiva o Assets workspace a absorver ownership que nao e dele.

Option C - workspace autoral proprio com integracao via asset

• Approach: O Scene Workspace edita e cria a scene como dominio proprio; o Assets workspace apenas pode criar/mostrar o asset SCENE e delega a autoria da scene para o Scene Workspace.
• Pro: Separa claramente authoring editorial de scene da gestao asset-first do Assets, sem deixar o Assets absorver o editor.
• Con: Exige fechar um contrato de binding entre scene autoral e asset SCENE, alem de definir handoff entre os dois workspaces.
• Maintainability: Strong, porque o Scene Workspace permanece owner do conteudo e o Assets fica restrito a criacao/gestao do asset.

Discussion

O ponto mais importante desta discussao nao e apenas layout. O runtime ja tem um contrato canonico claro o bastante para impor restricoes no editor:

1. o payload final SCENE nao e um documento arbitrario; e um asset binario versionado com 4 layers fixos;
2. cada layer possui TileMap proprio e, portanto, o editor nao deve assumir um canvas unificado com dimensoes compartilhadas;
3. viewport cache, camera drift e outras preocupacoes de renderizacao nao pertencem ao modelo canonico do scene workspace;
4. o Scene Workspace nao deve editar o payload final do asset diretamente; ele deve editar um material intermediario proprio;
5. o tileset precisa se alinhar aos glyph banks que ja existem como assets, sem criar um segundo sistema de tiles paralelo no Studio.

Tambem existe uma decisao estrutural de produto a ser tomada cedo:

• se o Scene Workspace for somente um modo interno do Assets, o Studio arrisca repetir o anti-pattern de transformar um workspace asset-first em container generico de editores;
• se ele nascer como workspace proprio, a arquitetura de abas por aspecto e a expansao futura para boundaries/lights/AABB ficam mais honestas;
• como a scene autoral nao e o proprio asset, a costura correta passa por um contrato entre artefato intermediario e asset SCENE, nao por subordinacao de um workspace ao outro;
• o Assets pode oferecer criacao de asset SCENE, mas a autoria e manutencao do conteudo da scene devem ser delegadas ao Scene Workspace.

Outro ponto aberto e a semantica do tileset:

• permitir qualquer glyph bank maximiza flexibilidade e reaproveitamento;
• exigir uma tag editorial de "tileset" melhora discoverability e reduz selecao invalida;
• uma combinacao pode ser a melhor direcao: qualquer glyph bank tecnicamente valido, com tagging opcional no Studio para curadoria UX.

Por fim, a primeira wave precisa resistir a overreach:

• a aba Tilemap ja e um escopo suficientemente grande;
• placeholders de abas futuras so fazem sentido se a shell structure realmente precisar reservar esse contrato agora;
• caso contrario, placeholders podem comunicar suporte inexistente e gerar pressao artificial sobre uma decision ainda nao tomada.

Convergence pass - recommended answers for the open questions

1. Workspace proprio ou extensao do Assets

Recomendacao: Scene Workspace deve existir como workspace shell-level proprio e nao deve ser subordinado ao Assets.

Motivo:

• o shell ja foi especificado para hospedar workspaces independentes;
• o Assets workspace deve continuar asset-first e didatico, nao virar um host generico de editores;
• a scene autoral tem natureza propria e vira um artefato intermediario, nao o payload final do asset.
• o Scene Workspace deve aceitar tanto abertura por seu proprio navegador quanto handoff contextual quando o Assets criar um asset SCENE.

2. Identidade do navegador da esquerda

Recomendacao: a identidade primaria deve ser a scene autoral, nao o asset SCENE.

Contexto de apoio:

• path continua visivel como contexto secundario;
• o workspace pode precisar de um identificador editorial proprio para a scene intermediaria;
• o asset SCENE correspondente pertence ao Assets workspace e deve aparecer apenas como vinculacao ou estado derivado.

Direcao adicional:

• o navegador deve ser scene-first;
• path de projeto entra como contexto secundario;
• o asset vinculado pode aparecer como badge, status ou acao contextual, mas nao como unidade primaria de navegacao.

3. Modelo de edicao e persistencia

Recomendacao: a primeira wave deve tratar a scene como documento/artefato autoral com save proprio, separado de qualquer fluxo de criacao ou gestao do asset no Assets.

Motivo:

• o usuario deixou explicito que o Scene Manager trabalha sobre um artefato intermediario proprio;
• o Scene Workspace e owner do conteudo da scene;
• o Assets pode continuar com fluxos proprios para criacao/gestao de asset, mas sem absorver a autoria da scene;
• misturar save do conteudo autoral com apply do asset apagaria a fronteira entre autoria e empacotamento.

Direcao adicional:

• o Scene Workspace salva o artefato intermediario;
• criar ou vincular o asset SCENE e um passo de integracao entre workspaces, nao a mesma operacao de salvar a scene.

4. Binding entre scene autoral e asset SCENE

Recomendacao: o binding deve ser mediado por metadata do Studio, nao por inferencia de path como regra primaria.

Motivo:

• path pode mudar por rename ou reorganizacao de projeto;
• a scene autoral precisa de identidade mais estavel do que localizacao fisica;
• o Assets e o Scene Workspace precisam compartilhar um vinculo explicito sem colapsar um no outro.

Direcao adicional:

• a scene autoral deve ter um identificador proprio;
• o asset SCENE correspondente deve referenciar esse identificador, ou vice-versa, por um contrato editorial do Studio;
• path continua relevante como localizacao de arquivo, nao como ancora semantica principal do binding.

5. Selecao de glyph bank como tileset

Recomendacao: a scene autoral deve poder referenciar glyph banks como tilesets em nivel editorial, e essa escolha deve ser owned pelo Scene Workspace.

Motivo:

• o runtime ja referencia glyph_bank_id por layer, nao um tipo separado de tileset;
• criar um subtipo obrigatorio de asset agora inventaria uma regra de produto nao exigida pelo contrato canonico;
• uma tag editorial ainda pode melhorar descoberta sem restringir um contrato que hoje e genericamente GLYPH.

Direcao adicional:

• a escolha de glyph bank por layer ou por scene deve ser resolvida no Scene Workspace;
• o Assets nao deve redefinir tileset da scene;
• tags editoriais opcionais no Studio podem melhorar filtragem e discoverability.

6. Metadados por layer

Recomendacao: para a primeira wave, o contrato do runtime parece suficiente para authoring inicial de tilemap.

Rastro observado no runtime:

• SceneLayer ja possui active;
• glyph_bank_id;
• tile_size;
• motion_factor;
• tilemap com width, height e tiles.

Conclusao:

• isso e suficiente para uma aba Tilemap com visibilidade por layer, dimensoes independentes, tileset por layer e pintura;
• camera bounds, lights e AABB ficam corretamente fora dessa wave e devem motivar metadados adicionais apenas quando virarem tema de nova decision.

7. Tile vazio, brush e pintura

Recomendacao: o Studio deve respeitar a semantica canonica de presenca explicita por tile.

Consequencias:

• glyph_id = 0 deve permanecer valido;
• apagar um tile deve atuar sobre o bit/estado de presenca (active = false), nao sobre um glyph magico;
• brush, eyedropper e futuras ferramentas devem operar sobre active, glyph_id, palette_id, flip_x e flip_y.

8. Ferramentas da primeira wave

Recomendacao: limitar a primeira wave a pintura basica, apagador, seletor de tile e controles de layer como visibilidade/foco.

Excluir agora:

• marquee complexo;
• bucket fill;
• multi-select estrutural;
• automacoes de brush avancadas.

Motivo:

• o objetivo da wave 1 e provar o fluxo canonico de scene authoring;
• ferramentas mais ricas multiplicam edge cases antes de estabilizar modelo, persistencia e UX base.

Direcao adicional:

• multi-layer visibility e layer focus entram na wave 1;
• lock, marquee, bucket, flood fill e automacoes avancadas ficam explicitamente fora.

9. Abas futuras agora ou depois

Recomendacao: o workspace deve nascer com uma faixa superior de tabs, mas expor apenas a aba Tilemap na primeira wave.

Motivo:

• a estrutura de tabs faz parte da composicao arquitetural pedida;
• tabs placeholder para Camera, Lights ou AABB sugeririam suporte que ainda nao existe;
• reservar o componente estrutural agora facilita expansao futura sem mentir sobre cobertura funcional.

Resolution

Abandoned on 2026-04-15 by explicit user request.

The accepted direction captured here was superseded before implementation.

Follow-up direction:

• abandon the dedicated Scene Workspace approach;
• open a new discussion for a Tiled parser;
• manage the resulting authoring flow from Assets through a new asset type.

Direcao recomendada: convergir para Option C, em que o Scene Workspace e um workspace autoral de primeira classe no shell e o Assets workspace permanece apenas como superficie asset-first capaz de criar ou exibir o asset SCENE, sem editar o conteudo da scene.

Essa recomendacao parte de quatro principios:

1. a scene autoral e um artefato intermediario proprio do dominio Scene Workspace;
2. o asset SCENE pode ser criado tanto pelo Scene Workspace quanto pelo Assets, mas o conteudo da scene e owner do Scene Workspace;
3. o Assets nao pinta mapa nem faz configuracoes editoriais da scene;
4. o binding entre scene autoral e asset SCENE deve ser explicito e estavel;
5. a primeira wave deve fechar apenas o aspecto Tilemap, sem fingir maturidade para camera bounds, lights ou AABB.

Proximo passo sugerido: transformar esta agenda em uma decision que feche:

1. Scene Workspace como workspace shell-level proprio e owner do artefato intermediario de scene;
2. identidade primaria do workspace pela scene autoral, nao pelo asset;
3. save proprio da scene autoral no Scene Workspace, separado da criacao/gestao do asset no Assets;
4. contrato de binding entre scene intermediaria e asset SCENE;
5. glyph banks como tilesets validos por contrato, com eventual curadoria editorial no Studio;
6. aba unica Tilemap na primeira wave, preservando a shell de tabs para expansao futura;
7. propagacao necessaria para specs do studio, incluindo a pequena extensao do Assets para criacao de scene asset e o ownership do Scene Workspace sobre a autoria da scene.