Praxis Visual Builder Graph Runtime
Use this skill for the canonical visual rule graph in @praxisui/visual-builder. Treat RuleBuilderState as the visual source of truth for authoring sessions; JSON Logic and form-rule payloads are projections that must be validated against this graph.
Pair it with:
praxis-visual-builder-jsonlogic-roundtrip when import/export, currentJSON, JSON Logic parsing, or dsl.roundTrip.validate is involved.
praxis-visual-builder-schemas-templates when node configs depend on field schemas, target schemas, property schemas, collection validators, context variables, or templates.
praxis-visual-builder-ai-validation when an AI manifest operation edits nodes, edges, variables, conditions, effects, or validates round-trip.
praxis-core-runtime-contracts when shared JsonLogicExpression, FormLayoutRule, RULE_PROPERTY_SCHEMA, or exported public model contracts change.
praxis-page-builder-authoring when graph editing is hosted as a child widget config editor inside Page Builder.
Source Audit
Before editing graph runtime behavior, inspect:
projects/praxis-visual-builder/AGENTS.md
projects/praxis-visual-builder/README.md
projects/praxis-visual-builder/src/public-api.ts
projects/praxis-visual-builder/src/lib/models/rule-builder.model.ts
projects/praxis-visual-builder/src/lib/services/rule-builder.service.ts
projects/praxis-visual-builder/src/lib/services/rule-node-registry.service.ts
projects/praxis-visual-builder/src/lib/services/rule-validation.service.ts
- focused specs for rule editor, rule canvas, rule definition, rule list, rule builder service, registry, and validation service
Also inspect component hosts such as rule-editor.component.ts, rule-canvas.component.ts, rule-node.component.ts, and visual-rule-builder.component.ts when UI events or selection state change.
Canonical Boundary
@praxisui/visual-builder owns:
RuleBuilderState.nodes and RuleBuilderState.rootNodes;
RuleNode.id as stable node identity;
RuleNode.children as string node IDs only;
RuleNode.parentId for graph hierarchy;
- selection, dirty state, validation errors, and history snapshots;
RuleBuilderService state transitions for add, update, remove, select, clear, undo, redo, import, export, and validation;
RuleNodeRegistryService node resolution, child resolution, orphan cleanup, cycle detection, and integrity checks;
RuleValidationService tree validation for structure, dependency, business logic, performance, and custom rules.
Consumers must not embed child node objects in children, derive node identity from labels, or keep a parallel local graph model. If a host needs visual rule authoring, it should host the visual builder or delegate to this graph contract.
Hosts may store the resulting rule document in their own config, but graph state identity remains Visual Builder-owned and must be round-tripped before persistence.
Inventory Before New Contract
Before adding fields or services, classify the need:
ja-suportado-so-ux: selection, validation errors, root nodes, history, or registry state exists but the editor does not surface it clearly.
ja-suportado-mal-nomeado-ou-mal-materializado: a host uses labels, array indexes, embedded child objects, or local aliases where RuleNode.id, rootNodes, children, or parentId already carry the identity.
suportado-parcialmente: the graph can represent the decision, but a specific node type lacks complete validation, UI editing, or JSON Logic round-trip.
lacuna-real-de-contrato: no current node model, graph relation, registry check, validation error, or projection path can represent the visual decision.
Only a real contract gap justifies public model changes. Name the canonical owner, impacted consumers, docs/examples, AI manifest impact, derived artifacts, and minimum validation before editing.
Graph Rules
- Preserve
RuleNode.id during updates. RuleBuilderService.updateNode(...) must not allow identity mutation.
- Keep
children as string IDs. RuleNodeRegistryService.resolveChildren(...) intentionally fails on embedded objects because that state violates the graph model.
- Keep
rootNodes limited to top-level rules. A node should not be both root and referenced as a child unless the graph semantics explicitly allow it and validation is updated.
- Reject missing roots, missing children, cycles, and invalid parent references through service-level validation.
- Treat orphan warnings as authoring diagnostics, not as permission to persist disconnected semantics.
- Use
saveSnapshot(...)-driven history for undo/redo rather than ad hoc local copies in hosts.
- Keep destructive node or edge operations explicit when conditions, effects, or descendants can be lost.
For property-rule condition edits, use RuleBuilderService.updateNode(nodeId, updates, conditionState?) with the complete existing RuleBuilderState, including every reachable group
child. The canonical service transfers the owned condition graph atomically, preserves unrelated
or shared nodes and selection, and records one undo snapshot. Incomplete or cyclic conditions
remain graph drafts with diagnostics, never unconditional rules; complete conditions project from
fresh nodes/rootNodes, not cached currentJSON. Do not merge partial subgraphs through import
or reset history through whole-state replacement. Prove repair, selection/reopen, ownership,
cycles, and undo in rule-builder.service.spec.ts and rule-editor.component.spec.ts.
For wizard echoes, compare the actual normalized projection returned by the owning
service, including its reachable condition graph. Adding a second root may wrap
roots or remap IDs; acknowledge only that exact own projection once, preserving
the current step. Same rule ID alone is not an echo proof. A meaningful external
graph replacement must still hydrate, even after an own update; do not ignore all
incoming states while waiting for an expected echo.
Recursive RuleNodeComponent instances must forward each descendant update with
the original leaf ID and update payload through every ancestor to the canonical
owner. Prove this through mounted templates, not only direct service calls: add a
second incomplete root without leaving Condition, then repair a typed false
leaf through several AND/OR levels. Check sibling IDs/order, unrelated rules,
validation gates, the exact exported condition and one undo/redo snapshot per
logical edit. An emitted leaf event without a changed owning graph is not success.
Validation
Use the smallest reliable proof:
- graph service changes:
rule-builder.service.spec.ts, registry specs, and validation service specs;
- editor state changes:
rule-editor.component.spec.ts, rule-canvas.component.spec.ts, rule-node.component.spec.ts, and rule-list.component.spec.ts;
- graph serialization side effects: add
praxis-visual-builder-jsonlogic-roundtrip validation;
- hosted editor side effects: add the host authoring validation when Page Builder, Dynamic Form, Table, or Manual Form persists the graph result;
- public API or model changes:
npm run build:praxis-visual-builder plus one focused consumer when exported contracts are touched.
Report exactly which graph, UI, registry, round-trip, and build gates were executed or skipped.
1---2name: praxis-visual-builder-graph-runtime3description: "Use when Codex must implement, audit, or consume @praxisui/visual-builder graph runtime state: RuleBuilderState, RuleNode, RuleNodeType, RuleBuilderService node add/update/remove/select, undo/redo snapshots, rootNodes, children edge IDs, RuleNodeRegistryService, RuleValidationService, graph integrity, cycles, orphaned nodes, validationErrors, or visual rule editor state."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-visual-builder-graph-runtime6---78# Praxis Visual Builder Graph Runtime910Use this skill for the canonical visual rule graph in `@praxisui/visual-builder`. Treat `RuleBuilderState` as the visual source of truth for authoring sessions; JSON Logic and form-rule payloads are projections that must be validated against this graph.1112Pair it with:1314- `praxis-visual-builder-jsonlogic-roundtrip` when import/export, `currentJSON`, JSON Logic parsing, or `dsl.roundTrip.validate` is involved.15- `praxis-visual-builder-schemas-templates` when node configs depend on field schemas, target schemas, property schemas, collection validators, context variables, or templates.16- `praxis-visual-builder-ai-validation` when an AI manifest operation edits nodes, edges, variables, conditions, effects, or validates round-trip.17- `praxis-core-runtime-contracts` when shared `JsonLogicExpression`, `FormLayoutRule`, `RULE_PROPERTY_SCHEMA`, or exported public model contracts change.18- `praxis-page-builder-authoring` when graph editing is hosted as a child widget config editor inside Page Builder.1920## Source Audit2122Before editing graph runtime behavior, inspect:2324- `projects/praxis-visual-builder/AGENTS.md`25- `projects/praxis-visual-builder/README.md`26- `projects/praxis-visual-builder/src/public-api.ts`27- `projects/praxis-visual-builder/src/lib/models/rule-builder.model.ts`28- `projects/praxis-visual-builder/src/lib/services/rule-builder.service.ts`29- `projects/praxis-visual-builder/src/lib/services/rule-node-registry.service.ts`30- `projects/praxis-visual-builder/src/lib/services/rule-validation.service.ts`31- focused specs for rule editor, rule canvas, rule definition, rule list, rule builder service, registry, and validation service3233Also inspect component hosts such as `rule-editor.component.ts`, `rule-canvas.component.ts`, `rule-node.component.ts`, and `visual-rule-builder.component.ts` when UI events or selection state change.3435## Canonical Boundary3637`@praxisui/visual-builder` owns:3839- `RuleBuilderState.nodes` and `RuleBuilderState.rootNodes`;40- `RuleNode.id` as stable node identity;41- `RuleNode.children` as string node IDs only;42- `RuleNode.parentId` for graph hierarchy;43- selection, dirty state, validation errors, and history snapshots;44- `RuleBuilderService` state transitions for add, update, remove, select, clear, undo, redo, import, export, and validation;45- `RuleNodeRegistryService` node resolution, child resolution, orphan cleanup, cycle detection, and integrity checks;46- `RuleValidationService` tree validation for structure, dependency, business logic, performance, and custom rules.4748Consumers must not embed child node objects in `children`, derive node identity from labels, or keep a parallel local graph model. If a host needs visual rule authoring, it should host the visual builder or delegate to this graph contract.49Hosts may store the resulting rule document in their own config, but graph state identity remains Visual Builder-owned and must be round-tripped before persistence.5051## Inventory Before New Contract5253Before adding fields or services, classify the need:5455- `ja-suportado-so-ux`: selection, validation errors, root nodes, history, or registry state exists but the editor does not surface it clearly.56- `ja-suportado-mal-nomeado-ou-mal-materializado`: a host uses labels, array indexes, embedded child objects, or local aliases where `RuleNode.id`, `rootNodes`, `children`, or `parentId` already carry the identity.57- `suportado-parcialmente`: the graph can represent the decision, but a specific node type lacks complete validation, UI editing, or JSON Logic round-trip.58- `lacuna-real-de-contrato`: no current node model, graph relation, registry check, validation error, or projection path can represent the visual decision.5960Only a real contract gap justifies public model changes. Name the canonical owner, impacted consumers, docs/examples, AI manifest impact, derived artifacts, and minimum validation before editing.6162## Graph Rules6364- Preserve `RuleNode.id` during updates. `RuleBuilderService.updateNode(...)` must not allow identity mutation.65- Keep `children` as string IDs. `RuleNodeRegistryService.resolveChildren(...)` intentionally fails on embedded objects because that state violates the graph model.66- Keep `rootNodes` limited to top-level rules. A node should not be both root and referenced as a child unless the graph semantics explicitly allow it and validation is updated.67- Reject missing roots, missing children, cycles, and invalid parent references through service-level validation.68- Treat orphan warnings as authoring diagnostics, not as permission to persist disconnected semantics.69- Use `saveSnapshot(...)`-driven history for undo/redo rather than ad hoc local copies in hosts.70- Keep destructive node or edge operations explicit when conditions, effects, or descendants can be lost.7172For property-rule condition edits, use `RuleBuilderService.updateNode(nodeId, updates,73conditionState?)` with the complete existing `RuleBuilderState`, including every reachable group74child. The canonical service transfers the owned condition graph atomically, preserves unrelated75or shared nodes and selection, and records one undo snapshot. Incomplete or cyclic conditions76remain graph drafts with diagnostics, never unconditional rules; complete conditions project from77fresh `nodes`/`rootNodes`, not cached `currentJSON`. Do not merge partial subgraphs through import78or reset history through whole-state replacement. Prove repair, selection/reopen, ownership,79cycles, and undo in `rule-builder.service.spec.ts` and `rule-editor.component.spec.ts`.8081For wizard echoes, compare the actual normalized projection returned by the owning82service, including its reachable condition graph. Adding a second root may wrap83roots or remap IDs; acknowledge only that exact own projection once, preserving84the current step. Same rule ID alone is not an echo proof. A meaningful external85graph replacement must still hydrate, even after an own update; do not ignore all86incoming states while waiting for an expected echo.8788Recursive `RuleNodeComponent` instances must forward each descendant update with89the original leaf ID and update payload through every ancestor to the canonical90owner. Prove this through mounted templates, not only direct service calls: add a91second incomplete root without leaving Condition, then repair a typed `false`92leaf through several AND/OR levels. Check sibling IDs/order, unrelated rules,93validation gates, the exact exported condition and one undo/redo snapshot per94logical edit. An emitted leaf event without a changed owning graph is not success.9596## Validation9798Use the smallest reliable proof:99100- graph service changes: `rule-builder.service.spec.ts`, registry specs, and validation service specs;101- editor state changes: `rule-editor.component.spec.ts`, `rule-canvas.component.spec.ts`, `rule-node.component.spec.ts`, and `rule-list.component.spec.ts`;102- graph serialization side effects: add `praxis-visual-builder-jsonlogic-roundtrip` validation;103- hosted editor side effects: add the host authoring validation when Page Builder, Dynamic Form, Table, or Manual Form persists the graph result;104- public API or model changes: `npm run build:praxis-visual-builder` plus one focused consumer when exported contracts are touched.105106Report exactly which graph, UI, registry, round-trip, and build gates were executed or skipped.