Studio with hint decorators

This commit is contained in:
2026-04-03 11:20:08 +01:00
parent f368ed94d2
commit e8ec9973cd
4 changed files with 306 additions and 1 deletions
@@ -0,0 +1,112 @@
---
id: AGD-0018
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Inline Type Hints for Let Bindings in the Studio Editor
status: accepted
created: 2026-04-03
resolved: 2026-04-03
decision: DEC-0015
tags: [studio, editor, inline-hints, inlay-hints, lsp, pbs, type-inference]
---
## Pain
O Code Editor do Studio já mostra semantic highlighting e structure guides, mas ainda não ajuda o usuário a visualizar tipos inferidos localmente em bindings como `let value = expr;`.
Isso cria duas fricções:
- o usuário perde feedback rápido sobre o tipo efetivo inferido pelo frontend;
- o editor fica atrás de IDEs que mostram hints não textuais inline para reduzir ambiguidade sem poluir o source.
## Context
- O editor atual usa `CodeArea` do RichTextFX com `StyleSpans`, gutter graphics e semantic read vindo do LSP.
- O frontend PBS já infere o tipo de `let` durante a análise de fluxo, mas esse dado não é publicado como uma surface explícita consumível pelo editor.
- O Studio hoje não possui uma camada de rendering inline equivalente a inlay hints do IntelliJ.
- O repositório já adotou a direção de presentation frontend-owned para semantic rendering, mas inlay hints de tipo parecem tocar uma fronteira diferente: parte do dado nasce no frontend/LSP, parte do rendering nasce no host editor.
## Open Questions
- [x] Qual deve ser o owner do payload do hint: frontend puro, LSP derivado, ou Studio como consumer de uma surface semântica padronizada?
Resposta: o frontend define a surface e o payload; o LSP fixa e transporta o contrato; o Studio renderiza.
- [x] O hint deve ser limitado a `let` com tipo omitido ou também cobrir `const`, parâmetros inferidos futuros e outros binders?
Resposta: quem decide quais hints existem é o frontend; se o hint vier no contrato, o Studio imprime.
- [x] O rendering deve ser inline real no fluxo do texto ou uma aproximação visual menos invasiva numa primeira wave?
Resposta: o estado final obrigatório da feature é inline real; aproximação visual só é aceitável como etapa transitória.
- [x] O hint precisa participar de hit testing, seleção, caret navigation e copy/paste, ou deve ser estritamente decorativo?
Resposta: o hint é totalmente decorativo.
- [x] Em caso de erro parcial de análise, o editor deve manter hints estáveis dos spans válidos ou desligar hints do documento?
Resposta: manter hints estáveis dos spans válidos.
## Options
### Option A - LSP Inlay Hints + Inline Rendering Real no Editor
- **Approach:** adicionar uma surface explícita de inlay hints no LSP para bindings `let` e evoluir o Studio para renderização inline não textual no fluxo do editor.
- **Pro:** modelo mais correto, escalável e alinhado com a UX esperada de IDE.
- **Con:** exige mudança estrutural maior no editor, possivelmente acima do que `CodeArea + StyleSpans` entrega nativamente.
- **Maintainability:** boa no longo prazo se virar um primitive reutilizável para hints, parameter names e outras decorações inline.
### Option B - LSP Inlay Hints + Overlay Visual Aproximado na Primeira Wave
- **Approach:** publicar hints no LSP, mas renderizar numa camada visual acoplada ao editor sem inserir segmentos inline reais no documento na primeira etapa.
- **Pro:** destrava valor ao usuário mais cedo e reduz risco inicial na infraestrutura do editor.
- **Con:** pode divergir do comportamento esperado de caret, wrapping e alinhamento fino; corre risco de parecer remendo se ficar permanente.
- **Maintainability:** aceitável apenas se explicitamente tratada como wave transitória rumo a rendering inline real.
### Option C - Não criar inlay hints; usar apenas hover/inspector
- **Approach:** expor tipo inferido via hover, status bar ou helper panel em vez de hint persistente na linha.
- **Pro:** implementação menor e compatível com a arquitetura atual.
- **Con:** não resolve o objetivo principal de feedback contínuo e local; perde ergonomia frente ao benchmark citado.
- **Maintainability:** simples, mas funcionalmente insuficiente para a dor descrita.
## Discussion
O ponto crítico não é só “mostrar texto cinza depois do nome”. A decisão precisa fechar três contratos:
1. contrato de dados:
o frontend/LSP precisa publicar um hint estável com anchor, conteúdo textual e política de exibição;
2. contrato de rendering:
o Studio precisa decidir se quer suportar uma primitive geral de adornos inline ou apenas uma solução pontual para `let`;
3. contrato de interação:
hints não podem contaminar o conteúdo real do documento, mas também não podem quebrar leitura, seleção, scroll ou layout.
O risco de uma solução ad hoc é repetir o problema já visto em outras áreas: valor imediato, mas sem primitive reusável e com alto custo para generalizar depois.
Ao mesmo tempo, exigir inline rendering “perfeito” logo de saída pode atrasar demais uma ergonomia que já tem valor alto para PBS.
Direção já aceita nesta agenda:
1. ownership e contrato:
o frontend oferece a surface de hints, o LSP a transforma em contrato estável de transporte/consumo, e o Studio apenas renderiza;
2. policy de conteúdo:
o Studio não escolhe quais hints existem; se o frontend publicar hint válido no contrato, o host imprime;
3. rendering target:
a feature só fecha corretamente quando o hint for inline real; qualquer overlay aproximado deve ser explicitamente tratado como etapa transitória;
4. interaction model:
hints são decorativos e não alteram texto, seleção, copy/paste ou modelo documental;
5. degradação parcial:
hints válidos devem sobreviver mesmo quando o restante da análise do documento estiver parcialmente degradado.
## Resolution
Recomendação inicial:
- seguir com uma discussion owner de `studio/editor`;
- tratar o problema como uma capability formal de `inlay hints` do editor, não como uma exceção do PBS;
- modelar o contrato como frontend-defined, LSP-enforced/transported, Studio-rendered;
- manter o Studio host-agnostic quanto ao conteúdo do hint;
- aceitar waves transitórias apenas se convergirem explicitamente para inline real;
- preservar hints válidos sob degradação parcial de análise.
Próximo passo sugerido:
- derivar um `plan` que separe explicitamente:
contrato FE/LSP,
primitive de rendering no Studio,
wave transitória opcional,
testes de degradação parcial e comportamento decorativo.