@praxisui/dynamic-form 8.0.0-beta.2 → 8.0.0-beta.21

package/README.md

@@ -70,10 +70,11 @@ Peer dependencies (Angular v20):
 - `@angular/core` `^20.0.0`
 - `@angular/common` `^20.0.0`
 - `@angular/cdk` `^20.0.0`
-- `@praxisui/core` `^0.0.1`
-- `@praxisui/visual-builder` `^0.0.1`
-- `@praxisui/settings-panel` `^0.0.1`
-- `@praxisui/cron-builder` `^0.0.1`
+- `@praxisui/core` `^8.0.0-beta.12`
+- `@praxisui/rich-content` `^8.0.0-beta.10`
+- `@praxisui/visual-builder` `^8.0.0-beta.10`
+- `@praxisui/settings-panel` `^8.0.0-beta.10`
+- `@praxisui/cron-builder` `^8.0.0-beta.10`
 
 ## Quick Start
 
@@ -112,8 +113,16 @@ export class FormDemoComponent {
         rows: [
           {
             columns: [
-              { id: 'col-fullName', fields: ['fullName'] },
-              { id: 'col-email', fields: ['email'] },
+              {
+                id: 'col-fullName',
+                items: [{ kind: 'field', id: 'field-fullName', fieldName: 'fullName' }],
+                fields: ['fullName'],
+              },
+              {
+                id: 'col-email',
+                items: [{ kind: 'field', id: 'field-email', fieldName: 'email' }],
+                fields: ['email'],
+              },
             ],
           },
         ],
@@ -316,6 +325,19 @@ export class FormEditorLauncherComponent {
 
 Alternatively, when `enableCustomization` is true, `praxis-dynamic-form` renders a gear button that opens the editor internally.
 
+## Agentic Authoring & Manifest
+
+`praxis-dynamic-form` supports executable authoring contracts through the `ComponentAuthoringManifest`. This allows AI agents to perform structured, safe, and deterministic edits to the form configuration.
+
+- **Manifest:** `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`
+- **Editable targets:** `field`, `section`, `row`, `column`, `visualBlock`, `formAction`, `formRule`, `message`, `layoutPlacement`, `localField`, `schemaBackedField`.
+- **Operations:** Covers field property updates, local field lifecycle, layout item manipulation, visual block authoring, rule management, and action configuration declared in `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`.
+- **Validation:** Deterministic validators cover ID uniqueness, layout integrity, rich content document validity, local/schema-backed separation, destructive confirmation, and editor round-trip preservation.
+- **Examples/evals:** Fixtures cover local transient fields, schema-backed relabeling, layout moves, visual block add/move, visibility rules, unknown target rejection, destructive confirmation, and save/reopen without drift.
+- **Round-trip:** Preserves editor state and ensures that AI-generated patches are compatible with the visual editor.
+
+For more details on authoring manifests, see `docs/ai/agentic-authoring/component-authoring-contracts/README.md`.
+
 ## API Surface
 
 - Components: `PraxisDynamicForm`, `PraxisDynamicFormConfigEditor`, `JsonConfigEditorComponent`, `LayoutEditorComponent`
@@ -419,8 +441,16 @@ const formConfig: FormConfig = {
       rows: [
         {
           columns: [
-            { fields: ['fullName'] },
-            { fields: ['workEmail'] },
+            {
+              id: 'registration-full-name',
+              items: [{ kind: 'field', id: 'field-fullName', fieldName: 'fullName' }],
+              fields: ['fullName'],
+            },
+            {
+              id: 'registration-work-email',
+              items: [{ kind: 'field', id: 'field-workEmail', fieldName: 'workEmail' }],
+              fields: ['workEmail'],
+            },
           ],
         },
       ],
@@ -452,10 +482,71 @@ Notas:
 
 See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 
+## Blocos visuais em colunas
+
+O layout de coluna usa `sections[].rows[].columns[].items[]` como contrato
+canônico ordenado. Itens `kind: 'field'` referenciam
+`fieldMetadata[].name`; itens `kind: 'richContent'` hospedam um
+`RichContentDocument` dentro da coluna e não entram em `fieldMetadata`,
+`formData` ou payload HTTP.
+
+`sections[].rows[].columns[].fields[]` permanece aceito como entrada de
+migração e como projeção derivada dos itens `kind: 'field'`, mas não deve ser
+usado para criar blocos visuais.
+
+No editor visual, **Campos da API** lista apenas campos existentes em
+`fieldMetadata[]` que ainda não aparecem em `columns[].items[]` como
+`kind: 'field'`. Ao adicionar um campo, o editor reinsere o item em `items[]`
+e mantém `fields[]` sincronizado como projeção; `fieldMetadata[]` não é
+alterado.
+
+**Adicionar bloco visual** oferece presets internos como texto, aviso,
+separador, card informativo, `callout`, `keyValueList`, `recordSummary`,
+`disclosure` e `emptyState`. Esses presets são apenas atalhos de authoring que
+geram documentos `praxis.rich-content` válidos para itens `kind: 'richContent'`;
+eles não criam novo `kind`, não criam `FieldMetadata` e não participam do
+payload de submit.
+
+O runtime do formulário também passa `hostCapabilities` canônicos para
+`@praxisui/rich-content`, permitindo:
+- `actionButton` despachar ações via a mesma trilha de `customAction`/`globalAction`
+  já usada pelo formulário;
+- `requiresCapabilities` resolver capacidades como `form.mode.edit`,
+  `form.mode.view`, `form.customization.enabled`, `form.resource.connected` e
+  `form.actions.submit`.
+
+Exemplo mínimo de uma coluna com campo, bloco visual e projeção `fields[]`:
+
+```json
+{
+  "items": [
+    {
+      "kind": "richContent",
+      "id": "identity-guidance-block",
+      "document": {
+        "schemaVersion": 1,
+        "nodes": [
+          {
+            "type": "paragraph",
+            "text": "Revise os dados principais antes de salvar."
+          }
+        ]
+      }
+    },
+    { "kind": "field", "id": "field-nome", "fieldName": "nome" },
+    { "kind": "field", "id": "field-email", "fieldName": "email" }
+  ],
+  "fields": ["nome", "email"]
+}
+```
+
+Guia completo: `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`.
+
 ## Documentacao Tecnica da Lib
 
 - `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.json-api.md`
 - `projects/praxis-dynamic-form/docs/hot-metadata-updates.md`
+- `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`
 
 ## Header de seção com avatar dinâmico
 
@@ -494,6 +585,8 @@ See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 
 ## IA — catálogo de capacidades (composição)
 
+O copiloto semântico do formulário usa o shell global de `@praxisui/ai` e registra uma sessão segura no `PraxisAssistantSessionRegistryService`. O botão local apenas abre o contexto do formulário; minimizar/reabrir deve preservar a sessão no cockpit global, sem tratar o formulário como fonte primária de regra de negócio.
+
 O assistente usa um catálogo agregado de capabilities para gerar patches seguros:
 
 - **Macro (FormConfig)**: layout, regras, ações, hooks e mensagens (`form-ai-capabilities`).
@@ -502,27 +595,39 @@ O assistente usa um catálogo agregado de capabilities para gerar patches seguro
 
 Os paths micro são normalizados para `fieldMetadata[].<prop>` para garantir que os patches apontem para a raiz correta do formulário.
 
+O fluxo agentic-authoring do formulário exige `componentEditPlan` validado pelo `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST` antes de aplicar patch local. Prompts de regra de negócio, política, elegibilidade, compliance, LGPD, aprovação/publicação ou decisão compartilhada devem seguir para `domain-rules`/`shared_rule_authoring`; em `view` sem customização ou readonly, o assistente opera apenas como ajuda/diagnóstico e não aplica mutação local.
+
 ## Regras de formulário (novo contrato)
 
-- Formato: cada regra tem `targetType` (`field | section | action | row | column`), `targets: string[]` (IDs canônicos do alvo), e `effect` com `condition` (`JsonLogicExpression | null`), `properties` e `propertiesWhenFalse`.
+- Formato: cada regra tem `targetType` (`field | section | action | row | column | visualBlock`), `targets: string[]` (IDs canônicos do alvo), e `effect` com `condition` (`JsonLogicExpression | null`), `properties` e `propertiesWhenFalse`.
+- Regra de negócio, política, elegibilidade, validação, compliance ou decisão compartilhada deve ser authorada no fluxo governado de `domain-rules`/`shared_rule_authoring`. `visualBlockGuidance` fica restrito a projeção visual opcional: quando uma decisão já governada precisar explicar impacto na UI, a materialização `form_config` pode gerar `type: "visualBlockGuidance"`, `targetType: "visualBlock"` e `metadata.origin: "llm"` com `metadata.reviewStatus: "pending"`; o editor aceita a projeção, marca como `accepted` e materializa `formRulesState` internamente para round-trip visual.
 - Compatibilidade: regras antigas (`context/targetField`) são migradas para `properties/targets` automaticamente; prefixes legados `section:/action:/row:/column:` continuam sendo normalizados quando representarem alvos tradicionais. Para header actions de seção, o ID canônico é preservado como `section:<sectionId>:header-action:<actionLogicalId>`.
 - Semântica de limpeza: valores `null` em `properties/propertiesWhenFalse` removem o override e retornam ao valor base do layout; ausência mantém o valor base.
 - Whitelist por tipo (somente propriedades a seguir são aplicadas; demais são descartadas e logadas em dev):
-  - `field`: `visible`, `required`, `readonly`, `disabled`, `className`, `style`, `label`, `description`, `placeholder`, `hint`, `tooltip`, `prefixIcon`, `suffixIcon`, `prefixText`, `suffixText`, `defaultValue`, `options` (array `{label,value,disabled?}`), `appearance` (`fill|outline`), `color` (`primary|accent|warn`), `floatLabel` (`auto|always|never`), `hintPosition` (`start|end`), `validators` (primitivos por chave).
+  - `field`: `visible`, `required`, `readonly`, `disabled`, `className`, `style`, `label`, `description`, `placeholder`, `hint`, `tooltip`, `prefixIcon`, `suffixIcon`, `prefixText`, `suffixText`, `defaultValue`, `value`, `options` (array `{label,value,disabled?}`), `appearance` (`fill|outline`), `color` (`primary|accent|warn`), `floatLabel` (`auto|always|never`), `hintPosition` (`start|end`), `validators` (primitivos por chave).
   - `section`: `visible`, `title`, `description`, `icon`, `sectionHeader` (objeto rico), `headerActions` (ações contextuais do cabeçalho) e tambem subpropriedades tipadas como `sectionHeader.mode`, `sectionHeader.sourceField`, `sectionHeader.initialsSourceField`, `sectionHeader.altField`, `sectionHeader.fallbackIcon`, `sectionHeader.emptyState`, `sectionHeader.size`, `sectionHeader.initialsMaxLength`, `className`, `style`, `collapsible`, `collapsed`, `headerTooltip`, `headerAlign` (`start|center`), `appearance` (`card|plain|step`), `stepLabel`, gaps (`gapBottom`, `titleGapBottom`, `descriptionGapBottom`), cores/tipografia (`titleColor`, `descriptionColor`, `titleStyle`, `descriptionStyle`).
   - `action`: `visible`, `disabled`, `loading`, `label`, `icon`, `tooltip`, `color` (`primary|accent|warn|basic`), `variant` (`raised|stroked|flat|fab`), `size` (`small|medium|large`), `className`, `style`.
-- IDs canônicos de regras para actions do header de seção usam o formato `section:<sectionId>:header-action:<actionLogicalId>`, evitando colisão com botões globais e com ações repetidas em seções diferentes.
-- Se a seção ainda não tiver `id`, o runtime aceita o fallback `header-action:<actionLogicalId>` por compatibilidade; para contratos persistidos, prefira sempre materializar `section.id`.
   - `row`: `visible`, `gap`, `rowGap`, `className`, `style`.
   - `column`: `visible`, `span`, `offset`, `order`, `hidden`, `align` (`start|center|end|stretch`), `padding`, `className`, `style`.
-- Runtime (FormRulesService): filtra por whitelist, converte tipos (enum/number/boolean/string), saneia objetos (`options/validators/style`), aplica remoção de chaves com `null` e retorna mapas `fieldProps/sectionProps/actionProps/rowProps/columnProps`.
-- Renderização: `PraxisDynamicForm` aplica overrides em campos/seções/ações/linhas/colunas (visibilidade, gaps, padding, classes, estilos, labels, etc.); colunas respeitam `align/span/offset/order/hidden/padding` vindo das regras.
+  - `visualBlock`: `visible`, `hidden`, `layout`, `className`, `rootClassName`, `style`, `text`, `title`, `message`; para documentos compostos, use `textNodeId`, `titleNodeId` ou `messageNodeId` para apontar o node textual seguro.
+- IDs canônicos de regras para actions do header de seção usam o formato `section:<sectionId>:header-action:<actionLogicalId>`, evitando colisão com botões globais e com ações repetidas em seções diferentes.
+- Se a seção ainda não tiver `id`, o runtime aceita o fallback `header-action:<actionLogicalId>` por compatibilidade; para contratos persistidos, prefira sempre materializar `section.id`.
+- Valores calculados: regras de `targetType: "field"` podem escrever `effect.properties.value` ou `effect.propertiesWhenFalse.value`. Use envelope fechado e exclusivo: exatamente `{ "expression": <JsonLogic> }` para calcular ou exatamente `{ "literal": <valor> }` para valor estruturado. Primitivos, `null` e arrays continuam aceitos como literais; objetos literais devem usar `{ "literal": ... }` para não serem tratados como Json Logic legado. Envelopes com chaves extras ou com `literal` e `expression` juntos são inválidos.
+- Ordem de regras: valores calculados são resolvidos em fase anterior, com iteração limitada até estabilizar, antes da aplicação das demais propriedades. Assim uma regra pode calcular `age` e outra regra pode depender de `age` sem depender da posição no array.
+- Comandos condicionais: `formCommandRules` é a superfície aditiva para side effects governados, avaliada depois que `formRules` estabilizam valores calculados. O primeiro corte suporta `effects[].kind: "global-action"` com `globalAction: GlobalActionRef`, policy operacional (`trigger`, `distinct`, `distinctBy`, `debounceMs`, `errorPolicy`, `runOnInitialEvaluation`) e default `trigger: "on-condition-enter"`. Comandos não devem ser colocados em `formRules[].effect.properties`. No editor visual, `payloadExpr` permanece escape hatch de JSON avancado: ele e preservado quando ja existe e nenhum payload estruturado e definido, mas novos campos visuais authoram `payload` literal.
+- Runtime (FormRulesService): filtra por whitelist, converte tipos (enum/number/boolean/string), saneia objetos (`options/validators/style`), aplica remoção de chaves com `null`, resolve `fieldValues` calculados e retorna mapas `fieldProps/sectionProps/actionProps/rowProps/columnProps/visualBlockProps`.
+- Renderização: `PraxisDynamicForm` aplica overrides em campos/seções/ações/linhas/colunas/blocos visuais (visibilidade, gaps, padding, classes, estilos, labels e texto seguro, conforme o tipo); colunas respeitam `align/span/offset/order/hidden/padding` vindo das regras.
+- Regras de `visualBlock` são visual-only: elas não criam `FieldMetadata`, `FormControl`, valor em `formData` ou payload HTTP. Use campo local com `submitPolicy` quando a experiência precisar de valor persistível ou leitura em `rawFormData`.
+
+Politica de erro dos comandos condicionais: falhas de `GlobalActionService.executeRef(...)` geram diagnostico sem propagar excecao para o ciclo do form, e a memoria `distinct` evita repeticao enquanto a condicao segue verdadeira. Sem `GlobalActionService`, actions mutaveis (`api.post`, `api.put`, `api.patch`, `api.delete`) falham fechado e nao sao emitidas via `customAction`.
 
 ### Builder integrado
 
-- No editor visual, use a aba “Propriedades” (integrada ao builder) para selecionar o alvo (`targetType` + autocomplete de IDs de campos/seções/ações/linhas/colunas), escolher propriedades whitelisted e definir valores para `properties` (branch true) e `propertiesWhenFalse` (branch false). Botão “Limpar override” remove a propriedade (equivalente a `null`).
+- No editor visual, use a aba “Propriedades” (integrada ao builder) para selecionar o alvo (`targetType` + autocomplete de IDs de campos/seções/ações/linhas/colunas/blocos visuais), escolher propriedades whitelisted e definir valores para `properties` (branch true) e `propertiesWhenFalse` (branch false). Botão “Limpar override” remove a propriedade (equivalente a `null`).
+- Para `visualBlock`, o painel de propriedades exibe um seletor de node quando a propriedade é `text`, `title` ou `message`; o editor persiste `textNodeId`, `titleNodeId` ou `messageNodeId` automaticamente para evitar sobrescrever o node errado em documentos compostos.
+- No round-trip do builder, `config.type` continua sendo reservado para o tipo visual do node; semântica de regra como `visualBlockGuidance` é preservada internamente em `config.ruleType` e volta para `formRules[].type`.
 - A aba de Propriedades usa inputs tipados (enum/number/boolean/string/JSON) conforme o schema injetado; valores inválidos são ignorados.
-- O config editor fornece `targetSchemas` (campos/seções/ações/linhas/colunas) e `targetPropertySchemas` para o builder; `formRules` são salvas no formato canônico (sem `context/targetField`).
+- O config editor fornece `targetSchemas` (campos/seções/ações/linhas/colunas/blocos visuais) e `targetPropertySchemas` para o builder; `formRules` são salvas no formato canônico (sem `context/targetField`).
 
 ## Layout padrão (sem FormConfig)
 
@@ -665,14 +770,14 @@ Cobertura ja estabilizada:
 - `JSON` com edicao real e bloqueio de payload invalido
 - `Hooks`
 - `Acoes` (`Botoes Padrao` e `Layout`)
-- `Acoes` customizadas profundas (`showAlert` simples e estruturado)
+- `Acoes` customizadas profundas (`dialog.alert` com `globalAction` simples e estruturado)
 - `Comportamento`
 - `Mensagens`
 - `Dicas e Tooltips`
 
 Ajuste tecnico aplicado durante essa fase:
 - [praxis-dynamic-form-config-editor.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts) agora chama `this.jsonEditor?.updateJsonFromConfig(this.editedConfig)` em `onConfigChange(...)` para manter o editor JSON sincronizado com mudancas vindas de abas como `Hooks`.
-- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora mescla catalogo legado + catalogo global do app para o editor de acoes customizadas.
+- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora usa o catalogo global canonico do app para o editor de acoes customizadas.
 - [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora preserva draft local dos campos globais e usa `track` estavel em `actions.custom`.
 
 Comando base usado para rerodar suites isoladas:
@@ -720,6 +825,8 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 - Fluxo de Schema (ETag/304, schemaId, reconciliação): `projects/praxis-core/docs/schema-flow.md` (canônico) e `docs/schemas/fluxo-schema.md` (resumo operacional)
 - Guia de implementação e metadados da cascata: `docs/CASCADE-NATIVA.md`
 - Padrões de endpoints (Options vs Filter) para selects: `projects/praxis-dynamic-fields/docs/generic-crud-service.md` (canônico) e `docs/DEVS-GENERIC-CRUD-SERVICE.md` (resumo operacional)
+- Recipe oficial de Entity Lookup corporativo com `RESOURCE_ENTITY`, `dependsOn`, `dependencyFilterMap`, reidratação por `by-ids` e política de seleção: `examples/ai-recipes/praxis-dynamic-form.entity-lookup-procurement.json`
+- Recipe oficial de comandos condicionais governados com `formCommandRules`, `GlobalActionRef`, policy operacional, valor calculado e date range confirmado: `examples/ai-recipes/praxis-dynamic-form.command-rules.json`
 
 ## Verificação de Schema (ETag/If-None-Match)
 
@@ -747,3 +854,44 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 - Quando `API_URL.default.baseUrl` for relativo (ex.: `'/api'`), a lib resolve a origem a partir de `location.origin` no browser. Isso cobre o cenário comum com proxy de dev (`/api`, `/schemas`).
 - Em SSR (sem `location.origin`), configure `baseUrl` absoluto (ex.: `https://api.acme.com/api`) para evitar erros do tipo “Invalid URL” ao construir chamadas de `/schemas/filtered`.
 - O `GenericCrudService.getSchemasFilteredBaseUrl()` retorna sempre uma URL absoluta; o `SchemaMetadataClient` também aceita `baseUrl` relativo quando há origin disponível.
+
+## Regras de Domínio Compartilhadas
+
+`praxis-dynamic-form` pode consumir regras materializadas pelo backend sem gravá-las dentro de `FormConfig`. O input `domainRules` é opt-in e combina as regras remotas com `config.formRules` no mesmo `FormRulesService`.
+
+```html
+<praxis-dynamic-form
+  formId="funcionarios-form-demo"
+  [config]="formConfig"
+  [domainRules]="{
+    enabled: true,
+    targetArtifactKey: 'funcionarios-form-demo',
+    targetLayer: 'form_config',
+    targetArtifactType: 'praxis-dynamic-form',
+    status: 'applied'
+  }">
+</praxis-dynamic-form>
+```
+
+- `targetArtifactKey` usa `formId`/`componentInstanceId` quando omitido.
+- `targetLayer` default: `form_config`.
+- `targetArtifactType` default: `praxis-dynamic-form`.
+- Para consumo runtime, prefira `status: 'applied'`; `pending_review` pertence a etapas de governança antes da aplicação.
+- `materializedPayload` pode ser um `FormLayoutRule` direto ou uma operação reconhecida, como `rule.visualBlockGuidance.add`, desde que essa operação seja tratada como projeção visual derivada e não como fonte primária da regra de negócio.
+- A rastreabilidade da regra compartilhada fica em `metadata.domainRule`.
+- Quando o backend enviar `decisionDiagnostics`, o runtime preserva esse envelope em `metadata.domainRule.decisionDiagnostics`, mantendo a explicação canônica da decisão semântica governada junto da regra derivada.
+
+E2E vivo com API real:
+
+```bash
+PAX_PROXY_TARGET=https://praxis-api-quickstart.onrender.com \
+node scripts/run-playwright-with-dev-host.js \
+  --port 4003 \
+  --path /funcionarios-form-demo \
+  --spec projects/praxis-dynamic-form/test-dev/e2e/funcionarios-form-demo-domain-rules.playwright.spec.ts
+```
+
+Validado em 2026-04-23 contra `praxis-api-quickstart` publicado no Render com
+`praxis-config-starter:0.1.0-rc.22`: o spec confirmou resposta 200 de
+`/api/praxis/config/domain-rules/materializations` e presença de materialização
+`form_config` com `operation: "rule.visualBlockGuidance.add"`.

package/docs/dynamic-form-authoring-document-semantics.md

@@ -0,0 +1,80 @@
+---
+title: "Dynamic Form Authoring Document Semantics"
+doc_type: "adr"
+component: "praxis-dynamic-form"
+status: "accepted"
+owner: "praxis-ui"
+last_updated: "2026-04-15"
+---
+
+# Dynamic Form Authoring Document Semantics
+
+## Decision
+
+`DynamicFormAuthoringDocument` e o snapshot canônico completo de autoria de `praxis-dynamic-form`.
+
+Ao aplicar um documento canônico:
+
+- `config` substitui integralmente a configuração anterior.
+- `bindings` substitui integralmente os bindings persistíveis anteriores.
+- ausência de `bindings.mode` implica limpeza do binding persistido e retorno ao modo default efetivo do host.
+- `contextSnapshot` substitui integralmente o contexto autoral persistido anterior.
+- ausência de `backConfig`, `presentation` ou `schemaPrefs` dentro de `contextSnapshot` significa remoção explícita do bloco ausente.
+
+Payloads legados ou parciais recebidos por APIs de compatibilidade, como `applyConfigFromAdapter(...)`, permanecem com semântica `merge-compat`: campos não informados devem ser preservados até migração completa para o contrato canônico.
+
+Valores de runtime/discovery, como `schemaUrl`, `submitUrl` e `submitMethod`, não fazem parte do `DynamicFormAuthoringDocument`. O editor pode exibi-los apenas como diagnóstico read-only do host atual, mas nunca os persiste em `bindings` ou `contextSnapshot`.
+
+## Field Metadata Editor Patches
+
+Patches vindos de `@praxisui/metadata-editor` para `fieldMetadata` seguem semantica de JSON Merge Patch no campo editado.
+
+Para `entityLookup`, o bloco `fieldMetadata[].optionSource` e aninhado e deve ser mesclado em profundidade. O dynamic-form deve preservar campos existentes, como `key`, `resourcePath`, `valuePropertyPath` e `capabilities.byIds`, quando o editor alterar apenas partes do contrato, como `dependsOn`, `selectionPolicy`, `detail` ou `capabilities.auditSnapshot`.
+
+Essa regra evita perda silenciosa do contrato canonico de Entity Lookup durante o fluxo: abrir editor -> aplicar/salvar -> reabrir editor -> runtime consumir.
+
+## Consequences
+
+- `backConfig`, `presentation` e `schemaPrefs` permanecem fora de `FormConfig`, mas fazem parte oficialmente do documento autoral persistível em `contextSnapshot`.
+- `Apply` e `Save` vindos do editor operam em modo `replace-all`.
+- `reset` do editor limpa todos os modos persistidos do artefato.
+- adapters legados continuam suportados sem limpeza destrutiva de contexto ausente.
+
+## Visual Blocks Inside Layout
+
+Blocos visuais dentro de seção, linha ou coluna devem seguir a decisão
+canônica registrada em:
+
+- `../../../docs/2026-04-dynamic-form-visual-blocks-layout-items-plan.md`
+- `../../../../docs/adr/ADR-0006-dynamic-form-layout-items-visual-blocks.md`
+- `./layout-items-visual-blocks.md`
+- `./dynamic-form-rules-authoring-plan.md`
+
+A semântica alvo é `FormColumn.items`, com uma union discriminada entre campo e
+rich content. `FormColumn.fields` pode ser aceito como entrada de migração para
+configurações antigas, mas não deve seguir como segunda fonte de verdade.
+
+O editor deve produzir e persistir o documento canônico, e o runtime deve
+consumi-lo sem adaptador oculto. O round-trip esperado é:
+
+`abrir editor -> adicionar bloco visual -> aplicar/salvar -> reabrir -> renderizar`
+
+Guardrail permanente:
+
+- bloco visual não entra em `fieldMetadata`;
+- bloco visual não cria `FormControl`;
+- bloco visual não entra no payload de submit;
+- bloco visual não usa `source`, `transient` ou `submitPolicy`.
+- operações AI para bloco visual devem escrever apenas em
+  `sections[].rows[].columns[].items[]`, usando itens `kind: 'richContent'`;
+- `sections[].rows[].columns[].fields[]` é apenas projeção/migração de campos
+  e não pode ser usado para representar bloco visual.
+- presets de bloco visual no editor são atalhos internos para criar
+  `RichContentDocument` com nodes já suportados por `@praxisui/rich-content`;
+  presets não introduzem novo `kind` nem contrato paralelo.
+- "Adicionar campo da API" reinsere somente campos já existentes em
+  `fieldMetadata[]` e ausentes de `columns[].items[]`; a operação escreve o
+  item `kind: 'field'` em `items[]` e preserva `fieldMetadata[]`.
+
+Em fase beta, não vamos deixar legado para trás sem migração, mas também não
+vamos manter legado como contrato paralelo permanente.