@praxisui/page-builder 9.0.35 → 9.0.36

package/README.md

@@ -16,6 +16,7 @@ Use this package when an application must let users compose governed operational
 - Dynamic page examples: https://praxisui.dev/examples/dynamic-page
 - Live demo: https://praxis-ui-4e602.web.app
 - Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Factory readiness and prioritized evolution: [docs/ui-composition-plan-factory-readiness.md](docs/ui-composition-plan-factory-readiness.md)
 
 ## Install
 
@@ -273,6 +274,8 @@ Page-owned copy can remain compact in the authoring plan. When a `PraxisTextValu
 
 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.
 
+Master-detail materialization uses the existing semantic envelope instead of component-name inference. An authored `canvas`, `slotAssignments`, or `deviceLayouts` remains authoritative; otherwise the compiler resolves the official `master-detail-dashboard` preset family from `layoutPresetOptions.presetFamily` and exact widget roles/slots (`master`, `detail`, `filters`, `actions`, `supporting`, or `detail-*`). It derives side-by-side desktop placement and deterministic tablet/mobile stacks, emits stable diagnostics for missing or ambiguous roles, and persists only canonical `WidgetPageDefinition` fields. Selection still travels through authored component ports and composition links.
+
 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.
@@ -281,6 +284,12 @@ For complete governed page templates, the additive `UiCompositionPlanTemplateRef
 
 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.
 
+Every official local apply of a `UiCompositionPlan` now runs a fail-closed preflight against the `ComponentMetadataRegistry` of the target host. The gate compiles the plan, delegates executable link validation to Core's `CompositionValidatorService`, resolves every top-level and nested component port against the same registry used by the runtime, and preserves canonical `DiagnosticRecord` codes and paths. A missing registry, component, materializable Angular type, port, compatible direction or semantic contract blocks apply before `applyConfigFromAdapter` can mutate the active page. Non-blocking layout diagnostics remain visible as preview warnings.
+
+`preflightUiCompositionPlan(plan, targetRegistry)` is exported by `@praxisui/page-builder` for official Dynamic Page hosts that compile plans outside `DynamicPageBuilderComponent`. Those hosts must inject their runtime `ComponentMetadataRegistry`; omitting it fails closed with `UI_COMPOSITION_TARGET_REGISTRY_REQUIRED`.
+
+When a preview contains both `uiCompositionPlan` and `compiledFormPatch`, the semantic plan is the attested source for local preview. Persistence rebuilds `patch.page` from that locally materialized page so a backend patch cannot bypass the registry-aware gate. Provider readiness in this cut means that the target registry contains owner metadata with a materializable Angular component type; uniform certification of the owner providers and bootstrap recipes remains tracked by issue #392 and is not inferred through Page Builder heuristics.
+
 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.
 
 ## Public API
@@ -301,6 +310,7 @@ Main exports:
 - `providePageBuilderWidgetAiCatalogs`
 - `PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST`
 - `UiCompositionPlan` contracts
+- `preflightUiCompositionPlan`
 
 ## Notes