@praxisui/page-builder 9.0.5-rc.3 → 9.0.5-rc.4

package/README.md

@@ -225,9 +225,23 @@ selectionSyncs: [{
 }]
 ```
 
-Repeated parent/resource context can be declared through `UiCompositionPlan.contextScopes`. Each context value is explicitly either `constant` or `state`; each target uses a stable owner widget and optional canonical `nestedPath`. During compilation, constants are materialized into component inputs through core's `NestedWidgetConfigAccessor`, while state values become normal `state-read` links. Targets can inherit all keys or an explicit subset. The persisted page therefore contains only concrete widget inputs and `composition.links`, never ambient or implicit context inheritance.
+Repeated parent/resource context can be declared through `UiCompositionPlan.contextScopes`. Each context value is explicitly either `constant` or `state`; each target uses a stable owner widget and optional canonical `nestedPath`. During compilation, constants and an explicitly authored `state.initial` are materialized into component inputs through core's `NestedWidgetConfigAccessor`, while state values become normal `state-read` links. `initial` is the pre-propagation input state (for example, `null` for an unselected parent), not a second state store. Targets can inherit all keys or an explicit subset. The persisted page therefore contains only concrete widget inputs and `composition.links`, never ambient or implicit context inheritance.
 
-The official Employee Operations case is an executable regression for this boundary. Its 22 persisted links are expressed in authoring as one `selectionSyncs` declaration plus two `contextScopes` declarations, while compilation preserves the same 22 source/target paths, guards and policies. This reduces the repeated wiring declarations from 22 to 3 (86%) without hiding the executable graph from runtime inspection, audit or the public JSON viewer.
+Compiled links may retain `metadata.source: 'ui-composition-plan'` as explicit authoring provenance. This value is part of core's public `LinkMetadata` contract and remains distinct from `native-composition-link`, `persisted-composition-link`, and legacy migration provenance.
+
+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.
+
+An explicit `layout` is a complete spatial decision. When a plan provides `layout` and omits both `canvas` and a preset/master-detail intent, the compiler preserves the layout without synthesizing a canvas that would take precedence at runtime. Automatic canvas materialization remains available for plans without an explicit layout and for preset- or role-driven master-detail plans.
+
+Schema-derived table columns already use the canonical `TableConfig.columnProjection` contract. Omit `columns` or keep it empty, set `columnProjection.source: 'schema'`, optionally restrict the ordered projection through `include`, and declare only field-keyed editorial differences in `overrides` (plus genuinely local columns in `additions`). Do not introduce a parallel `useSurfaceDefaults`/`columnOverrides` dialect: the related-resource outlet and table runtime already materialize schema defaults and validate the projection against the remote schema.
+
+`ComponentDocMeta.insertionPresets` remains the canonical catalog for reusable defaults owned by one component. It is not a page/domain template system: do not publish Employee Operations presets from CRUD, tabs, or related-resource outlet metadata merely to shorten a business recipe.
+
+For complete governed page templates, the additive `UiCompositionPlanTemplateReference` pins the canonical `ai_registry` key and complete `configJson` SHA-256. The Config Starter resolves the active `SYSTEM/GLOBAL` record, verifies the exact hash, extracts its governed `authoringPlan`, and only then invokes the existing compiler. Angular consumers can use the pure `resolveUiCompositionPlanTemplate` helper only with an explicitly supplied `UiCompositionPlanTemplateMaterialization`; the helper performs no HTTP, search, or implicit selection. The first contract accepts no non-empty overrides, fails closed for missing, inactive, malformed, or stale references, and never persists the unresolved reference. `version` and `etag` are retained as audit evidence, while `configSha256` is the required content pin.
+
+Keep the compact authoring plan, the compiled executable page, and the surrounding recipe metadata as distinct artifacts. `UiCompositionPlan` is the reviewable authoring intent; `WidgetPageDefinition` is the explicit runtime graph; recipe metadata and operational evidence document when and how the example should be used. The server compiler must produce the same executable page as the Page Builder compiler before persistence.
 
 Streaming apply is fail-closed. A preview is persistable only when it is the unchanged payload of an applicable terminal `result` event and its diagnostics carry the matching `streamId`, `threadId`, `turnId`, and `resultEventId`. A locally regenerated or normalized preview remains available for review, but it cannot reuse an older terminal reference or call `page-apply`; the backend must issue a new terminal result for the new patch.