---
title: "Dynamic Form Visual Builder Parity Audit"
slug: "dynamic-form-visual-builder-parity-audit"
description: "Auditoria de claims, paridade runtime/editor e plano de melhoria para o fluxo de regras do Dynamic Form com Visual Builder."
doc_type: "audit"
document_kind: "host-guide"
category: "architecture"
audience:
  - "frontend"
  - "platform-team"
  - "architect"
  - "llm-integrator"
level: "advanced"
status: "draft"
owner: "praxis-ui"
tags:
  - "dynamic-form"
  - "visual-builder"
  - "rules"
  - "json-logic"
  - "llm"
toc: true
sidebar: false
reading_time: "18 min"
last_updated: "2026-06-17"
source_of_truth:
  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.html"
  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts"
  - "projects/praxis-dynamic-form/src/lib/utils/rule-converters.ts"
  - "projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.ts"
  - "projects/praxis-dynamic-form/src/lib/services/form-rules.service.ts"
  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
  - "projects/praxis-visual-builder/src/lib/praxis-visual-builder.ts"
  - "projects/praxis-visual-builder/src/lib/services/rule-builder.service.ts"
  - "projects/praxis-visual-builder/src/lib/components/field-condition-editor.component.ts"
  - "projects/praxis-visual-builder/src/lib/ai/praxis-visual-builder-authoring-manifest.ts"
---

# Dynamic Form Visual Builder Parity Audit

## Classification

`docs-apenas` for this artifact.

This document does not change runtime behavior, public exports, manifest
operations or npm package documentation. Any follow-up that changes
`README.md`, public AI manifests, `RULE_PROPERTY_SCHEMA`, JSON Logic parsing,
`FormLayoutRule`, `formCommandRules` or editor behavior must be reclassified as
`contrato-publico` or `transversal` before editing.

## Canonical Owner And Boundaries

| Area | Canonical owner | Boundary |
| --- | --- | --- |
| `FormConfig`, `formRules`, `formCommandRules`, embedded config editor | `@praxisui/dynamic-form` | Dynamic Form owns the authored form document and editor integration. |
| JSON Logic visual authoring and `RuleBuilderState` | `@praxisui/visual-builder` | Visual Builder owns visual rule graph, condition authoring and round-trip to serialized JSON expressions. |
| Allowed rule effect properties | `@praxisui/core` via `RULE_PROPERTY_SCHEMA` | Core owns the canonical property schema consumed by Dynamic Form and authoring tools. |
| Global action execution shape | `@praxisui/core` / shared action contract | Persisted command effects must use `globalAction: { actionId, payload?, payloadExpr?, meta? }`. |
| Public docs and npm claims | Package READMEs, landing docs, AI manifests | Public claims must not exceed tested runtime/editor parity. |

## Expert Review Synthesis

Four specialist reviews were requested before creating this artifact:

| Review area | Main confirmation | Required adjustment |
| --- | --- | --- |
| Contract/runtime | `formRules`, `formRulesState` and `formCommandRules` are distinct contracts and must not be collapsed. | Build two technical parity matrices instead of one. |
| UX/design | The issue is a trust gap: the editor suggests some capabilities that are not safely persisted or reopened. | Add a short confidence-hygiene phase before broad UX expansion. |
| Docs/LLM | Public claims and AI manifests can lead LLMs to generate valid JSON that is not visual-builder compatible. | Add a public-claims matrix and an LLM-safe subset before updating npm docs. |
| Tests/E2E | Existing tests cover basic rules and commands, but advanced round-trip gaps are under-tested. | Add focused converter/diagnostic specs before broad Playwright flows. |

## Core Problem

The current flow has four different levels of support that are not consistently
distinguished:

| Level | Meaning |
| --- | --- |
| Runtime-supported | The saved JSON/config can be consumed by the runtime. |
| JSON-authorable | A user or LLM can express the config in JSON. |
| Visual-authorable | The editor can create and edit it through guided UI. |
| Visual round-trip stable | The editor can reopen the saved config without semantic drift. |

The risky state is when a capability is runtime-supported or modelled, but the
editor either hides it behind raw JSON or exposes it without preserving the
semantic payload.

## Public Claims Matrix

This matrix prevents public docs, npm READMEs and AI manifests from promising
more than the implementation can safely support.

| Claim / surface | Published or advertised | Implemented | Tested | LLM-safe status | Recommended action |
| --- | --- | --- | --- | --- | --- |
| LLMs and consumers should write `formRules`, not `formRulesState` | README now includes an `LLM-Safe Authoring Subset` | Yes | Manifest spec protects AI rule operations from writing `formRulesState` | Safe when stated explicitly | Keep this wording in npm README and landing docs before publication. |
| Simple field conditions with scalar values and `and/or` round-trip visually | Advertised indirectly by visual rule authoring | Yes | Yes, basic coverage | Safe | Keep as stable visual round-trip subset. |
| Advanced JSON Logic operators round-trip visually | README and AI manifest now mark advanced operators as runtime JSON-only until focused visual round-trip support exists | Partial | Converter specs cover representative JSON-only operators; manifest spec protects condition descriptions | Not safe for visual claims | Keep runtime JSON-only wording until parser/emitter support exists. |
| `valueType = field/context/function` is a visual condition capability | UI/model expose it | Field-to-field is implemented; context/function are explicitly blocked until a canonical shape exists | Partial | Field is safe; context/function are not safe | Keep field-to-field as supported; define canonical shapes before enabling context/function. |
| Context variables are authorable through visual-builder | Manifest now separates registry support from field-condition operands | Registry/config support only | Manifest spec updated | Safe as registry-only; not safe as condition operand | Keep registry wording; define canonical condition operand shape before enabling context references. |
| `dsl.roundTrip.validate` is a general guarantee | Manifest now scopes it to the runtime-supported visual subset | Limited by supported subset | Manifest spec updated; advanced nodes still insufficient | Safe only when scoped | Keep subset wording; fail or classify unsupported advanced cases. |
| `surface.open` command payload is visually authorable | Dynamic Form command rules now reuse the canonical `SurfaceOpenActionEditorComponent` | Yes for structured `payload`; `payloadExpr` remains advanced | Focused config-editor spec plus Playwright save/reopen flow | Safe for structured payload | Keep `payloadExpr` as advanced JSON-only; common target coverage includes `praxis-dynamic-form`, `praxis-table` and `praxis-crud`. |
| `payloadExpr` is missing from UI | JSON contract supports it | Runtime-supported and preserved through advanced JSON | Focused config-editor specs cover preserve-without-payload and replace-when-structured-payload-is-authored | Advanced JSON-only | Treat as deliberate escape hatch unless product decision promotes it to structured UI. |
| Multiple command effects are authorable | Contract shape is array-based | Primary effect is visually editable; secondary effects are preserved when editing the primary effect | Focused config-editor spec | Not fully LLM-safe for visual authoring | Keep secondary effects JSON-authored until a multi-effect UI is designed. |
| Visual Builder README npm reflects local source | Published npm can lag local README and search metadata can be stale | npm search and `npm view` show canonical packages published as `9.0.0-beta.20`; retired `@praxisui/specification*` packages are tracked as known retired packages | `release:postflight:npm`, `validate:npm-search-surface`, `validate:npm-docs`, `validate:package-peers` and `audit:npm-packages` pass for the canonical inventory | Safe for version parity; retired npm packages remain visible externally until npm deprecation is executed by an authenticated owner | Keep `@praxisui/specification*` out of active docs, configs and release inventory. |

## Technical Matrix A: `formRules`

This matrix covers `FormLayoutRule`, `RuleBuilderState`, `RULE_PROPERTY_SCHEMA`
and the visual rule builder embedded in the Dynamic Form config editor.

| Capability | Runtime | JSON authoring | Visual create/edit | Reopen round-trip | Diagnostics | Current classification | Recommended action |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Field target rule | Executes through `FormRulesService` | Yes | Yes | Stable for simple cases | Compatible | Stable visual round-trip | Keep and protect with specs. |
| Section/action/row/column/visualBlock target rule | Executes when target exists and properties are allowed | Yes | Yes | Covered for known, prefixed and section header action target cases | Compatible or property diagnostics | Stable visual round-trip for covered target types | Keep focused converter and diagnostic coverage for target normalization. |
| Multiple targets | Runtime shape supports target arrays | Yes | Yes for homogeneous target arrays | Stable for representative field and prefixed non-field targets | Compatible for covered prefixes | Stable for homogeneous target arrays | Add mixed-target visual interaction only if the UI starts allowing heterogeneous target sets. |
| Simple condition: field op literal | Executes | Yes | Yes | Stable for supported operators | Compatible | Stable visual round-trip | Keep as canonical baseline. |
| Nested `and/or` | Executes when JSON Logic is valid | Yes | Yes for field-condition groups | Stable for nested `and`/`or` with visual-safe field conditions | Covered by converter specs | Stable visual round-trip for covered subset | Keep separate from advanced operators such as `not`, `xor`, `implies`, `between` and `notIn`. |
| `not`, `!`, `xor`, `implies` | Runtime support must be verified per operator | JSON may be valid | Model suggests support | Not stable | Runtime-only | Runtime-supported JSON-only or experimental | Do not advertise visual round-trip until parser/emitter support exists. |
| `between`, `notIn`, null/empty operators | Runtime support must be verified per operator | JSON may be valid | Hidden from visual condition editor until round-trip is canonical | Not stable | Runtime-only / invalid | Runtime-supported JSON-only or experimental | Keep hidden from visual UI; re-enable only with parser/emitter specs. |
| Compare with another field | JSON Logic can express `{ var: otherField }` | Yes | UI exposes `valueType=field` | Stable after field-to-field round-trip support | Compatible | Stable visual round-trip | Keep and protect with converter/service specs. |
| Compare with context variable | Depends on context provider semantics | Yes if canonical path exists | Disabled in UI until canonical shape exists | Blocked by validation | Invalid/unsupported | Planned/experimental | Define canonical var path and round-trip before public claim. |
| Compare with function result | Depends on function registry semantics | Possibly | Disabled in UI until canonical shape exists | Blocked by validation | Invalid/unsupported | Planned/experimental | Keep experimental until function call JSON shape is canonical. |
| Property effect true values | Runtime sanitizes through property schema utilities | Yes | Yes | Stable for scalar values and covered structured editors | Covered for scalar hydrate and structured emit/hydrate | Stable for covered editors | Keep object-property expansion scoped to high-frequency properties. |
| Property effect false values | Runtime shape supports false branch | Yes | Yes for structured property editors | Stable for `options`, `validators`, breakpoint maps and `style` | Covered for emit/hydrate | Stable for covered editors | Improve clearer review UI only if product UX requires stronger visual comparison. |
| Object properties: `style`, `options`, validators, responsive maps | Runtime may accept sanitized values | Yes | `field.options`, `field.validators`, `field.style` and column breakpoint maps (`span`, `offset`, `order`, `hidden`) now have structured editors; `style` supports generic CSS string/number pairs | Partial | Sanitized / unsupported property | Supported partially | Specialize high-frequency style tokens only when product UX requires stronger guided controls. |
| VisualBlock text/title/message node ids | Runtime supports governed overrides | Yes | Yes through property panel | Stable for value and node-id hydrate/apply | Covered by property-panel specs | Stable guided property path | Keep technical `*NodeId` fields hidden from the primary property selector. |
| LLM-generated pending review | Adapter rejects direct `formRulesState` writes | Yes via `formRules` | Review flow exists with guarded accept action | Stable when diagnostics are clean | Pending review until accepted | Stable governance path | Preserve; public docs must emphasize reviewed `formRules` and no direct `formRulesState`. |
| Runtime-only existing rule | Runtime may execute | Yes | Visible as diagnostics, not visually editable | Preserved without visual conversion | Runtime-only with `Ver JSON` action | Supported JSON-only | Keep non-destructive JSON review; add conversion only after a canonical visual shape exists. |

## Technical Matrix B: `formCommandRules`

This matrix covers conditional commands, JSON Logic conditions,
`GlobalActionRef`, policies and effects.

| Capability | Runtime | JSON authoring | Visual create/edit | Reopen round-trip | Diagnostics | Current classification | Recommended action |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Command condition: simple field op literal | Executes when condition validates | Yes | Yes via condition mode | Stable for simple cases | Preview | Stable visual round-trip | Keep and protect with specs. |
| Command condition: advanced JSON Logic | Runtime validator may accept broader JSON Logic | Yes | Not fully | Runtime-only in visual editor | Preview/JSON | Runtime-supported JSON-only | Mark clearly; do not imply full visual condition parity. |
| `dialog.alert` structured payload | Executes via `GlobalActionRef` | Yes | Yes | Covered by E2E | Preview/errors | Stable visual authoring | Keep as baseline. |
| `surface.open` payload | Executes if valid `GlobalActionRef` | Yes | Structured editor now reused in command rules | Focused spec and Playwright flow cover hydrate/edit/apply/save/reopen | Error/preview | Supported structured path | Keep common target coverage aligned with canonical `SURFACE_OPEN_PRESETS`; focused specs cover dynamic-form/table round-trip and CRUD payload preservation. |
| `payloadExpr` | Runtime contract supports escape hatch | Yes | Not exposed as primary UI | Preserved when no structured payload is authored; replaced when structured payload is authored | Preview / focused spec | Advanced JSON-only escape hatch | Keep JSON-only unless product decision promotes a structured expression editor. |
| Multiple effects | Contract uses array | Yes | UI edits the primary global action and preserves secondary effects | Secondary effects are preserved when editing the primary effect | Focused spec protects non-destructive primary-effect edits | Primary visual authoring plus secondary JSON preservation | Design explicit multi-effect UI before advertising full visual authoring. |
| Policy `distinct` and `distinctBy` | Runtime policy supported | Yes | Yes | Stable for visual edit/apply | Preview | Stable visual authoring | Keep controls scoped to the common command policy path. |
| Policy `runOnInitialEvaluation` | Runtime skips initial command execution unless explicitly enabled | Yes | Yes | Stable for hydrate/preview/apply | Preview | Stable visual authoring | Keep explicit because initial side effects are high-risk. |
| Other trigger modes / while-true behavior | Runtime behavior may be limited | JSON may express variants | Not exposed as visual controls | JSON-authored policy fields are preserved when editing visual fields | Focused spec protects non-destructive policy round-trip | Runtime-supported JSON-only | Keep JSON-only until runtime semantics are aligned; do not advertise full visual trigger authoring. |
| Invalid command payload | Runtime should reject or fail safely | Yes | Yes for catalog-required payload keys | Covered for `dialog.alert` and `surface.open` incomplete payloads | Authoring error / invalid preview | Stable for catalog-required keys | Keep deeper structural validation in the shared global-action catalog/runtime, not in the Dynamic Form editor. |

## Confidence Hygiene Backlog

These items are intentionally smaller than full parity work. They reduce false
signals before expanding the editor.

| Item | Class | Reason | Risk | Validation |
| --- | --- | --- | --- | --- |
| Remove visible placeholder buttons or implement their actions | `ja-suportado-mal-nomeado-ou-mal-materializado` | Placeholder actions damage authoring trust. | Low if hidden; medium if implemented. | Component spec or focused Playwright interaction. |
| Fix mojibake in critical editor surfaces | `ja-suportado-so-ux` | Corrupted labels weaken UX and LLM-facing docs; clear-column copy now has i18n-backed coverage. | Low, but encoding-sensitive. | `row-configurator` spec asserts clear-column copy has no `Ã`/`Â`; continue scanning broader editor surfaces. |
| Mark unsupported visual condition options as unavailable | `suportado-parcialmente` | `context` and `function` operands are shown as JSON-only and normalized out of visual authoring; unsupported operators such as `between`, `notIn`, null/empty and regex operators are hidden until parser/emitter support exists; `literal`, `field` and the visual-safe operator subset remain authorable. | Medium; may appear as feature removal. | `field-condition-editor` spec covers visual-safe valueType normalization, visual-safe operator filtering and unsupported reopened operators. |
| Replace native `confirm()` in authoring chrome | `ja-suportado-so-ux` | Platform authoring now uses the governed Material confirmation dialog for clearing column content. | Low. | `row-configurator` spec covers cancel and confirm flows. |
| Improve runtime-only rule state actions | `ja-suportado-mal-nomeado-ou-mal-materializado` | Runtime-only diagnostics now expose a non-destructive `Ver JSON` action that opens JSON review without rewriting visual state. | Low/medium. | Config editor spec covers JSON review navigation without mutating `formRulesState`. |
| Add focused advanced-condition gap specs | `docs-apenas` | Converter specs now explicitly preserve `!`, `xor`, `implies`, `between` and `notIn` as JSON-only instead of silently implying visual round-trip support. | Low; test-only guard. | `rule-converters` spec documents unsupported visual shapes without changing runtime behavior. |
| Keep target normalization parity specs | `docs-apenas` | Prefix handling for `visualBlock`, `section`, row, column and action targets is protected against false runtime-only diagnostics and round-trip drift. | Low; test-only guard. | `rule-converters` and `rule-authoring-diagnostics` specs cover explicitly typed prefixed targets, multiple prefixed non-field targets and section header actions. |

## Visual QA Findings

The first browser-level validation of the expanded rule property panel found two
runtime/editor gaps that unit specs did not expose:

| Finding | Cause | Resolution | Evidence |
| --- | --- | --- | --- |
| Numeric structured fields could fail in the browser while unit specs passed | Angular `input type="number"` can write a numeric value into `ngModel`, while the editor builders expected string-only `.trim()` semantics. | Structured builders now normalize editor values through a shared string conversion before validation and persistence. | Focused Playwright flow covers `style`, `options`, `validators` and column `span`. |
| A property-panel apply could be overwritten by a stale visual-builder echo | The config editor accepted a delayed `rulesChanged` event after applying a newer property-panel state. | The config editor now suppresses stale builder echoes until the expected property-panel state is observed. | Config-editor spec simulates stale echo after applying column `span`; Playwright confirms visual round-trip. |

## Follow-Up Implementation Order

1. Baseline current tests before behavior changes.
2. Add focused unit specs that document current advanced-condition gaps. Completed for unary negation and unsupported advanced operator shapes in `rule-converters.spec.ts`.
3. Add focused unit specs for target normalization and multiple prefixed non-field targets. Completed in `rule-converters.spec.ts` and `rule-authoring-diagnostics.spec.ts`.
4. Decide the operator and `valueType` policy. Completed by keeping `literal` and `field` as visual-safe operands, disabling `context` and `function`, and hiding unsupported operators from the visual condition editor until round-trip support exists.
5. Update public claims and AI manifest language to match the supported subset. Completed for Dynamic Form README and AI rule-operation condition descriptions.
6. Expand editors for the next highest-frequency JSON-only command/property
   paths. Completed for structured `surface.open`, scalar property hydration,
   `propertiesWhenFalse` hydration, visual-block node-id guided properties,
   command payload fail-closed validation and non-destructive preservation of
   secondary command effects/policy fields.
7. Keep `payloadExpr`, secondary effects, advanced condition operators,
   `context/function` operands and non-common trigger policies as JSON-only
   until each one has a canonical visual shape and focused round-trip specs.
8. Add focused Playwright flows only after contract and converter behavior are
   explicit.
9. Validate npm publication and landing links after GitHub Actions publishes a
   new package version. Completed for version parity after aligning local
   package manifests to the published `9.0.0-beta.20`; legacy
   `@praxisui/specification*` packages are retired known packages, not active
   release inventory.

## NPM Publication Check

Registry checks on 2026-06-17 show the canonical `@praxisui/*` packages
published as `9.0.0-beta.9` with `latest` also pointing to `9.0.0-beta.9`.
The local workspace manifests were aligned from `9.0.0-beta.4` to
`9.0.0-beta.9`, so the existing postflight validators now pass for canonical
version parity.

Commands run:

```powershell
npm search praxisui --json
npm view @praxisui/table-rule-builder version dist-tags homepage repository.url bugs.url --json
cmd.exe /c npm run validate:npm-registry -- --published
cmd.exe /c npm run validate:npm-search-surface
cmd.exe /c npm run validate:package-peers
cmd.exe /c npm run validate:npm-docs
cmd.exe /c npm run audit:npm-packages
```

Resolved:

- `validate:npm-registry -- --published` passes after local package manifests
  were aligned to `9.0.0-beta.9`.
- `validate:npm-search-surface` passes for the 22 canonical packages after the
  local-vs-search version drift was removed.
- `validate:package-peers`, `validate:npm-docs` and `audit:npm-packages` pass
  for the aligned package metadata.

Retired package policy:

- npm search can still report `@praxisui/specification` and
  `@praxisui/specification-core` at `1.0.0-beta.28`.
- They are tracked as known retired packages and must stay out of active docs,
  workspace paths, test libs and release inventory.
- External npm deprecation still requires an authenticated package owner.

## Validation Plan

Before functional changes:

```powershell
cmd.exe /c npx ng test praxis-visual-builder --watch=false --browsers=ChromeHeadless
cmd.exe /c npx ng test praxis-dynamic-form --watch=false --browsers=ChromeHeadless --include=projects/praxis-dynamic-form/src/lib/utils/rule-converters.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.spec.ts
```

For authoring flows after behavior changes:

```powershell
cmd.exe /c npx playwright test projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-rules.playwright.spec.ts
cmd.exe /c npx playwright test projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-command-rules.playwright.spec.ts
cmd.exe /c npx playwright test projects/praxis-dynamic-form/test-dev/e2e/surface-open-form-demo.playwright.spec.ts
```

Use Playwright screenshots as visual evidence only. Functional assertions should
prefer config JSON, diagnostics state and stable `data-testid` selectors.

## Ready Criteria For The Next Public Docs Update

- Public README claims are mapped to `stable visual round-trip`,
  `runtime-supported JSON-only` or `planned/experimental`.
- AI manifest operations that cannot round-trip are downgraded, made explicit
  as experimental, or backed by focused tests.
- Structured command payloads, scalar properties, false-branch property values
  and visual-block guided properties are backed by focused round-trip specs
  before being described as visually authorable.
- `formRulesState` is documented as internal editor state, never as an LLM write
  target.
- NPM package page, `npm view`, dist-tags, landing page and official links are
  checked after publication.
- The LLM-safe subset is explicit: simple JSON Logic field comparisons,
  `and/or`, existing targets, properties allowed by `RULE_PROPERTY_SCHEMA`,
  reviewed `formRules`, no direct `formRulesState`, no JavaScript/textual DSL.
