@praxisui/page-builder 9.0.0-beta.8 → 9.0.0-beta.81

package/README.md

@@ -26,7 +26,7 @@ npm i @praxisui/page-builder@latest
 Peer dependencies:
 
 - `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/cdk`, `@angular/material` `^21.0.0`
-- `@praxisui/ai`, `@praxisui/core`, `@praxisui/settings-panel` `^9.0.0-beta.4`
+- `@praxisui/ai`, `@praxisui/core`, `@praxisui/settings-panel` `^9.0.0-beta.12`
 - `rxjs` `~7.8.0`
 
 ## Quick Start
@@ -115,6 +115,22 @@ const page: WidgetPageDefinition = {
 
 Use the same canonical `composition.links` contract for widget-to-widget links, nested component ports through `nestedPath`, and global actions through `to.kind = "global-action"`.
 
+Feedback cycles are validated before authoring and runtime delivery. Direct or indirect cycles across component ports and page state are reported as diagnostics; unguarded cycles are blocking in the core runtime and surfaced by the Connection Editor. Intentional feedback must be explicit by tagging every involved link with `metadata.tags: ['intentional-feedback']` and declaring a canonical guard such as `condition`, `policy.distinct`, `policy.distinctBy` or `policy.debounceMs`.
+
+## Connection Editor
+
+The visual connection editor is an authoring surface over the saved `composition.links` document. It does not create a parallel graph DSL.
+
+Current capabilities include:
+
+- inspecting persisted links, endpoints, intent, condition, transform and policy;
+- highlighting widget, state and global-action flows in the same graph;
+- creating assisted links only between known endpoints;
+- suggesting canonical table row selection to form detail wiring with a `payload.row.id` projection when the existing ports support that flow;
+- explaining nested component ports by showing the `nestedPath` while preserving the top-level widget as the canonical endpoint owner.
+
+For nested components, keep `ref.widget` pointed at the top-level host widget and describe the internal target with `ref.nestedPath`. The editor should make that ownership visible instead of flattening child widgets into a second page-level widget namespace.
+
 ## Settings Panel Bridge
 
 Register the Settings Panel bridge when the host must open page, shell, and component config editors in a side panel.
@@ -133,6 +149,15 @@ providers: [
 
 Component input editors belong to the component owner. Page Builder discovers `ComponentDocMeta.configEditor` and hosts the published editor instead of redefining table, form, chart, list, upload, stepper, tab, expansion, CRUD, or rich-content configuration locally.
 
+## Page Settings Presets
+
+Page settings expose the canonical layout and theme preset catalogs from `@praxisui/core`.
+
+- `layoutPreset` selects the structural page template, including default grouping, slot expectations, responsive policy, and a recommended theme.
+- `themePreset` is optional. When omitted, the runtime inherits the selected layout preset's `defaultThemePreset`.
+- Pin `themePreset` only when the page must intentionally diverge from future layout-preset defaults or when governance requires an explicit visual decision in the saved document.
+- Canvas item positions remain explicit page state. Presets guide layout, grouping, slot intent, and theme inheritance; they do not silently rewrite existing widget geometry.
+
 ## AI Authoring
 
 Register widget capability catalogs so the assistant can reason about component inputs and supported operations.
@@ -179,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.
 
+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
 
 Main exports: