IA · A2UI

Decisões

As 12 decisões de projeto do renderer A2UI da ui-nova. Todas estão aplicadas no catálogo, nos exemplos e no pacote @vueui-nova/a2ui 1.0.0. A coluna “Onde está aplicada” mostra onde conferir cada uma.

#DecisãoEscolha adotadaOnde está aplicadaOpções consideradas
D1aplicado
Nome e local do pacotePacote separado @vueui-nova/a2ui, no repositório ui-nova-a2ui.ui-nova-a2ui/packages/a2ui 1.0.0: build ES + CJS, .d.ts, CSS, catálogo, instruções e galeria incluídos. Esta doc renderiza tudo com o pacote.@vueui-nova/a2ui (separado) · vueui-nova-kit/a2ui (subpath)
D2aplicado
NúcleoAdapter Vue sobre @a2ui/web_core.O MessageProcessor, o Catalog, o DataContext e o SurfaceModel do @a2ui/web_core 0.15 cuidam de validação, surfaces, data model, @path, @call, checks e actions; o Vue lê um espelho reativo. O runtime aceita as duas grafias de checks e acessibilidade (@checks/checks, @accessibility/accessibility). Ids seguem UAX #31. A suíte de conformance oficial da v1.0 roda no pacote.Adapter sobre @a2ui/web_core · núcleo próprio
D3aplicado
catalogId / $idcatalogId e $id em https://, servidos pela doc em /a2ui/catalog/v1.json.Domínio https://uinova.walderpinheiro.com.br, configurável com A2UI_BASE_URL=https://seu-dominio no gerador do catálogo e no build da doc. O renderer também aceita o URN anterior.urn:vueui-nova-kit:a2ui:catalog:v1 (anterior) · https://<domínio-da-doc>/a2ui/catalog/v1.json
D4aplicado
Compatibilidade com o catálogo básicoCamada de compatibilidade opcional com o catálogo básico.Opção compat do runtime: o catálogo básico do web_core valida a surface e o renderer traduz TextField, CheckBox, ChoicePicker, MultipleChoice, DateTimeInput, Tabs, Modal e Icon para a ui-nova. Ligada no playground.Aceitar também catalogId básico mapeando para V* · só o catálogo ui-nova
D5aplicado
TransportesHelpers finos de transporte; A2A e AG-UI ficam como receita do host.parseJsonl, processStream (JSONL/SSE em pedaços) e connectWebSocket. A mensagem manual do playground aceita JSONL.Nenhum (host integra) · JSONL/SSE + WebSocket · A2A/AG-UI
D6aplicado
Lista do catálogo v1Catálogo v1 único e completo.73 componentes: 67 da lib e 6 primitivos. Componentes com dois valores ligados (TimeRange, TreeNavigation, Pagination) usam bind múltiplo. Os 44 restantes ficam fora do catálogo com o motivo registrado no mapeamento.Os 39 propostos · cortar ou adicionar
D7aplicado
IconName central na libFonte única de nomes de ícone (IconName).A lib exporta iconNames, iconRegistry e resolveIconName (vueui-nova-kit 1.0.0-rc.5). O IconName do catálogo sai de iconNames, e o renderer resolve os ícones, inclusive os aninhados em itens, com resolveIconName.Lib exporta um tipo/registry único · gerador continua extraindo dos .types.ts
D8aplicado
Props de cor livreProps de cor livre viram enum de tokens semânticos.dotColor, items[].color e stats[].color aceitam só primary, info, success, warning, danger ou neutral, e o renderer traduz para --v-color-*.Enum de tokens · excluir
D9aplicado
Action de changeSem action de change nos inputs: os valores vão no context quando uma action dispara.Catálogo e renderer seguem isso. Busca ao vivo usa a action própria do SearchField.Não (só context no envio) · opcional (changeAction)
D10aplicado
Table.rowsTable.rows livre, com validação semântica no renderer.O renderer emite error VALIDATION_FAILED quando falta id numa linha ou quando uma coluna não existe em nenhuma linha.Livre (additionalProperties: true) · schema por coluna derivado de columns
D11aplicado
Inputs sensíveisInputs sensíveis com opt-in explícito do host.PasswordInput e OtpInput estão no catálogo, marcados como sensíveis. Sem allowSensitive: true o runtime não os monta e responde com error. FileUpload fica fora do catálogo: arquivo não cabe no data model JSON.Nunca · opt-in do host
D12aplicado
MojibakeMojibake corrigido na lib, e o gerador falha se encontrar U+FFFD.Corrigido na lib (VCardGrid e VAutoLayoutGrid). O gerador do catálogo, o gen-a2ui da doc e o build do pacote interrompem se encontrarem U+FFFD.Corrigir já (outro agente/Walder) · deixar

Riscos e como foram tratados

#RiscoProb.ImpactoTratamento
R1@a2ui/web_core ainda é 0.x e muda de API entre minorsAltaMédioVersão exata pinada; camada fina de bridge isolando o core; conformance no CI detecta quebras; atualizar em PRs dedicados
R2web_core traz lit/preact/zod para o bundle (lit é dependência declarada)MédiaMédioSpike L0 mede; importar só subpaths de core; se inaceitável, D2 = núcleo próprio (+10–15 dias)
R3setSignalImplementation é global: conflito com outro renderer A2UI na mesma páginaBaixaMédioDocumentar: um renderer A2UI por app. Alternativa: manter preact signals e só fazer bridge por effect → shallowRef
R4Spec v1.0 recente: a conformance pode ter casos ambíguosMédiaBaixoRegistrar divergências; seguir o comportamento do renderer React como referência
R5Catálogo depende do formato de ui-nova-docs/app/generated/components/*.json (outro agente mexe na doc)MédiaMédioGerador falha alto em campo ausente; --check no CI; plano B: extrair direto dos .types.ts (já usado para enums e IconName)
R6Órfãos: updateComponents não remove componentes, que acumulam em sessões longasMédiaBaixoMontar só o alcançável a partir de root; validador avisa (já faz: 2 avisos esperados no exemplo 01); coletor de órfãos opcional no renderer
R7Props de cor livre (Badge.dotColor, StatCard.stats[].color, BarList.items[].color) permitem cor arbitráriaAlta (se nada for feito)BaixoD8: enum de tokens ou exclusão
R8$id/catalogId em URN quebra a resolução relativa de common_types.json em validadoresMédiaMédioHoje o catálogo embute o necessário; D3 recomenda https://
R9Mojibake no upstream (U+FFFD em descrições) vaza para o catálogo e para a docCerta (já ocorre)BaixoCorrigir na lib (fora do escopo deste repo; ver seção 17); o gerador poderá falhar se encontrar U+FFFD
R10LLMs inventam props ou componentesAltaMédioadditionalProperties: false, instructions, skill com catálogo gerado, error com path para autocorreção
R11Phishing via UI gerada (pedir senha/cartão)MédiaAltoInputs sensíveis fora do catálogo; UrlPolicy; host pode exibir selo "conteúdo gerado por agente"
R12Componentes da lib chamam requestAnimationFrame no setup (SSR)CertaBaixoPlayground client-only; recomendar o raf-shim (já na skill ui-nova-vue)