@praxisui/page-builder 9.0.61 → 9.0.63

package/README.md

@@ -65,11 +65,20 @@ export class PageAuthoringComponent {
 
 The persisted document remains `WidgetPageDefinition` from `@praxisui/core`. Page Builder edits that canonical document; it does not introduce a separate page DSL.
 
+For a page created by governed AI authoring, reopen the complete
+`ConfigDocument<WidgetPageDefinition>` returned by
+`ApiConfigStorage.loadConfigDocument()` and bind it through
+`[authoringDocument]`. This preserves payload, strong ETag and the server-attested
+`UiCompositionPlan` in one revision. The builder verifies both canonical hashes
+before using the plan as semantic context for another turn; a stale or tampered
+source fails closed.
+
 ## Runtime Contract
 
 `praxis-dynamic-page-builder` accepts:
 
 - `page`: `WidgetPageDefinition | string`
+- `authoringDocument`: canonical Config response containing payload, ETag and optional semantic source; takes precedence over `page`
 - `context`: runtime context shared with widgets and composition links
 - `enableCustomization`: enables builder and child authoring affordances; when `false`, the same
   runtime remains mounted in presentation mode without editing chrome
@@ -130,6 +139,12 @@ It emits:
 - `agenticAuthoringSharedRuleHandoff`: governed shared-rule continuation handoff
 - `pageRestart`, `savedPageDeleteRequested`
 
+Do not use Angular two-way binding `[(page)]` for an authoring draft unless the
+host intentionally wants runtime state to become part of that draft.
+`pageChange` includes runtime composition updates. Bind `[page]` and feed only
+`pageAuthoringChange` back into the source document when persisted authoring and
+runtime projections must remain separate.
+
 ## Governed page persistence
 
 Page Builder owns the authoring lifecycle but the host owns persistence. Keep
@@ -304,6 +319,16 @@ pipeline and its materializing step, allowing registry-aware preflight to compar
 the transformed contract with the target port. Do not relax target compatibility
 or relabel the source port to hide a transformation.
 
+Use `fallbackValue` when a projection that can resolve to `undefined` must
+deliver an explicit total value such as `null`. Use `select-case` when the
+result itself changes according to canonical Json Logic. Every branch requires
+`when` and `value`, and the transform requires `defaultValue`; conditions are
+validated against the same `event`, `payload`, `state`, `context` and implicit
+`source` roots used by Core. Unless `output.stableShape` is explicitly `false`,
+all branch values must preserve the JSON shape of `defaultValue`. Malformed
+sources, outputs, cases and conditions fail before `WidgetPageDefinition`
+materialization rather than degrading silently at runtime.
+
 The official Employee Operations case is an executable regression for this boundary. Its first-class `*.ui-composition-plan.json` artifact expresses 22 persisted links as one `selectionSyncs` declaration, two `contextScopes` declarations and one explicit transformed binding, while compilation preserves the same 22 source/target paths, guards, transforms and policies. This reduces the wiring declarations from 22 to 4 (82%) without hiding the executable graph from runtime inspection, audit or the public JSON viewer. Context scopes are deliberately limited to direct inheritance: a value that must be wrapped or reshaped remains an explicit binding with a canonical transform.
 
 Page-owned copy can remain compact in the authoring plan. When a `PraxisTextValue` descriptor declares only `{ key }` and the key exists in `i18n.dictionaries[fallbackLocale]`, both canonical compilers materialize that message as the descriptor's runtime `text` fallback. The persisted `WidgetPageDefinition` therefore stays portable while authors do not repeat the same fallback beside every key. Explicit `text` still wins and unknown keys remain untouched, so the compiler never invents copy.