@praxisui/dynamic-form 9.0.66 → 9.0.68-rc.0

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

@@ -64,6 +64,14 @@ Essa regra evita perda silenciosa do contrato canonico de Entity Lookup durante
 - IDs de linha devem ser únicos dentro da seção e IDs de coluna devem ser únicos dentro da linha;
 - o estado `dirty` desses editores é reversível: restaurar o snapshot inicial deve desabilitar novamente Apply/Save.
 
+## Responsive column values
+
+The canonical grid uses integer values: `span` 1..12, `offset` 0..11 and `order` -12..12 for `xs`, `sm`, `md`, `lg` and `xl`. A missing or null value inherits the preceding breakpoint; XS defaults are 12, 0 and 0 respectively. These ranges validate each property independently; they do not impose `span + offset <= 12`.
+
+Column controls, authoring-document validation and layout/config validation share the same domains. JSON Apply revalidates the current text before loading or emitting it, even if an earlier draft was valid. Diagnostics identify the property and breakpoint path. The AI `layout.column.add` input declares `span` as an integer. Invalid drafts are not silently rewritten; the editor withholds its preview and numeric summaries until corrected.
+
+Core runtime resolvers recover malformed input into supported CSS grid values without mutating the source document. This is defensive rendering, not approval to save that input. Visibility commands preserve geometry and style; hiding XS/SM also preserves the previously effective MD visibility so inheritance does not unexpectedly hide larger screens.
+
 ## Visual Blocks Inside Layout
 
 Blocos visuais dentro de seção, linha ou coluna devem seguir a decisão
@@ -102,3 +110,100 @@ Guardrail permanente:
 
 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.
+
+## Preferência inicial de apresentação
+
+`bindings.presentationModeGlobal?: boolean | null` materializa no documento o input já existente do Dynamic Form. `true` solicita apresentação em `view`, `false` força campos e `null`/ausência herda `layoutPolicy`. A apresentação não altera `mode`; `create` e `edit` continuam permitindo preenchimento.
+
+O editor Geral oferece ambas as escolhas. O wrapper do Page Builder publica a preferência nos inputs do widget sem persistir uma projeção de schema vazia. O editor aberto pelo runtime salva o snapshot completo de bindings em `form-inputs` e emite os bindings no patch parcial ao host. Em `input-first`, preferências locais não sobrescrevem os inputs. Omitir a preferência em replace-all limpa o override anterior.
+
+Estilos permanecem em `contextSnapshot.presentation`, acessível pela aba **Estilo da apresentação** nos editores direto e do Page Builder. O input `presentation?: DynamicFormPresentationSnapshot | null` projeta esse bloco no widget, sem criar `config.sections` vazias; `null` limpa ajustes explícitos, enquanto ausência mantém a resolução padrão. O wrapper de Filter Form compartilha o documento, mas não oferece a ativação, pois seu runtime não implementa apresentação.
+
+
+### Presentation style projection and editor UX
+
+- `contextSnapshot.presentation` is the canonical style snapshot. The optional runtime input `presentation: DynamicFormPresentationSnapshot | null` projects it into page widgets independently of schema-generated `config`. Explicit styles take precedence over stored style preferences; `null` restores defaults and blocks stale stored overrides; omission retains normal style resolution.
+- Runtime editor Apply/Save emits `presentation` with `mode` and `presentationModeGlobal` in `configPatchChange.inputPatch`. Widget save/reopen preserves the same snapshot; omitting the document block clears the widget projection with `null`.
+- Numeric font sizes and label widths are pixels. Capturing a runtime `rem` size converts it using the host root font size; opening and saving must not reinterpret `0.78rem` as `0.78px`.
+- **Geral → Dados do formulário** separates **Criar / Editar / Visualizar** from **Automático / Campos / Apresentação**. Selecting presentation in Create/Edit keeps the operation unchanged and explains the inactive state with an explicit action to switch to View.
+- **Estilo da apresentação** remains discoverable regardless of the current mode. It previews sample data and does not activate presentation by itself. Filter Form does not expose this tab because it has no presentation runtime.
+- Applying or finishing widget editing updates the page draft. **Salvar página** persists the composition. Shortening sample text affects the preview only.
+
+
+### Page Builder: effective layout and authored input
+
+The widget config editor receives the live `config` through the component editor's transient
+`contextResolver`. Its sections and API field metadata are available for editing without turning
+schema materialization into persisted page input. Opening, cancelling, or changing only mode or
+presentation does not copy generated sections, schema hashes, hooks, or field metadata into the page.
+
+An explicit section/row/column change projects the edited `sections` into authored `inputs.config`.
+When the existing `layoutPolicy.source` is `schema`, this layout edit changes it to `authored`,
+preserving the other policy settings. Reload reconciles current API metadata with the saved layout;
+it does not store the selected record as an authoring snapshot. The intended contract preserves authored configuration and explicit property removals, storing
+per-field overrides by canonical field name rather than the untouched API catalog. The
+[corporate integrity review](../test-dev/corporate-integrity-review-2026-09-08.md)
+recorded gaps in partial schemas, visual override materialization and automatic presentation.
+Those gaps were corrected with the focused validation documented in
+[the implementation evidence](../test-dev/corporate-integrity-fixes-2026-09-08.md).
+The original browser demonstration with explicit presentation alone was not proof of these cases.
+
+The Layout palette lists only eligible API fields that are not already positioned. An empty palette
+with an allocated catalog says that all available fields are already in the layout; it does not imply
+that the resource schema could not be loaded.
+
+
+The wrapper also exposes the existing `configPersistenceStrategy` as **Fonte da configuração**.
+**Definida nesta página** selects `input-first`; **Preferências salvas** selects `local-first`.
+The runtime default remains `local-first`. When the goal is a page-owned layout, select `input-first`
+so an older saved form preference does not replace the correctly persisted page sections on reload.
+Changing only the source preserves the authored page config even if the currently displayed effective
+layout came from older local preferences. This is an existing runtime input, not a new persistence
+channel or authoring operation.
+
+
+### Governed field overrides and partial operation schemas
+
+The effective editor catalog is a projection, not the complete authored document.
+Editing a field must preserve authored overrides for fields absent from both the
+current catalog and its initial baseline. A field present in the baseline and
+explicitly deleted from the edited document may have its authored override removed.
+Reintroducing a schema field into the layout remains a separate layout operation.
+
+With `layoutPolicy.source='schema'`, permitted visual overrides (for example
+`placeholder` and `width`) are reconciled before layout materialization through
+Core's `applyLocalFormCustomizations`. They must not disappear on reload. This
+uses the same server-ownership rules as authored layouts: server labels,
+requiredness, visibility and field access cannot be overridden through a local
+widget document. The existing `field.label.set` and `field.required.set` authoring
+operations remain valid for locally owned fields; persisting those properties
+is not evidence that a schema-governed runtime may supersede backend semantics.
+
+Detaching geometry from schema ownership preserves the existing detail intent
+and automatic presentation. Explicit `presentationModeGlobal=false` still asks
+for readonly controls; edit/create still use input mode. No business operation,
+submit endpoint or command policy is changed by moving a field.
+
+Validation must follow editor output through JSON serialization and runtime schema
+rehydration, in addition to checking the emitted document. The precedence matrix
+also supplies an older conflicting preference through `AsyncConfigStorage` with
+`layoutPolicy.persistence='authorable'`: `input-first` keeps the page layout and
+visual override, while `local-first` uses the saved preference. Both cases reopen
+the wrapper against the resulting runtime config and verify that a no-op save
+preserves the authored page document instead of copying the effective preference.
+Transient layouts skip that preference read and cannot prove this conflict case.
+
+
+Integrity review validation (2026-09-08): 32 focal tests passed across the widget
+config editor, schema layout policy, and external config hydration suites. The
+reorder round-trip includes automatic detail presentation after the saved layout
+becomes authored. The tests also preserve server readonly authority against a
+conflicting canonical local value. Package builds and live browser validation are
+tracked by the integration review; this focal run does not claim those gates.
+
+
+Conflicting preference regression: the external config hydration suite passed all
+11 tests, including the two strategy cases with conflicting order, section title,
+and placeholder (log `/private/tmp/praxis-form-preference-conflict-tests.log`). This
+is an isolated storage-service test and serialized widget round-trip; actual
+backend persistence and visual editor interaction are validated separately.

package/docs/entity-read-feedback.md

@@ -0,0 +1,162 @@
+# Feedback local na troca de registro
+
+Estado consolidado em 08/09/2026: feedback local, erro/retry, recuperação de foco
+e ocultação sem transição implementados e validados. As seções de evidência abaixo
+são cronológicas; contagens, limitações e ausência de gravação pertencem à etapa
+descrita, não substituem resultados posteriores. A configuração da página real foi
+aplicada na etapa de [apresentação do cabeçalho](../../praxis-core/docs/widget-header-presentation-followup.md).
+Consulte a [revisão final de documentação e skills](../../praxis-core/docs/widget-identity-documentation-review.md)
+para o estado das orientações canônicas e seus limites de validação.
+
+## Escopo e inventário
+
+Mudança transversal pelo consumo do Dynamic Form em páginas, widgets e diálogos,
+sem novos inputs, outputs, opções de editor ou contratos HTTP. Fonte canônica:
+`PraxisDynamicForm.loadEntity`; consumidores continuam usando `resourceId`.
+
+A pendência de hidratação, os eventos `loadingStateChange` e o cancelamento da
+leitura já existiam. Aderência: `ja-suportado-mal-nomeado-ou-mal-materializado`
+para feedback; `suportado-parcialmente` para falha e recuperação.
+
+## Comportamento
+
+- Durante a leitura, o corpo mantém geometria e componentes montados, mas fica
+  totalmente transparente, `inert` e `aria-hidden`. O status local fica fora da
+  região marcada `aria-busy`, permitindo anunciar o carregamento.
+- Não usar apenas `visibility:hidden`: campos podem definir `visibility:visible`
+  e reaparecer. Essa situação foi detectada e corrigida no navegador real.
+- Erros e respostas inválidas mantêm o corpo e o envio bloqueados. A ação local
+  de nova tentativa invalida a deduplicação e lê novamente a identidade atual.
+- O sucesso substitui o snapshot com `form.reset(normalized)`, limpando valores
+  ausentes em vez de carregar campos da pessoa anterior. Leituras substituídas
+  continuam canceladas; alteração de identidade durante hooks cancela o envio.
+- Criação e snapshots locais authorados por `initialValue` preservam seu fluxo.
+
+## Validação
+
+A bateria focal de seleção, runtime/submit, external-config-hydration e
+first-config-hydration passou com 238 testes. Build oficial focal:
+`npm run build:praxis-dynamic-form`, sucesso. Logs locais:
+`/tmp/praxis-entity-read-tests-final.log` e `/tmp/praxis-entity-read-build.log`.
+Após separar o status da região `aria-busy`, os 11 testes de seleção foram
+reexecutados e passaram (`/tmp/praxis-entity-read-a11y-final.log`). Essa execução
+recompilou o template final; o build de pacote precedeu esse último ajuste ARIA.
+
+Foram acrescentados testes para ocultação sem desmontar, erro e retry pelo botão,
+bloqueio de submit após erro, resposta parcial, resposta inválida, B tardio após C
+e troca de identidade durante hooks. Os casos existentes cobrem limpar seleção,
+cancelamento e preservação de criação/initialValue. Dois fixtures visuais
+inicialmente falharam por inicialização incompleta; foram corrigidos antes da
+bateria final.
+
+CUA em `localhost:4003/page-builder-ia`, sem interceptação de rede: troca real
+entre funcionários, cabeçalho imediato, corpo anterior oculto, status local e
+conteúdo atualizado após sucesso. Conferidos desktop escuro e 390×844 em tema
+claro; árvore de acessibilidade durante loading sem os campos anteriores. Tema,
+viewport e modo de edição restaurados. Nenhum registro ou página remota foi salvo.
+Falha/retry foi validada por teste de componente, sem provocar erro no backend
+real. Não foi realizada sessão com leitor de tela nem publicação de pacotes.
+
+## Artefatos derivados
+
+README atualizado. Não houve alteração de public-api, shapes de configuração,
+operações de authoring ou portas: não há novo campo didático no editor nem novo
+link a apresentar. Manifestos AI, registry e corpus HTTP não exigem regeneração.
+Naquela etapa, o guidance instalado de runtime mencionava apenas bloqueio durante pending; a
+família correspondente não está disponível em `codex-skills/` deste checkout
+do monorepo. A sincronização dessa orientação ficou registrada, sem editar só
+a cópia instalada nem criar outra skill paralela. A revisão final localizou a
+fonte em `praxis-codex-skills` e resolveu essa lacuna na skill existente de runtime.
+
+## Prova visual adicional de falha e recuperação
+
+O laboratório `/dynamic-page-lab` agora inclui o painel “Validação técnica:
+atualização e recuperação do formulário”. O componente
+`src/app/features/dynamic-page-lab/form-entity-read-proof.component.ts` usa
+`PraxisDynamicForm` e `WidgetShellComponent` reais, com um `HttpBackend` controlado
+e restrito à instância da prova. Não envia HTTP nem modifica registros/configuração.
+Os controles de demonstração completam ou falham a leitura explicitamente;
+não há timers que tornem a inspeção visual dependente da velocidade do operador.
+
+Validação via CUA:
+
+- Ana carregada → Bruno pendente → falha: cabeçalho Bruno, mensagem local e
+  botão de nova tentativa; valores anteriores ausentes da árvore acessível.
+- Enter em “Tentar novamente”: contagem de leituras 2 → 3; após concluir, nome e
+  contato são de Bruno. O transporte real da API não foi exercitado neste cenário.
+- Erro em 390×844, tema escuro: mensagem quebra em duas linhas, botão visível,
+  sem sobreposição; Tab alcança o elemento seguinte.
+- Bruno → Ana → limpar durante pendência: leitura cancelada, nenhum pedido
+  pendente e estado de seleção vazia visível. Foco permaneceu em “Limpar seleção”.
+- O servidor Angular recompilou a demonstração. Não foi reexecutada a bateria
+  de runtime nem o build de pacote, pois esta etapa só adicionou o consumidor de
+  laboratório e documentação. `resourceId` vazio usa `undefined`, conforme o
+  tipo público atual; o runtime normaliza essa ausência para seleção vazia.
+
+### Pendência encontrada: foco após retry
+
+Ao acionar “Tentar novamente” por Enter, o botão é removido durante o loading e
+o foco retorna ao documento. A recuperação de dados funciona, mas essa transição
+de foco ainda precisa ser corrigida no Dynamic Form e coberta por teste. O
+critério recomendado é manter orientação dentro do detalhe quando a nova
+tentativa foi explicitamente acionada, sem roubar o foco de quem mudou a seleção
+ou navegou para outro controle durante a leitura. Esta prova não equivale a uma
+certificação completa com leitor de tela.
+
+### Correção e validação do foco
+
+A pendência acima foi corrigida no Dynamic Form. A região estável “Dados do
+registro”, com `tabindex=-1`, recebe foco somente na nova tentativa explicitamente
+acionada. Permanece montada no carregamento, erro e sucesso. A resposta não chama
+focus, portanto não retira o foco de quem navegou para outro controle. Uma região
+live persistente anuncia carregamento, erro e sucesso; o texto visual duplicado
+fica fora da árvore acessível. Strings disponíveis em português e inglês.
+
+A bateria de runtime/submit/hidratação passou com **240 testes**. Depois do ajuste
+final para evitar texto duplicado, os **13 testes de seleção** foram reexecutados
+e passaram, assim como o build final do pacote. Logs:
+`/tmp/praxis-retry-focus-tests.log`, `/tmp/praxis-retry-focus-final.log` e
+`/tmp/praxis-retry-focus-build-final.log`.
+
+CUA confirmou Enter em retry com foco na região de dados no desktop e em 390×844;
+após concluir a leitura, a árvore acessível contém “Dados atualizados” e os valores
+atuais. Preservação do foco até a resposta e não interferência após navegação para
+outro controle foram verificadas com DOM real nos testes de componente. Não houve
+sessão com leitor de tela. Nenhuma configuração remota foi gravada.
+
+## Inventário histórico da evolução de apresentação e integração
+
+Inventário inicial, sem novo contrato criado nessa etapa. Vazio, subtítulo
+condicional, formatação e ações estreitas foram posteriormente tratados conforme
+o relatório de apresentação do cabeçalho vinculado acima; a tabela registra a
+decisão anterior à implementação, não pendências atuais.
+
+| Necessidade | Aderência e fonte existente | Trabalho restante |
+| --- | --- | --- |
+| Detalhe sem seleção | Já suportado pelo `emptyState` do formulário | Compor a mensagem adequada da página |
+| Cabeçalho vazio mostrando separador | Suportado parcialmente: interpolação de caminhos em Core, sem composição condicional do subtítulo | Auditar materializações/transformações canônicas antes de propor fallback público |
+| Nascimento/CPF no cabeçalho | Suportado parcialmente: `ValuePresentationConfig`/resolver de Core e máscaras de exibição de Dynamic Fields; shell recebe texto | Definir como a apresentação governada chega ao título/subtítulo sem acoplar o shell a funcionário |
+| Ações em largura estreita | Já suportado, mal materializado: shell possui grupos de ações e quebra de linha | Projetar prioridade/overflow no owner Core e conferir editor aberto |
+
+Mapa de impacto da próxima evolução: Core (shell/composição), Page Builder
+(editor/capabilities caso haja opção nova), Dynamic Fields (reuso de apresentação),
+consumidor oficial e documentação pública. Qualquer mudança no shape do shell
+exige plano de contrato público, testes de round-trip e revisão de manifestos e
+playgrounds antes da implementação. O inventário acima não declara ainda uma
+lacuna real de contrato.
+
+Para integrar esta correção, revisar em conjunto o runtime/template/SCSS/i18n e
+spec de seleção de Dynamic Form, seu README e este documento, mais o componente
+de prova e sua inclusão no Dynamic Page Lab. O checkout contém alterações de
+outras tarefas, inclusive nos mesmos arquivos; não incluir o diretório inteiro
+automaticamente em commit/PR. Nenhum commit, push ou publicação foi executado.
+
+
+## Ocultação sem transição entre identidades
+
+Durante leitura pendente ou falha, o elemento `form` também recebe `transition:
+none`. A opacidade zero deve ser efetiva no primeiro frame: animações de saída
+não podem manter o registro anterior parcialmente visível sob o novo cabeçalho.
+Ao concluir, o override transitório é removido. `inert`, `aria-hidden` e a reserva
+de espaço continuam ativos durante a espera. A regra pertence ao Dynamic Form,
+não à página consumidora, e não acrescenta configuração pública ou texto novo.

package/docs/layout-apply-save-reopen-2026-09-08.md

@@ -0,0 +1,114 @@
+# Form layout: Apply, Save and reopen
+
+## Scope and isolation
+
+Classification: `docs-apenas` for the repository changes. The operational proof
+reused `/remote-config-storage-persistence-lab` without changing production code,
+routes, providers or contracts. Existing editor documents, configuration storage
+and widget identities already support the journey; no new contract was required.
+
+The original `/page-builder-ia` document remained at version 92. Its payload was
+copied through the reference Config API into the existing lab's session identity,
+after a GET confirmed that the target did not exist (404):
+
+- Component type: `praxis-dynamic-page`.
+- Component ID: `dynamic-page:remote-canvas-resize-proof:ik=bf5a3dd8-27c8-4aed-b367-afffd680794f`.
+- Lab tenant/user: `demo` / `codex-remote-persistence-lab`, environment `local`.
+- UI tab: 15, opened on the existing remote persistence lab.
+
+Every widget key and matching composition/canvas reference was remapped. Form ID,
+table ID and component-instance IDs also received the run UUID. The original
+resource paths, layouts and modes were retained. The setup PUT created version 1;
+it was fixture preparation, not an action performed in the visual editor. All
+subsequent layout edits and saves used the actual UI. This proves the embedded
+Form + DynamicWidgetPage + ApiConfigStorage path, not the complete Page Builder
+host/agentic-document path used by `/page-builder-ia`.
+
+## Observed journey
+
+1. Reloaded the lab and opened its proof. Status became **restaurada**. Selected
+   Ayla, opened **Configurar formulário → Layout**.
+2. Moved Nome Completo right of CPF using the column menu and clicked **Aplicar**.
+   The displayed detail changed and the page host reported unsaved changes.
+3. Moved Nome Completo left again, then cancelled and confirmed **Descartar
+   rascunho**. The already-applied CPF → Nome Completo order remained visible and
+   was reconstructed when reopening Layout. This exercises opening A → draft B
+   → Apply B → draft A → discard A, without treating Apply as a remote save.
+4. Read the copy through the API: it still exactly matched seeded version 1.
+5. Moved Email after Telefone in Contato and used **Salvar e fechar** in the Form
+   editor. Then used **Salvar layout de teste** in the page host. Status became
+   **salva** after the host saved and read back its document.
+6. A separate GET returned version 2 with a changed ETag. The persisted layout
+   contained CPF → Nome Completo and Telefone → Email. The contact-column widths
+   travelled with their columns (Telefone 4/12, Email 8/12). Mode remained `view`,
+   presentation remained `true`, all five composition links matched the seed,
+   and page state remained `{ "values": {} }`.
+7. Reloaded the browser and reopened the proof. After loading completed, status
+   was **restaurada** and the empty-selection instruction appeared. Keyboard
+   selection subsequently loaded Ayla. Both edited orders were present in the
+   rendered detail and in the reopened Layout editor. A stabilized General tab
+   showed **Visualizar** and **Apresentação** checked.
+
+Final GETs confirmed that the original was unchanged at version 92 and the copy
+was unchanged at version 2 after reload and selection. No employee write command
+was executed. The copy is retained under the owned identity above for review and
+the selection investigation; it is not a published preset.
+
+## Separate selection observation
+
+Do not certify the entire interaction flow as defect-free. After reload, pointer
+actions on the selection radio sometimes produced a visually checked radio while
+the table's selection announcement/action availability and detail remained empty.
+A later snapshot showed radio 194 checked while the status still described record
+193 deselected with zero selections. A click on the Sol row's text also did not
+replace Ayla's detail. Pressing Space on radio 193 did publish selection and load
+the detail correctly.
+
+The saved configuration still enables row-click selection and all five links are
+unchanged. Therefore loss of the persisted link is not supported by the evidence.
+The lab holds page customization enabled; pointer interception, radio native
+activation versus Table selection, and interaction timing remain candidates to
+distinguish. No runtime root cause is established, and no speculative patch was
+made. A transient selector deadline while loading the empty state was followed by
+a snapshot proving that the state was present; it is not evidence of a lost
+empty-state setting. Initial immediate mode snapshots also preceded panel
+rendering; the stabilized General tab confirmed both modes.
+
+Follow-up: the radio inconsistency was subsequently reproduced in standalone
+Table DOM tests and corrected at its Material `change` handler. The retained
+copy passed pointer selection, switching records, repeated activation, Space
+clear and row-cell selection; see the
+[radio selection evidence](../../praxis-table/test-dev/radio-pointer-selection-2026-09-08.md).
+This establishes the reproduced radio cause without attributing earlier browser
+crashes to it.
+
+The follow-up also found an error in this run's fixture preparation: it had added
+`componentInstanceId` to Rich Content, which does not declare that input. On a
+fresh dev load, metadata validation rejected it. A separate If-Match-protected
+fixture correction removed only this input and advanced the copy to version 3;
+all saved layouts, links and Table/Form identities were preserved. Version 2 is
+the historical UI-save receipt above; version 3 is the corrected retained copy.
+The original page remained unchanged at version 92.
+
+## Evidence and validation limits
+
+Read-only receipts/snapshots from this run:
+
+- `/tmp/praxis-layout-roundtrip-owned.json`: ownership, initial status and ETag.
+- `/tmp/praxis-layout-roundtrip-seed.json`: version 1.
+- `/tmp/praxis-layout-roundtrip-after-apply.json`: still identical to version 1.
+- `/tmp/praxis-layout-roundtrip-saved.json`: version 2 with both column moves.
+- `/tmp/praxis-layout-roundtrip-reloaded.json`: unchanged version 2.
+- `/tmp/praxis-layout-roundtrip-original-after.json`: unchanged original version 92.
+
+Runtime/editor assertions were based on rendered DOM, actual UI actions and
+independent API reads. They do not establish which individual child storage
+requests carried If-Match, enumerate all child config keys, or prove conflict
+handling against deliberately older child preferences. The page version/ETag
+change is confirmed; request-header conformance was not captured in this run.
+
+No unit suite or production build was rerun for documentation-only changes. No
+public API, generated manifest, public example, HTTP corpus or skill needed an
+update: `praxis-form-editor-document-roundtrip` already distinguishes Apply,
+component Save, page Save and rehydration. The finding adds concrete evidence,
+not new platform guidance.

package/docs/layout-toolbar-accessibility-2026-09-08.md

@@ -0,0 +1,57 @@
+# Layout toolbar: accessible editor preferences
+
+Classification: `local-pequena`. Adherence:
+`ja-suportado-mal-nomeado-ou-mal-materializado`. Dynamic Form already owns density
+and border/separator editor state, Material toggles, CSS token bindings and an
+i18n namespace. No missing contract justified a new input, configuration flag,
+token or persisted setting.
+
+The three density controls and two style controls previously had hardcoded
+Portuguese tooltips but no accessible names on their native buttons. The style
+group was also unnamed. The group labels did not distinguish editor preferences
+from changes to the published form.
+
+The fix adds translated accessible names to the Material inputs (not only their
+hosts), translates both group labels and the toolbar name, and explains the
+editor-only scope in tooltips. Visible groups are now **Densidade do editor** and
+**Guias do editor**. `compact/cozy/regular` and `border/divider` retain their
+existing state semantics. No CSS, icon source, token or document shape changed.
+
+## Validation
+
+- 38 tests passed across `layout-editor-toolbar.spec.ts` and
+  `layout-editor.component.spec.ts`. The new cases check native control names in
+  pt-BR/en-US, host translator override, selected/pressed states, and preference
+  changes without document mutation or configChange emission.
+- The first test compile exposed a fixture translator return-type error; this
+  was corrected to use the existing typed host translator contract. Subsequent
+  initial-state assertions required a change-detection pass after asynchronous
+  ngModel stabilization. The final 38-test run passed.
+- Browser on the official `/page-builder-ia` route, existing tab 8: opened the
+  selected employee's Form editor and Layout; verified all five accessible names;
+  used Space on Compacta, Bordas das seções and Separadores. States changed while
+  **Sem alterações**, disabled Apply and disabled Save remained intact. Restored
+  the initial preferences through the same UI.
+- Screenshot review at viewport 1125×912, dark theme, expanded panel and reduced
+  panel (720px wide): group labels and controls wrap without overlap; the tooltip
+  explains editor-only behavior. This is reduced-panel coverage, not mobile or
+  full screen-reader certification. No light-theme screenshot or full AXE audit
+  was performed for this naming-only change.
+
+Test log: `/tmp/praxis-layout-toolbar-tests-final.log`.
+Build log: `/tmp/praxis-layout-toolbar-build.log`.
+`npm run build:praxis-dynamic-form` completed successfully through the official
+script's dependency/build closure. A final Config API GET confirmed page version
+92, payload and ETag unchanged; receipt:
+`/tmp/praxis-layout-toolbar-config-after.json`. No page or employee save was used.
+
+The README now explains these existing preferences. Authoring manifests and
+public APIs need no change: no authorable path, payload or operation changed.
+Public-site examples, HTTP corpus and generated catalogs do not expose a new
+contract to synchronize. Existing layout/design skills already require named
+icon controls, i18n, host overrides and preservation of drafts; no skill change
+or installation sync is needed for this correction.
+
+Other hardcoded copy, the global gap control and broader layout composition
+remain outside this focused fix. This does not certify the whole editor as
+localized or redesign its information architecture.

package/docs/master-detail-customization-matrix-2026-09-08.md

@@ -0,0 +1,182 @@
+# Master-detail customization: controlled comparison
+
+## Scope
+
+Classification: `local-pequena` tests and documentation. Existing widget inputs,
+composition links, authoring document and capabilities represent every scenario;
+no new contract or runtime patch is justified by these results.
+
+The reported failure remains open on `/page-builder-ia`. This matrix progressively
+adds factors from that page to the previously passing minimal composition, using
+real Table, Form, widget loader and Page Builder components with controlled HTTP.
+
+## Final result
+
+All **8 scenarios passed** in ChromeHeadless:
+
+| Scenario | Added factor | Result |
+| --- | --- | --- |
+| 1 | Direct composition runtime with child customization | Pass |
+| 2 | Page Builder host | Pass |
+| 3 | Saved form layout and metadata: 18 fields, 4 sections | Pass |
+| 4 | Builder agentic control enabled | Pass |
+| 5 | Form AI control also enabled | Pass |
+| 6 | Authoring document plus host `pageChange` acknowledgement | Pass |
+| 7 | Saved identity links, transient state, detail shell and canvas | Pass |
+| 8 | Resource schema discovery/reconciliation with `input-first` layout | Pass |
+
+Each scenario uses two fictional employees with populated names, dates, monetary
+values, booleans and job/department references. It clicks real table rows and
+checks both child customization inputs, the selected entity, displayed name,
+view/presentation mode, stable loaded component instances during mode changes,
+unchanged authored page JSON and no page/FormConfig saves. It also leaves editing
+while the second entity read is pending and hovers/selects a form section before
+leaving editing. Section selection is cleared on exit.
+
+The reference fields issue canonical `jobRole` and `department` option-source
+`options/by-ids` GETs. The test answers these with matching IDs/labels, ignores
+already-cancelled requests and requires settling within a bounded number of
+response rounds. Earlier name-only responses did not exercise these lookups and
+were insufficient to represent a populated employee detail.
+
+Log: `/tmp/praxis-master-detail-schema-boundary.log`. The final eight scenarios
+completed successfully (1.906 seconds of test execution). No full
+workspace suite, production build or live LLM request was run. Enabling AI
+controls does not certify backend AI authoring or session transport.
+
+## Fixture provenance and limits
+
+`src/lib/test-fixtures/page-builder-employee-form.config.json` takes layout,
+field metadata and editorial block configuration from the version-92 reference
+document. It excludes schema hash/context/verification timestamp and records.
+`page-builder-employee-framing.json` takes its state, five composition links,
+canvas/layout and detail shell; widget keys are mapped to the fixture's `people`
+and `detail`, and the unrelated page-header widget is excluded.
+
+These fixtures are test inputs, not new public presets or a second metadata
+source. They intentionally retain field configuration details that a simplified
+handwritten form would omit. Responses are fictional; avatars remain null.
+
+`page-builder-employee-response.schema.json` is the response read on September 8
+from the reference API's `/schemas/filtered` for
+`path=/api/human-resources/funcionarios/all&operation=get&schemaType=response`.
+It contains schema metadata and documentation examples, not queried employee
+records. Scenario 8 uses the real SchemaMetadataClient and normalizer, with only
+the `fetch` transport intercepted. Responses use a synthetic ETag and return 304
+when that tag is supplied. The test asserts successful initialization, retained
+authored section IDs, the schema hash, no false outdated warning, and no further
+schema reads during three additional settling turns after the interactions.
+
+Initial failures in this extension concerned overly broad persistence assertions,
+not hydration or a reproduced browser crash. The runtime separately persists
+`form-schema-meta:*` evidence/index and `conn:form:*` connection identity with
+`origin: input`. The final assertion checks those keys and payload shapes while
+rejecting page/FormConfig saves. `input-first` and page `autoPersist=false` do not
+mean that every child storage write is disabled. This is observed existing
+behavior, not a new persistence contract. Storage reads still return null in this
+fixture; persisted-child conflict/roundtrip behavior is outside this proof.
+
+This matrix does **not** reproduce the full saved-page host: real network timing,
+persisted child configuration loading, the remote table, the app's
+global providers/interceptors/theme, and actual pointer movement
+remain differences. Mouse events in a DOM test cover handlers, not full browser
+hit testing. No factor can be excluded as a cause under every combination merely
+because the controlled scenario passes.
+
+## Earlier browser failure
+
+The previously responsive reference tab navigated to `/page-builder-ia` and
+loaded its table. Selecting Ayla and waiting for her name in the detail region
+completed; the next request to access the app switch for keyboard interaction
+timed out in `Runtime.evaluate`. The switch transition was not confirmed. This
+does not establish editing as the exclusive trigger: failure may occur after
+detail hydration, before the next interaction can be performed.
+
+Old crashed tabs could not be cleaned up through the browser tool: attempting to
+obtain a crashed tab was blocked by its URL policy for the generated crash page.
+No bypass was attempted and clean browser-process recovery is not claimed.
+
+Read-only GET after the comparison returned version 92, structurally identical
+to `/tmp/praxis-draft-rollout-final.json`. The saved page was not modified.
+
+## Follow-up browser journey and next gate
+
+The schema gate above is now covered by scenario 8. A fresh inventory confirmed
+four previously failed tabs and one responsive existing tab (8). No new tab was
+opened. In that tab, the following actual UI journey completed:
+
+1. Leave page editing, select reference record 235 and wait for its detail.
+2. Enable editing and confirm the checked switch in a subsequent snapshot.
+3. Leave editing, select record 193 (Ayla, also used in the earlier failure),
+   wait for detail and confirm that another DOM read succeeds.
+4. Enable editing, open **Configurar formulário**, and confirm **Visualizar**
+   plus **Apresentação** selected in General settings.
+5. Open **Layout**, inspect its populated sections/fields, cancel without
+   changes, and leave editing. Confirm no dialog, an unchecked switch and the
+   detail region still present. The tab was left available for visual review.
+
+The final read-only configuration GET again matched version 92 exactly. This
+journey did not save a page, edit employee data or modify a layout draft. It
+proves successful interaction in this run; it does not explain previous crashed
+tabs or establish lasting stability. The readonly resolved-runtime panel also
+displayed `legacy CRUD fallback`; that label alone is not evidence that the
+actual schema request fell back and should be checked against transport evidence
+before being used diagnostically.
+
+## Layout edit and cancellation proof
+
+The next interactive gate also passed on September 8 in existing tab 8.
+Classification of this follow-up: `docs-apenas`; no production code or test code
+changed. The behavior is `ja-suportado-so-ux`: column movement, draft tracking,
+discard confirmation and the data/presentation modes already have canonical
+implementations. No additional contract was required.
+
+Starting with record 193 selected and page editing off, the journey captured the
+detail region's text and the Layout tab's text as comparison baselines. It then:
+
+1. Enabled page editing and opened **Configurar formulário → Layout**.
+2. Opened **Seção 1 → Linha 2 → Coluna 1 → Opções da coluna** and selected
+   **Mover para direita**. The draft then showed CPF before Nome Completo,
+   with both columns still at 6/12. Apply and Save became enabled.
+3. Clicked **Cancelar**. The **Descartar rascunho não salvo** dialog appeared.
+   Choosing **Continuar editando** retained the changed field order.
+4. Cancelled again and chose **Descartar rascunho**. Reopened the same editor:
+   the complete Layout tab text matched its initial baseline, including field
+   ordering. General settings showed **Sem alterações**, **Visualizar** and
+   **Apresentação** selected; the table still had record 193 selected.
+5. Closed the unchanged editor and left editing. The complete detail-region text
+   matched its initial baseline, including the displayed values and their order.
+   The responsive tab was left in consultation mode for user review.
+
+Read-only page configuration GETs before and after were structurally identical,
+both at version 92 (`/tmp/praxis-layout-cancel-before.json` and
+`/tmp/praxis-layout-cancel-after.json`). No Apply, Save or employee command was
+used. These comparisons establish cancellation behavior for a menu-based column
+move. They do not cover drag hit testing, discard after Apply, browser reload,
+remote save/reopen, or every child storage key. The earlier eight automated
+scenarios were not rerun for this documentation-only follow-up.
+
+UX observation: the discard dialog explains that an already-applied preview is
+retained, even in this journey where Apply was never used. That wording describes
+the general behavior but introduces an unused state into the decision. If refined,
+it should derive from the editor's existing applied/draft state and translation
+resources; this run does not justify a new configuration flag or contract.
+
+The isolated Apply/Save/reopen gate subsequently completed; see
+[the operational proof](./layout-apply-save-reopen-2026-09-08.md). It confirms both
+column moves, modes and page versioning, while recording a separate pointer
+selection inconsistency after reload. That radio behavior was subsequently
+isolated and corrected; see
+[the Table selection proof](../../praxis-table/test-dev/radio-pointer-selection-2026-09-08.md).
+The eight integration scenarios passed again, with the resource-schema scenario
+now activating Material's touch target. The retained copy also passed live
+pointer/keyboard/row selection after correcting an undeclared Rich Content input
+introduced during fixture preparation. The original version 92 remained intact.
+The remaining broader gate is the complete Page Builder host journey; the lab
+proof does not certify that host or explain earlier browser crashes. Capture any
+recurring failure before changing runtime, without removing customization, draft
+preservation or field configuration to mask it.
+
+No public API, generated manifest, HTTP corpus or installed skill changed.
+Existing skills already require canonical sources and exact coverage statements;
+this investigation adds evidence rather than a new runtime rule.