Studio with hint decorators
This commit is contained in:
+112
@@ -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.
|
||||
Reference in New Issue
Block a user