prometeu-runtime/discussion/workflow/agendas/AGD-0036-prometeu-hub-ui-direction.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0036	prometeu-hub-ui-direction	Agenda - Prometeu Hub UI Direction	accepted	2026-05-15			hub ui shell system-apps lifecycle design-system

Contexto

O Prometeu Hub esta entrando em uma etapa em que a Shell precisa deixar de ser apenas uma superficie funcional e passar a expressar uma identidade visual propria do Prometeu OS.

A direcao desejada e uma UI retro/minimalista inspirada em console portatil, fantasy console e Homebrew Channel: baixa resolucao, tipografia pixelada, poucos tons, bordas marcadas, componentes simples, leitura clara e navegacao confortavel por controle.

O alvo inicial nao e criar um toolkit completo. A etapa deve estabelecer a linguagem visual e um conjunto pequeno de componentes suficientes para validar a Home do Hub e o fluxo de lifecycle ja construido.

Componentes iniciais esperados:

• Channel/Card
• Button
• Panel
• Tabs
• List
• Status bar
• Footer/help bar
• Focus highlight

O Hub deve continuar respeitando a arquitetura atual:

• Hub renderiza e navega.
• Hub emite acao.
• SystemOS/Firmware executa lifecycle, task, process e window.

Portanto, a UI do Hub nao deve manipular diretamente VM, process/task lifecycle ou window ownership fora das facades do SystemOS.

Problema

A ausencia de uma direcao visual clara cria risco de o Hub virar uma UI desktop/mobile generica ou um conjunto de componentes sem coesao. Ao mesmo tempo, tentar resolver um design system completo agora pode atrasar a validacao do fluxo mais importante: Home -> abrir app Shell nativo fake -> fechar app -> retornar ao Hub.

O problema central e definir o primeiro contrato de direcao da UI: qual experiencia visual e interativa sera validada agora, quais componentes fazem parte do primeiro corte, e quais limites arquiteturais nao podem ser atravessados pela implementacao da Shell.

Pontos Criticos

• A estetica retro precisa melhorar legibilidade e identidade, nao apenas adicionar decoracao.
• A baixa resolucao deve ser tratada como linguagem de composicao, escala e foco, sem comprometer leitura.
• Navegacao por controle precisa ser primeira classe: foco visivel, ordem previsivel e acoes claras.
• A Home precisa listar canais/apps e acionar apps sem assumir posse do lifecycle.
• Apps nativos fake devem existir para validar janela, retorno, fechamento e estado de foco, mas nao devem virar arquitetura definitiva de apps.
• Os componentes iniciais devem ser pequenos o bastante para evoluir depois para um toolkit, mas nao acoplados prematuramente a um toolkit completo.
• O Hub nao pode atravessar as facades do SystemOS para manipular VM, process/task lifecycle ou ownership de window.

Opcoes

Opcao A - Slice visual minimo dentro do Hub

Criar uma primeira Home retro consistente diretamente no Hub, com componentes locais simples e dois apps Shell nativos fake para validar navegacao, abertura, fechamento e retorno.

Tradeoffs:

• Pro: entrega rapidamente a experiencia desejada e valida o fluxo real de Shell/lifecycle.
• Pro: evita desenhar um toolkit abstrato antes de entender as necessidades concretas.
• Contra: pode gerar componentes locais que precisarao ser extraidos ou reorganizados depois.
• Risco: se os componentes nao tiverem limites claros, a implementacao pode misturar visual, navegacao e chamadas de lifecycle.

Opcao B - Definir um mini toolkit antes da Home

Criar primeiro um modulo formal de componentes retro do Hub, depois construir a Home sobre ele.

Tradeoffs:

• Pro: melhora consistencia e reaproveitamento desde o inicio.
• Pro: facilita testes isolados de componentes e futuras telas do sistema.
• Contra: aumenta escopo antes de validar a experiencia principal.
• Risco: o toolkit pode cristalizar abstracoes erradas antes de haver uso suficiente.

Opcao C - Prototipo descartavel de UI antes de integrar lifecycle

Criar uma tela visual isolada, focada apenas em look and feel, sem acoplar ainda ao fluxo de lifecycle, tasks, process e windows.

Tradeoffs:

• Pro: permite iterar visualmente com baixo risco arquitetural.
• Pro: reduz chance de alterar indevidamente SystemOS durante exploracao visual.
• Contra: nao valida a parte mais importante do Hub como Shell operacional.
• Risco: o prototipo pode parecer aprovado visualmente, mas falhar quando integrado ao fluxo real.

Sugestao / Recomendacao

Seguir pela Opcao A, mas com escopo reduzido pelas respostas da agenda: implementar um slice visual minimo dentro do Hub, com Home manual em 270p, dois botoes clicaveis e dois apps Shell nativos fake.

A recomendacao e tratar essa etapa como uma direcao de Shell, nao como toolkit completo. O primeiro objetivo deve ser uma Home visualmente consistente que prove:

• dois botoes manuais para abrir ShellA e ShellB;
• ShellA como app/janela verde simples;
• ShellB como app/janela azul simples;
• abertura de app via acao emitida pelo Hub e executada pelo SystemOS/Firmware;
• fechamento de app como comando da propria app/janela;
• retorno ao Hub apos fechamento;
• estilo retro/minimalista consistente em viewport 270p;
• uso de mouse/click como input inicial;
• respeito estrito ao limite Hub -> SystemOS facade.

A extracao para toolkit, a lista/grid de canais, Tabs, Status bar e Footer/help bar devem ficar para waves futuras, guiadas por uso real dos componentes.

Perguntas em Aberto

• A Home deve priorizar grid de canais, lista vertical, ou alternar entre os dois via Tabs? na verdade eu tinha pensado em montar os dois shell fakes na mao mesmo, sem lista de canais e coisas mais sofisticadas
• Qual resolucao logica deve orientar a composicao visual desta UI: a viewport interna atual do runtime, uma escala propria do Hub, ou uma convencao derivada da Shell? a viewport toda, 270p.
• A fonte pixelada sera um asset proprio, uma fonte embutida existente, ou uma simulacao inicial via estilo/render atual? podemos ir de proprio mas temos um asset pronto em assets/pixel_operator.zip
• Quais dois apps Shell nativos fake devem existir neste primeiro corte? ShellA e ShellB, uma simples tela verde e outro tela azul.
• O fechamento de app deve ser exposto como comando da app, comando global da Shell, ou ambos? na primeira wave comando da app. toda app vai ser embrulhada em uma janela controle (como no windows)
• O footer/help bar deve mapear acoes de controle de forma fixa ou depender do item/app focado? o footer fica para uma proxima wave
• A navegacao inicial precisa suportar apenas controle/teclado, ou tambem mouse para debug/host desktop? vamos usar o mouse primeiramente (como clique)
• Quais facades do SystemOS ja sao suficientes para abrir/fechar/retornar, e quais lacunas precisam virar trabalho separado? eu acredito que estamos bem com session e lifecycle, qq coisa a gente vai implementando no caminho

Criterio para Encerrar

Esta agenda pode ser encerrada quando houver acordo sobre:

• direcao visual inicial da Shell;
• escopo exato da Home e dos dois apps fake;
• componentes minimos do primeiro corte;
• comportamento esperado de foco/navegacao;
• fronteira operacional entre Hub UI e SystemOS/Firmware;
• se a implementacao deve seguir como slice local do Hub ou exigir uma decisao separada para toolkit.

Com essas respostas, a agenda deve virar uma decisao normativa antes de qualquer plano ou edicao de codigo.

Discussao

Entrada inicial: a UI deve ter aparencia de sistema embarcado/fantasy console, proxima em espirito a Switch/Homebrew Channel, mas com estetica propria de console retro. O objetivo pratico e inaugurar a identidade visual do Prometeu OS validando a Home do Hub e o lifecycle de apps Shell nativos fake.

Analise apos respostas iniciais

As respostas mudam o primeiro corte de "Home com grid/lista de canais" para uma wave menor e mais direta: uma Shell/Home manual, em 270p, com dois apps nativos fake montados na mao. Isso reduz bastante o risco de criar um toolkit cedo demais.

O escopo recomendado para a primeira wave passa a ser:

• Hub em tela cheia 270p, com linguagem retro/minimalista consistente;
• dois affordances clicaveis para ShellA e ShellB, sem lista de canais generica;
• ShellA como janela/tela verde simples;
• ShellB como janela/tela azul simples;
• fonte pixelada propria usando o asset assets/pixel_operator.zip, se o pipeline de asset/font permitir sem abrir outro problema arquitetural;
• fechamento como comando da propria app/janela;
• mouse/click como input inicial;
• footer/help bar fora da primeira wave.

Isso enfraquece a necessidade de Tabs, List, Status bar e Footer/help bar no primeiro corte. Eles podem continuar como direcao de linguagem, mas nao devem ser criterios de aceite da wave inicial. Os componentes realmente necessarios agora sao:

• Panel ou frame de janela;
• Button/click target;
• Focus/hover/active highlight, mesmo que inicialmente guiado por mouse;
• Channel/Card apenas se os dois atalhos manuais da Home forem desenhados como cards.

Sobre as facades do SystemOS, o codigo atual ja tem pecas importantes:

• os.sessions().create_native_shell_task(app_id, title) cria process/task de Shell nativo e coloca a task em foreground.
• os.lifecycle().close_task(task_id) fecha task e marca o processo como stopped.
• os.windows().add_window(...), set_focus(...), close_window(...) e focused_window_belongs_to_task(...) permitem registrar, focar e observar janelas.
• ShellRunningStep ja retorna ao Hub quando a task fecha ou quando a janela focada nao pertence mais a task.

Mas a superficie ainda nao esta ideal para o contrato da agenda:

• o Hub atual cria janelas diretamente como WindowOwner::Hub, nao como WindowOwner::Task(task_id);
• PrometeuHub::update_shell_profile retorna apenas crash, entao nao ha ainda um resultado explicito tipo "launch ShellA/ShellB" para o Firmware transicionar para ShellRunningStep(task_id);
• sessions().create_native_shell_task cria task/process, mas nao cria uma janela owned-by-task em uma unica operacao de alto nivel;
• WindowFacade::remove_all_windows() e WindowOwner exposto no Hub facilitam um corte rapido, mas tambem permitem a UI atravessar demais o contrato de ownership se virarem padrao;
• fechar apenas a janela nao e semanticamente igual a fechar a app; para Shell nativa, o comando de fechar deve terminar em lifecycle().close_task(task_id), e a janela deve ser removida como consequencia operacional ou mantida coerente pela mesma facade.

Sugestao para fechar a lacuna sem criar toolkit:

• manter a UI local no Hub;
• introduzir um resultado de Hub mais explicito, por exemplo HubAction::LaunchNativeShell { app_id, title, kind } ou equivalente, em vez de o Hub executar tudo diretamente;
• deixar Firmware/SystemOS criar a task nativa via sessions().create_native_shell_task;
• criar a janela com WindowOwner::Task(task_id) no mesmo fluxo de launch, preferencialmente por uma facade de sessao/janela de nivel mais alto, para nao espalhar ownership manual no Hub;
• fazer o comando de fechar da app chamar lifecycle().close_task(task_id) ou emitir uma acao equivalente para o SystemOS, nao apenas remover a janela;
• manter ShellRunningStep como responsavel pelo retorno ao Hub quando a task fechar.

Com isso, a arquitetura continua: Hub renderiza/navega e emite acao; SystemOS/Firmware executa lifecycle, task, process e window.

Pontos que ainda precisam de resposta

• Confirmar se a primeira wave deve abandonar completamente grid/lista/tabs/footer, ou apenas deixar isso fora dos criterios de aceite. -- nao vamos nos ater no componentes nessa wave, mas caso seja necessario, podemos criar alguns.
• Confirmar se a Home manual tera dois cards/botoes clicaveis para ShellA/ShellB ou se as janelas fake aparecem direto na Home. -- Um btn para cada shell.
• Confirmar se assets/pixel_operator deve ser extraido/registrado como asset de fonte nesta wave ou se pode entrar como follow-up caso o pipeline de fonte nao esteja pronto. -- jah estah extraido
• Confirmar se a decisao deve exigir uma nova facade de alto nivel para launch de Shell nativa com janela owned-by-task, ou se o plano pode aceitar um uso transitorio de sessions() + windows() desde que fique encapsulado fora dos componentes visuais. -- vamos tentar usar o que temos.

Resolucao

Validada para decisao, pendente apenas de confirmacao explicita para aceitar a agenda e iniciar o artefato de decisao.