Praxis Form Editor Document Roundtrip
This praxis-form-* skill family is the canonical Codex skill surface for @praxisui/dynamic-form and projects/praxis-dynamic-form; do not create parallel praxis-dynamic-form-* guidance unless this family cannot express a proven contract gap.
Use this skill for the canonical authoring document contract of @praxisui/dynamic-form. The editor document is the complete snapshot exchanged by Settings Panel/editor surfaces; runtime discovery values are evidence, not persisted semantic ownership.
Source Audit
Inspect these files before editing:
projects/praxis-dynamic-form/AGENTS.mdprojects/praxis-dynamic-form/src/lib/dynamic-form-editor-document.model.tsprojects/praxis-dynamic-form/src/lib/dynamic-form-editor-capability.tsprojects/praxis-dynamic-form/src/lib/settings-panel.providers.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.tsprojects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form-widget-config-editor.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form-authoring-protocol.spec.tsprojects/praxis-dynamic-form/src/lib/dynamic-form-editor-capability.spec.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form.first-config-hydration.spec.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form.external-config-hydration.spec.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form.config-editor.spec.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.spec.tsprojects/praxis-dynamic-form/src/lib/config-editor/**projects/praxis-dynamic-form/src/lib/behavior-editor/**projects/praxis-dynamic-form/src/lib/rules-editor/**projects/praxis-dynamic-form/src/lib/messages-editor/**projects/praxis-dynamic-form/src/lib/hooks-editor/**projects/praxis-dynamic-form/src/lib/actions-editor/**projects/praxis-dynamic-form/src/lib/json-config-editor/**projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.tsprojects/praxis-dynamic-form/src/lib/ai/dynamic-form-agentic-authoring-turn-flow.tsprojects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.tsprojects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.tsprojects/praxis-dynamic-form/docs/dynamic-form-authoring-document-semantics.mdprojects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.json-api.mdprojects/praxis-dynamic-form/src/lib/json-config-editor/form-json-config-editor.json-api.md- related JSON API docs for editor surfaces when public docs or generated docs can change
Inspect projects/praxis-settings-panel/AGENTS.md when changing Settings Panel providers, drawer values, apply, save, reset, ETag, or persistence behavior.
For Settings Panel protocol changes, inspect these concrete files:
projects/praxis-settings-panel/src/lib/settings-panel.component.tsprojects/praxis-settings-panel/src/lib/settings-panel.component.spec.tsprojects/praxis-settings-panel/src/lib/settings-panel.ref.tsprojects/praxis-settings-panel/src/lib/settings-panel.service.tsprojects/praxis-settings-panel/src/lib/settings-panel.service.spec.tsprojects/praxis-settings-panel/src/lib/settings-panel-bridge.provider.tsprojects/praxis-settings-panel/src/lib/settings-panel-bridge.provider.spec.tsprojects/praxis-settings-panel/src/lib/ai/praxis-settings-panel-authoring-manifest.tsprojects/praxis-settings-panel/src/lib/ai/praxis-settings-panel-authoring-manifest.spec.ts
Document Contract
DynamicFormAuthoringDocument has:
kind: "praxis.dynamic-form.editor"version: 1config: FormConfig- optional
bindings, includingmode,presentationModeGlobal, andemptyState - optional
contextSnapshot, includingbackConfig,presentation, andschemaPrefs
Canonical apply/save is replace-all:
configreplaces previous config.bindingsreplaces previous persistible bindings.- missing
bindings.modeclears persisted mode. contextSnapshotreplaces previous authoring context.- missing
backConfig,presentation, orschemaPrefsinsidecontextSnapshotclears that block. - runtime values such as
schemaUrl,submitUrl,submitMethod, and resolved resource metadata are diagnostics only; do not persist them into bindings or context snapshots. - editor
runtimeContextis read-only operational evidence. It may exposeresolvedContract.schemaUrl,submitUrl, orsubmitMethodin the UI, but must not be copied into the authoring document. formRulesStateis internal derived round-trip state for the visual builder. Do not make AI, JSON authoring, or manual editor workflows write it directly; derive or preserve it through the existing editor paths.
When projecting formRulesState into formRules, distinguish an intentionally empty rootNodes: [] from a declared root that is missing or has no valid target. ruleBuilderStateToFormLayoutRules must throw for missing/targetless roots instead of silently returning an empty rule list; the editor must retain the last accepted config, keep the invalid visual draft available for repair, and block Apply/Save. While conversion fails, hide the stale accepted effects panel and accepted-rule diagnostics and explain that repair belongs in the visual wizard or JSON; restore that panel after successful conversion. Programmatic recovery handlers do not establish an available panel-based UI repair path. Intentional deletion of the last rule must instead clear formRules/formRulesState and recover validity. Prove both paths and save/reopen in utils/rule-converters.spec.ts and config-editor/praxis-dynamic-form-config-editor.spec.ts; preserve the existing graph-validation boundary rather than treating conversion failure as a deletion.
When reopening canonical formRules, formLayoutRulesToBuilderState must create one selectable
propertyRule root per rule, preserving its ID, full targets/targetType, both effect branches,
description, and authoring/semantic metadata. Do not downgrade property effects to legacy
conditional-validator nodes or duplicate a multi-target rule into separate roots. Preserve advanced
conditions inline when the visual graph cannot reconstruct them exactly; prove selectable reopen
and lossless serialization in utils/rule-converters.spec.ts.
Legacy editor payloads may be normalized into the canonical document, but new code should author the document shape directly.
DynamicFormAuthoringDocument owns authoring state only. FormConfig owns form config. bindings owns persistible runtime mode preferences. contextSnapshot owns persistible authoring context such as backConfig, presentation, and schema preferences. Host discovery values, resolved schema URLs, submit endpoints, HTTP methods, and current resource metadata are read-only diagnostics and may appear in editor UI only as evidence.
Field metadata editor patches may use merge semantics inside the edited field. For nested entityLookup.optionSource, preserve existing canonical values such as key, resourcePath, valuePropertyPath, and capabilities.byIds when editing only dependsOn, selectionPolicy, detail, or audit metadata.
domainRules is a runtime input for consuming governed materializations from
/api/praxis/config/domain-rules/materializations; it is not a field of
DynamicFormAuthoringDocument. Do not save materialized DomainRuleMaterialization rules back into
config.formRules as if the editor authored them locally. If a product explicitly needs to detach a
governed projection into local config, require a named migration/detach decision and preserve
metadata.domainRule provenance so the loss of governance is visible.
Schema/layout materializations with layoutPolicy.persistence='transient' are runtime projections.
Do not persist generated sections, runtime domainRules, resolved schema URLs, submit endpoints, or
materialized domain rules into the authoring document just because the user opened Settings Panel.
Nested layout policy is still canonical authoring data when it was explicitly authored. In
particular, preserve groupedCommand.partialRowStrategy through document normalization, editor
apply plans, JSON serialization, save, and reopen. Do not flatten it into generated column spans or
drop it because the generated schema sections are transient; the policy is authored while those
sections are derived.
Filter form and dynamic form widget editors must follow the same document semantics. Do not create a separate filter-form authoring document unless the shared contract cannot represent a proven gap.
The Filter Form authoring manifest is a fail-closed projection of the Dynamic
Form owner manifest. Reference runtime inputs, operations, targets, validators,
examples, and round-trip requirements by stable identity through
projectComponentAuthoringManifest(); do not copy or weaken owner operations.
Apply Plan Rules
For governed page children, inspect dynamic-form-page-widget-adapter.ts and its
focused specs alongside Config's page-publication-p0 contract. Use
decodeDynamicFormPageInputs / encodeDynamicFormPageInputs to reconstruct the
native document from the single definition.inputs.config plus admitted
binding/context inputs. The raw page profile preserves absence and explicit
values; a normalized editor snapshot must not become a second source of config.
Use projectDynamicFormPageEditorChanges with the original inputs and the mounted
editor's initial/current snapshots to persist only intentional changes. A changed
binding/context requires a new widget key and admitted seed. Do not silently drop
unsupported envelope blocks or add authoringDocument as a runtime input.
The native Form contract preserves all five Core DynamicFormMode values:
create, edit, view, presentation, dossier. Check normalization, apply
plans, real editor save/reopen, metadata and AI runtime-input manifests together.
An editor may recommend view plus presentation options, but it must retain
existing supported values. Filter Form still exposes its own three-mode runtime
subset through a copied projection; never mutate the owner manifest or extend
Filter behavior merely because the shared document supports five modes.
Page admission additionally rejects nulls in merged config objects; null inside
atomic arrays remains distinct and permitted by the Form profile. Exercise raw
presence, reserved JSON keys, native corpus vectors and whole-envelope Core
bounds, rather than asserting only a normalized config. Pair with
praxis-core-composition-runtime for the root codec and
praxis-form-schema-runtime-modes for runtime persistence isolation. These APIs
alone do not prove publication or the later Page Builder/host journey.
The editor capability should produce an apply plan that names what changes:
canonicalConfigbindingsPatchcontextSnapshot- persistence flags for config, bindings, and context snapshot
- runtime refresh flags for mode, presentation, schema state, and back navigation
- metadata flags such as schema snapshot attachment
- diagnostics for invalid document kind/version, config shape, mode, schema prefs, presentation, and command rules
Do not silently merge partial editor state when the canonical document requires replacement semantics.
After Apply, update the dirty baseline only when the owner accepts the local application. Keep that baseline separate from the opening document used by Form Reset. Exercise A → B → Apply → A: the final A must be dirty and applicable. The session-local appliedValues$ acknowledgement is transient and must never enter persisted widget inputs; it confirms local application, not HTTP persistence. Rejected application must not acknowledge the draft.
Isolate SETTINGS_PANEL_DATA at embedded Form wrapper boundaries. A child must not parse its parent's transport envelope as legacy Form config or subscribe to a wrapper acknowledgement as a canonical document. Supply optional session channels only to editors declaring support. Cover this with a real Angular wrapper/child fixture: instance-only stubs cannot detect DI leakage or attempts to clone Observables.
When replaceContext is active, absence is intentional: absent bindings.mode, contextSnapshot.presentation, contextSnapshot.schemaPrefs, or contextSnapshot.backConfig should emit clear flags/patches that remove previously persisted values. A partial editor form that does not own a block must either preserve it explicitly or declare why replacement is correct.
AI-generated edit plans must target the canonical document/apply-plan surface. Do not let AI output ad hoc config patches, prompt-only field moves, or local editor state when the existing capability can express the change.
For Ergon-style migrations, distinguish authored local form configuration from reusable platform
decisions before applying/saving: local layout polish can round-trip through the document, but legal
guidance, shared validation, command availability, approval policy, option-source policy, and other
governed decisions should remain in domain-rules or metadata-backed contracts and project into the
runtime. A successful editor reopen is not proof that the canonical owner is correct if the save
silently converted governed runtime evidence into local FormConfig.
Round-Trip Checklist
For every editor change, prove or inspect:
- Existing runtime/editor document opens with the correct values.
- The canonical editor surface can modify the values.
- Apply emits the expected document/apply plan.
- Runtime reflects the applied values.
- Save persists the intended config, bindings, and context snapshot.
- Reopen reconstructs the same document.
- Reset clears only the intended block.
If the change has no visual editor impact, state why.
Also identify which path owns the proof:
- Settings Panel provider lifecycle: drawer value, apply, save, reset, ETag/persistence integration.
- Widget config editor: dynamic form and filter form document creation, serialization, and reopen.
- Config editor tabs: layout, behavior, rules, messages, hooks, actions, JSON, and cascades.
- Runtime hydration: first config hydration, external config hydration, mode/presentation/schema refresh, and back navigation.
- AI authoring: manifest operation, turn flow, diagnostics, and generated apply plan.
- Governed runtime projections:
domainRulesoptions, materialization status, provenance inmetadata.domainRule, and whether save/reopen preserves the projection as external evidence instead of converting it into local authoredformRules.
Empty selection authoring
bindings.emptyState reuses PraxisDynamicFormEmptyState; it is not a FormConfig section or a second widget-shell state model. The runtime renders it only in view mode without a selected resource id or local record snapshot. Preserve its supported title, description, icon and appearance options through the editor and widget inputs.
Disabling the feature emits null. Replacing a document without the binding clears it; input-first page settings and explicit null must not revive an older preference. The Filter Form must not advertise a selection placeholder it cannot render. Verify valid selection, cleared selection, create/edit, invalid blank title and save/reopen.
Do not confuse empty selection with an empty data value. A form filled with Not informed placeholders does not explain that no record was selected. Before changing runtime templates, audit the existing empty-state input and its authoring bridge. Likewise, a literal separator between missing template values belongs to the authored composition; do not strip arbitrary punctuation globally to compensate for it.
Partial Effective Config and Corporate Acceptance
The effective editor baseline may be only a projection of the authored document, especially with operation-specific schemas. Absence from that baseline is not an explicit deletion. When projecting field edits by canonical name, preserve authored fields absent from both baseline and edited view; separately test intentional removal of a field that was present in the baseline.
Do not approve per-field persistence from emitted JSON alone. Exercise editor → projection → canonical reconciler → schema materialization → reload. Use a permitted visual customization (for example a placeholder) and a server-owned boundary case. Inspect Core's form-config reconciler before deciding whether visibility, requiredness, validation or access metadata can be overridden locally.
Changing layout ownership from schema to authored must not incidentally change operation or visual
intent. Pair layout edits with praxis-form-schema-runtime-modes and cover presentation
Automático/null, true and false across schema/authored ownership. A demo with explicit true does not
prove automatic presentation survives detachment.
Test configuration source with an actual older persisted form preference, not only an input-first fixture. Distinguish Apply, saving the component draft, and saving the page. Await the page persistence acknowledgment before reload, then reopen the editor and compare authored and effective configuration. Report helper tests, runtime tests and browser evidence separately; overlapping suites are not additive.
Aderence Inventory
Classify editor gaps before adding a contract:
ja-suportado-so-ux: document/apply plan is right, but editor UI or diagnostics are incomplete.ja-suportado-mal-nomeado-ou-mal-materializado: a value exists in config, bindings, or context snapshot but is surfaced under the wrong editor concept.suportado-parcialmente: one editor path round-trips while Settings Panel, JSON editor, or reopen path does not.lacuna-real-de-contrato: the value cannot be represented byFormConfig, bindings, context snapshot, or existing settings provider.
Only lacuna-real-de-contrato justifies a new public document field.
Treat a value that works in one editor tab but fails in another path as suportado-parcialmente, not a new contract. First repair the missing editor, JSON, Settings Panel, apply-plan, or reopen projection.
Validation
- Document normalization/apply plan:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/dynamic-form-editor-capability.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-authoring-protocol.spec.ts - Widget editor round-trip:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form-widget-config-editor.spec.ts - Runtime hydration/context:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.first-config-hydration.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.external-config-hydration.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.layout-policy.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.compact-presentation-dom.spec.ts - Config/editor paths:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts - For nested
layoutPolicyadditions, add a focused serialize/parse/reopen assertion that proves the exact nested value survives; runtime layout tests alone are not document round-trip evidence. - Tab-specific editor paths: add the focused specs under
behavior-editor,rules-editor,messages-editor,hooks-editor,actions-editor, andconfig-editor/rule-properties-panel.component.spec.tswhen those blocks change. - Settings Panel protocol:
npx ng test praxis-settings-panel --watch=false --progress=false --include=projects/praxis-settings-panel/src/lib/settings-panel.component.spec.ts --include=projects/praxis-settings-panel/src/lib/settings-panel.service.spec.ts --include=projects/praxis-settings-panel/src/lib/settings-panel-bridge.provider.spec.ts - Settings Panel AI/protocol manifest:
npx ng test praxis-settings-panel --watch=false --progress=false --include=projects/praxis-settings-panel/src/lib/ai/praxis-settings-panel-authoring-manifest.spec.ts - AI/rule authoring:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.spec.ts --include=projects/praxis-dynamic-form/src/lib/ai/dynamic-form-agentic-authoring-turn-flow.spec.ts --include=projects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.spec.ts - Browser authoring: focused Playwright such as
form-config-editor-smoke,form-config-editor-json,form-config-editor-layout,form-config-editor-behavior,form-config-editor-rules,form-config-editor-messages,form-config-editor-hooks,form-config-editor-actions,form-config-editor-cascades, and apply/save/reset/reopen flows when visible behavior changes. npm run build:praxis-dynamic-formwhen public document models, capability exports, Settings Panel providers, or editor public APIs change.npm run validate:published-doc-assetsandnpm run generate:registry:ingestionwhen JSON API docs, generated docs, AI manifests, or registry surfaces change.
When Filter Form projection changes, add
praxis-filter-form-authoring-manifest.spec.ts and Core
authoring-manifest-projection.spec.ts to the focused proof.
Companion Skills
- Use
praxis-form-authoring-settingsfor the broader editor family and Settings Panel workflow. - Use
praxis-form-schema-runtime-modeswhen bindings/context affect runtime mode, schema prefs, or presentation. - Use
praxis-form-actions-hooks-runtimefor actions/hooks editor round-trip. - Use
praxis-form-ai-rules-validationfor AI component edit plans, diagnostics, and registry ingestion.