Praxis Page Builder Composition
Use this skill for the Page Builder runtime/composition surface. @praxisui/page-builder is the canonical visual editor for dynamic pages based on WidgetPageDefinition and the praxis-dynamic-page runtime; it must not become a parallel component runtime, host-local connection language, or owner of child widget semantics.
Pair it with:
praxis-core-composition-runtime for shared WidgetPageDefinition, widget events, widget shell, composition links, transforms, runtime observations, and dynamic page materialization.
praxis-navigation-container-composition-events when Page Builder pages embed tabs, stepper/wizard, or expansion containers with nested widgets, lazy content, event paths, or composition links.
praxis-page-builder-authoring for page config editors, shell editor, Settings Panel bridge, and visual round-trip.
praxis-page-builder-ai-agentic for agentic page composition, AI catalogs, manifests, streaming authoring, and preview/apply flows.
- the owning child component skill, such as charts, table, form, fields, or CRUD, when a widget input/config document changes.
praxis-list-runtime-data, praxis-list-authoring-settings, and praxis-list-ai-validation when Page Builder hosts rich praxis-list widgets. Page Builder should host the list contract, not redefine list templating, data precedence, or declared-only runtime status.
praxis-rich-content-runtime, praxis-rich-content-authoring-settings, and praxis-rich-content-integration-adapters when Page Builder hosts praxis-rich-content, insertion presets, RichContentDocument, or rich-content config editors.
Canonical Boundary
Persist and materialize WidgetPageDefinition. Do not reintroduce GridPageDefinition as the canonical builder shape. Legacy options, layout, x/y/cols/rows, and similar compatibility fields must be normalized explicitly and not promoted as current guidance.
Page Builder owns:
- visual page editing around
praxis-dynamic-page;
- component palette insertion from
ComponentMetadataRegistry, ComponentDocMeta, and insertion presets;
- stable
widget.key identity and canvas items;
- page-level shell, grouping, theme/layout presets, state, context, device layouts, and slot assignments;
page.composition.links, connection graph UX, diagnostics, nested component-port paths, state endpoints, and global-action endpoints.
- surface handoff through shared core surface/global-action/composition contracts, not Page Builder-local commands.
- runtime observations as frontend grounding evidence for authoring and diagnostics, not backend truth.
Child components own their inputs, runtime behavior, config editors, authoring manifests, and validation. Page Builder may host or delegate those editors; it must not special-case table/form/chart/list semantics locally.
Required Source Inventory
Before editing Page Builder composition, inspect:
projects/praxis-page-builder/AGENTS.md
projects/praxis-page-builder/src/public-api.ts
projects/praxis-page-builder/src/lib/dynamic-page-builder.component.ts
projects/praxis-page-builder/src/lib/praxis-page-builder.metadata.ts
projects/praxis-page-builder/src/lib/editor/component-palette-dialog.component.ts
projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor.component.ts
projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor-graph.util.ts
projects/praxis-page-builder/src/lib/editor/connection-editor/*.{ts,spec.ts} for graph, geometry, layout, port order, trace, and wire changes
projects/praxis-page-builder/src/lib/connections-viewer-panel.component.ts
projects/praxis-page-builder/src/lib/connections-viewer.util.ts
projects/praxis-page-builder/src/lib/ai/page-builder-runtime-normalization.util.ts when runtime observations or AI context depend on normalized page state
projects/praxis-core/src/lib/composition/**, widgets/**, and composition model files when runtime contracts are affected
- focused specs called out by the local
AGENTS.md
Composition Rules
For connecting installed widgets through the browser, read
browser-connections.md. It covers query,
selection, state and action flows without prescribing a screen archetype.
For connection-diagram work, load connection-editor-ux.md.
It maps the existing editorial, trace, caption, routing, viewport, and inspection
sources to their invariants and focused proof. This is the Page Builder connection
graph over composition.links, not Visual Builder's RuleBuilderState.
Use stable widget keys for all widget, canvas, shell, and composition operations. Never address widgets by array index in persisted links or AI/edit operations.
Model wiring as canonical page.composition.links:
- component endpoints:
{ kind: "component-port", ref: { widget, port, direction, bindingPath?, nestedPath? } }
- state endpoints:
{ kind: "state", ref: { path, layer? } }
- global-action endpoints:
{ kind: "global-action", ref: { actionId, payload?, payloadExpr?, meta? } }
- link identity: stable
id
- intent: use the runtime
LinkIntent vocabulary, not command strings
- conditions/transforms: use the shared composition transform/JSON Logic path
For nested widgets, preserve nestedPath and terminal child widget identity. Do not flatten nested component ports into string aliases that cannot round-trip through the runtime.
For palette work, derive entries from ComponentMetadataRegistry and ComponentDocMeta. ComponentDocMeta.configEditor, actions, commands, insertion presets, tags, icon, and descriptions are owned by the component metadata source, not by a Page Builder hardcoded list.
For surface handoff, prefer shared GlobalActionRef, SurfaceOpenPayload, surface.result, and dynamicPage.composition.dispatch paths from core. Do not encode open/edit/select behavior as string commands in page-builder links.
surface.open should be authored as a global-action endpoint with structured ref payload,
payloadExpr, or meta when needed. Row selections, drawer results, and returned surface payloads
should re-enter the page through canonical composition/state/action paths such as surface.result or
dynamicPage.composition.dispatch; do not persist runtime drawer envelopes, result$ values, or
selection payload snapshots into definition.inputs as a shortcut.
When a surface.open flow writes back into page state or another component, validate it like any
other composition link, including feedback-cycle diagnostics and guards. A drawer result is runtime
event data, not proof that the target widget's config/input document should be mutated.
For runtime observations, preserve the trust boundary: observations can explain selected widgets, visible runtime state, component ids, resource refs, and diagnostics, but they must remain serializable and redacted before being sent into agentic authoring.
Factory And Certification Evidence
Composition factory readiness requires more than a valid page literal. Preflight
the UiCompositionPlan against the target registry, preserve semantic lineage
through first-pass, refinement, preview, apply, persistence, reload, and mode
switches, and emit sanitized receipts that name the archetype and canonical
sources without embedding raw rows or prompts. A successful render does not
certify CRUD, related-resource, global-action, or cross-filter behavior; use the
matrix-owned production-like scenario for the exact archetype.
Do not persist factory projections or readiness/receipt state in
WidgetPageDefinition. Those remain derived execution evidence.
Dashboard Host And Persistence Ownership
A dashboard is a WidgetPageDefinition consumed by Dynamic Page/Page Builder; do
not introduce a dashboard-specific public wrapper merely to repeat a toolbar,
identity or persistence workflow. Keep domain presentation in the host and fix
reusable lifecycle behavior in Core. Inspect the resolved library version before
using lifecycle APIs; previously published packages may not contain them.
For manual pages, the builder can opt in to Core persistence with autoPersist and
pageIdentity. Its default is false, preserving host-owned persistence. Do not
also save pageChange in the host. Runtime persistenceChange is operational
feedback, not a persisted page field or AI runtimeInputs entry. Show success only
after storage acknowledgement; distinguish loading, saved, idle/factory and error.
Forward identity before loading another owner's page and restore the host seed on
a miss. Never copy a shared persona cache into a new owner's configuration.
resetPersistedPage(defaultPage) restores the supplied default only after clear
acknowledgement. reloadPersistedPage(defaultPage) explicitly discards a draft and
reloads storage; a missing document uses that default. Surface this intent in UX.
For transient save failures, offer retryPersistedPage() to retain the current draft,
including an empty page, without emitting host save lifecycle events. Conflicts still
require explicit reload; do not make discarding a draft the only recovery choice.
Core serializes mutations, ignores obsolete identity responses, retains edits made
while loading/resetting and blocks conflicted writes until an explicit reload.
Persisted empty pages are valid; do not append factory widgets or overwrite saved
child inputs during rehydration. Test child enableCustomization with a stored
value different from the host seed and assert there is no load-to-save echo.
Keep automatic generic persistence disabled for authoringDocument and agentic
previews. Governed apply owns revision/provenance; enabling a generic autosave must
not bypass it. Use focused Core and builder persistence specs plus real host UI
save/reopen/reset and identity-switch proof. Mocked HTTP browser tests do not prove
remote database behavior; database-dependent proof requires an isolated Neon branch.
Public API
Treat projects/praxis-page-builder/src/public-api.ts as public contract. Changes can affect hosts, AI registry ingestion, @praxisui/core, Settings Panel bridge, child component config editors, docs, and examples. Map those consumers before changing exports.
Do not make Page Builder a transitively convenient root barrel for another public lib. Prefer the canonical owner for shared types and expose only Page Builder's own intentional surface.
Validation
Use the smallest reliable gate:
- composition graph/link changes:
connection-editor.component.spec.ts plus relevant graph/layout/port-order/trace/wire util specs.
- palette changes:
component-palette-dialog.component.spec.ts and browser smoke when insertion UX changes.
- runtime page shape changes:
dynamic-page-builder.component.spec.ts, core composition runtime specs, and ng build praxis-page-builder.
- runtime observations or surface handoff: pair Page Builder specs with
praxis-core-composition-runtime, praxis-core-widget-observations, praxis-core-global-action-payloads, or praxis-core-surface-materialization validation as applicable.
- public API changes: build
praxis-page-builder and at least one direct consumer when feasible.
- browser interaction changes: local Playwright lane for palette insertion or page-builder authoring, not GitHub Actions as the first diagnostic tool.
When validation is partial, state exactly which specs or browser lanes ran and which runtime/materialization gates remain. If composition changes alter agentic context, runtime observations, preview/apply, backend tools, manifests, SSE, or LLM-backed page edits, pair with praxis-page-builder-ai-agentic and use the full local agentic Playwright gate required by projects/praxis-page-builder/AGENTS.md; the quick smoke is diagnostic, not a substitute for that gate.
1---2name: praxis-page-builder-composition3description: "Use when Codex must inspect, change, or scaffold @praxisui/page-builder composition behavior: DynamicPageBuilderComponent, WidgetPageDefinition, praxis-dynamic-page runtime materialization, component palette, ComponentMetadataRegistry, widget keys, canvas layout, page.composition.links, connection editor graph, nestedPath component-port endpoints, page state, global-action endpoints, public API, or composition changes that feed Page Builder agentic validation gates."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-page-builder-composition6---78# Praxis Page Builder Composition910Use this skill for the Page Builder runtime/composition surface. `@praxisui/page-builder` is the canonical visual editor for dynamic pages based on `WidgetPageDefinition` and the `praxis-dynamic-page` runtime; it must not become a parallel component runtime, host-local connection language, or owner of child widget semantics.1112Pair it with:1314- `praxis-core-composition-runtime` for shared `WidgetPageDefinition`, widget events, widget shell, composition links, transforms, runtime observations, and dynamic page materialization.15- `praxis-navigation-container-composition-events` when Page Builder pages embed tabs, stepper/wizard, or expansion containers with nested widgets, lazy content, event paths, or composition links.16- `praxis-page-builder-authoring` for page config editors, shell editor, Settings Panel bridge, and visual round-trip.17- `praxis-page-builder-ai-agentic` for agentic page composition, AI catalogs, manifests, streaming authoring, and preview/apply flows.18- the owning child component skill, such as charts, table, form, fields, or CRUD, when a widget input/config document changes.19- `praxis-list-runtime-data`, `praxis-list-authoring-settings`, and `praxis-list-ai-validation` when Page Builder hosts rich `praxis-list` widgets. Page Builder should host the list contract, not redefine list templating, data precedence, or declared-only runtime status.20- `praxis-rich-content-runtime`, `praxis-rich-content-authoring-settings`, and `praxis-rich-content-integration-adapters` when Page Builder hosts `praxis-rich-content`, insertion presets, `RichContentDocument`, or rich-content config editors.2122## Canonical Boundary2324Persist and materialize `WidgetPageDefinition`. Do not reintroduce `GridPageDefinition` as the canonical builder shape. Legacy `options`, `layout`, `x/y/cols/rows`, and similar compatibility fields must be normalized explicitly and not promoted as current guidance.2526Page Builder owns:2728- visual page editing around `praxis-dynamic-page`;29- component palette insertion from `ComponentMetadataRegistry`, `ComponentDocMeta`, and insertion presets;30- stable `widget.key` identity and canvas items;31- page-level shell, grouping, theme/layout presets, state, context, device layouts, and slot assignments;32- `page.composition.links`, connection graph UX, diagnostics, nested component-port paths, state endpoints, and global-action endpoints.33- surface handoff through shared core surface/global-action/composition contracts, not Page Builder-local commands.34- runtime observations as frontend grounding evidence for authoring and diagnostics, not backend truth.3536Child components own their inputs, runtime behavior, config editors, authoring manifests, and validation. Page Builder may host or delegate those editors; it must not special-case table/form/chart/list semantics locally.3738## Required Source Inventory3940Before editing Page Builder composition, inspect:4142- `projects/praxis-page-builder/AGENTS.md`43- `projects/praxis-page-builder/src/public-api.ts`44- `projects/praxis-page-builder/src/lib/dynamic-page-builder.component.ts`45- `projects/praxis-page-builder/src/lib/praxis-page-builder.metadata.ts`46- `projects/praxis-page-builder/src/lib/editor/component-palette-dialog.component.ts`47- `projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor.component.ts`48- `projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor-graph.util.ts`49- `projects/praxis-page-builder/src/lib/editor/connection-editor/*.{ts,spec.ts}` for graph, geometry, layout, port order, trace, and wire changes50- `projects/praxis-page-builder/src/lib/connections-viewer-panel.component.ts`51- `projects/praxis-page-builder/src/lib/connections-viewer.util.ts`52- `projects/praxis-page-builder/src/lib/ai/page-builder-runtime-normalization.util.ts` when runtime observations or AI context depend on normalized page state53- `projects/praxis-core/src/lib/composition/**`, `widgets/**`, and composition model files when runtime contracts are affected54- focused specs called out by the local `AGENTS.md`5556## Composition Rules5758For connecting installed widgets through the browser, read59[browser-connections.md](references/browser-connections.md). It covers query,60selection, state and action flows without prescribing a screen archetype.6162For connection-diagram work, load [connection-editor-ux.md](references/connection-editor-ux.md).63It maps the existing editorial, trace, caption, routing, viewport, and inspection64sources to their invariants and focused proof. This is the Page Builder connection65graph over `composition.links`, not Visual Builder's `RuleBuilderState`.6667Use stable widget keys for all widget, canvas, shell, and composition operations. Never address widgets by array index in persisted links or AI/edit operations.6869Model wiring as canonical `page.composition.links`:7071- component endpoints: `{ kind: "component-port", ref: { widget, port, direction, bindingPath?, nestedPath? } }`72- state endpoints: `{ kind: "state", ref: { path, layer? } }`73- global-action endpoints: `{ kind: "global-action", ref: { actionId, payload?, payloadExpr?, meta? } }`74- link identity: stable `id`75- intent: use the runtime `LinkIntent` vocabulary, not command strings76- conditions/transforms: use the shared composition transform/JSON Logic path7778For nested widgets, preserve `nestedPath` and terminal child widget identity. Do not flatten nested component ports into string aliases that cannot round-trip through the runtime.7980For palette work, derive entries from `ComponentMetadataRegistry` and `ComponentDocMeta`. `ComponentDocMeta.configEditor`, actions, commands, insertion presets, tags, icon, and descriptions are owned by the component metadata source, not by a Page Builder hardcoded list.8182For surface handoff, prefer shared `GlobalActionRef`, `SurfaceOpenPayload`, `surface.result`, and `dynamicPage.composition.dispatch` paths from core. Do not encode open/edit/select behavior as string commands in page-builder links.83`surface.open` should be authored as a `global-action` endpoint with structured `ref` payload,84`payloadExpr`, or `meta` when needed. Row selections, drawer results, and returned surface payloads85should re-enter the page through canonical composition/state/action paths such as `surface.result` or86`dynamicPage.composition.dispatch`; do not persist runtime drawer envelopes, `result$` values, or87selection payload snapshots into `definition.inputs` as a shortcut.88When a `surface.open` flow writes back into page state or another component, validate it like any89other composition link, including feedback-cycle diagnostics and guards. A drawer result is runtime90event data, not proof that the target widget's config/input document should be mutated.9192For runtime observations, preserve the trust boundary: observations can explain selected widgets, visible runtime state, component ids, resource refs, and diagnostics, but they must remain serializable and redacted before being sent into agentic authoring.9394## Factory And Certification Evidence9596Composition factory readiness requires more than a valid page literal. Preflight97the `UiCompositionPlan` against the target registry, preserve semantic lineage98through first-pass, refinement, preview, apply, persistence, reload, and mode99switches, and emit sanitized receipts that name the archetype and canonical100sources without embedding raw rows or prompts. A successful render does not101certify CRUD, related-resource, global-action, or cross-filter behavior; use the102matrix-owned production-like scenario for the exact archetype.103104Do not persist factory projections or readiness/receipt state in105`WidgetPageDefinition`. Those remain derived execution evidence.106107## Dashboard Host And Persistence Ownership108109A dashboard is a `WidgetPageDefinition` consumed by Dynamic Page/Page Builder; do110not introduce a dashboard-specific public wrapper merely to repeat a toolbar,111identity or persistence workflow. Keep domain presentation in the host and fix112reusable lifecycle behavior in Core. Inspect the resolved library version before113using lifecycle APIs; previously published packages may not contain them.114115For manual pages, the builder can opt in to Core persistence with `autoPersist` and116`pageIdentity`. Its default is false, preserving host-owned persistence. Do not117also save `pageChange` in the host. Runtime `persistenceChange` is operational118feedback, not a persisted page field or AI `runtimeInputs` entry. Show success only119after storage acknowledgement; distinguish loading, saved, idle/factory and error.120Forward identity before loading another owner's page and restore the host seed on121a miss. Never copy a shared persona cache into a new owner's configuration.122123`resetPersistedPage(defaultPage)` restores the supplied default only after clear124acknowledgement. `reloadPersistedPage(defaultPage)` explicitly discards a draft and125reloads storage; a missing document uses that default. Surface this intent in UX.126For transient save failures, offer `retryPersistedPage()` to retain the current draft,127including an empty page, without emitting host save lifecycle events. Conflicts still128require explicit reload; do not make discarding a draft the only recovery choice.129Core serializes mutations, ignores obsolete identity responses, retains edits made130while loading/resetting and blocks conflicted writes until an explicit reload.131Persisted empty pages are valid; do not append factory widgets or overwrite saved132child inputs during rehydration. Test child `enableCustomization` with a stored133value different from the host seed and assert there is no load-to-save echo.134135Keep automatic generic persistence disabled for `authoringDocument` and agentic136previews. Governed apply owns revision/provenance; enabling a generic autosave must137not bypass it. Use focused Core and builder persistence specs plus real host UI138save/reopen/reset and identity-switch proof. Mocked HTTP browser tests do not prove139remote database behavior; database-dependent proof requires an isolated Neon branch.140141## Public API142143Treat `projects/praxis-page-builder/src/public-api.ts` as public contract. Changes can affect hosts, AI registry ingestion, `@praxisui/core`, Settings Panel bridge, child component config editors, docs, and examples. Map those consumers before changing exports.144145Do not make Page Builder a transitively convenient root barrel for another public lib. Prefer the canonical owner for shared types and expose only Page Builder's own intentional surface.146147## Validation148149Use the smallest reliable gate:150151- composition graph/link changes: `connection-editor.component.spec.ts` plus relevant graph/layout/port-order/trace/wire util specs.152- palette changes: `component-palette-dialog.component.spec.ts` and browser smoke when insertion UX changes.153- runtime page shape changes: `dynamic-page-builder.component.spec.ts`, core composition runtime specs, and `ng build praxis-page-builder`.154- runtime observations or surface handoff: pair Page Builder specs with `praxis-core-composition-runtime`, `praxis-core-widget-observations`, `praxis-core-global-action-payloads`, or `praxis-core-surface-materialization` validation as applicable.155- public API changes: build `praxis-page-builder` and at least one direct consumer when feasible.156- browser interaction changes: local Playwright lane for palette insertion or page-builder authoring, not GitHub Actions as the first diagnostic tool.157158When validation is partial, state exactly which specs or browser lanes ran and which runtime/materialization gates remain. If composition changes alter agentic context, runtime observations, preview/apply, backend tools, manifests, SSE, or LLM-backed page edits, pair with `praxis-page-builder-ai-agentic` and use the full local agentic Playwright gate required by `projects/praxis-page-builder/AGENTS.md`; the quick smoke is diagnostic, not a substitute for that gate.