@praxisui/page-builder 9.0.4 → 9.0.5-rc.10

package/README.md

@@ -204,6 +204,8 @@ providers: [
 
 The package exports `PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST` for governed operation discovery. The persisted runtime page is still `WidgetPageDefinition`; intermediate AI plans such as `UiCompositionPlan` must compile before preview, apply, or save.
 
+`UiCompositionPlan` can carry the complete page-owned envelope required by the runtime: `i18n`, explicit `context`, canonical `layout`, state, presets, responsive variants, governed widget `shell`, component inputs and semantic wiring. The compiler clones these fields into `WidgetPageDefinition`; hosts must not add business copy, tenant context, layout or widget chrome after compilation as an undocumented enrichment step. `context` is page-wide runtime context, while `contextScopes` is an authoring shorthand that expands repeated values into explicit widget inputs and links.
+
 Repeated selection projections can be authored once through `UiCompositionPlan.selectionSyncs`. A sync declares structured component-output sources, a base state target, and a field-to-payload mapping. `compileUiCompositionPlan` expands every source/mapping pair into explicit `page.composition.links` with stable ids, canonical `pick-path` transforms, policy, condition, and `selection-sync` intent. The shorthand is never persisted in `WidgetPageDefinition`, so runtime inspection and audit continue to see the complete executable graph.
 
 ```ts
@@ -223,7 +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.
+
+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.