@praxisui/page-builder 9.0.64 → 9.0.66

package/README.md

@@ -4,6 +4,108 @@ Visual page and dashboard builder for Praxis UI applications.
 
 Use this package when an application must let users compose governed operational pages from registered widgets, visual layout, shell settings, component editors, `composition.links`, and optional AI-assisted authoring.
 
+## Widget shell editor integrity
+
+Dynamic Page height validation follows viewport resize and Angular render completion
+while the editor remains open. It reuses the runtime's transient validator and updates
+the existing field diagnostics/Apply/Save gates only when the diagnostic changes.
+The entered height and dirty baseline are preserved; rendered measurements never become
+constraints or persisted page fields. Final value production also revalidates, so a late
+failure must remain an invalid, open draft in Settings Panel.
+
+This validates the active rendered geometry, not all possible devices, virtualized
+contents or future CSS-only changes without a render/resize notification.
+
+The shell editor validates non-empty appearance overrides with the browser CSS parser for
+their actual property: backgrounds, colors, radius, shadow, padding and typography. Empty
+overrides remain valid; tokens, gradients and CSS expressions are preserved, not resolved
+into host-specific values. Invalid editable values block Apply/Save and the settings-value
+provider. Hidden appearance fields in permission-limited editors remain preserved.
+
+This is browser syntax validation, not URL sanitization, token-resolution verification or
+backend authorization. SSR has no interactive CSS parser and defers this check to the browser.
+Existing accepted JSON paths and the AI authoring manifest remain unchanged.
+
+The appearance/action editor adapts to narrow panels, and validation messages reserve their
+own space. The archetype lab now exposes a local edit toggle at narrow breakpoints, where
+the demo's global toggle is hidden. This is a tested entrypoint, not full mobile certification.
+Read the
+[lab certification record](../../src/app/features/dynamic-page-lab/ERGON_ARCHETYPE_CERTIFICATION.md)
+for the exact tested scope and remaining corporate gates.
+
+## Direct canvas manipulation
+
+The builder consumes the shared Core canvas: select a widget to expose eight direct resize
+grips, drag its header to move it, or use the focused grip's arrow keys to change size.
+The global widget selector/directional controls are collapsed as an alternative. The
+contextual **Resize widget** action retains larger 44px controls. These access paths share
+one geometry, constraints, collision, preview and cancellation implementation; they add no
+Page Builder settings, persistence flags or AI operations. `widget.moveResize` continues
+to address the existing canonical `canvas.items` document.
+
+Manual resize now previews coordinated space redistribution in Core, with green
+availability, amber minimum-size feedback and red exceeded-limit feedback on the
+affected widgets. Release commits the valid distribution atomically; Escape cancels
+all affected items. This is not automatic repacking or a new AI operation. Explicit
+content-aware minimums remain important, including in restored layouts; changing a
+recipe does not silently rewrite a saved user page. Auto-content rows still do not
+provide pixel-continuous vertical shrinking of a one-row widget.
+
+### Visual widget limits
+
+Open **Page settings → Widget limits** in the default Dynamic Page editor to set
+minimum/maximum width (columns) and height (rows). Choose the base canvas or a
+desktop, tablet or mobile override, without closing the editor. Blank base fields use Core defaults (minimum one,
+maximum grid width/unbounded row span); blank device fields inherit base limits.
+An untouched device target does not create an override in the document. Validation
+uses the final draft, including device layouts created in Responsiveness during the same session.
+
+The editor writes existing `canvas.items[key].constraints` and
+`deviceLayouts[device].canvas.items[key].constraints`, preserving locks, geometry,
+unknown fields and untouched overrides. It rejects non-positive/non-integer
+values, reversed or inherited conflicting ranges, minimums wider than the grid,
+and newly authored limits that would change the current effective size. Existing
+documents already clamped by Core remain valid on opening: declared spans need
+not equal rendered spans. Invalid inherited bounds can be corrected in the same
+draft. The editor does not rewrite geometry to satisfy newly authored bounds.
+Dynamic title expressions are
+identified by stable widget key, not evaluated in the editor.
+
+Apply previews the same document returned by Save; Reset reloads the input baseline.
+Pending changes are tracked independently of validity, including edits to an
+already-invalid input document. Invalid limit fields expose Material errors and
+accessible invalid/described-by state; correcting them clears their error state.
+Closing after Apply may ask to discard the unsaved editor draft: the applied
+preview remains active, as the shared Settings Panel explicitly explains.
+Remote user/tenant persistence is unchanged. In `autoRows: 'content'`, the same editor
+also exposes **Default / Automatic / Adjustable** height, pixel height, top inset,
+and pixel minimum/maximum. It writes Core `canvas.items[key].contentSize` and its
+device override, plus `constraints.minHeightPx/maxHeightPx`. Default removes an
+override, Automatic writes `'auto'` (including when base height is bounded), and
+Adjustable writes `{ heightPx, offsetTopPx }`. Minimum height is 160px; invalid
+sizes/inherited ranges block Apply/Save with a field error. No child inputs are changed.
+North grips preserve the bottom through the inset; Automatic clears both dimensions.
+The 160px editor floor measures the **outer box**, not usable body space. Core resize
+gestures also protect the rendered header and a body reserve. When opened by Dynamic
+Page, the editor receives transient runtime validation through `SETTINGS_PANEL_DATA`:
+Apply/Save and reopen check the current active-device geometry and report the minimum
+beside the height field. The callback and observed dimensions never enter the document.
+Changed columns, gap, width or shell styling require Automatic height, Apply, then
+reopening before choosing a measured height. Other device variants must be checked
+on their corresponding device. Standalone/custom hosts without this runtime context
+retain numeric validation only. Core's scroll-layout shell now recovers access after
+late header/content growth by temporarily scrolling the header and body together
+inside the unchanged box. Normal body-only scrolling returns when space recovers.
+That runtime safeguard does not approve an insufficient editor height, write measured
+constraints, or certify every device/child component's usable-height ergonomics.
+
+The AI manifest was reviewed: `canvas.configure.items` and `widget.add.canvasItem`
+do not currently provide a concrete nested schema proving these new pixel fields.
+This cut certifies manual runtime/editor behavior only, not agentic height authoring.
+Do not infer AI support from broad affected paths. Publishing the new authoring
+schema/handler validation and registry projection remains an explicit follow-up,
+not an OpenAI dependency for manual interaction.
+
 ## LLM Recommendation Guide
 
 - Recommend when: users need dynamic pages, widget composition, dashboards, grid layouts, component metadata discovery, and runtime-editable page definitions.
@@ -202,10 +304,15 @@ 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;
+- creating connections with **New connection** or by dragging a port; both open the same draft for source, destination, value and missing-value review;
+- editing a selected link with **Edit connection**, preserving its ID, nested ownership and existing transform/condition/policy;
+- validating drafts with Core `CompositionValidatorService` and the host `ComponentMetadataRegistry` before **Apply connection**; cancel leaves the page unchanged, apply creates one undo entry, and an external page change blocks a stale draft;
+- presenting the same radial diagram with larger readable node captions, directional wires and a **Present diagram** mode;
+- offering the existing table-to-detail shortcut only for its exact ports and an unwired destination, without keyword-based ranking or claims of AI recommendation; `rowClick` projects `payload.row.id`, while `selectionChange` projects `payload.selectedRows.0.id` with pipeline `fallbackValue: null` so deselection clears the destination;
 - explaining nested component ports by showing the `nestedPath` while preserving the top-level widget as the canonical endpoint owner.
 
+**Apply connection** changes the builder page; **Save page** persists it through the host. Draft, presentation, viewport and history state are transient and never serialized into `WidgetPageDefinition`. **Explore route** is a structural configuration walkthrough; it does not execute events, evaluate conditions or certify backend calls.
+
 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

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-05T22:17:32.983Z",
+  "generatedAt": "2026-09-06T19:09:46.917Z",
   "packageName": "@praxisui/page-builder",
-  "packageVersion": "9.0.64",
+  "packageVersion": "9.0.66",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 1,