@praxisui/dynamic-fields 9.0.65 → 9.0.67

package/docs/color-components-evolution-plan.md

@@ -0,0 +1,369 @@
+---
+title: Evolucao dos componentes de cor
+description: Plano orientado por evidencias para elevar Color Input, Color Picker e Inline Color Label a uma experiencia corporativa governada.
+---
+
+# Evolucao dos componentes de cor
+
+## Objetivo
+
+Evoluir a familia de cores do Praxis como materializacao de decisoes semanticas governadas, e nao como um conjunto de seletores de valores isolados. O alvo inclui paridade com experiencias corporativas de referencia e diferenciais proprios de authoring por IA, governanca, auditoria e explicabilidade.
+
+## Fonte canonica e mapa de impacto
+
+| Responsabilidade                                            | Fonte canonica                                                                              | Consumidores e derivados                               |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Decisao de paleta, ciclo de simulacao/publicacao e projecao | `praxis-config-starter`, decisao `design_token_palette` e artefato `governed-color-palette` | `@praxisui/core`, hosts, docs e receitas               |
+| Transporte, cache, ETag e modelos TypeScript                | `@praxisui/core`                                                                            | Dynamic Fields, Metadata Editor e demais libs publicas |
+| Runtime de formulario e filtro inline                       | `@praxisui/dynamic-fields`                                                                  | Dynamic Form, Table, CRUDs e apps host                 |
+| Authoring estruturado e round-trip de metadata              | `@praxisui/metadata-editor`                                                                 | Page Builder, editores e ferramentas assistidas por IA |
+| Prova operacional                                           | Color Lab e `praxis-api-quickstart`                                                         | E2E, exemplos e documentacao publica                   |
+
+Risco de breaking change: medio para alteracoes de tipos exportados e de semantica de commit; alto para troca de identificadores de tokens ou do artefato publicado. Novos controles visuais internos, mantendo os contratos atuais, tem risco baixo.
+
+## Inventario de aderencia
+
+### `ja-suportado-so-ux`
+
+- O contrato atual ja transporta paleta local, recentes, formatos e politicas de commit; faltava apresentar essas capacidades de forma consistente na vitrine e nos editores.
+- Modos de inclusao, edicao, visualizacao e presentation ja pertencem ao runtime do formulario; o laboratorio agora os exercita sem criar um segundo contrato.
+- O inline ja separa rascunho de valor comprometido e preserva IDs semanticos; a cor permanece um canal auxiliar.
+- O editor ja possui infraestrutura de secoes, estado sujo, aplicar, salvar e cancelar; a paleta passou a usar editor estruturado nessa infraestrutura.
+
+### `ja-suportado-mal-nomeado-ou-mal-materializado`
+
+- Propriedades sem implementacao observavel, como adaptacao avancada e canal de cor arbitrario, apareciam como capacidades authoraveis. Elas foram retiradas do catalogo/editor ate existir comportamento real.
+- Tokens CSS eram aceitos, mas o picker podia materializa-los como literal ao confirmar. O runtime agora preserva a referencia completa, inclusive fallback.
+- Fechar por Escape ou backdrop encerrava o painel sem restaurar o rascunho. O picker agora aplica a mesma semantica de cancelamento explicito.
+
+### `suportado-parcialmente`
+
+- Tokens e fallback CSS: identidade preservada, mas ainda faltam busca, agrupamento, aliases, origem e grafo de uso.
+- Contraste: a projecao governada valida evidencias publicadas, mas o picker ainda nao oferece matriz interativa para multiplas superficies, tamanhos e pesos de texto.
+- Responsividade: popovers cabem em viewport estreita, mas ainda nao ha modo adaptativo de tela cheia nem estrategia consistente de teclado virtual.
+- Densidade, recentes e historico: existem em partes da familia, sem politica compartilhada de persistencia, privacidade e limite.
+- A paleta e versionada e filtrada por finalidade; variantes de tema, alto contraste e escopos organizacionais ainda nao formam uma familia governada completa.
+
+### `lacuna-real-de-contrato`
+
+- A ausencia de uma projecao publicada de paleta governada era uma lacuna real. Ela foi coberta pelo artefato `governed-color-palette`, com `paletteKey`, versao, ETag, finalidades, tokens e evidencias de contraste.
+- Variantes correlacionadas de uma mesma decisao (`light`, `dark`, alto contraste, marca/unidade/tenant) ainda precisam de identidade canonica e regras de compatibilidade. Nao devem ser inventadas em metadata de campo.
+- Politicas corporativas de contraste por contexto de uso, com excecao aprovada e validade temporal, ainda precisam ser modeladas na decisao governada; um warning local no picker nao e fonte de verdade suficiente.
+- Importacao/exportacao interoperavel de design tokens exige contrato de proveniencia, namespace, resolucao de aliases e diagnosticos. Aceitar JSON arbitrario no componente criaria uma segunda fonte de verdade.
+
+## Evidencia funcional atual
+
+O Color Lab cobre os tres controles canonicos e o baseline legado:
+
+- Color Input com digitacao, amostras, validacao, clear e commit imediato;
+- Color Picker com rascunho, cancelar, aplicar, transparencia, formato e tokens governados;
+- Inline Color Label com multisselecao, payload semantico, aplicar/descartar e uso em filtro;
+- editores de metadata para os tres controles, incluindo paleta visual e referencia governada;
+- materializacao por finalidade, exibindo `paletteKey`, versao, ETag, owner e evidencias;
+- viewport estreita, navegacao por setas, Escape, lifecycle de formulario e reset.
+
+## Roadmap recomendado
+
+### Fase 0 — fundamento governado (implementado, com validação por fronteira)
+
+- publicar a decisao canonica e sua projecao imutavel;
+- integrar cache/ETag e precedencia governada no runtime;
+- preservar token, fallback, rascunho e payload semantico;
+- fornecer editor visual com round-trip e laboratorio E2E;
+- remover capacidades declaradas sem comportamento real.
+
+Gate: testes focais das libs, prova HTTP preview-to-publication, contratos do registry e jornada E2E do Color Lab.
+
+A revisão posterior identificou e corrigiu seis regressões: fallback ambíguo, cor inline atribuída por posição, ETag fixado ignorado em HTTP 304, colisão da identidade de publicação entre versões, comparação incorreta de versões Java e aceitação de cores CSS inválidas. O corte tem testes focais para essas regressões, publicação HTTP v1 → v2 com leitura histórica e validação focal da V62 em PostgreSQL. A interação no navegador também revelou e corrigiu uma seção duplicada no editor por diferença de acentuação e um input nativo que podia reter o rascunho descartado após Escape e reabertura rápida.
+
+O Color Lab sem query usa uma fixture local explicitamente identificada. A rota `/color-lab?paletteKey=<chave>&version=<versão>` conecta os três controles ao Quickstart em `http://127.0.0.1:8088`; omitir `version` consulta a publicação mais recente. Falhas HTTP ou referências inválidas não acionam a fixture como fallback. Os editores mantêm metadata em memória: salvar não publica uma decisão nem prova persistência remota da configuração.
+
+A jornada integrada `GovernedColorPaletteBrowserPostgresTest` passou no Quickstart real, com Chromium, autenticação do Governance Lab, CORS/Origin, segregação de autor/aprovador/publicador, CSRF habilitado e PostgreSQL descartável. Ela comprova publicação v1 → v2, 304 observado na rede, preservação da leitura histórica, seleção inline, edição de versão/ETag em viewport estreita e falha fechada sem sessão. O teste também verifica as aprovações persistidas e encerra o host/banco que criou. Instruções e limites estão em `praxis-api-quickstart/docs/governed-color-palette-browser-proof.md`.
+
+Essa integração revelou outro defeito do host: `CsrfCookieFilter` estava registrado como servlet filter e também na cadeia de segurança. A remoção do registro duplicado mantém sua execução exclusivamente após `CsrfFilter`, permite materializar o cookie XSRF e restaura a troca autenticada de identidade sem desligar a proteção. A mudança reutiliza o contrato existente (`ja-suportado-mal-nomeado-ou-mal-materializado`), sem criar contratos públicos de cor.
+
+Limites: a prova usa migrations canônicas focais de regras com pré-requisitos mínimos de domínios externos; não certifica upgrade completo do Config/pgvector, banco operacional integral, IdP corporativo ou deployment publicado. Não há percentual de conclusão ou certificação de paridade com concorrentes derivável apenas da contagem de testes.
+
+Validação local do corte de correção (2026-09-05):
+
+- 16/16 cenários Playwright do Color Lab, incluindo viewport estreita e revisão das capturas do inline/editor;
+- 36 testes focais Angular: serviço de paletas (12), inline (15), picker (6) e configuração do editor (3);
+- 106 testes focais de contrato, projeção, controller, ciclo de decisão e estrutura da migration no Config;
+- uma prova de migrations e constraints em PostgreSQL e uma jornada HTTP de publicação no Quickstart;
+- build da cadeia de bibliotecas e consumidor Dynamic Form; composição MatSelect sem dívida declarada;
+- registry regenerado e sincronizado; catálogo sem erros/avisos e 20/20 contratos de authoring aprovados.
+
+Esse recorte não equivale a build de produção do aplicativo completo, auditoria com leitor de tela ou publicação das bibliotecas.
+
+Validação adicional da integração local (2026-09-05):
+
+- 7 testes unitários da página: fonte local/HTTP, identidade nos três consumidores, última versão, erros sem fallback, referência inválida e paridade de chaves pt-BR/en-US;
+- 1 jornada Chromium–Quickstart–PostgreSQL, com capturas desktop/editor estreito inspecionadas;
+- 28 testes focais de segurança do host: CSRF, CORS, Origin, rate limit e políticas de acesso;
+- 16 cenários Playwright da vitrine local reexecutados após a integração;
+- validação de frontmatter das docs alteradas e composição MatSelect aprovadas; avisos documentais preexistentes não foram tratados como erros deste corte.
+
+### Fase 1 — paridade essencial de selecao
+
+Incremento iniciado em 2026-09-06 (`ja-suportado-mal-nomeado-ou-mal-materializado`): edição HEX/RGB sincronizada, validação de canais, conversão sRGB pura com round-trip HSL e alpha aplicado corretamente. Escape/cancelamento restauram os valores, alterações diretas do campo são carregadas ao abrir e CSS inválido não reutiliza a cor anterior do probe. Tokens continuam referências até edição explícita dos canais; sua opacidade não é alterada localmente. O painel respeita a largura real do menu e as setas pertencem aos inputs. Não foram adicionados tipos ao barrel, paths de metadata ou operações de IA.
+
+Segundo incremento em 2026-09-06: núcleo RGB↔HSL/HSV compartilhado, canais HSL/HSV em área expansível e plano bidimensional de saturação/valor HSV implementados. Edição é somente rascunho até Aplicar, com alpha preservado e matiz/saturação HSV mantidos ao editar preto. O plano aceita pointer capture e limita coordenadas; os campos numéricos oferecem alternativa por teclado. O popover tem altura limitada e rolagem interna para não crescer fora da tela. Não foi implementado um plano de luminosidade HSL nem slider dedicado de matiz. Este incremento não certifica leitor de tela nem substitui a evolução estrutural do overlay atual (`mat-menu`).
+
+Evidência do segundo incremento: 43 testes Angular, 18 cenários da vitrine e um cenário adicional de toque em viewport 390×844, incluindo aplicar/reabrir; build oficial da cadeia Dynamic Fields/Dynamic Form; catálogo sem erros e 20/20 contratos; 58 testes de registry/snapshot no Config. Capturas desktop e narrow foram revisadas e o teste passou a verificar também que o menu não ultrapassa o topo da viewport. O novo teste de toque usa emulação Chromium, não dispositivo físico. AXE, leitor de tela, inglês no navegador e alto contraste permanecem gates pendentes.
+
+Evidência focal do incremento: 36 testes Angular (conversão, picker e catálogo), 17 cenários Playwright do Color Lab, build da cadeia oficial de Dynamic Fields e consumidor Dynamic Form, registry com 20/20 contratos e 58 testes de registry/snapshot no Config. O cenário de precisão verifica abertura com foco no HEX, Tab entre canais e ações, setas, validação, Escape, restauração de foco, reabertura e ausência de rolagem horizontal no menu. As capturas em 1280×720 e 390×844 foram inspecionadas. A conformidade dos novos textos foi testada em pt-BR/en-US e fallback; o navegador foi exercitado em pt-BR.
+
+O Angular MCP foi consultado (`get_best_practices` e `search_documentation`): foram aplicados formulários reativos tipados, signals para estado derivado/validação, transformações puras e control flow nativo. Não houve mudança no formato salvo pelo editor de metadata, em resolvers/operations de IA ou nos contratos de publicação. A regeneração do registry foi local, sem upload ou release. O teste de integração PostgreSQL/Quickstart da fase anterior não foi repetido, pois transporte e publicação não mudaram. Build de produção do aplicativo completo, auditoria AXE/leitor de tela, locale inglês no navegador e tema de alto contraste continuam sem certificação neste incremento.
+
+- plano bidimensional HSV/HSL com slider de matiz e alpha;
+- editores sincronizados HEX, RGB(A), HSL(A) e HSV, com validacao por canal;
+- copiar/colar no formato escolhido e normalizacao previsivel;
+- eyedropper via capability detection e fallback acessivel;
+- teclado completo, foco restaurado, live announcements e alvos touch;
+- grupos, busca, favoritos e recentes com politica compartilhada;
+- popover adaptativo: ancorado em desktop e dialog de tela cheia em viewport/teclado virtual restritos.
+
+Gate: nenhuma divergencia entre representacoes; testes de teclado/leitor de tela; visual regression nos temas e densidades; E2E desktop, touch e mobile.
+
+### Fase 2 — governanca corporativa
+
+- familias de variantes light/dark/alto contraste e por escopo organizacional;
+- matriz WCAG por superficie, tamanho e peso, incluindo justificativa de excecao;
+- simulacao de deficiencias de visao de cor como diagnostico, nunca como unica validacao;
+- proveniencia, aliases, deprecacao e impacto de consumo por token;
+- importacao/exportacao interoperavel de design tokens com preview, conflitos e aprovacao;
+- historico auditavel de proposta, simulacao, aprovacao, publicacao e rollback de decisao.
+
+Gate: round-trip sem perda; ETag e concorrencia otimista; auditoria de aprovador; consumidores materializam a mesma versao; nenhum campo ou app redefine a paleta.
+
+### Fase 3 — diferenciais Praxis
+
+- authoring por IA orientado por intencao: finalidade, marca, contexto regulatorio e superficies;
+- proposta de paleta com evidencias, alternativas e explicacao de trade-offs;
+- reparo assistido de contraste com simulacao de impacto antes de publicar;
+- grafo de impacto mostrando componentes, telas e tokens afetados;
+- politicas que impeçam cores arbitrarias em dominios regulados sem bloquear exploracao em rascunho;
+- observabilidade de adocao, excecoes, falhas de resolucao e drift entre hosts.
+
+Gate: toda sugestao de IA referencia evidencias e contrato canonico; simulacao nao altera runtime; publicacao requer autorizacao; materializacoes sao reproduziveis e auditaveis.
+
+## Ordem de implementacao imediata
+
+### Contexto e escala da paleta governada — 2026-09-06
+
+Incremento `local-pequena`, classificado como `ja-suportado-so-ux`. Color Input e Color Picker materializam `displayName`, `version`, ETag e contagem de resultados já publicados: o cabeçalho mantém contexto e busca estáveis enquanto a grade possui altura limitada, rolagem própria e overscroll contido. Nenhum campo, operação AI, payload ou editor foi alterado.
+
+A auditoria classificou labels humanos, aliases e famílias de variantes como `lacuna-real-de-contrato`: cada entrada publicada contém apenas `tokenId`, `semanticRole`, referência/fallback e finalidades. Esses conceitos não serão inferidos pelo frontend. A próxima fase precisa definir a fonte canônica no Praxis Config, consumidores afetados e migração limpa de beta antes de qualquer UI de seleção de variante.
+
+Essa lacuna agora possui RFC canônico no Praxis Config: `docs/governed-color-palette-token-identity-rfc.md`. O documento define `familyKey`, identidade/dimensões de variante, `displayName` e `aliases` por token, invariantes, migração beta sem endpoint paralelo, mapa de impacto e critérios de aceite. O runtime Angular adotou esses campos somente após sua publicação canônica, sem inferências locais nem contrato paralelo.
+
+O primeiro corte backend foi implementado: DTOs, validador, preview e projeção publicada agora exigem e preservam esses campos; aliases ambíguos são rejeitados e o ETag derivado muda quando a apresentação publicada muda. O segundo corte também foi concluído no `@praxisui/core`: modelos de paleta, preview, variante e token transportam o contrato completo, e o cliente rejeita projeções publicadas legadas ou incompletas antes do cache. Fixtures do Dynamic Fields e do Color Lab foram migradas sem modo de compatibilidade. A materialização visual de nomes/aliases, a navegação entre variantes e a prova operacional no Quickstart permanecem nos cortes seguintes.
+
+### Nomes, aliases e navegação de variantes — 2026-09-06
+
+O terceiro corte materializa no Color Input e no Color Picker dados já publicados pelo contrato canônico: `displayName` e `aliases` participam da busca, o nome humano aparece antes do `tokenId` no tooltip e as paletas com a mesma `familyKey` formam uma faixa compacta de variantes. A associação usa exclusivamente `familyKey` e `variant.key`; tema, texto, prefixo do token e igualdade de cor não decidem parentesco.
+
+O quarto corte fecha a prova operacional: Praxis Config aceita consulta exata por `familyKey`, ordena variantes deterministicamente e garante no PostgreSQL um único head aplicado por família/variante. O Quickstart publica light, dark e high-contrast por identidades governadas distintas, comprova a listagem familiar, preserva histórico e ETag, e o Core passa o escopo da família ao servidor em vez de baixar o catálogo inteiro.
+
+A troca de variante substitui apenas a projeção explorada no painel e mantém o filtro de `purposes`. Ela não reescreve `governedPaletteRef`, não cria configuração de editor e não altera os payloads existentes: Color Input continua com confirmação imediata e Color Picker continua com rascunho/aplicar. O Color Lab local oferece variantes principal, escura e de alto contraste para prova interativa.
+
+Próximo corte: decidir separadamente o contrato de identidade de token no payload e a matriz interativa de contraste. Favoritos, importação/exportação e grafo de impacto permanecem posteriores.
+
+### Identidade governada sem quebra do payload — 2026-09-06
+
+O quinto corte preserva o contrato `string | null` dos campos e adiciona `governedSelectionChange` como observação estruturada. Color Input emite a identidade no commit imediato; Color Picker mantém a identidade no rascunho e só a emite em Aplicar. Entrada livre, recentes, customização, precisão e limpeza emitem `null`, evitando associar um token por igualdade de cor. O evento contém `paletteKey`, `familyKey`, `variantKey`, versão, ETag, `tokenId`, papel semântico e a cor materializada.
+
+Essa observação não entra automaticamente no submit. Persistência exige campo de domínio ou mapeamento explícito do host, pois substituir a cor por um objeto quebraria DTOs existentes e misturaria identidade de design token com valores de negócio que aceitam cor livre.
+
+Validação: uma prova unitária materializou e pesquisou 120 tokens sem colapsar identidade; 94 testes focais da família de seleção passaram, assim como os dois cenários Playwright em 390 e 1440 px. O build completo da cadeia de Dynamic Fields passou após substituir três usos incompatíveis de `Array.at(-1)` pelo acesso equivalente ao último item em Material Select, Inline Select e Inline Multi Select.
+
+### Busca e organização de paleta governada — 2026-09-06
+
+Incremento `local-pequena`, classificado como `ja-suportado-so-ux`: `tokenId`, `semanticRole`, `purposes` e cor já chegavam pela projeção do Core. Color Input e Color Picker agora reutilizam `PdxCollectionSearch`, filtram esses campos sem diferença de caixa/acentos e organizam o resultado visualmente por `semanticRole`. A organização não cria grupos ou regras de negócio e não altera metadata, editor, operação AI ou payload.
+
+A busca é limpa a cada abertura, apresenta estado vazio explícito e preserva as chaves estáveis dos tokens. A simulação humana confirmou busca por `status`, estado sem resultado e busca por `secondary`; após selecionar/aplicar, o Picker preservou `var(--md-sys-color-secondary, #625b71)`. Próximas lacunas: escala/densidade para paletas muito grandes, aliases e nomes humanos governados, identidade do token no payload e navegação entre variantes correlacionadas.
+
+Validação focal: 26 testes de Color Input/Picker e dois cenários Playwright (390 e 1440 px) passaram; o catálogo/authoring passou em 20/20 e o snapshot focal do Config passou. O bloqueio de build encontrado nessa etapa foi removido no incremento seguinte, sem mudar o comportamento dos controles afetados.
+
+### Identidade dos tokens nas paletas de formulario — 2026-09-06
+
+Incremento `contrato-publico`, posterior à auditoria abaixo. O Core agora publica `materializeGovernedPaletteEntries`, associando cada entrada canônica à sua cor materializada. A projeção existente de strings usa o mesmo resolvedor; não há reconstrução de identidade por índice ou igualdade de cor nem novos campos de negócio no backend.
+
+Color Input e Color Picker consomem essa associação e exibem tokenId, semanticRole e referência CSS no tooltip. Tokens diferentes com a mesma cor permanecem entradas distintas. O Input continua confirmando HEX imediatamente; o Picker mantém rascunho/aplicar e referência CSS. O valor persistido continua sendo cor, não tokenId. Recentes e cores locais não recebem identidade inferida.
+
+Validação focal: 14 testes do Core e 26 de Input/Picker passaram; build da cadeia de Dynamic Fields passou. No navegador, 28 cenários de regressão passaram e os dois novos cenários de tooltip passaram na reexecução corrigida (390 e 1440 px). A falha inicial desses dois testes era um seletor de papel inexistente no tooltip Material, não falha de renderização. Capturas estreita/desktop foram inspecionadas. Catálogo e aceitação de authoring passaram em 20/20; README e JSON APIs foram atualizados. Nenhuma nova operação AI, dependência entre libs ou propriedade de editor foi introduzida.
+
+O gate focal do snapshot no Config também passou: RegistryIngestionServiceTest, RegistryIngestionServiceIdentityTest, AiRegistrySnapshotContractTest, AiRegistryBootstrapServiceTest, AiRegistryTemplateServiceTest, AiRegistryTemplateControllerTest e AiRegistryRevisionPolicyTest. Não houve publicação externa nem execução de suíte integral da plataforma.
+
+Próximo recorte: busca e organização das paletas governadas desses dois controles, aproveitando a identidade agora preservada, sem confundir semanticRole/purposes com grupos locais. Permanecem fora deste incremento: busca/agrupamento no Input/Picker, identidade de token no payload, variantes corporativas e matriz interativa de contraste. A auditoria abaixo registra o estado anterior a esta implementação.
+
+### Paridade de descoberta: Color Input e Color Picker — 2026-09-06
+
+Recorte `docs-apenas`: auditoria de contratos, runtime e editores, com repetição de dois cenários E2E existentes. Nenhum runtime foi alterado.
+
+| Dimensão          | Color Input                                        | Color Picker                                           | Implicação                                                                                          |
+| ----------------- | -------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Paleta local      | `paletteColors: string[]`                          | `paletteSettings.colors: string[]`                     | Sem label/group estruturado nessas listas; não aplicar silenciosamente o modelo de opções do inline |
+| Fonte governada   | `governedPaletteRef` → `get` → `materializeColors` | Mesmo caminho                                          | Dados ricos existem no resultado de get, mas a apresentação guarda strings                          |
+| Confirmação       | `applyColor` resolve HEX e confirma imediatamente  | `onApply` confirma draft e preserva referência CSS var | Paridade de descoberta não autoriza uniformizar payload ou confirmação                              |
+| Organização atual | Recentes e paleta                                  | Abas e recentes/paleta                                 | Nenhuma busca ou agrupamento textual desses dois controles foi implementado                         |
+| Identidade visual | Comparação pela cor resolvida                      | Paleta deduplicada por string                          | Não reconstruir tokenId por igualdade de cor ou índice                                              |
+
+Inventário de aderência:
+
+- `ja-suportado-mal-nomeado-ou-mal-materializado`: tokenId, semanticRole, purposes, identidade da paleta e proveniência já chegam do Config. Melhorar sua apresentação não exige novos atributos de negócio no backend.
+- `suportado-parcialmente`: a projeção compartilhada `materializeGovernedPaletteColors` preserva resolução de fallback e finalidades, mas retorna `string[]`, não a associação entre entrada e cor. Input/Picker reduzem novamente a informação a esse array. Auditar uma projeção associada no owner Core antes de qualquer enriquecimento visual; não usar zip por posição nem mapeamento por cor como autoridade de identidade.
+- `lacuna-real-de-contrato` para um opt-in de busca configurável nesses dois contratos de cor, caso esse opt-in seja requisito: não existe `searchable` declarado nos contratos/editor atuais. Isso não autoriza automaticamente criar o campo; primeiro decidir se a descoberta será comportamento interno de uma apresentação existente ou configuração pública comum da família.
+- Grupos/labels em paletas locais de strings também não estão representados, mas a necessidade de uma segunda estrutura local ainda não foi demonstrada. Priorizar a paleta governada já rica, sem converter arrays existentes em objetos ou duplicar o catálogo publicado.
+
+Próximo corte recomendado: definir e validar a associação canônica entrada → cor materializada, preservando fallback, filtro por finalidade e identidade, e então mostrar identificação dos tokens nas paletas de Input/Picker sem alterar seus valores emitidos. Mapa de impacto: Core (projeção/resolução), Dynamic Fields (dois consumidores), Color Lab, documentação JSON API e registry derivados; editor apenas se houver nova configuração pública. Se mudar export/tipo público, classificar como contrato-publico antes de editar e executar build Core + consumidor, specs de fallback/ciclo/finalidades e E2E dos dois controles. Evitar aliases ou endpoints novos para contornar a projeção atual.
+
+Validação executada: dois cenários Color Lab em `http://127.0.0.1:4013/color-lab` passaram — isolamento de draft/commit e preservação de referência governada. Isso não comprova busca/agrupamento nesses componentes. Sem build ou geração de registry neste recorte documental; nenhum artefato público derivado exigiu atualização. Leitor de tela continua fora do ciclo acordado.
+
+### Agrupamento local materializado — 2026-09-06
+
+- Inline Color Label renderiza cabeçalhos a partir de `group` nas opções locais. Ordem dos grupos pela primeira ocorrência na lista completa; ordem dos itens preservada dentro do grupo. Opções sem grupo ficam em bloco sem cabeçalho artificial. Strings vazias/brancas e valores não textuais não criam grupos.
+- Busca oculta grupos sem resultados e mantém sua ordem relativa, badges e identidade selecionada. Não pesquisa o nome do grupo. Rascunho/Aplicar/Cancelar não mudaram. O agrupamento não altera payload nem deriva categorias de cor/token/semanticRole/purposes.
+- Fonte canônica: metadados de opções existentes; apenas modelo visual privado e template da lib foram ampliados. Sem novo toggle, contrato ou operação AI. Editor JSON de opções e seu round-trip permanecem o caminho de authoring. Documentação JSON API e registry local regenerados; sem upload/publicação.
+- Limite: apresentação de grupos com `resourcePath` não implementada. A projeção remota da base precisa ser corrigida/validada separadamente antes de anunciar suporte. A opção local com grupo apenas muda sua organização visual, portanto consumidores com grupos já informados passarão a ver seções.
+- Provas adicionadas: grupos intercalados, itens sem grupo, seleção fora da busca e grupos vazios após busca; cabeçalhos e busca com 60 opções no Color Lab em 390 × 600 e 1440 × 600, com capturas revisadas. Leitor de tela e teclado virtual físico não foram certificados.
+- Resultado final: 21 specs inline, 28 cenários Playwright, build oficial da lib/consumidores, registry (20/20 contratos), gate do snapshot Config, frontmatter incremental, composição MatSelect e diff passaram. Próximo recorte: revisar paridade de descoberta de paletas no Color Input/Picker, mantendo o limite remoto explícito até corrigir sua projeção canônica.
+
+### Preservação de grupos comprovada — 2026-09-06
+
+- Recorte `local-pequena`: somente testes e este plano, sem alteração de runtime ou contrato público. O dado `group` já existe em opções do contrato select e sobrevive ao spread de `mapRawOption`, ao armazenamento da base e ao filtro local. A projeção `toVisualOption` não o expõe à grade: aderência `suportado-parcialmente`, com lacuna de materialização, não de contrato.
+- Prova adicionada: normalização de opções JSON com grupos, pesquisa sem perda do atributo, identidade selecionada estável e troca de grupo por atualização de metadata sem alterar o valor. 20 specs inline passaram. Os dois cenários do Color Lab com 60 opções foram ampliados com grupos e passaram em 390 e 1440 px, incluindo salvar/reabrir o JSON exatamente igual. Esses testes comprovam preservação, não cabeçalhos visuais de grupo.
+- `group` não é o `group` dos descriptors do editor (que organiza propriedades), nem um alias de `semanticRole`/`purposes`. Os dois últimos vêm do Config, são validados/publicados como semântica do token e podem representar múltiplas finalidades. O inline atualmente reduz essa projeção a um mapa tokenId → cor. Não inferir agrupamento a partir da cor, do prefixo do tokenId ou da primeira finalidade.
+- Limite remoto identificado: `SimpleBaseSelectComponent.loadOptions` projeta cada item recebido somente em label/value. Não há preservação de group nessa projeção. Agrupamento remoto requer auditar/corrigir o owner compartilhado e consumidores, não adicionar um mapper especial no Color Lab.
+
+Próximo corte implementável: materializar `group` explícito das opções locais no Inline Color Label, sem novo input ou taxonomia. Preservar ordem de primeira ocorrência dos grupos e ordem original dentro de cada grupo; opções sem grupo continuam disponíveis; busca mantém apenas grupos com resultados, sem alterar badges/identidades/commit. Cabeçalhos são texto do domínio authorado, não categorias inferidas. Agrupamento não autoriza mudar o índice de busca por conveniência: busca por nome de grupo precisa de decisão e prova próprias.
+
+Mapa de impacto antes desse próximo corte: Dynamic Fields (modelo visual privado/template), editor existente de opções JSON (round-trip), docs JSON API/catálogos e registry derivados, Color Lab (grupos + busca + cancel/apply desktop/narrow). Sem breaking change de payload; risco visual de reordenação deve ser documentado. Gates: specs do componente, build focal/consumidor, E2E com grupos mistos e vazios após busca, revisão de artefatos derivados. Não foi repetido build/registry neste inventário porque nenhum runtime ou documento público do componente mudou. Leitor de tela e teclado virtual físico permanecem fora da prova atual.
+
+### Busca local implementada no Inline Color Label — 2026-09-06
+
+- O opt-in `searchable` agora materializa `PdxCollectionSearchComponent` para opções locais. Default false preservado. Busca por label, identidade e description/subtitle reutiliza a normalização da base select, sem criar contrato paralelo ou roteamento de intenção textual.
+- Somente a grade é filtrada. Badges, IDs visuais, valor comprometido e seleção em rascunho continuam derivados das opções completas. Limpar o termo não limpa seleções; reabrir ou atualizar metadados reinicia a busca. O campo permanece fora da região rolável.
+- Limite explícito: com `resourcePath`, o painel ainda não apresenta busca. Busca remota, agrupamento, favoritos e expansão para Color Input/Picker não foram implementados neste corte.
+- Editor existente validado em ativar/salvar/reabrir. Profile AI `select` já inclui o componente e `fieldMetadata.searchable`; não foi criada operação, capability ou parâmetro novo. Documentação JSON API e registry derivados atualizados pelo pipeline oficial, sem upload/release.
+- Evidência: 21 testes focais inline/collection-search; build oficial Dynamic Fields e consumidores; 28 cenários Color Lab; repetição dos dois cenários de 60 opções ampliados com busca por identidade em 390 e 1440 px. Busca sem resultados, badges preservados, limpar termo/foco, cancelar/reabrir e aplicar comprovados. Capturas desktop/narrow revisadas.
+- Registry local aprovado (20/20 contratos de authoring), gate do snapshot no Config aprovado, composição MatSelect sem dívida, frontmatter incremental sem bloqueios e diff sem erros. Não houve validação de busca remota, teclado virtual físico ou leitor de tela.
+- Próximo passo: completar o inventário de preservação e apresentação de `group` nas opções e de `semanticRole`/`purposes` nos tokens governados, antes de implementar agrupamento. Não transformar a ausência dessa apresentação em uma nova taxonomia local.
+
+### Inventário de busca e agrupamento — 2026-09-06
+
+Classificação deste recorte: `docs-apenas` (investigação de código e prova de interação, sem alteração de runtime).
+
+| Necessidade                               | Evidência existente                                                                                                                                              | Aderência e decisão                                                                                                                        |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Ativar busca no Inline Color Label        | `MaterialSelectMetadata.searchable`, propriedade “Buscável” herdada por `inline-color-label.config.ts`; runtime força `searchable: false` em `setSelectMetadata` | `suportado-parcialmente`: concluir a materialização do contrato existente; não criar `colorSearchEnabled`                                  |
+| Campo visual de busca                     | `PdxCollectionSearchComponent`, tokens compartilhados e labels da base select                                                                                    | `ja-suportado-so-ux`: compor o campo compartilhado fora da região rolável                                                                  |
+| Filtrar opções locais                     | `SimpleBaseSelectComponent.filteredOptions`, `searchTerm` e `onSearch`; normalização de acentos/caixa sobre label, value e description                           | `suportado-parcialmente`: reutilizar a filtragem; verificar subtitle no mapeamento, pois subtitle não consta diretamente do índice da base |
+| Preservar seleção ao buscar               | Rascunho explícito e valor comprometido já separados; `selectedOptions()` deriva de `colorLabelOptions()`                                                        | `suportado-parcialmente`: manter lista completa para badges e identidade; filtrar somente as opções da grade                               |
+| Agrupar opções locais                     | `MaterialSelectMetadata.selectOptions[].group` existe; a grade colorida não renderiza grupos                                                                     | `suportado-parcialmente`: auditar preservação do atributo na normalização antes de definir projeção visual                                 |
+| Agrupar tokens governados                 | `GovernedColorTokenEntry.semanticRole` e `purposes`; publicação pertence ao Config                                                                               | `suportado-parcialmente`: aproveitar semântica publicada; não inferir taxonomias a partir de nomes ou cores                                |
+| Busca/agrupamento no Color Input e Picker | Paletas materializadas e abas existentes, sem controle de busca nesses templates                                                                                 | Inventário ainda insuficiente para novo contrato: preservar identidade de tokens e revisar projeção antes de generalizar a solução inline  |
+
+Prova de interação em `http://127.0.0.1:4013/color-lab`, 390 × 844: abrir editor inline → Formato/Comportamento → ativar Buscável → Salvar e fechar → abrir painel. Resultado: zero inputs de busca. Ao reabrir editor, Buscável permanece ativado. A documentação `pdx-inline-color-label.json-api.md` já declara `metadata.searchable` parcial, coerente com a limitação observada.
+
+Próximo corte proposto, `transversal`, sem novo contrato público:
+
+1. Dynamic Fields: respeitar o opt-in existente, compor `PdxCollectionSearchComponent`, filtrar apenas a grade, preservar badges/rascunho/valor e resetar o termo de maneira determinística ao reabrir. Matching textual será apenas filtro de opções dentro do controle já escolhido, nunca roteamento primário de intenção.
+2. Metadata Editor e host: provar ativar/salvar/reabrir, resultado encontrado, nenhum resultado, limpar termo, selecionar em buscas diferentes, cancelar e aplicar. Não prometer busca remota sem validar o fluxo próprio de optionSource/resourcePath: `filteredOptions` não faz filtro local quando há resourcePath.
+3. Artefatos: revisar documentação JSON API, catálogo/profile AI e projeção no registry; a capability de cores não deve anunciar busca genérica para Picker/Input só porque o inline passou a suportá-la.
+4. Gates mínimos: specs inline e busca compartilhada; build focal com consumidor Dynamic Form; E2E Color Lab desktop/narrow, incluindo 60 opções e editor; composição MatSelect e derivados afetados. Risco principal: perda visual ou descarte de seleções fora da busca, não mudança de identidade persistida. Default permanece sem busca.
+5. Agrupamento fica em corte posterior, após auditar o caminho de `group` até as opções visuais e decidir a projeção das múltiplas finalidades governadas. Nenhum novo contrato foi justificado neste inventário.
+
+Não houve edição de API, manifesto ou artefato derivado público; não foram repetidos build e suites nesta investigação, pois o único arquivo alterado é este plano. A prova manual automatizada acima não equivale à implementação da busca.
+
+### Paleta extensa no navegador e fidelidade da vitrine — 2026-09-06
+
+- Prova integrada adicionada em 390 × 600 e 1440 × 600: editar 60 opções pelo editor canônico, usar rótulos/subtítulos longos em português/inglês, rolar até a última opção, cancelar, reabrir, aplicar pelo teclado e reabrir o editor sem perda de opções.
+- A região de opções apresentou rolagem vertical sem overflow horizontal; cabeçalho e ações permaneceram visíveis. Capturas do runtime e do editor narrow foram revisadas. Este cenário é conteúdo bilíngue de teste, não certificação de todos os locales da plataforma.
+- Encontrado e corrigido um erro de observabilidade no host Color Lab: `selectedSemanticLabels` usava a lista inicial fixa. Agora consulta os metadados atuais e conserva a identidade de valores comprometidos removidos do catálogo. O ledger não substitui a resolução de cores governadas do runtime.
+- Validação final local: 8 testes unitários do host e 27 cenários Playwright passaram; `git diff --check` sem erros. Sem publicação ou CI remoto.
+- Mudança `local-pequena` restrita ao host e testes; sem alteração de API pública, editor, manifesto AI ou artefato público derivado. A biblioteca não precisou de nova correção para este cenário. Testes unitários do host e E2E são a validação focal; não há necessidade de reconstruir toda a cadeia de libs para esta mudança.
+- Próximo recorte recomendado: inventariar e melhorar descoberta de opções em coleções extensas (busca e agrupamento), reutilizando contratos existentes antes de acrescentar metadata. Permanecem sem prova teclado virtual físico, todos os locales e condições extremas de texto sem espaços. Leitor de tela continua fora do ciclo acordado.
+
+### Rolagem interna e reabertura por teclado — 2026-09-06
+
+- O Inline Color Label agora limita a altura ao viewport dinâmico e mantém cabeçalho e ações fora da região rolável de opções/seleções. Paletas curtas não ganham rolagem desnecessária. A alteração é interna ao runtime, sem novo metadata, token ou dependência.
+- A jornada em 390 × 320 revelou fechamento concorrente por Escape no CDK e no componente, impedindo a reabertura com Enter. O componente passou a ser o único responsável pelo fechamento por Escape, preservando cancelamento do rascunho e retorno de foco.
+- Cobertura adicionada: 60 opções em teste de componente; geometria e rolagem em 390 × 320, 390 × 600 e 390 × 844; cancelar, reabrir e aplicar pelo teclado após rolar. Capturas desktop e narrow revisadas.
+- Resultado final local: 17 testes unitários e 25 cenários Playwright passaram; build oficial da lib e consumidores passou, assim como o verificador de composição MatSelect e `git diff --check`. Sem release ou execução de CI remoto.
+- Color Input: seleção imediata, limites do menu e retorno de foco passaram em 390 × 320 usando o runtime existente. Isso não representa migração para diálogo adaptativo nem certificação do seletor nativo do sistema operacional.
+- Revisados os paths `inlineOverlay` do authoring e editor: sem alteração de contrato ou configuração editável, não há novos campos nem artefatos derivados públicos a sincronizar. Permanecem pendentes teclado virtual físico, conteúdo traduzido extremo e prova de paletas grandes no navegador integrado (além do teste de componente). Leitor de tela continua fora deste ciclo.
+
+### Correção focal de posicionamento inline — 2026-09-06
+
+- Reproduzido no Color Lab: em 390 × 600, o painel do Inline Color Label começava em `y=-122.09`, cortando o cabeçalho. O teste anterior verificava apenas os limites horizontais.
+- Corrigida a materialização do overlay conectado no componente canônico com viewport push do CDK e margem configurada, sem alterar `inlineOverlay`, seleção ou metadados públicos. Após foco automático, o painel observado ficou em `y=0`, integralmente visível; não se afirma margem visual efetiva de 8 px.
+- Evidência local: 16 testes unitários, 22 cenários Playwright do Color Lab e build oficial da lib com consumidores passaram. Capturas revisadas em 390 × 600 e 1440 × 900; regressão cobre também 390 × 844, Escape e retorno de foco.
+- Manifestos AI e editores não requerem novos campos: a mudança é somente posicionamento interno. Não há artefatos públicos derivados a sincronizar neste recorte.
+- Pendente: limitar e organizar a rolagem para paletas maiores/alturas inferiores ao conteúdo; concluir a avaliação adaptativa do Color Input. Esta correção não encerra a adaptação da família nem certifica teclado virtual físico. Leitor de tela permanece fora do ciclo acordado.
+
+Evidência do corte adaptativo: 45 specs de picker/conversão/catálogo, 4 de configuração do editor, 19 de dialog, 21 cenários Playwright e 58 testes do snapshot/registry no Config. O navegador prova desktop 1280×720, narrow 390×844 e diálogo expandido a 390×600, incluindo preservação do rascunho ao reduzir a altura. Foi corrigida a dimensão da borda no owner Dialog (`border-box`) e a disputa do foco inicial com interações já iniciadas no picker. A compilação focal inclui Dialog, Dynamic Fields, Metadata Editor e o consumidor Dynamic Form. Registry local: 20/20 contratos de authoring; sem upload/release. O teste em altura reduzida não equivale a uma prova em teclado virtual físico.
+
+Incremento de overlay adaptativo: o Color Picker materializa `adaptiveMode` (opt-in, default false) com `PraxisDialog` abaixo de 600 px e preserva o menu em desktop. Template e estado são compartilhados; fechamento restaura rascunho/foco e Aplicar confirma uma única vez. O editor de metadados expõe o opt-in com textos pt-BR/en-US. A lib agora declara `@praxisui/dialog` como peer dependency, sem reexportar seu barrel; não existe dependência inversa. Não foram criados operations, resolvers ou parâmetros de authoring por IA. Color Input e Inline Color Label ainda não foram migrados para essa apresentação, e teclado virtual físico continua sem prova. Leitor de tela foi retirado deste ciclo por decisão do usuário.
+
+A jornada integrada local navegador–backend está fechada no recorte descrito acima. Mantê-la como gate opt-in para alterações de publicação, transporte, cache e segurança. Certificação com IdP/deployment e migrations integrais continua sendo um gate operacional distinto, sem impedir a evolução focal da seleção.
+
+1. Refinar o workspace de precisão: auditoria automatizada e eventual plano de luminosidade HSL, sobre canais HSL/HSV, slider de matiz e plano HSV já implementados, sem criar paths públicos por conveniência. O slider possui teste focal de sincronização com H e jornada de teclado em cores forçadas; isso não certifica acessibilidade integral. Leitor de tela está fora do ciclo acordado.
+2. Unificar acessibilidade e adaptacao de overlay entre Color Input, Color Picker e Inline Color Label.
+3. Modelar no `praxis-config-starter` as variantes correlacionadas e a politica contextual de contraste, atualizando consumidores no mesmo corte.
+4. Acrescentar busca, grupos, favoritos e historico sobre tokens governados, preservando identidade e proveniencia.
+5. Implementar importacao/exportacao como fluxo de decisao governada com preview, diagnosticos e aprovacao.
+6. Adicionar authoring por IA e grafo de impacto somente depois de os contratos das fases anteriores estarem estaveis.
+
+### Matriz interativa de contraste publicada — 2026-09-06
+
+- Classificacao final: `ja-suportado-so-ux`. `GovernedColorPalette.contrastEvidence` ja entrega pares de tokens, razao, nivel AA/AAA e resultado calculados pela fonte canonica. Nenhum campo, endpoint ou calculador concorrente foi criado no frontend.
+- O Color Lab agora materializa a evidencia como matriz: identidade e amostra visual do foreground/background, razao localizada, criterio exigido e resultado. O operador alterna entre todos os pares e somente reprovacoes; a ausencia de falhas em uma paleta publicada possui estado vazio explicito.
+- O filtro atua apenas sobre a evidencia ja resolvida e nao altera paleta, metadados, valor de formulario, ETag ou decisao de publicacao. Labels ausentes usam o `tokenId` publicado como fallback, sem inferir semantica pela cor.
+- Provas: 9 testes focais do host, E2E real da matriz/filtro em `127.0.0.1:4013`, build do aplicativo e verificador MatSelect. A revisao visual desktop confirmou hierarquia e legibilidade; o E2E narrow existente continua verificando ausencia de overflow horizontal da pagina.
+- Nao houve mudanca em API publica, metadata de campo, editor ou registry; portanto nao ha artefato derivado adicional a sincronizar neste recorte. Warnings do build pertencem ao baseline existente de outros componentes. Leitor de tela continua fora do ciclo por decisao do usuario.
+- Limite: esta matriz e uma superficie de diagnostico da vitrine. O proximo recorte deve projetar evidencia contextual dentro do Color Picker para o token em rascunho, sem recalcular ou transformar warning local em politica canonica.
+
+### Diagnostico contextual no Color Picker — 2026-09-06
+
+- Classificacao: `ja-suportado-so-ux`, restrita ao owner Dynamic Fields. Ao selecionar uma amostra governada, o picker cruza o `tokenId` do rascunho com os pares publicados em `contrastEvidence` e mostra contraparte, razao, nivel AA/AAA e resultado.
+- A selecao continua sendo rascunho: o diagnostico aparece antes de `Aplicar`, desaparece ao trocar para cor local/edicao livre e nao altera o valor nem a identidade emitida. Trocar variante substitui conjuntamente tokens e evidencias, evitando combinar decisoes publicadas diferentes.
+- Tokens de contraparte fora do filtro de finalidade continuam identificados porque o lookup usa a paleta publicada completa. Label ausente recua para `tokenId`; nenhuma semantica e inferida por nome, prefixo ou cor.
+- Textos pt-BR/en-US foram adicionados ao catalogo da familia. Nao ha metadata, output, endpoint ou API publica novos; o registry e seu snapshot ainda sao regenerados porque a documentacao JSON API alimenta o corpus de componentes.
+- Provas focais: projecao do par governado, remocao ao escolher cor local, 25 specs do picker, composicao MatSelect, E2E real do diagnostico no Color Lab e build oficial ate o consumidor Dynamic Form.
+- Proximo recorte recomendado: decidir se comparacao ad hoc de uma cor livre contra superficies governadas pertence ao runtime ou a uma simulacao canonica de authoring. Nao implementar calculo local como atalho enquanto a politica contextual, excecoes e validade temporal pertencem ao Praxis Config.
+
+### Previa matematica local de contraste — 2026-09-06
+
+- Classificacao: `ja-suportado-so-ux`, com mudanca `local-pequena` no Dynamic Fields. As cores e finalidades `surface` ja existem na paleta publicada; nenhum campo, endpoint ou contrato publico novo foi necessario.
+- Para rascunhos de cor livre, o picker calcula a razao sRGB contra cada superficie governada da variante ativa. Alpha e composto sobre a superficie; superficies translucidas sao resolvidas deterministicamente sobre branco.
+- A interface rotula o resultado como `nao governado`, mostra apenas a razao matematica e nao apresenta AA/AAA, aprovado/reprovado ou recomendacao automatica. A decisao corporativa continua exclusiva de `contrastEvidence` publicada pelo Praxis Config.
+- Selecionar um token governado substitui a previa local pelo diagnostico publicado. A previa nao altera o valor, o evento de identidade ou o submit.
+- Proximo recorte recomendado: simulacao canonica de reparo no authoring, com politica contextual, excecoes, validade e impacto entre consumidores antes de publicar; favoritos e importacao/exportacao permanecem posteriores.
+
+### Cockpit de simulacao canonica de reparo — 2026-09-06
+
+- Inventario final: `ja-suportado-mal-nomeado-ou-mal-materializado`. O `DomainRuleService` e `POST /api/praxis/config/domain-rules/simulations` ja aceitam `design_token_palette` e retornam cobertura existente, materializacoes previstas, aprovacoes, warnings, prontidao e explainability. O preview de paleta ja recalcula contraste a partir dos fallbacks e bloqueia evidencia abaixo da politica declarada.
+- Nenhum endpoint, DTO, campo de metadata ou contrato paralelo foi criado. O Color Lab combina o preview nao persistente de `color-palettes/previews` com a simulacao de decisao existente e apresenta o resultado como dry-run.
+- A proposta troca somente o fallback candidato de `brand.primary`; a publicacao ativa, seu ETag e os valores dos campos permanecem intactos. O cockpit mostra razao recalculada, validade do preview, prontidao, aprovacoes, cobertura, warnings e materializacao prevista.
+- O fluxo conectado passa a provar por HTTP real que uma definicao persistida de `design_token_palette` pode ser simulada antes da aprovacao/publicacao e que sua materializacao prevista pertence a `design_token_catalog/governed-color-palette`.
+- Politicas contextuais mais ricas, excecoes com justificativa/validade e grafo de consumidores continuam sendo lacunas reais da decisao governada; nao foram inventadas no Angular. Proximo recorte recomendado: modelar essas tres dimensoes no contrato canonico da decisao, com RFC e migracao beta limpa.
+
+Revisao de integridade do cockpit no mesmo corte:
+
+- O fluxo foi renomeado para **validacao governada de candidato**. O valor demonstrativo `#004f59` e fornecido pelo host e nao constitui recomendacao ou reparo gerado pelo Config.
+- A demonstracao local identifica sua resposta como fixture sintetica e nao como evidencia de backend. A razao da fixture foi alinhada aos fallbacks exibidos (`9,05:1` para `#004f59` sobre `#fffbfe`). O modo conectado identifica a origem HTTP separadamente.
+- A decisao exibida e fail-closed: preview invalido ou evidencia de contraste reprovada prevalecem sobre a prontidao generica da simulacao. Troca de finalidade, recarga da publicacao e reset invalidam o resultado anterior; respostas tardias de outro contexto sao descartadas.
+- O candidato agora envia somente o shape de authoring/preview e registra a versao de origem na proveniencia, sem herdar `status`, ETag, validacao ou datas da publicacao. URLs e headers duplicados foram removidos do componente; transporte e identidade usam `API_URL`, proxy e interceptores do host.
+- O teste HTTP real permanece um gate condicionado ao Quickstart/PostgreSQL e comprova a simulacao de uma definicao persistida. Ele nao comprova ainda o ciclo falha de contraste → proposta gerada → reparo, nem transforma o dry-run ad hoc do laboratorio em registro auditavel.
+- Proximo recorte: separar na UX `validar candidato` de `criar proposta governada`, persistir a segunda por `ruleDefinitionId` e somente depois oferecer geracao assistida de candidatos com politica contextual, excecoes, validade e impacto entre consumidores.
+
+## Validacao minima por incremento
+
+- build focal da lib proprietaria e de um consumidor direto;
+- testes de contrato para tipos publicos, ETag, versao, finalidades e precedencia;
+- testes unitarios de conversao com round-trip e limites de canal;
+- E2E de commit/cancelamento, teclado, foco, mobile, editor e modos do formulario;
+- axe ou verificacao equivalente para dialog/popover e mensagens de erro;
+- prova HTTP real da decisao ate a materializacao quando o contrato governado mudar;
+- atualizacao do registry, docs, playground e receitas publicas afetadas.

package/docs/dynamic-fields-field-catalog.md

@@ -114,14 +114,14 @@ Regra editorial:
 
 ## Numero, moeda e range
 
-| Field          | controlType                                       | Quando usar                                                                           | Quando evitar                        | Valor esperado  | Snippet                                                                                            | Detail doc                              |
-| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Number input   | <span id="numerictextbox"></span>`numericTextBox` | numero simples                                                                        | intervalo guiado por slider          | `number`        | `{ name: 'age', controlType: 'numericTextBox' }`                                                   | `pdx-number-input.json-api.md`          |
-| Currency input | <span id="currency"></span>`currency`             | valor monetario unico                                                                 | faixa monetaria                      | `number`        | `{ name: 'budget', controlType: 'currency' }`                                                      | `pdx-material-currency.json-api.md`     |
+| Field          | controlType                                       | Quando usar                                                                                               | Quando evitar                        | Valor esperado  | Snippet                                                                                            | Detail doc                              |
+| -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Number input   | <span id="numerictextbox"></span>`numericTextBox` | numero simples                                                                                            | intervalo guiado por slider          | `number`        | `{ name: 'age', controlType: 'numericTextBox' }`                                                   | `pdx-number-input.json-api.md`          |
+| Currency input | <span id="currency"></span>`currency`             | valor monetario unico                                                                                     | faixa monetaria                      | `number`        | `{ name: 'budget', controlType: 'currency' }`                                                      | `pdx-material-currency.json-api.md`     |
 | Slider         | <span id="slider"></span>`slider`                 | valor unico em faixa continua, com marks, value label, bandas semanticas e histograma responsivo ao valor | campos financeiros complexos         | `number`        | `{ name: 'score', controlType: 'slider', min: 0, max: 10, valueLabelDisplay: 'on' }`               | `pdx-material-slider.json-api.md`       |
 | Range slider   | <span id="rangeslider"></span>`rangeSlider`       | faixa numerica com marks, inputs opcionais, distancia min/max, bandas e distribuicao responsiva ao range  | datas/horarios                       | `{ start,end }` | `{ name: 'range', controlType: 'rangeSlider', mode: 'range', min: 0, max: 100, showInputs: true }` | `pdx-material-range-slider.json-api.md` |
-| Price range    | <span id="pricerange"></span>`priceRange`         | faixa monetaria                                                                       | uma moeda unica                      | `{ min,max }`   | `{ name: 'priceBand', controlType: 'priceRange' }`                                                 | `pdx-material-price-range.json-api.md`  |
-| Rating         | <span id="rating"></span>`rating`                 | nota/avaliacao visual                                                                 | quando precisao numerica e dominante | `number`        | `{ name: 'satisfaction', controlType: 'rating' }`                                                  | `pdx-material-rating.json-api.md`       |
+| Price range    | <span id="pricerange"></span>`priceRange`         | faixa monetaria                                                                                           | uma moeda unica                      | `{ min,max }`   | `{ name: 'priceBand', controlType: 'priceRange' }`                                                 | `pdx-material-price-range.json-api.md`  |
+| Rating         | <span id="rating"></span>`rating`                 | nota/avaliacao visual                                                                                     | quando precisao numerica e dominante | `number`        | `{ name: 'satisfaction', controlType: 'rating' }`                                                  | `pdx-material-rating.json-api.md`       |
 
 ### Contrato de preview do catalogo jogavel
 
@@ -139,18 +139,18 @@ Use `stateInitialValues` apenas quando o valor do preset precisa continuar coere
 
 ## Data e tempo
 
-| Field          | controlType                                     | Quando usar                   | Quando evitar                                   | Valor esperado          | Snippet                                                 | Detail doc                             |
-| -------------- | ----------------------------------------------- | ----------------------------- | ----------------------------------------------- | ----------------------- | ------------------------------------------------------- | -------------------------------------- |
-| Date input     | <span id="dateinput"></span>`dateInput`         | integracao com input nativo   | quando o host precisa UX Material forte         | `string \| Date`        | `{ name: 'birthDate', controlType: 'dateInput' }`       | `pdx-date-input.json-api.md`           |
-| Date picker    | <span id="date"></span>`date`                   | selecao de data no formulario | se o fluxo pede intervalo                       | `Date \| string`        | `{ name: 'startDate', controlType: 'date' }`            | `pdx-material-datepicker.json-api.md`  |
+| Field          | controlType                                     | Quando usar                                                                           | Quando evitar                                   | Valor esperado          | Snippet                                                              | Detail doc                             |
+| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------- | -------------------------------------------------------------------- | -------------------------------------- |
+| Date input     | <span id="dateinput"></span>`dateInput`         | integracao com input nativo                                                           | quando o host precisa UX Material forte         | `string \| Date`        | `{ name: 'birthDate', controlType: 'dateInput' }`                    | `pdx-date-input.json-api.md`           |
+| Date picker    | <span id="date"></span>`date`                   | selecao de data no formulario                                                         | se o fluxo pede intervalo                       | `Date \| string`        | `{ name: 'startDate', controlType: 'date' }`                         | `pdx-material-datepicker.json-api.md`  |
 | Date range     | <span id="daterange"></span>`dateRange`         | intervalo de datas, incluindo periodos corporativos estaticos publicados por metadata | data unica                                      | `{ startDate,endDate }` | `{ name: 'period', controlType: 'dateRange', shortcuts: ['today'] }` | `pdx-material-date-range.json-api.md`  |
-| Datetime local | <span id="datetimelocal"></span>`dateTimeLocal` | data + hora local em um campo | quando o fluxo precisa seletor dedicado de hora | `string`                | `{ name: 'appointment', controlType: 'dateTimeLocal' }` | `pdx-datetime-local-input.json-api.md` |
-| Month input    | <span id="month"></span>`month`                 | mes/ano                       | datas completas                                 | `string`                | `{ name: 'competence', controlType: 'month' }`          | `pdx-month-input.json-api.md`          |
-| Time input     | <span id="time"></span>`time`                   | hora simples                  | intervalo de horario                            | `string`                | `{ name: 'startAt', controlType: 'time' }`              | `pdx-time-input.json-api.md`           |
-| Time picker    | <span id="timepicker"></span>`timePicker`       | seletor de horario Material   | campo simples sem picker                        | `string`                | `{ name: 'slot', controlType: 'timePicker' }`           | `pdx-material-timepicker.json-api.md`  |
-| Time range     | <span id="timerange"></span>`timeRange`         | janela de horario             | apenas uma hora                                 | `{ start,end }`         | `{ name: 'window', controlType: 'timeRange' }`          | `pdx-material-time-range.json-api.md`  |
-| Week input     | <span id="week"></span>`week`                   | semana ISO                    | quando o negocio trabalha por data convencional | `string`                | `{ name: 'weekRef', controlType: 'week' }`              | `pdx-week-input.json-api.md`           |
-| Year input     | <span id="year"></span>`year`                   | ano isolado                   | mes/ano ou data completa                        | `number \| string`      | `{ name: 'fiscalYear', controlType: 'year' }`           | `pdx-year-input.json-api.md`           |
+| Datetime local | <span id="datetimelocal"></span>`dateTimeLocal` | data + hora local em um campo                                                         | quando o fluxo precisa seletor dedicado de hora | `string`                | `{ name: 'appointment', controlType: 'dateTimeLocal' }`              | `pdx-datetime-local-input.json-api.md` |
+| Month input    | <span id="month"></span>`month`                 | mes/ano                                                                               | datas completas                                 | `string`                | `{ name: 'competence', controlType: 'month' }`                       | `pdx-month-input.json-api.md`          |
+| Time input     | <span id="time"></span>`time`                   | hora simples                                                                          | intervalo de horario                            | `string`                | `{ name: 'startAt', controlType: 'time' }`                           | `pdx-time-input.json-api.md`           |
+| Time picker    | <span id="timepicker"></span>`timePicker`       | seletor de horario Material                                                           | campo simples sem picker                        | `string`                | `{ name: 'slot', controlType: 'timePicker' }`                        | `pdx-material-timepicker.json-api.md`  |
+| Time range     | <span id="timerange"></span>`timeRange`         | janela de horario                                                                     | apenas uma hora                                 | `{ start,end }`         | `{ name: 'window', controlType: 'timeRange' }`                       | `pdx-material-time-range.json-api.md`  |
+| Week input     | <span id="week"></span>`week`                   | semana ISO                                                                            | quando o negocio trabalha por data convencional | `string`                | `{ name: 'weekRef', controlType: 'week' }`                           | `pdx-week-input.json-api.md`           |
+| Year input     | <span id="year"></span>`year`                   | ano isolado                                                                           | mes/ano ou data completa                        | `number \| string`      | `{ name: 'fiscalYear', controlType: 'year' }`                        | `pdx-year-input.json-api.md`           |
 
 ## Selecao
 
@@ -177,25 +177,25 @@ Use `stateInitialValues` apenas quando o valor do preset precisa continuar coere
 
 ## Toggle e choice
 
-| Field         | controlType                                   | Quando usar                                                                                           | Quando evitar                                    | Valor esperado                | Snippet                                                                         | Detail doc                                |
-| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
+| Field         | controlType                                   | Quando usar                                                                                                                                                                    | Quando evitar                                    | Valor esperado                | Snippet                                                                         | Detail doc                                |
+| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
 | Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou múltiplas escolhas com `selectionMode: 'multiple'`; em migrações, flags `S`/`N` e `1`/`0` são normalizadas no modo booleano | contrato novo sem `selectionMode`; escolha única | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
-| Radio group   | <span id="radio"></span>`radio`               | escolha unica explicita com `selectionMode: 'single'`                                                 | muitas opcoes/espaco restrito                    | `string \| number \| boolean` | `{ name: 'priority', controlType: 'radio', selectionMode: 'single' }`           | `pdx-material-radio-group.json-api.md`    |
-| Toggle        | <span id="toggle"></span>`toggle`             | booleano binario                                                                                      | multiplos estados                                | `boolean`                     | `{ name: 'active', controlType: 'toggle' }`                                     | `pdx-material-slide-toggle.json-api.md`   |
-| Button toggle | <span id="buttontoggle"></span>`buttonToggle` | escolha segmentada curta                                                                              | listas longas                                    | `string \| number`            | `{ name: 'mode', controlType: 'buttonToggle' }`                                 | `pdx-material-button-toggle.json-api.md`  |
+| Radio group   | <span id="radio"></span>`radio`               | escolha unica explicita com `selectionMode: 'single'`                                                                                                                          | muitas opcoes/espaco restrito                    | `string \| number \| boolean` | `{ name: 'priority', controlType: 'radio', selectionMode: 'single' }`           | `pdx-material-radio-group.json-api.md`    |
+| Toggle        | <span id="toggle"></span>`toggle`             | booleano binario                                                                                                                                                               | multiplos estados                                | `boolean`                     | `{ name: 'active', controlType: 'toggle' }`                                     | `pdx-material-slide-toggle.json-api.md`   |
+| Button toggle | <span id="buttontoggle"></span>`buttonToggle` | escolha segmentada curta                                                                                                                                                       | listas longas                                    | `string \| number`            | `{ name: 'mode', controlType: 'buttonToggle' }`                                 | `pdx-material-button-toggle.json-api.md`  |
 
 ## Upload
 
-| Field       | controlType                       | Quando usar         | Quando evitar                    | Valor esperado               | Snippet                                         | Detail doc                             |
-| ----------- | --------------------------------- | ------------------- | -------------------------------- | ---------------------------- | ----------------------------------------------- | -------------------------------------- |
+| Field       | controlType                       | Quando usar                                              | Quando evitar                                                                                            | Valor esperado               | Snippet                                                                                | Detail doc                             |
+| ----------- | --------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------- |
 | File upload | <span id="upload"></span>`upload` | anexos, documentos e escolha local de imagem com preview | quando o fluxo nao exige arquivo ou exige persistencia operacional completa sem `@praxisui/files-upload` | `File \| File[] \| metadata` | `{ name: 'attachment', controlType: 'upload', accept: 'image/*', imagePreview: true }` | `pdx-material-file-upload.json-api.md` |
 
 ## Cor
 
-| Field        | controlType                                 | Quando usar                   | Quando evitar             | Valor esperado | Snippet                                          | Detail doc                     |
-| ------------ | ------------------------------------------- | ----------------------------- | ------------------------- | -------------- | ------------------------------------------------ | ------------------------------ |
-| Color input  | <span id="color"></span>`color`             | cor simples por valor textual | UX rica de paleta         | `string`       | `{ name: 'brandColor', controlType: 'color' }`   | `pdx-color-input.json-api.md`  |
-| Color picker | <span id="colorpicker"></span>`colorPicker` | paleta, presets, selecao rica | entrada rapida sem picker | `string`       | `{ name: 'accent', controlType: 'colorPicker' }` | `pdx-color-picker.json-api.md` |
+| Field        | controlType                                 | Quando usar                                                      | Quando evitar                                          | Valor esperado | Snippet                                          | Detail doc                     |
+| ------------ | ------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ | -------------- | ------------------------------------------------ | ------------------------------ |
+| Color input  | <span id="color"></span>`color`             | entrada direta, seletor nativo e paleta local/governada          | alpha e confirmação explícita                          | `string`       | `{ name: 'brandColor', controlType: 'color' }`   | `pdx-color-input.json-api.md`  |
+| Color picker | <span id="colorpicker"></span>`colorPicker` | seletor nativo, alpha, paleta local/governada e aplicar/cancelar | canais de precisão e contraste ainda não implementados | `string`       | `{ name: 'accent', controlType: 'colorPicker' }` | `pdx-color-picker.json-api.md` |
 
 ## Visual e acao
 

package/docs/dynamic-fields-inline-components-guide.md

@@ -224,6 +224,7 @@ Critério visual e acessível para `graphic specialized`:
 - O painel deve oferecer modo compacto legível: quantidade controlada de opções, wrap previsível, foco visível e seleção identificável sem depender apenas de cor.
 - Em `inlinePipelineStatus`, a barra segmentada precisa representar etapas reais do processo. Quando o usuário precisa comparar apenas rótulos, use o modo text-first (`pipelineShowBar=false`).
 - Em `inlineColorLabel`, `inlineSentiment`, `inlineScorePriority` e `inlineRating`, mantenha texto visível no resumo e nas opções; use paleta apenas como reforço semântico.
+- Em `inlineColorLabel`, `governedPaletteRef` pode substituir a representação cromática por tokens publicados (`paletteKey`, `version`, `etag`, `purposes`), mas nunca substitui os IDs semânticos authorados em `options[].value` que seguem para o payload do filtro.
 - Para dashboards corporativos com muitas colunas ou toolbar densa, documente um preset ou metadata de fallback: `density`, `inlineAutoSize`, `colorLabelColumns`, `pipelineChipMaxVisible`, `pipelineShowBar=false` ou clear button explícito.
 
 Tiers de densidade recomendados:

package/docs/dynamic-fields-inline-filter-catalog.md

@@ -489,10 +489,19 @@ Para hosts oficiais:
 - Snippet:
 
 ```json
-{ "name": "labels", "controlType": "inlineColorLabel", "options": [] }
+{
+  "name": "labels",
+  "controlType": "inlineColorLabel",
+  "options": [],
+  "governedPaletteRef": {
+    "paletteKey": "praxis.corporate.main",
+    "version": 4,
+    "purposes": ["state"]
+  }
+}
 ```
 
-- UX note: siga WCAG AA e nao dependa apenas de cor; sem texto curto e consistente, prefira `inlineMultiSelect`
+- UX note: siga WCAG AA e nao dependa apenas de cor; a paleta governada altera apenas a representação cromática e preserva `options[].value` no payload; sem texto curto e consistente, prefira `inlineMultiSelect`
 - Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`
 
 ## 9. Toggle

package/docs/dynamic-fields-inline-filter-runtime-contract.md

@@ -276,6 +276,8 @@ Para specialized controls como:
 
 use `controlType` explicito.
 
+Para `inlineColorLabel`, `governedPaletteRef` é uma projeção visual publicada e não redefine o domínio do filtro: os valores comprometidos continuam vindo de `options[].value`. A indisponibilidade ou divergência de `version`/`etag` deve ser anunciada no controle, sem trocar silenciosamente para uma semântica cromática local diferente.
+
 Regra adicional de produto/plataforma:
 
 - `inlinePipelineStatus`, `inlineRelativePeriod`, `inlineRating`, `inlineDistanceRadius`,