# Praxis Page Builder Composition

> 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.

- Skill: `codexrodrigues/praxis-page-builder-composition` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-page-builder-composition`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-page-builder-composition/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-page-builder-composition

---


# 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](references/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](references/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.

