Praxis Page Builder Authoring
For composing pages through installed editors, read
browser-page-authoring.md. Use
praxis-browser-editor-workflows for browser mechanics and rehearsal evidence.
The component skills own child configuration; the implementation sections below
apply when changing the editor code. This routing serves analytical views,
registration screens and selection/detail workspaces equally.
Use this skill for the visual/textual authoring editors that produce or update WidgetPageDefinition. The goal is not "any editor can mutate JSON"; the goal is a stable round-trip between canonical page semantics, visual editors, Settings Panel, persistence, and runtime rendering.
Pair it with:
praxis-settings-panel-shellandpraxis-settings-roundtrip-authoringfor Settings Panel protocol, footer state, apply/save/reset/cancel, and bridge behavior.praxis-authoring-editorsfor cross-component editor ownership rules.praxis-page-builder-compositionforWidgetPageDefinition, canvas, composition links, connection graph, and runtime materialization.praxis-page-builder-ai-agenticwhen authoring changes affect AI manifests, UI composition plans, or agentic preview/apply.
Canonical Chain
Keep this chain coherent:
WidgetPageDefinition -> Page/DynamicPage config editor state -> SettingsValueProvider output -> pageChange/apply/save -> ui_user_config identity/ETag when persisted -> reopen -> praxis-dynamic-page runtime
For widget shell:
widget.shell -> WidgetShellEditorComponent -> ShellEditorResult -> page.widgets[].shell / pagePreset -> runtime shell
For child widget config:
ComponentDocMeta.configEditor or child ComponentAuthoringManifest -> child-owned document/input patch -> page.widgets[].definition.inputs
Page Builder hosts child editors; it does not redefine child component config documents.
When a child editor needs schemas, capabilities, resource catalogs, page targets, ports, or diagnostics only for authoring, provide them through ComponentDocMeta.configEditor.contextResolver as transient context/contextDiagnostics. Do not persist those values in page.widgets[].definition.inputs; only the editor's explicit settings result may update child inputs.
If the child editor is Visual Builder, Dynamic Form, Table, Chart, List, Rich Content, or another Praxis component, load that component's authoring skill and preserve its document/apply semantics inside page.widgets[].definition.inputs.
When a hosted child editor returns a SettingsValueProvider payload, Page Builder must apply the
child-owned canonical input patch/document projection as definition.inputs, not wrap it in a
Page-Builder-local envelope or merge back transient context. Missing blocks in a replace-all child
document must remain cleared unless the child owner declares merge semantics.
Each editor session must remain tied to the current page/widget instance and authoring context. Pass
the transient owner through the Settings Panel bridge, preserve a valid session across a controlled
pageChange -> [page] echo of the same canonical document, and invalidate it when page identity,
widget instance, context or authoring eligibility changes. Negotiate panel replacement before
destroying the previous owner; stale close/context callbacks must not replace a newer editor or keep
Apply/Save subscriptions alive after their target disappears.
Save As A New Page
When a host repeats page name, menu destination, icon, save/retry and saved-route UI,
inspect src/lib/page-save-as/page-save-as.component.{ts,html,spec.ts} and
page-save-as.model.ts in projects/praxis-page-builder, the library README and
public API, then the host adapter and browser proof. Prefer the standalone
PraxisPageSaveAsComponent from @praxisui/page-builder; it is a composed journey,
not a registered canvas widget or AI operation. Do not add a second host save form,
icon catalog or storage mechanism to the library.
For a copy entry point, use PraxisPageCopyActionComponent from the same library:
feed the current builder draft as page, bind canCopy to the builder's save/review
eligibility and let copyRequested hand the isolated full snapshot to the host's
editor/route placement. Inspect page-copy-action.component.ts and the copy cases
in page-save-as.component.spec.ts; preserve unknown/native fields and clone-failure
feedback. This is a local draft snapshot, not copyPageAuthoringDocument's governed
identity remapping. The host may pass it as transient navigation information; no new
storage, source attestation or corporate copy evidence is implied. The destination
still completes the explicit save-as chain below.
Wire the explicit lifecycle as one chain:
canSave -> saveRequested -> builder.saveCurrentPage() -> pageSaveRequested -> saveAs.save(definition)
Keep the builder's agentic-preview/save eligibility as canSave; do not call the
adapter with builder.currentPage() to bypass the builder's canonical save event.
Use autoPersist=false when the adapter owns the page document, preventing a second
runtime writer. The host supplies a stable adapter and a view/session contextKey
that changes across tenant/persona/route/seed transitions, including A -> B -> A.
This key invalidates UI callbacks; it is not an authentication or authorization grant.
PageSaveAsRequest is a transient UI intent: creation key, full
WidgetPageDefinition, presentation and menu label. Presentation reuses Core's
PageAuthoringDocument type; Page Builder must not reexport Core's public barrel or
create another persisted page envelope. Do not pass this request to Config's
POST /pages: that command admits an exact registered-native or published-page
source, not arbitrary browser content. The full runtime definition may contain
fields/widgets outside the closed publication profile. Preserve them in laboratory
adapters; incompatible corporate content needs owner diagnostics and an admitted
profile extension, never silent stripping or relaxed publication validation.
The adapter owns admission, persistence, page/menu consistency, durable identity and
an openable local route. There is no default storage. Its {pageId, routePath} receipt
must resolve only after confirmation. The component snapshots each attempt, protects
retries from adapter mutation, reuses its creation key for the same payload and
starts a new attempt when the payload/destination changes. Preserve the last confirmed
route on a later failure. Ignore save/icon completions after context or adapter
replacement/destruction; underlying writes still require host/server admission.
Use Core's IconPickerService, accept plain Material names and handle cancellation,
invalid values and dialog failure without losing the draft. The simple journey uses
one chosen icon for presentation and its menu projection; it does not redefine the
separate canonical navigation-binding icon. titleMaxLength/menuMaxLength are view
limits (default 160, valid 1..160); hosts may supply stricter limits such as 80/60.
Those controls do not replace backend or native-document validation.
Prove page-save-as.component.spec.ts, the library build, a direct consumer build
and browser create/copy -> edit -> save -> URL -> reload, plus failed save/retry and
identity change. Keep laboratory Web Lock/storage proof separate from corporate HTTP,
ETag, provenance and Neon proof. Consume through the official package workflow;
private candidate installation proves that candidate only. A host locked to a public
version without the new export remains blocked for merge until a public dependency
contains it; keep its adoption PR draft and dependent. A save-as implementation does
not authorize a package release. Update the owning authoring guidance and public
README in the same cycle; do not claim release, installed parity or corporate
publication from a passing local browser journey.
Governed Corporate Page Publication (P4 / P5-B / P5-D)
When an Angular host adopts governed corporate page authoring and publication:
- Reuse
@praxisui/corepage authoring codecs (encodePageAuthoringDocument,decodePageAuthoringDocument,copyPageAuthoringDocument,validatePageAuthoringDocument,encodeNavigationGroupsAuthoringDocument,decodeNavigationGroupsAuthoringDocument,materializeGovernedPagePreview) and@praxisui/page-builderGovernedPageWorkflowController+GovernedPageNavigationController+createCorporateGovernedPagePersistenceAdapter. Never build a parallel publication state machine or serialize raw runtime state to/api/praxis/config/ui-layouts/**. - Keep child widget configuration exclusively in
widget.definition.inputs.configwithconfigPersistenceStrategy: 'volatile'inside governed pages so personalui_user_configoverrides never shadow the published release. - Declare
childSourcesonPOST /api/praxis/config/ui-layouts/drafts/{draftId}/revisionsonly for newly inserted widget keys; omit unchanged and restored keys, and reject changed fixed binding envelopes (resourcePath,mode,readOnly,operation) for existing widget keys. - Keep
praxis.dynamic-page.editor(navigationBindings[]) separate frompraxis.navigation-groups.editor(groups[]); never embed page routes inside group documents or publish an invalid/unadmitted icon. - For legacy published snapshots in
ui_user_config(LEGACY_PUBLISHED_PAGE_STORAGE_PREFIX), migrate explicitly viainspectLegacyPublishedPagePayload+GovernedPageWorkflowController.importLegacyPublishedPage(POST /api/praxis/config/pagesfrom an admitted native seed + governed revision withlegacyImportedFrom) instead of falling back silently at runtime.
AI Target Context And Operation Ownership
Before validating a targeted AI edit, inspect DynamicPageBuilderComponent's
resolveSelectedWidgetKey, toggleAgenticAuthoring and
resolveSelectedComponentAuthoringContext, plus the emitted stream-start request.
Visual canvas selection is not proof of the pinned AI target. Opening the global
assistant without resuming a minimized instance clears pinned widget context;
resuming a minimized assistant can preserve it. Exercise the intended UI journey and verify the actual
selectedWidgetKey resolves inside the request's currentPage.widgets. A widget
key mentioned only in the prompt does not establish structured target context.
Separate the selected target from the operation owner. Shell operations such as
widget.shell.configure belong to the Page Builder manifest and operate on the
complete page's widgets[].shell. A child's manifest owns its declared inputs;
its contextual assistant and definition.inputs are not authority to change the
parent shell. Inspect Config Starter's AgenticAuthoringPreviewService
(previewComponentEditPlan, direct/component context validation and materialization)
and the owning effect compiler before claiming the page-owned operation is reachable.
A registered schema, resolver or handler unit test does not establish a working
SSE → preview → apply → host persistence → reopen journey.
If that owner/target dispatch is missing, record the platform gap and fix the canonical dispatch rather than rerouting through a child or weakening the proof. Do not fabricate context hints, select targets through prompt keywords, inject a plan into the test, or invent SSE ids/replay cursors to make a live gate pass. Keep local editor round-trip, real AI operation execution and remote persistence as separate evidence; prove unchanged child inputs and unrelated shell state.
Required Source Inventory
Before editing Page Builder authoring, inspect:
projects/praxis-page-builder/AGENTS.mdprojects/praxis-page-builder/src/lib/page-config-editor/page-config-editor.component.tsprojects/praxis-page-builder/src/lib/page-config-editor/page-config-editor.component.spec.tsprojects/praxis-page-builder/src/lib/dynamic-page-config-editor.component.tsprojects/praxis-page-builder/src/lib/dynamic-page-config-editor.component.spec.tsprojects/praxis-page-builder/src/lib/editor/widget-shell-editor.component.tsprojects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor.component.tswhen links or page state are editor-visibleprojects/praxis-page-builder/src/lib/editor/component-palette-dialog.component.tswhen insertion presets or child editor launch points changeprojects/praxis-page-builder/src/lib/i18n/page-builder.*.tswhen labels, helper text, errors, or empty states changeprojects/praxis-page-builder/src/lib/ai/praxis-page-builder-authoring-manifest.tswhen authorable paths change
Also inspect projects/praxis-core composition and widget shell models when changing page or shell shape.
Editor Rules
Page config editors may edit page layout/theme presets, canvas, grouping, device layouts, context, and state. They must preserve unknown canonical fields unless the change explicitly removes deprecated compatibility semantics.
Treat JSON text areas as advanced escape hatches that still produce validated canonical objects. Do not persist invalid JSON strings, legacy grid options, or page-builder-only shapes that praxis-dynamic-page cannot render.
Widget shell editor owns shell chrome only: title, subtitle, icon, preset, appearance, window actions, and shell actions. It must not mutate child component inputs. Available widget actions and commands should come from ComponentMetadataRegistry and ComponentDocMeta, not local command vocabularies.
When applyToAll or page preset behavior changes, confirm whether the canonical owner is page preset, shell preset, or widget shell. Do not silently copy shell style into every widget when a page-level preset can express the decision.
Preset comparison and appearance overrides
Resolve page layout presets through Core's resolver, including presetFamily
fallback, and preserve an explicit page theme while comparing layouts. Shell previews
must render Core's resolved preset; avoid a second appearance catalog in the editor.
Changing a shell preset preserves explicit appearance overrides; the explicit
"Use style only" action clears them. Keep that distinction visible in preview and
customization count.
Round-trip Core's card.borderWidth/borderStyle/backdropFilter/fallbackBackground and
header.borderWidth/borderStyle with the other appearance fields. Trim CSS input
before deciding whether to emit an override; whitespace-only values restore
inheritance. Validate header border color with border-bottom-color, since its
single divider cannot consume the card's multi-side color shorthand. Invalid values
must block Save. Test corrected validity, Apply, clearing overrides and fresh remote
reopen without altering child inputs or persisting resolved inherited context.
Widget selection and focus highlight
Use Core's optional shell.appearance.card.interactionHighlight enum (standard or
gradient) for the authoring selection/focus and resize-grip appearance. Standard
uses a single theme color; gradient opts into theme-derived gradient grips and highlight. An absent override inherits
from the resolved shell preset, then falls back to standard; clearing the editor
control must remove the override rather than persist an inherited value. Explicit
standard overrides a gradient preset. Keep gradient opt-in in examples and preserve
unrelated appearance sections and child inputs through Apply, Reset and reopen.
The highlight is editing chrome only: published/view-only pages must not acquire it,
including on pointer or keyboard focus. Derive gradient colors from the active theme;
preserve visible keyboard focus and a usable conventional fallback in forced-colors
mode. Check both choices, inheritance, nested widgets and canvas wrappers with focused
Core runtime and WidgetShellEditor specs plus a focused browser proof of visible UI.
Extend the existing widget.shell.configure operation schema with the concrete enum;
do not introduce a parallel AI operation or permit arbitrary CSS as this value.
Page Spacing And Canvas Geometry
Shared lateral breathing room belongs to WidgetPageDefinition.layout.paddingInline, not to
individual table cells or form sections. Inspect page-layout-spacing.ts, the Page Builder
README's shared-margin section and Core's wrapper materialization. Device layout overrides base
layout, then the host --pdx-page-padding-inline token applies (default 0px). Explicit 0px
removes the inset; clearing the editor removes the override and restores inheritance, preserving
other layout properties. Validate aligned header/table/form edges and drag/resize coordinates:
the inset belongs outside the canvas; editing-control safety space remains separate.
For Size, widget limits, responsive stacking or direct resize, inspect Core's
docs/rfc-dynamic-page-canvas-runtime.md, geometry helpers/specs and the Page Builder README's
Direct canvas manipulation section. These paths author existing canvas.items, device
overrides, constraints and contentSize; do not persist measured geometry or validation callbacks
as child inputs. Distinguish omitted inherited height, explicit 'auto', and an adjustable size.
Validate locks, inherited bounds, active-device measurements, cancellation of the complete resize
transaction and unchanged child inputs. A numeric editor check alone does not certify usable body
space or remote persistence; use the real consumer and the owning resize round-trip tests.
The explicit blocked-height recovery action must use current canonical diagnostics,
not a global invalid flag. Refresh diagnostics first, convert only fixed targets
marked for height/vertical-offset limits, then revalidate to reveal another height
blocker. Bound repeated validation and preserve valid siblings, column bounds,
constraints and authored child inputs. A column-width error never authorizes changing
all fixed heights. Keep any previous-height summary limited to targets actually
changed. Prove mixed blocked/valid heights and column-only failure in
dynamic-page-config-editor.component.spec.ts; consumer geometry and persistence
remain separate evidence.
Round-Trip Checklist
For Connection Editor, separate inspection from mutation. Selecting a port
opens its catalogue; explicit create/edit actions start a cancellable draft.
Opening, zooming, following a structural route and dismissing details must not
emit page changes. Naming state information is different: it edits the existing
state.schema[path].description or state.derived[path].description through
history, preserving paths, values and endpoints; persistence still uses page
Save. Do not name transient state through a persisted layer or fill absent
descriptions by guessing business meaning. Load the connection-editor reference
in praxis-page-builder-composition for panel, route and geometry invariants.
Before calling a Page Builder editor ready, verify:
- opening an existing page preserves
WidgetPageDefinitionwithout converting it to legacyGridPageDefinition. - layout/theme/shell presets survive apply/save/reopen.
- canvas items reference existing widget keys.
- grouping and device layout JSON parse and preserve shape.
- page context/state remain structured objects.
- widget shell changes affect only
page.widgets[].shell. - child widget settings open through the child
ComponentDocMeta.configEditoror manifest path. - destroying/removing the page or widget owner cancels its editor tree without Save, while replacing one child preserves the parent draft and focus when the replacement is vetoed.
- transient child editor context from
configEditor.contextResolveris separated from persisted inputs and is not saved back topage.widgets[].definition.inputs. - Page Builder does not persist
context,contextDiagnostics, runtime drawersurfaceRuntime,result$envelopes, row-selection payloads, resolved catalogs, or diagnostics output as child widget inputs unless the child owner explicitly declares those paths as stable inputs. - Visual Builder or rule editors hosted as child config preserve JSON Logic/graph round-trip and do not leak Page Builder-only rule state.
- reset returns to the initial page/shell and updates dirty/valid/busy state.
- runtime preview consumes the same document shape that persistence saves.
- i18n covers user-visible editor text.
Validation
Run focused validation:
- page config editor: page config editor spec and dynamic page config editor spec.
- widget shell: widget shell editor coverage plus metadata/registry integration where action catalogs are involved.
- Settings bridge: Settings Panel focused specs or a real editor open/apply/save/reopen smoke.
- composition-visible authoring: connection editor specs and
praxis-page-builder-composition. - public behavior:
ng build praxis-page-builder; browser validation when visible editor layout or page runtime changes.
Report skipped E2E explicitly. Build/spec validation is enough for non-agentic editor-only changes. Escalate to praxis-page-builder-ai-agentic and the full Playwright validation gate from projects/praxis-page-builder/AGENTS.md when the authoring change touches agentic authoring, SSE, manifests, backend tools, patch/apply, LLM integration, or Settings Panel bridge behavior used by agentic preview/apply.
Preset selection and document fidelity
Selecting an organization reference must not synthesize a canvas for an existing
flow page, freeze omitted canvas defaults, or persist a resolved theme/context
shell as an explicit page override. Compare the authored document before/after,
including omitted fields; only an explicit base-grid edit may introduce its canvas.
Prove theme changes and clear/reopen inheritance after Apply. When GlobalConfig.pages.defaults
(layoutPreset, themePreset, shellPreset, columns, gap, paddingInline, autoRows)
is configured, PageConfigEditorComponent and DynamicPageConfigEditorComponent must
surface those inherited corporate defaults with the localized (global) indicator in
summary chips, PagePresetComparisonComponent, and the paddingInline placeholder
(floatLabel="always"), while keeping the omitted properties undefined in getSettingsValue().
In Widget Settings, Undo stages an inverse preview that still requires Apply; do not confuse it with
discarding the current draft or persisting the page.
Collective Canvas Arrangement
For explicit base-canvas arrangement, inspect Core prepareCanvasArrangement and
its focused specs. The editor prepares geometry, compares numbered before/after maps with stable widget identity, stages it,
and uses the existing panel Apply/Undo flow. Keep the proposal transient and reject
it when its source draft changes. An exact Apply echo may preserve the single undo;
page replacement and Reset invalidate it. Preserve child inputs, composition, heights,
limits and device documents. Locked positions are obstacles, not permission to move
an entire locked group. Partial device anchors may block base reorganization; do not
invent overrides or claim a device/selection solver. Column choices express geometry,
not inferred business roles or a new assistant tool.
For page-level Apply, consume the owner-confirmed session receipt through the existing
SettingsValueProvider.acceptAppliedValue. Capture the authored document before runtime
bootstrap enriches it. Advance the dirty baseline only on that receipt, never during
getSettingsValue; test Apply → Undo → Apply through the actual panel.
Revalidate staged arrangements at final submission with Core
validateCanvasArrangement(candidate, source). Device numeric constraints still apply
when positions inherit. Grid edits after staging must not emit out-of-bounds items.
A rendered diagnostic can change without a form fingerprint change; handle a null
candidate before reading canvas. Keep Undo tied to reviewed geometry across unrelated
edits, and restore only geometric fields so content/limits/gap edits survive.
Include the four canvas-arrangement-regressions.spec.ts cases and the mixed-edit
Apply/Undo browser journey when changing this path.
Keep Visual templates, Layout templates, Arrange and Adjustments as exclusive tasks in the canvas page editor. Theme/shell samples derive from canonical tokens and remain illustrative; composition diagrams explain roles, not actual canvas positions. The nine distribution choices are transient ratios passed to Core, not new persisted preset IDs. Verify tab navigation does not dirty the document, errors route to the correct adjustment, proposal feedback receives focus, and narrow/keyboard use retains access to the primary tabs. More choices must not bury the before/after review.