@praxisui/page-builder 10.0.0-rc.7 → 10.0.0-rc.8

package/README.md

@@ -4,6 +4,54 @@ Visual page and dashboard builder for Praxis UI applications.
 
 Use this package when an application must let users compose governed operational pages from registered widgets, visual layout, shell settings, component editors, `composition.links`, and optional AI-assisted authoring.
 
+## Dashboard pages and persistence ownership
+
+A dashboard is a `WidgetPageDefinition` rendered by `praxis-dynamic-page` and edited
+by `praxis-dynamic-page-builder`. The beta `PraxisDashboardPage` wrapper was removed;
+use these existing components instead. Application titles, toolbar presentation and
+business navigation remain host concerns.
+
+For manual page editing, opt in to the Core persistence lifecycle:
+
+```html
+<praxis-dynamic-page-builder
+  #builder
+  [page]="defaultPage"
+  [pageIdentity]="identity"
+  [autoPersist]="true"
+  [enableCustomization]="editing"
+  (persistenceChange)="persistence = $event"
+/>
+```
+
+`autoPersist` defaults to `false` on the builder, preserving its previous effective
+behavior (the child runtime previously always received `false`). Hosts that already
+persist `pageAuthoringChange`/`pageSaveRequested` must leave it disabled. Core Dynamic
+Page keeps its own existing default. Do not enable a second host writer when Core
+owns persistence.
+
+Pass `PageIdentity` with the application's actual tenant/user/route. Core uses the
+configured `ASYNC_CONFIG_STORAGE`; no separate localStorage cache, browser globals
+or persona-specific host reconciler is needed. Storage identity is not backend
+authorization. Persisted documents, including an empty widget list, are authoritative;
+new factory widgets are not silently appended to a user's saved page.
+
+`persistenceChange` forwards Core's operational `WidgetPagePersistenceState`:
+`idle`, `loading`, `saving`, `saved`, `resetting` or `error`, with `customized`, optional
+ISO `savedAt`, operation and a safe `errorKind`. Show success only after acknowledgement,
+and distinguish conflicts from a pending or failed write. It is not business metadata
+and must not be persisted in `WidgetPageDefinition`.
+
+`builder.resetPersistedPage(defaultPage)` deletes this identity's saved page and applies
+the supplied default only after acknowledgement. `builder.reloadPersistedPage(defaultPage)`
+explicitly discards the draft and reloads storage, using the supplied default when no saved
+page exists. Make that destructive-to-draft intent visible in the host. The existing Save
+button retries through Core for manually managed pages; conflicts require an explicit reload.
+
+For `authoringDocument` or agentic authoring, Core automatic persistence is disabled even
+when requested: the existing host/server apply lifecycle owns revisions and provenance.
+An AI preview must never be saved through an automatic generic config write.
+
 ## Widget shell editor integrity
 
 The shell editor exposes **Keep header visible while scrolling the page**
@@ -1089,6 +1137,10 @@ losing unrelated context. Arrangement choices track their draft baseline even wh
 selected distribution initially produces no changes, so later edits clear stale status.
 These fixes are not part of the already published 9.0.68-rc.2 package.
 
+`retryPersistedPage()` retries the current draft after a non-conflict save failure,
+including empty pages, without emitting host save lifecycle events. Conflicts require
+explicit `reloadPersistedPage(defaultPage)`; reload discards the local draft.
+
 <!-- praxis-npm-catalog-links:start -->
 ## Official documentation and examples