# Praxis Page Builder Authoring

> Use when Codex must create, inspect, or fix @praxisui/page-builder authoring editors and save-as adoption: PraxisPageCopyActionComponent, PraxisPageSaveAsComponent, PageSaveAsAdapter, PageConfigEditorComponent, DynamicPageConfigEditorComponent, WidgetShellEditorComponent, SettingsValueProvider, Settings Panel bridge, page settings, canvas/grouping/device/state/context editors, widget shell actions, ComponentDocMeta.configEditor hosting, visual/textual round-trip, save/apply/reset/reopen, i18n, page editor runtime parity, or authoring changes that may require Page Builder agentic validation gates.

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

---


# Praxis Page Builder Authoring

For composing pages through installed editors, read
[browser-page-authoring.md](references/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-shell` and `praxis-settings-roundtrip-authoring` for Settings Panel protocol, footer state, apply/save/reset/cancel, and bridge behavior.
- `praxis-authoring-editors` for cross-component editor ownership rules.
- `praxis-page-builder-composition` for `WidgetPageDefinition`, canvas, composition links, connection graph, and runtime materialization.
- `praxis-page-builder-ai-agentic` when 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/core` page authoring codecs (`encodePageAuthoringDocument`,
  `decodePageAuthoringDocument`, `copyPageAuthoringDocument`,
  `validatePageAuthoringDocument`, `encodeNavigationGroupsAuthoringDocument`,
  `decodeNavigationGroupsAuthoringDocument`, `materializeGovernedPagePreview`) and
  `@praxisui/page-builder` `GovernedPageWorkflowController` +
  `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.config`
  with `configPersistenceStrategy: 'volatile'` inside governed pages so personal
  `ui_user_config` overrides never shadow the published release.
- Declare `childSources` on `POST /api/praxis/config/ui-layouts/drafts/{draftId}/revisions`
  only 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 from
  `praxis.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 via `inspectLegacyPublishedPagePayload` +
  `GovernedPageWorkflowController.importLegacyPublishedPage` (`POST /api/praxis/config/pages`
  from an admitted native seed + governed revision with `legacyImportedFrom`) 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.md`
- `projects/praxis-page-builder/src/lib/page-config-editor/page-config-editor.component.ts`
- `projects/praxis-page-builder/src/lib/page-config-editor/page-config-editor.component.spec.ts`
- `projects/praxis-page-builder/src/lib/dynamic-page-config-editor.component.ts`
- `projects/praxis-page-builder/src/lib/dynamic-page-config-editor.component.spec.ts`
- `projects/praxis-page-builder/src/lib/editor/widget-shell-editor.component.ts`
- `projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor.component.ts` when links or page state are editor-visible
- `projects/praxis-page-builder/src/lib/editor/component-palette-dialog.component.ts` when insertion presets or child editor launch points change
- `projects/praxis-page-builder/src/lib/i18n/page-builder.*.ts` when labels, helper text, errors, or empty states change
- `projects/praxis-page-builder/src/lib/ai/praxis-page-builder-authoring-manifest.ts` when 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 `WidgetPageDefinition` without converting it to legacy `GridPageDefinition`.
- 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.configEditor` or 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.contextResolver` is separated from persisted inputs and is not saved back to `page.widgets[].definition.inputs`.
- Page Builder does not persist `context`, `contextDiagnostics`, runtime drawer `surfaceRuntime`,
  `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.

