@praxisui/core 9.0.66 → 9.0.68-rc.0

package/README.md

@@ -4,8 +4,59 @@ Shared contracts, tokens, services, metadata models, widget runtime primitives,
 
 Use this package directly when a host application or library needs Praxis UI types, global actions, metadata registries, schema clients, resource discovery, i18n, theme bridge, dynamic widget contracts, or shared runtime services.
 
+## Governed color palettes
+
+`materializeGovernedPaletteEntries(palette, purposes)` returns `MaterializedGovernedColorToken[]`, pairing each original `entry` with its resolved `color`. It preserves distinct token IDs even when CSS references/colors match, applies purpose filtering, and resolves fallback dependencies against the complete palette. Use this projection for identified swatches; do not zip color arrays to entries or infer identity from color equality. `materializeGovernedPaletteColors` remains the string-only projection of the same resolver.
+
+`GovernedColorPaletteService` is the canonical Angular client for color-palette projections published by Praxis Config. Published palettes carry a stable `familyKey`, an explicit `variant` identity and token-level `displayName`/`aliases`; incomplete legacy projections are rejected before caching. The service supports list/read/capabilities/preview, exact `list(familyKey)` queries, tenant/environment-isolated caching, conditional ETag revalidation and deterministic `version`/`etag` pins. Consumers may use names and aliases for presentation and discovery only: `paletteKey` and `tokenId` remain the persisted identities, and local metadata must not become a second source of governance. `GovernedColorTokenSelection` carries the exact palette/version/ETag/token observation beside the existing CSS-string field value; applications persist it only through an explicit domain field or mapping.
+
 ## LLM Recommendation Guide
 
+- `BUILTIN_WIDGET_SHELL_PRESETS` is the canonical catalog for reusable shell
+  treatments. `integrated-card`, `outlined-card`, `elevated-card` and
+  `tonal-card` keep header actions and body on one continuous surface;
+  `sectioned-card` deliberately separates the header; `frameless` removes the
+  containing surface while retaining the standard content inset, aligned with the
+  header. For content that owns its own spacing, explicitly set
+  `appearance.body.padding: "0"` (and hide the header if the content owns its title).
+  Persist the preset `id` in `WidgetShellConfig.preset` and
+  use the descriptor for authoring labels and previews. Do not maintain a
+  second preset list in consumers.
+- `WidgetShellConfig.stickyHeader: true` retains the existing composition-derived
+  header within its widget during page scrolling. Omission/false keeps normal flow.
+  This differs from `bodyLayout: 'scroll'`, which governs body scrolling. No second
+  selection state, cloned header or page geometry is persisted.
+- Hosts with fixed chrome may set `--pdx-shell-sticky-header-offset` (CSS length,
+  default `0px`). Measure responsive chrome; do not assume a desktop-only height.
+  The lab uses a lifecycle-owned ResizeObserver for its functional heading.
+- Pinning releases at the widget boundary and is suspended during drag authoring,
+  collapse, hidden/disabled headers, expanded/fullscreen windows and scroll recovery.
+  This is not a global selected-record bar. Continuous-surface presets repeat
+  their opaque card surface on the header so pinned content does not bleed through.
+  Transparent/gradient custom headers are painted over an opaque Material surface.
+  Keyboard focus is revealed below pinned chrome without changing its target.
+- Dynamic Page publishes its existing `context` input as a `view-context` port.
+  Composition links can deliver runtime context to a nested page through Tabs or
+  Expansion using stable `nestedPath` segments. The child page owns its internal
+  bindings; callers should target its context boundary, not invent paths through
+  its widget array. Register the canonical Dynamic Page metadata before preflight.
+  Context is runtime data, not a replacement for backend authorization or a saved
+  business record. The metadata port is also preserved in the generated AI catalog.
+- Nested sticky shells add the measured height of sticky ancestor headers in the
+  same scrollport. This is transient geometry, not a saved offset or another
+  selection context. The stack stops at an independent scrolling container;
+  hidden/inactive headers cease contributing. Ancestor resize observation is
+  disconnected on destruction. Body scrolling/fill and window-layout rules apply
+  to the owning shell's direct body, not to every nested widget body.
+  For dynamic-height containers that should follow page scrolling, use content
+  flow (omit `bodyLayout` or use `content`), not `fill`. An intentional independent
+  scrollport remains a boundary for the sticky stack.
+- An invisible shell (`kind: 'none'`) removes padding only from its own body.
+  Nested dashboard shells retain their authored body spacing. Hiding a header
+  with `showHeader: false` does not hide child headers or reset child spacing.
+- The Page Builder shell editor exposes the option. Existing saved layouts are
+  preserved; changing the source recipe does not silently migrate saved pages.
+
 - Coordinated manual resize: an unambiguous edge collision yields space from the
   affected neighbors, preserving their opposite edges and respecting `minColSpan`,
   `minRowSpan`, `lockSize` and `lockPosition`. It does not swap widgets or push a
@@ -18,9 +69,9 @@ Use this package directly when a host application or library needs Praxis UI typ
   discards the entire preview. Feedback is transient, never serialized.
   Author useful content-specific minimums and device overrides: the grid default of
   one unit is a geometric limit, not a guarantee of readable enterprise content.
-  `autoRows: 'content'` still measures content-driven tracks: reducing a tall one-row
-  widget below `rowSpan: 1` is **not supported** by this grid model. Do not claim
-  pixel-continuous window resizing, auto-row vertical shrinking, or arbitrary packing.
+  `autoRows: 'content'` measures content-driven tracks and uses independent pixel
+  `contentSize` for vertical resizing; `rowSpan` remains at least one. Resizing does not
+  imply automatic packing or moving unrelated widgets to a new row.
 
 - Widget Shell sizing: the shell includes its border inside the height reserved by its
   host (`border-box`). Consumers do not need a global CSS reset to prevent a 2px overflow.
@@ -29,37 +80,38 @@ Use this package directly when a host application or library needs Praxis UI typ
   CSS Grid reflow, not automatic compaction of authored fixed coordinates.
 
 - Dynamic Page resize presentation: selecting an unlocked widget in an editable grid
-  exposes eight direct edge/corner grips. The visible grip is small; each native button
-  has a 24px target, themed focus and a localized accessible name/tooltip. Drag a grip
-  or use arrow keys (Shift changes two grid units). Selection alone does not change the
-  page. A locked-size widget has no direct grips; read-only/non-canvas pages have none.
-  Grips are hidden while a shell is expanded/fullscreen and inert while the contextual
-  resize panel is open. Header drag remains the reorder entrypoint.
-
-  The global selector and eight 44px controls now live in a collapsed **Alternative
-  resize controls** disclosure above the canvas, not the primary editing workflow.
-  Opening it does not edit the page. Its controls occupy normal flow and remain separate
-  from short headers, card contents and neighboring widgets. This alternative and the
-  contextual panel are intentional access paths, not parallel layout implementations.
-  All three presentations reuse `canvas.items`, constraints, collision policy and the
-  same pointer preview/commit/cancel pipeline. No resize config or host-specific CSS is
-  required. Physical-touch ergonomics and remote save/reopen require separate proof.
-
-  Widgets with a visible shell header also expose a transient **Resize widget** action.
-  It opens an anchored, dismissible compass of eight 44px controls, using the same canvas
-  gesture and keyboard runtime as the global group. Visual and Tab order follow the
-  compass rows. Escape closes the panel and restores its trigger; opening does not edit
-  the document. Existing widget identity supplies the selected title. The popup can
-  temporarily cover underlying content; it does not reserve space or shift the grid.
-  Headerless canvas widgets expose the same panel through their existing contextual toolbar;
-  the global group remains available as a fallback. The action and expanded
-  state are runtime projections, not shell settings to persist in page JSON.
-
-  During a contextual pointer resize, the panel background, explanatory copy and inactive
-  controls become invisible while the captured 44px control stays in place. No DOM removal,
-  grid reflow or separate gesture state is introduced. Ending/cancelling restores the panel;
-  Escape cancels and closes it. This reduces obstruction during the gesture, not while choosing
-  a direction before it. Physical-touch ergonomics remain a separate validation gate.
+  exposes eight edge/corner grips with targets up to 24px per axis, themed focus and localized names.
+  The widget wrapper is keyboard focusable: focus selects it, Tab reaches its controls,
+  arrow keys resize, and Escape from a grip returns focus to the wrapper. Selection alone
+  does not change the document. Header drag remains the reorder entrypoint.
+
+  **Configure widget → Size** offers width in grid columns and height in rows (fixed grid)
+  or pixels (content rows). **More actions → Size…** opens this same settings tab.
+  Widget and Size share the SettingsPanel footer and preserve drafts when switching tabs.
+  Hosts without `SETTINGS_PANEL_BRIDGE` retain the Core-owned size overlay with explicit
+  Apply and Cancel actions, so the canvas authoring capability does not depend on an optional host service.
+  An optional fixed-corner choice preserves the opposite edges.
+  Valid changes preview the same constrained distribution as the grips; Apply commits once,
+  Cancel/Escape discard the unapplied draft and restore widget focus; an earlier Apply remains. Out-of-range or blocked sizes
+  disable Apply rather than silently changing the requested numbers. The dialog identifies
+  whether the edit targets the base layout or a device override. Opening it preserves
+  automatic height; changing only width does not create a fixed height.
+
+  This menu is available with canvas authoring permission, including headerless widgets
+  and hosts that disable removal or shell configuration. Size-locked widgets disable it.
+  There is no dedicated Resize widget icon, global selector or detached directional panel.
+  The size action is transient and never persisted in page JSON. Shell actions can explicitly
+  use `placement: 'menu'` to stay in More actions even when header slots are free; the shell
+  editor and capability catalog share that value. Existing header/window placements retain
+  their behavior. All sizing reuses canonical canvas items, constraints and device targeting.
+  The editor offers exact grid-width presets (⅓, ½, ⅔, 100%) when the column count
+  can represent them without rounding. They change the width draft, preserve the fixed
+  corner and require Apply; an unavailable full width is rejected, never silently clamped.
+  After a committed resize, reopen Size… on that widget to undo the last resize in this
+  session, including yielded neighbors. Recovery restores prior device inheritance and
+  keeps unrelated content edits. It refuses changed affected geometry/limits, new collisions,
+  a different device scope or page identity. This is one-operation recovery, not a general
+  history or redo stack. Side and corner double-click shortcuts use the same constrained geometry.
 
 - Dynamic Page gesture note: drag/resize previews belong to one primary pointer at a time.
   Secondary buttons, non-primary touches and additional pointers do not replace an active
@@ -71,6 +123,9 @@ Use this package directly when a host application or library needs Praxis UI typ
   No additional persisted layout or shell setting is required.
 
 - Widget Shell header note: identity and actions wrap according to the available card width,
+  with one direct header action below 480px and up to three in wider widgets; secondary
+  actions remain available in the existing overflow menu. This uses the widget surface
+  width, including when it is resized or moved into fullscreen, rather than the viewport.
   including narrow cards inside wide canvases. Titles/subtitles retain up to two visible lines
   and expose their complete localized content through Material tooltips. Icon action targets
   remain 44px; resize affordances are a separate canvas concern. Existing `disabled` actions
@@ -88,6 +143,37 @@ Use this package directly when a host application or library needs Praxis UI typ
   keeps priority. The first Escape closes that select; the next closes the shell.
   Deferred handling is ignored after shell destruction. These are presentation
   changes only and do not rewrite saved shell appearance or canvas coordinates.
+  Expanded/fullscreen hosts are lifted into the CDK overlay container, outside parent
+  sticky, tab and transformed stacking contexts. The existing host/view is retained;
+  closing restores that same host to its original position. A placeholder reserves
+  its inline space, a focus trap bounds keyboard navigation, and locally inherited
+  theme variables are bridged from the original ancestry while open. Root theme
+  values are not frozen. This is presentation state, not a second widget instance
+  or a persisted window layout. Connected Material overlays keep Escape priority.
+  Floating shells expose `role="dialog"` and an accessible name from the existing
+  localized title/subtitle (exact duplicates are announced once), with a localized
+  content-window fallback. Inline shells do not retain dialog semantics. The active
+  Widget stack isolates background roots and lower registered windows with native
+  `inert`, preserving preexisting or subsequently assigned host restrictions.
+  The stack owns one CDK scroll block until its last window closes, including
+  parent-before-child closure. Connected menus/selects remain outside the isolated
+  branches; the CDK container is not disabled. This private lifecycle does not
+  infer ownership of foreign CDK overlays or coordinate their independent scroll
+  locks. No automatic `aria-modal` claim is made. If the opening control becomes
+  disabled, hidden or detached while the shell survives, closing recovers focus
+  to the restored shell with a localized accessible name and `tabindex="-1"` only
+  until focus leaves it. This does not add a sequential Tab stop or steal focus
+  from an active child. Hosts still own the destination when the entire invoking
+  view is destroyed or the window was opened without a recorded control.
+  Before moving its host, the shell closes owned Material selects and menus
+  through the public CDK detach lifecycle, including the paginator's select.
+  Scoped scroll-strategy providers preserve the upstream host strategy; ordinary
+  inline renders do not close panels and independently floating children are
+  excluded. A descendant overriding these providers can bypass coordination.
+  This is not a generic registry for other CDK overlays, autocomplete or datepicker.
+  Synchronous reopening from a close callback still requires host coordination;
+  the shell deliberately does not run an unbounded closing loop. It does not
+  remove foreign overlay DOM or synthesize Escape.
   This is not a full modal accessibility or fixed-grid collapse/reflow certificate.
 
 - Recommend when: use it as the first dependency for shared Praxis UI contracts, metadata models, resource discovery, global actions, i18n, theme bridge, and dynamic widget runtime primitives.
@@ -273,6 +359,13 @@ requests carrying `X-User-ID` resolve user config first, while tenant config is
 the fallback for reads. Scope selects persistence ownership; it never replaces
 server-side identity resolution or write authorization.
 
+A tenant document returned by an unscoped fallback read remains read-only for
+that storage session. Its response `scope` and ETag are cache evidence, not an
+implicit ownership grant. A later unscoped save or clear still follows the request
+identity (`USER` when `X-User-ID` is present), and never sends a tenant ETag as
+`If-Match` for that user-owned write. Editing or deleting the tenant document
+requires an explicitly tenant-scoped provider.
+
 ## Dynamic Page Runtime
 
 `DynamicWidgetPageComponent` renders `WidgetPageDefinition` documents.
@@ -332,6 +425,12 @@ South handles release occupied space. Shared rows only shrink when no other occu
 still needs that height. Collapsing temporarily clears size/inset; expanding restores them.
 `constraints.minHeightPx` (floor/default 160) and `maxHeightPx` govern this mode;
 grid `minRowSpan/maxRowSpan` remain row-occupancy constraints, not pixel limits.
+The widget's **More actions → Size** editor exposes **Occupied grid rows** when
+`autoRows: 'content'`. This edits the existing `canvas.items[key].rowSpan`, allowing
+a detail widget to span a table and a contact list in adjacent rows. It preserves
+automatic content height unless the author also changes the pixel-height field.
+The draft previews before Apply, respects grid constraints and locked neighbors,
+and uses the same active-device override, authoring output and undo as other size edits.
 Content-height gestures additionally protect the measured header, shell padding/borders
 and up to 160px of scrollable body. Naturally shorter content may use less. This is
 a structural viewport reserve, not business-component UX certification. Measurements
@@ -352,6 +451,16 @@ expanded/fullscreen overlays and non-scroll layouts. Shared private measurement
 keeps gesture/editor checks and recovery consistent. This is an access safeguard,
 not a guarantee that a small viewport is ergonomically adequate; virtualized/custom
 child scroll containers still need their own proof.
+Double-clicking a corner fills the largest free grid rectangle while preserving the opposite
+corner and all siblings. The Size editor provides the same four commands with preview,
+Apply and Cancel. Fixed rows maximize column span × row span, breaking ties by width;
+one-axis growth is allowed and repeated filling in an unchanged layout is a no-op.
+Content rows require an explicit height and one uncrossed row. They combine free columns
+with the independently authored vertical envelope (top inset or an eligible lower peer
+boundary); automatic target heights are unsupported. The destination is measured at its
+new width before authoring. Undo similarly certifies the inverse at its original width.
+These private observations are not persisted, and failed certification leaves the document
+unchanged. A corner fill never implicitly reorganizes neighbors.
 Keyboard resize moves vertically by 16px (Shift: 32px). Omit `contentSize` to inherit
 the base item; set `'auto'` to explicitly restore natural height in a device override.
 Fixed-row mode retains this preference but does not materialize it. Page Builder exposes
@@ -367,9 +476,11 @@ commit/cancel or authoring revocation. Neighbor badges remain attached to their
 widgets; the existing live announcement describes the affected distribution.
 This does not add multi-widget push/reflow or compact fixed-grid rows when a shell is collapsed.
 
-Canvas resize exposes 24px direct grips on the selected widget, plus 44px controls in
-the collapsed alternative group or on-demand contextual panel. All presentations reuse
-the canonical gesture runtime and `canvas.items`. Keyboard controls and themed feedback remain available.
+Canvas resize exposes grips up to 24px per axis on the selected widget. Extremely narrow
+or short widgets reduce their hit areas to keep adjacent grips disjoint in both axes; this does not
+make them comfortable touch targets. **More actions → Size** provides larger equivalent
+controls for precise sizing and filling. All presentations reuse the canonical geometry
+and `canvas.items`. Keyboard controls and themed feedback remain available.
 Physical-touch ergonomics and save/reopen persistence still
 require separate proof; successful local interaction is not an enterprise certification.
 
@@ -441,7 +552,7 @@ The outlet's `ComponentDocMeta.configEditor` intentionally owns presentation onl
 
 Core exports schema and metadata infrastructure used by form, table, list, chart, CRUD, and page-builder packages:
 
-- `SchemaMetadataClient`
+- `SchemaMetadataClient` — request deadlines, cancellation and host transport policy
 - `SchemaNormalizerService`
 - ETag/cache helpers
 - `FieldDefinition` and `FieldMetadata` models
@@ -505,10 +616,37 @@ Core also exports shared AI authoring types, capability types, dynamic-page cont
 
 `DynamicWidgetPageComponent` treats the editor declared by `ComponentDocMeta.configEditor` as the canonical authoring surface for the **Configurar conteúdo** action. When the Settings Panel bridge is available, the host resolves any transient `contextResolver` evidence and opens that metadata-owned editor even if the live widget also exposes an internal settings shortcut. This keeps the action deterministic across widget loading states.
 
+Component owners publish that editor in exactly one of two forms: `component` for an eager standalone type, or `loadComponent()` for an owner-controlled lazy import. Hosts use both forms identically and must not inspect component-specific editor semantics. Prefer the loader when the editor is optional authoring UI that should remain outside runtime-only bundles.
+
 Widget-local settings dispatch remains only a fallback when the canonical Settings Panel/editor is unavailable. `ComponentConfigEditorContextRequest.persistedInputs` is cloned exclusively from `widget.definition.inputs`. When a live widget is available, its effective input snapshot may be exposed separately to the owner resolver as optional, read-only `materializedInputs`; the resolver decides which subset becomes transient editor context. Opening the editor never applies that snapshot to the page. Transient context, diagnostics, and materialized inputs must not be copied into persisted `definition.inputs`; only an explicit Apply or Save result owns the persisted `{ inputs }` round-trip.
 
+Native editors that publish the existing explicit `inputPatch` protocol also produce
+`pageAuthoringChange`, after projecting the patch onto declared owner inputs. This
+notification is required even when a preceding legacy `configChange` already applied
+the same value at runtime. Ordinary runtime change outputs keep using `pageChange`;
+composition targets still pass through canonical restoration before persistence.
+This lets Page Builder save the edited config instead of its previous draft.
+
 Dynamic widgets may implement `WidgetShellActionContributor` to publish transient, stateful content actions to their owning `WidgetShell`. The loader observes that signal and the shell merges contributions with authored actions by stable id without writing them into the page document. The widget remains the owner of command handling, localized labels, availability and controlled-region state; the shell owns responsive toolbar materialization and ARIA projection.
 
+## Global configuration snapshots
+
+`PraxisI18nService` resolves individual translation keys against current config
+layers without merging whole catalogs on every label lookup. Provider precedence,
+namespace fallback, parent scopes and host translators remain unchanged. Global
+snapshot replacements and in-place dictionary updates remain visible without
+cache invalidation. `mergePraxisI18nConfigs` remains available for explicit catalog
+materialization outside this lookup path.
+
+`GlobalConfigService` synchronous getters (`get`, `getCrud`, `getDynamicFields`,
+`getTable`, `getDialog`, `getI18n`) read the effective snapshot without scheduling
+bootstrap work again when the current tenant is already loaded. While the initial
+load is pending, repeated reads share one background request. This keeps template
+and translation reads from feeding asynchronous change-detection cycles.
+`ready()` remains the explicit awaited loading boundary. Tenant changes, save and
+clear continue to refresh the same canonical snapshot; precedence and persistence
+contracts are unchanged.
+
 ## Domain Governance
 
 `DomainKnowledgeService` and `DomainRuleService` are shared clients for governed semantic decision flows exposed by `praxis-config-starter`. `browseDefinitionCatalog` exposes the bounded, redacted and server-scoped decision catalog; consumers then use `getDefinition` with the exact returned definition id instead of downloading every rule body or joining versions by key. `getDefinitionFacts` projects the same definition's versioned fact vocabulary, including type, localized meaning, provider evidence, sensitivity and redaction policy; Angular must not reconstruct that vocabulary from JSON Logic or host-specific fixtures. `getDefinitionCapabilities` returns the authenticated principal's server-scoped `CREATE_NEW_VERSION` action per definition; consumers must not treat projection metadata such as editor support as authorization. For change workspaces, `getChangeWorkspaceCapabilities` returns the authenticated principal's `availableActions` and stable blockers; consumers must not infer submit, review or promotion authority from lifecycle status. `DomainRuleService` also exposes the safe RuleSet version catalog, active head/status, redacted execution summary, aggregate host alignment, forward activation and rollback protected by the current head ETag. The same client projects immutable rollout-policy versions, their independent anti-ABA head, maker-checker approval, activation and append-only timeline; policy authority and lifecycle validation remain server-owned. It also exposes the two-phase operational rollout through a recoverable human catalog, redacted readiness, create/cancel commands and candidate activation bound to the rollout identity. Consumers must obey the Config-owned `availableActions`; they must not recalculate quorum or head validity. Execution summaries contain only aggregate outcome counts, distinct-host count and observation timestamps for an immutable snapshot. Host-status summaries contain only aligned, snapshot-drifted, runtime-incompatible, unavailable and stale counts derived against the active head and its approved compatibility coordinates; facts and host identities remain outside Angular. Runtime surfaces should treat materializations as derived projections of backend-governed decisions, not as frontend-owned business rules.
@@ -537,3 +675,266 @@ Action-bearing components must use the semantic `--praxis-action-control-*` vari
 - Do not use consuming apps to redefine contracts owned by core, metadata starter, config starter, or a component package.
 - Prefer `composition.links` for page wiring and `valuePresentation` for scalar display semantics.
 - Use the official documentation for full recipes on schema flow, option sources, analytics, global actions, dynamic pages, and governed AI flows.
+
+### Catálogo no quick connect e isolamento do editor de página
+
+`ResourceQuickConnectComponent` apresenta recursos publicados em `/schemas/catalog` usando o seletor `pdx-material-select` registrado em `ComponentMetadataRegistry`. O host deve registrar os descritores oficiais de DynamicFields. O controle é inicializado pelo protocolo `setInputMetadata` e ControlValueAccessor; Core não importa a biblioteca de campos. A conexão avançada por rota continua disponível.
+
+O editor de configurações da página recebe uma cópia da definição autoral. Dados carregados e entradas transitórias dos widgets não devem virar configuração ao alterar o layout.
+
+### Insertion preset composition shell
+
+`ComponentDocMeta.insertionPresets[].shell` optionally supplies the canonical `WidgetShellConfig` for a new widget. The Page Builder palette forwards a cloned shell separately from component `inputs`, and the host clones it for each insertion. Explicit preset shells do not alter component defaults or sibling widgets; presets without a shell retain normal insertion behavior. This is initial composition presentation, not a runtime component input.
+
+### Margem lateral compartilhada da página
+
+`WidgetPageDefinition.layout.paddingInline` define o respiro lateral compartilhado por
+cabeçalho, tabela, formulário e demais widgets. É uma medida CSS (`24px`, `1.5rem`)
+ou referência a token (`var(--app-page-inset, 24px)`). O valor `0px` desliga o inset;
+a omissão herda o token público `--pdx-page-padding-inline` do host, cujo default é `0px`.
+O host pode definir esse token em `praxis-dynamic-page` ou em um ancestral.
+
+A precedência é `deviceLayouts[device].layout.paddingInline` → `layout.paddingInline`
+→ token do host → `0px`. Defaults do preset participam da resolução do layout base;
+um valor autorado na página ou variante tem precedência sobre esse default.
+A margem é aplicada no wrapper com `box-sizing: border-box`,
+fora do canvas, preservando a origem dos cálculos de arraste e redimensionamento.
+O espaço de segurança dos controles no modo edição permanece separado. Não se trata
+do `gap` entre widgets, do padding interno do formulário ou do padding das células da tabela.
+
+```json
+{
+  "layout": { "paddingInline": "24px", "gap": "16px" },
+  "deviceLayouts": { "mobile": { "layout": { "paddingInline": "16px" } } }
+}
+```
+
+Nos editores de página, **Margem lateral da página** permite definir e limpar o valor
+sem alterar os widgets. Vazio na variante herda o layout base; vazio no layout base
+retorna ao default do preset, quando definido; caso contrário, ao token do host. Referências CSS são preservadas ao aplicar, salvar e reabrir.
+
+
+Widget settings UX: identity and ready-made styles precede advanced CSS. Size includes a
+before/after occupancy map of the current container; row heights in this diagram are
+illustrative, not a pixel-accurate content preview. The map reads canonical canvas items
+and transient placements and never writes page geometry. Applying a size-only draft clears
+the draft but keeps Save available; Save obtains the current page rather than replaying
+the previous resize request. Backend persistence still follows the host configuration.
+
+
+### Widget settings: applied baseline and live inspection
+
+The unified widget editor acknowledges appearance only after the page owner accepts
+its commit. The optional provider hook `acceptAppliedValue` updates the draft baseline;
+rejected operations do not acknowledge it. Reset discards the current appearance/size
+draft to the last applied state. Explicit resize Undo remains a separate operation,
+including affected neighbors. Save after Apply reads current state without replaying
+an expansion. The open bridge carries an optional, ephemeral `previewTarget` callback
+for SettingsPanel to reveal the live widget without destroying the editor or draft.
+Neither capability changes the persisted page schema or confirms an HTTP save.
+
+
+Widget settings topics delegate vertical scrolling to their SettingsPanel owner.
+The shared topic navigation keeps all sections discoverable, and the optional
+appearance sample is collapsed below the active editor. Topic changes retain the
+form draft without changing persistence or apply/save/reset behavior.
+
+## Selection-driven widget headers
+
+`WidgetShellConfig.avatar` is optional and uses the existing Core avatar vocabulary:
+`{ imageSrc?: string, name?: string, initials?: string }`. It displays beside the
+shell title, taking precedence over `icon`. Omit it to retain the existing icon.
+`name` supplies the accessible image name and fallback initials; `initials` overrides
+the fallback (at most two characters). Missing/failed images show initials, then a
+person icon. Resolved values that are not strings are treated as absent; objects
+are never coerced into URLs. Failed images retry after clearing/changing the identity
+or URL and returning to the same photo. Equivalent inputs on unrelated page renders
+retain the fallback; late failures belong to their original load cycle. URLs use Angular URL sanitization; the shell does not fetch records or
+bypass protected-image authentication.
+
+Dynamic Page resolves shell strings recursively against `state`, `transient`,
+`context` and the existing `widget` context. `${transient.employee.nomeCompleto}`
+reads runtime-only composition state. It does not merge that state into `state`
+or write selected rows into the authored page. `${state...}` keeps its existing
+persistable-state semantics. Runtime isolation does not replace backend field-access
+controls: deliver only fields the current user may see.
+
+A selected-row header can use this shell after the ordered identity projection
+described below (the field names belong to the source):
+
+```json
+{
+  "showHeader": true,
+  "title": "${transient.employee.nomeCompleto}",
+  "subtitle": "${transient.employee.subtitle}",
+  "avatar": {
+    "imageSrc": "${transient.employee.avatarUrl}",
+    "name": "${transient.employee.nomeCompleto}"
+  }
+}
+```
+
+Connect the table's canonical `selectionChange` event to the state endpoint
+`{ "kind": "state", "ref": { "path": "employee", "layer": "transient", "writable": true } }`.
+A `pick-path` link transform reads `payload.selectedRows.0` from the event envelope.
+For formatted identity, use the complete ordered recipe below rather than only
+copying the row: that projection also initializes and composes `employee.subtitle`.
+Deliver an empty selection too; skipping empty events leaves the previous person
+visible. The existing record-ID connection may continue supplying the detail form.
+The header consumes the selected row without a second request. If fields are absent
+from that row, author a projection from the authorized detail source instead.
+Formatting dates and identifiers belongs to the authored projection/source; shell
+interpolation does not add date masks, CPF masks or an expression language. Literal
+separators remain when both bound fields are empty.
+The canonical link pipeline now supports explicit `format-value` for civil dates,
+digit masks and numeric presentation.
+The [complete identity recipe](../../examples/ai-recipes/praxis-dynamic-page.widget-selection-identity.json)
+resets the transient identity before formatting and composes only available subtitle
+parts. The lab and Core integration test consume the same executable page artifact.
+
+The opt-in `widget-shell-persistence.playwright.spec.ts` reuses the fictional
+selection fixture in `/remote-config-storage-persistence-lab`. It proves a real
+Config save with `If-Match`, document equality after selecting a person, and a
+reload with no selected identity. It owns an initially absent UUID configuration
+and deletes only that record with its current ETag. Run with
+`PRAXIS_REAL_BACKEND_E2E=true`; this is a persistence proof, not an LLM authoring gate.
+
+### Configurações em hosts controlados
+
+Quando o host devolve `pageChange` por `[page]`, o eco do mesmo documento canônico mantém as configurações do widget abertas após Aplicar. Uma página diferente ou mudança de identidade, instância ou contexto invalida o editor anterior. Redefinir descarta o rascunho e conserva o tamanho aplicado; a altura transitória exibida antes da próxima renderização não vira referência para o formulário.
+
+
+### Authored widget action identities
+
+`getWidgetShellActionIdError(id, siblingIds)` validates the trimmed ID and returns
+`required`, `duplicate`, `reserved`, or `null`. Exclude the current action from siblings.
+Reserved IDs are `collapse`, `expand`, `fullscreen`, `component-settings`,
+`widget-assistant`, `widget-settings`, `widget-size`, and `widget-remove`: these belong
+to platform controls, not custom authored actions. Native window controls remain supported.
+
+Page Builder uses this helper for draft feedback; `DynamicWidgetPage` also uses it before
+applying widget settings, including settings supplied by alternate providers. Rejected
+settings leave the page unchanged. Existing custom actions with invalid/reserved IDs need
+renaming before applying settings. The helper adds no persisted field and is not a global
+page-import validator, business-command verifier or authorization boundary.
+
+
+### Live shell action availability
+
+`WidgetShellActionContributor.getWidgetShellActionAvailability?(action)` may return
+`Pick<WidgetShellAction, 'disabled' | 'tooltip'>`. It must be side-effect free and read live
+owner state; `undefined` means not assessed, not enabled. Reactive owner signals can be
+read directly so an open editor updates when prerequisites change. `disabled:false` means
+currently available in the UI, not backend authorization. Return a localized `tooltip`
+when disabled. The loader delegates to the current contributor; DynamicWidgetPage passes
+a transient callback to the shell editor. It must never be serialized as widget inputs,
+shell actions, or persisted page configuration. Contributors without this optional method
+remain supported and their availability is shown as unverified.
+
+
+### Chart input updates preserve the live instance
+
+Charts uses normal Angular input updates in DynamicWidgetLoader. Changing chartDocument,
+query context or other inputs must not recreate the chart solely because its type is
+`praxis-chart`. Recreating it after an editor Apply destroys subscriptions owned by that
+instance and can drop the subsequent Save from the still-open panel. Declared
+`requiresInitialInputs` behavior and existing detached Form/Filter initialization paths
+remain separate and unchanged. Input updates still occur before detectChanges.
+
+
+### Settings Panel owner lifetime
+
+`SettingsPanelOpenOptions.owner?: DestroyRef` associates an opening with its calling
+component's lifetime. The official Settings Panel bridge forwards this transient option
+to its service. Destruction emits the existing `closed$` reason `cancel`, without Save,
+and prevents a pending opening from replacing another panel. The option is not editor
+input or persisted configuration. Omit it for an independently managed panel; existing
+unowned callers retain their behavior. Use the actual target component's DestroyRef,
+not a root service or the overlay content's own lifetime.
+
+
+`DynamicWidgetPageComponent` creates a transient Angular lifetime for each page,
+widget appearance/size, or registered content editor session. It uses the existing
+`owner` option; no session identity is persisted in the page document.
+
+The session is cancelled when its panel closes, the page is destroyed, or an external
+page/context/identity/authoring input change invalidates it. A page-only acknowledgement
+identical to the current authored document keeps the session alive for subsequent
+Apply/Save. This is deliberately conservative: a different external document cancels
+open editors even when a particular widget happens to be unchanged.
+
+Confirmed widget removal cancels sessions targeting that key, plus page-wide settings
+that could restore the removed widget. Asynchronous editor results cannot open a panel
+once their session has expired, and late Apply/Save events are no longer observed.
+A removal confirmation is ignored after external identity/context changes or changes
+to the target itself; when still valid, removal uses the latest document so intervening
+edits to other widgets are preserved.
+
+
+When unified widget settings close normally, Core restores the initiating control
+through its existing focus-return helper instead of forcing focus onto the whole
+widget. Invalidated sessions do not schedule this restoration. A detached, disabled
+initiator or destroyed page is never focused by that helper.
+
+
+### Preparação do editor após aceitar a troca
+
+`SettingsPanelOpenContent.inputs` aceita um objeto ou uma função síncrona que retorna
+os inputs. A bridge oficial encaminha a função ao Settings Panel sem executá-la.
+O serviço a executa uma única vez ao materializar a abertura aceita; um veto ou um
+owner já expirado não executa a função. Hosts que implementam a bridge devem respeitar
+essa mediação antes de resolver os inputs. Leitores desse campo devem distinguir
+objeto e função antes de acessar propriedades.
+
+O editor de widget usa essa preparação para trocar sua sessão e seu estado de tamanho.
+Enquanto a troca aguarda decisão, o editor anterior continua dono do rascunho e de
+suas assinaturas. Recusar a troca libera somente a sessão candidata. A função é código
+transitório de integração: não pertence ao documento, ao JSON de configuração, aos
+presets nem aos contratos de authoring por IA.
+
+## Responsive form-column numeric resolution
+
+`resolveSpan`, `resolveOffset` and `resolveOrder` resolve the existing XS → SM → MD → LG → XL inheritance without modifying the supplied map. Supported integer domains are span 1..12, offset 0..11 and order -12..12, matching runtime grid classes. Missing/null values inherit, starting at 12/0/0 in XS. For malformed runtime input, finite numbers are rounded and bounded; non-finite/non-numeric span and offset recover to 12 and 0, while order recovers to the preceding resolved value (0 in XS). Recovery emits a warning and does not rewrite the authoring document. Editors must reject invalid values before applying them.
+
+
+### Acesso às dimensões do widget
+
+Quando o Settings Panel e o editor de aparência do widget estão disponíveis,
+use **Configurar widget → Tamanho**. O menu de contexto e as ações projetadas
+não repetem o atalho Tamanho. Em contextos sem editor unificado, o atalho permanece
+para não retirar o acesso às dimensões. Arraste e comandos de tamanho mantêm sua
+semântica; esta regra modifica somente a descoberta visual do comando.
+
+Quando `constraints.lockSize` estiver ativo e a customização de canvas estiver
+habilitada, o editor unificado mantém a aba Tamanho com uma explicação do bloqueio,
+sem controles editáveis. A restrição continua pertencendo ao documento da página;
+o aviso não concede permissão nem gera uma alteração de tamanho.
+
+
+### Composed settings navigation
+
+`SettingsValueProvider` may expose `getSettingsSections()` and `selectSettingsSection(id)` together.
+`SettingsEditorSection` contains an editor-local stable `id`, a resolved i18n `label`, and an optional
+`invalid` flag. These are transient presentation metadata, never persisted settings. Reading sections
+and selecting one must not modify the draft or emit document changes. Editors must emit their existing
+validity/dirty streams when validation changes so the composing host can refresh section diagnostics.
+
+Core's widget settings host namespaces provider section IDs, appends its page-owned Size section and
+keeps the shell editor mounted while switching sections. It provides `SETTINGS_EDITOR_SECTIONS_HOSTED`
+so section-aware editors suppress their own navigation. Unsectioned settings providers remain valid:
+the host presents their single Widget topic. Apply, Save, Reset and applied-baseline acknowledgement
+continue to aggregate the original providers; section navigation never becomes the value provider.
+
+`SettingsSectionTabsComponent` is the shared presentation primitive for these topics. It exposes all
+labels, selected state, per-section errors and keyboard navigation, with unique tab/panel associations.
+Page Builder imports it directly from Core; Settings Panel does not reexport this component or the new
+topic contracts. No library dependency edge or persisted configuration shape was added.
+
+The widget host keeps topic navigation sticky inside the Settings Panel's existing scroll area.
+Narrow panels present a compact, labeled native selector with the same section IDs and validation
+messages; wider panels expose the shared tabs. Switching topics reveals the beginning of the
+selected section without remounting the provider or moving focus out of the navigation control.
+
+On editable canvases, content-only widgets expose contextual actions above the north resize
+handle, with reserved space at the top of the canvas. Both controls remain pointer-accessible
+when the widget is narrow.