@praxisui/page-builder 9.0.66 → 9.0.68-rc.0

package/README.md

@@ -6,6 +6,23 @@ Use this package when an application must let users compose governed operational
 
 ## Widget shell editor integrity
 
+The shell editor exposes **Keep header visible while scrolling the page**
+(`widget.shell.stickyHeader`). It retains the current title/subtitle rather than
+copying record state into the host. Apply/save/reopen/reset use the same shell
+document and the existing identity-authoring capability governs the option.
+Pinning is visible in presentation mode, not while dragging/editing the canvas;
+hidden headers, collapsed/overlay widgets and scroll recovery retain their own
+behavior. Hosts with a fixed heading provide the Core CSS length
+`--pdx-shell-sticky-header-offset`. The default remains normal flow.
+
+The page editor keeps Material tab pagination/keyboard navigation with wrapped labels
+for narrow panels. Its configuration summary is progressively disclosed; when hosted
+in Settings Panel it does not repeat the shell's title, reset action or dirty status.
+The selected widget/layout remains visible while scrolling the limits inspector.
+Rendered-height diagnostics appear at the visible height field only; diagnostics for
+another target or a hidden height field remain in the section summary. The validity
+and apply/save protocol are unchanged.
+
 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.
@@ -29,16 +46,13 @@ 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
+contextual **Size** shortcut opens the **Size** tab in Widget Settings, with larger 44px directional 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.
@@ -51,6 +65,22 @@ content-aware minimums remain important, including in restored layouts; changing
 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.
 
+### Device composition
+
+**Page settings → Responsiveness** opens on Mobile and shows one device at a time.
+**Stack widgets** prepares a single-column variant in the base canvas's visual reading
+order, with natural content height. It replaces positions and width bounds only for
+that device, preserves hidden widgets and other overrides, and leaves the base and
+other device layouts unchanged. Apply/Save materializes the existing
+`deviceLayouts[device].canvas` contract; Reset restores the original draft.
+Advanced JSON overrides remain available under **Advanced overrides**.
+
+Reducing a device's column count also reflows inherited base positions in Core.
+Explicit device positions remain authoritative. With no device variant the base
+canvas is still inherited; the editor does not silently apply a mobile template.
+Grouping settings are preserved for flow layouts; canvas geometry currently takes
+precedence over grouping. The editor explains this distinction in the Grouping tab.
+
 ### Visual widget limits
 
 Open **Page settings → Widget limits** in the default Dynamic Page editor to set
@@ -234,7 +264,7 @@ Bind the grant with `[authoringCapabilities]="presentationAuthoring"`. Use
 It emits:
 
 - `pageChange`: every canonical `WidgetPageDefinition` update, including persistent runtime state
-- `pageAuthoringChange`: explicit visual authoring updates only; use this when the host keeps source/draft separate from runtime state
+- `pageAuthoringChange`: explicit visual authoring updates only; use this when the host keeps source/draft separate from runtime state; includes accepted native-editor `inputPatch` events, even after an equivalent legacy `configChange`
 - `widgetEvent`: runtime widget event envelope
 - `pageSaveRequested`: save intent for the current page
 - `agenticAuthoringApplied`: AI preview/apply result
@@ -300,18 +330,37 @@ Feedback cycles are validated before authoring and runtime delivery. Direct or i
 
 The visual connection editor is an authoring surface over the saved `composition.links` document. It does not create a parallel graph DSL.
 
+Invalid JSON in an embedded Surface editor starts or retains the connection draft
+and blocks Apply. Correcting that text still respects the other connection
+diagnostics; Cancel discards the transient text without publishing a page change.
+
 Current capabilities include:
 
-- inspecting persisted links, endpoints, intent, condition, transform and policy;
+- inspecting persisted links, endpoints, intent, condition, transform and policy through the on-demand **Inspector**; opening it from the toolbar, canvas, link list, **Locate**, or port catalogue brings focus to the inspector header; catalogue and inspector are mutually exclusive. Dismissal restores the initiating catalogue, selected port and connection when applicable, including its internal scroll position; Escape closes one inspection layer at a time. Other entries restore their initiating control, with the editor as fallback when a canvas target is offscreen;
+- keeping the initial canvas full width, with the link list in the bottom **Links** dock; at 640px or less of stage width, or below 400px of available stage height, a scrollable component/relationship list replaces the unreadable miniature map while retaining the same inspector and port catalogue;
+- reserving a scrollable area for the expanded link list on narrow screens, with its collapse control always visible; **Locate** uses the same readable endpoints as the inspector;
+- naming page information directly in the inspector: **Name page information** edits the existing state description, updates its labels across connections, and supports Cancel, Undo and Redo. Endpoint paths and stored values remain intact; use the page's Save action to persist the authored name;
+- selecting a node to pin theme-aware port details outside the zoom layer, with scrolling, full names and keyboard actions; opening the catalogue moves focus inside, and dismissal returns to the initiating control; choosing a port explains its use and lists existing connections; **Create connection with this port** explicitly starts the cancellable draft;
+- explaining visible connection categories with a compact legend and distinct terminal geometry; the radial layout grows with node count to give captions more room;
+- assigning stable per-widget color accents while retaining icons and readable names; hosts can override the internal `--pce-node-accent` color;
+- allocating separate visual perimeter terminals for each connection incidence, including shared state paths, without duplicating canonical ports or changing the saved document;
+- placing node captions above, below, left or right using neighbouring bodies, caption collisions and connection corridors; incidence terminals and routing consume the same caption geometry, so moving a name frees its former entry corridor; long names retain their full accessible name and title while displaying up to two lines;
+- navigating the overview with pointer coordinates that match its aspect-preserving SVG projection; zoom-out uses the same lower bound as fitting the map and keeps keyboard focus when a zoom limit is reached;
+- keeping caption sides, connection terminals and routes stable during zoom; fitting the map establishes label geometry independently of the previous zoom; visible captions cap their text at 16 screen pixels and shrink toward the node inside the unchanged routing reservation;
+- separating zoom/history controls, the category legend and overview into a strip outside the clipped drawing region, so neither captions nor radial shapes intercept the main toolbar; the map clips without native scrolling, keeping movement owned by pan/zoom while catalogues and compact lists retain their own scrolling; trace source selection remains available in compact layouts and exposes its active state to assistive technology;
+- routing polylines around inflated widget bodies and the chosen caption regions using a deterministic visibility graph, with routes cached by the editor's graph derivation; overlapping manually positioned nodes can still prevent a clear route;
+- displaying connection hover information in a theme-aware stage overlay above the radial canvas, outside its zoom transform; the tooltip remains pointer-transparent so it does not block selection;
+- **Organize connections** resets positions/rotations and recomputes segment order together; **Reorganize segments** uses the current displayed node positions;
 - highlighting widget, state and global-action flows in the same graph;
 - 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;
+- warning when a new draft uses endpoints that are already connected, with an explicit discard-and-inspect action; distinct delivery rules remain authorable;
 - 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.
+**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. Its primary navigation shows each reachable connection once, keeps technical operations under disclosure, and remains outside the transformed canvas. Reading order is explicitly not a claim of execution order between consumers. Advancing reveals the active step and its highlighted relationship in the compact list without moving keyboard focus. Navigation remains focusable at route boundaries with an unavailable state; closing the inspector by Escape or its close button restores the initiating control, including relationships opened from the destination component.
 
 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.
 
@@ -331,7 +380,7 @@ 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.
+Component input editors belong to the component owner. Page Builder discovers `ComponentDocMeta.configEditor` and hosts either its eager `component` or owner-controlled `loadComponent()` result instead of redefining table, form, chart, list, upload, stepper, tab, expansion, CRUD, or rich-content configuration locally.
 
 ## Page Settings Presets
 
@@ -497,6 +546,13 @@ transient; it must not become the page's durable semantic source across runtime
 recomposition. The People Operations certification scenario applies this rule to
 `state.activeFilter` and verifies the complete fan-out in the browser.
 
+Shell authoring reads `BUILTIN_WIDGET_SHELL_PRESETS` from `@praxisui/core` for
+both widget and page settings. The widget editor presents the descriptors as
+visual choices and keeps raw CSS overrides in the advanced appearance section.
+Selecting no widget preset inherits the page treatment; selecting a preset pins
+that treatment to the widget. Page themes and explicit page shell defaults remain
+lower-precedence projections than an explicit widget preset.
+
 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.
@@ -527,3 +583,292 @@ Main exports:
 - Use component-owned config editors through metadata instead of duplicating widget-specific editors in Page Builder.
 - Keep diagnostics and streaming opt-in for hosts that need auditability or richer authoring feedback.
 - Use the official documentation for extended recipes, playground routes, and advanced AI authoring flows.
+
+### Montagem manual de master detail a partir de uma página vazia
+
+1. Insira Filter, Table e Dynamic Form e conecte-os ao recurso pelo catálogo.
+2. No filtro, carregue o schema e selecione os campos sempre visíveis.
+3. Na tabela, habilite seleção única por clique e escolha paginação no servidor para APIs paginadas; no formulário, escolha modo `view`.
+4. Crie as conexões `Filter.change → Table.queryContext` e `Table.selectionChange → Dynamic Form.resourceId`. O editor usa os contratos públicos das portas para propor as transformações do filtro e do identificador.
+5. Configure a grade, salve a página e reabra para conferir filtro, seleção e detalhe.
+
+Ao converter uma página sem posições em grade, o editor acrescenta posições para todos os widgets e usa altura de conteúdo como padrão. Isso garante visibilidade; a distribuição lado a lado continua sendo uma decisão de layout do autor. O diagrama radial mantém os modos de edição e apresentação.
+
+### Menu de ações e tamanho preciso
+
+No host `/page-builder-ia`, a edição é controlada pelo toggle global do aplicativo. O host não acrescenta título de sandbox nem botão de edição à composição; título e subtítulo de negócio pertencem ao documento autorado. Feedback de reinício e diagnóstico de modelo aparecem apenas em edição.
+
+O editor de shell aceita `placement: 'menu'` para manter uma ação em Mais ações mesmo
+com espaço livre no cabeçalho. **Configurar widget** reúne as abas **Aparência** e **Tamanho**
+no SettingsPanel. `Mais ações → Tamanho…` é um atalho para essa mesma aba,
+com largura em colunas e altura em linhas ou pixels conforme `autoRows`. O ajuste usa
+as restrições e o layout de dispositivo canônicos, com prévia e aplicação explícita.
+O painel tem um único rodapé: Aplicar/Salvar validam o conjunto das duas abas; Cancelar
+descarta o rascunho não aplicado, preservando um Aplicar anterior. O mapa direcional 3×3
+corresponde às oito alças e oferece preenchimento sem mover vizinhos. **Avançado** reúne
+reorganização explícita, canto fixo e linhas ocupadas. Desfazer dentro da aba prepara
+uma prévia inversa para confirmação no rodapé.
+Com altura de conteúdo, **Linhas ocupadas na grade** controla separadamente quantas
+linhas o widget acompanha. Por exemplo: tabela na linha 2, contatos na linha 3 e
+ficha na linha 2 ocupando duas linhas. Esse controle usa `canvas.items[key].rowSpan`
+e preserva a altura automática ou em pixels já escolhida. Não exige editar JSON.
+Selecionar o widget continua expondo suas alças; o ícone dedicado e os painéis de setas
+separados foram removidos. O editor oferece presets exatos de largura e recuperação do último resize da sessão,
+incluindo vizinhos. Duplo clique nas alças laterais preenche o espaço livre até o primeiro
+vizinho ou limite, sem alterar altura nem vizinhos. A mesma operação está em
+`Tamanho… → Preencher à esquerda/à direita`, com prévia e Aplicar/Cancelar.
+Repetir o atalho no limite não reorganiza widgets. A seção
+`Tamanho… → Expandir até a borda e reorganizar` oferece esquerda/direita com prévia dos
+vizinhos que serão movidos para baixo, Aplicar/Cancelar e desfazer do conjunto.
+Posições bloqueadas ou limites que impeçam alcançar a borda bloqueiam a operação inteira;
+um layout alterado depois da prévia exige nova revisão. Dimensões configuradas e herança
+de dispositivo são preservadas; alturas automáticas continuam acompanhando o conteúdo.
+A âncora central superior também oferece duplo clique e `Tamanho… → Preencher acima`.
+Em linhas rígidas, preenche até o obstáculo acima ou limite, preservando a borda inferior.
+Em altura pelo conteúdo, consome somente o recuo superior existente, mantendo altura mais
+recuo constantes e preservando as linhas compartilhadas. Respeita limites e bloqueios;
+altura automática sem recuo permanece automática. Trilhas CSS flexíveis não oferecem essa
+expansão.
+A âncora central inferior oferece duplo clique e `Tamanho… → Preencher abaixo`, preservando
+o topo e os vizinhos. Em linhas rígidas, ocupa o espaço até o próximo obstáculo ou o fim
+lógico dos itens, respeitando o limite de altura e sem criar linhas adicionais. Em altura
+pelo conteúdo, exige alvo e referência com alturas explícitas na mesma linha, sem qualquer
+item atravessando essa linha por múltiplas linhas. O alvo cresce até a borda inferior
+sustentada pela referência, mantendo seu recuo. A geometria renderizada precisa corresponder
+ao canvas; casos automáticos ou sem referência segura ficam indisponíveis com explicação.
+O bloqueio de tamanho impede a expansão inferior; o bloqueio de posição permite crescer
+sem mudar coordenadas. Prévia, Aplicar/Cancelar e Desfazer seguem o mesmo fluxo dos outros
+lados. Os quatro cantos também oferecem duplo clique e `Tamanho… → Preencher pelos cantos`.
+O canto oposto permanece fixo e o preenchimento não desloca vizinhos. Em grade rígida,
+escolhe a maior área em colunas × linhas, com desempate pela largura; pode crescer somente
+em um eixo. Em conteúdo, exige altura explícita, uma linha sem spans cruzados e validação
+da geometria renderizada na largura final. Norte consome o recuo; sul usa referência
+independente. Sem espaço vertical, pode preencher apenas a largura. Alvos automáticos e
+geometrias que não possam ser certificadas ficam indisponíveis. A prévia, confirmação e
+inversa do desfazer verificam o canto fixo, os mínimos e os retângulos dos irmãos.
+Reorganização inferior, histórico geral e redo seguem fora desta etapa.
+
+### Revalidating edited pages
+
+`UiCompositionResourcePreflightService.preflight(plan)` validates an initial
+`UiCompositionPlan`. After visual authoring, use `preflightPage(page)` with the
+current `WidgetPageDefinition`; it shares the semantic composition validator and
+HTTP-backed resource schema checks. The service validates a cloned snapshot and
+never rebuilds the original plan or mutates the supplied page. Hosts must expire
+older evidence when inputs or links change and ignore out-of-order results.
+
+Page preflight rechecks components, links, runtime profiles and declared fields
+on every invocation. Only HTTP schema responses are reused: up to 64 entries per
+service instance for five minutes, keyed by the resolved API scope and resource
+schema request. Layout-only edits reuse those schemas while returning the current
+page snapshot. Failures and missing schemas are not retained across validations.
+Use `preflightPage(page, registry, { refreshSchemas: true })` for explicit retry
+or Save; this expires cached evidence before checking the current document. The
+Dynamic Page Lab uses this refresh for both actions. Plan-based preflight keeps
+its existing fresh-evidence behavior. This cache is not authorization evidence.
+
+The Dynamic Page Lab persists normal Save Page requests through its configured
+`ASYNC_CONFIG_STORAGE` using `dynamic-page:${buildPageKey(pageIdentity)}` and
+loads that key before mounting its Builder. The separate certification action
+uses a temporary key and does not delete the durable page. A failed validation
+blocks saving while retaining the editor and draft for correction; it does not
+certify or authorize the draft's live runtime effects. Backend access controls
+remain authoritative. Local storage is the default adapter unless the host
+provides another storage implementation.
+
+### 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.
+
+Connection inspector UX: one summary uses available port-contract labels and descriptions; raw endpoints remain in technical details. Close dismisses the inspector, and the full-path action opens the existing configuration trace from the selected source. The hover card is suppressed while inspecting. Missing localized contract labels remain a content limitation; no labels are inferred from endpoint identifiers.
+
+Editorial endpoint copy is resolved through `ComponentMetadataRegistry.resolveEditorial`, with port-contract copy as fallback. Page-state endpoints use the authored `state.schema[path].description` or derived-state description when present. These are presentation values; link identities and payloads are unchanged. The People Operations plan supplies descriptions for its filter values, filter presentation context and decision result.
+
+
+O percurso por origem acompanha as leituras de cada caminho/camada de estado escrito, na ordem da fila do runtime, sem repetir links em ciclos. Não presume que receber uma entrada dispara uma saída do componente. Condições e transformações aparecem como etapas da configuração; não são evidência de execução. O editor usa a mesma resolução editorial no catálogo, seletores, lista de links e percurso. IDs de links ficam nos detalhes técnicos ou na densidade técnica da lista.
+
+A ação de acompanhar uma conexão inicia no endpoint exato (incluindo identidade aninhada ou caminho/camada de estado), preservando ramificações dessa mesma origem. Escolher um componente no seletor de origens continua sendo uma visão agregada explícita do componente. Inspecionar um vínculo não altera o escopo nem a etapa do percurso ativo. Descrições de estado são resolvidas na camada do endpoint; estados transitórios não herdam descrições primárias ou derivadas.
+
+
+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.
+
+Escape dispensa detalhes e seleção sem apagar a origem ou o progresso de um percurso ativo. **Encerrar percurso** finaliza a exploração, limpa a origem e volta à visão geral; uma nova exploração começa na primeira etapa. Essa ação não é uma pausa e não altera a página.
+
+
+### Applied widget settings and live result
+
+The combined Appearance/Size editor refreshes its appearance baseline only after the
+Core confirms the application. Reset discards a later draft to that applied baseline;
+resize Undo remains explicit. View result temporarily reveals the live widget through
+SettingsPanel while retaining the form, tab and draft. Return or Escape resumes editing;
+viewing the result does not apply or save. The optional provider acknowledgement and
+preview target are transient authoring capabilities, not persisted widget properties.
+
+### Widget appearance sample
+
+The appearance editor renders its illustrative sample with the canonical
+`WidgetShellComponent`, including preset resolution and runtime header actions.
+Sample window interactions do not modify the saved editor payload. Custom appearance
+adjustments are counted; **Use style only** clears those adjustments while preserving
+the chosen preset, identity and actions. The sample illustrates the shell, not the
+widget's real content or dimensions.
+
+The local Dynamic Page Lab includes an appearance studio comparing the six built-in
+presets with identical metric, trend or exception-list content. Its data is illustrative;
+the trend is a static visual specimen, not a ChartDocument integration example.
+
+
+The shell editor gives the active topic the available editing width. Its illustrative sample follows
+the fields in a native keyboard-accessible disclosure, initially closed. Opening or closing it does
+not discard the draft or reserve a permanent second column. Field columns respond to the available
+inspector width rather than the width of the browser window.
+
+
+Widget action editing is organized around choosing a published component action,
+configuring its button text/style/placement, and editing the technical connection only
+when needed. The catalog search filters existing governed candidates; it does not
+route user intent. Usage-context filters expose their active count and empty results
+explain how to recover. Selection-dependent actions keep their warning visible.
+IDs, events, commands and sent data remain available in advanced disclosures; an
+invalid custom-action ID opens its connection fields and blocks Apply/Save. Renaming
+a button preserves its command and payload. Custom actions and component-property
+buttons remain explicit advanced tasks; creating a button does not create business
+behavior. Incoming component action labels continue to come from component metadata.
+
+
+The initial action-catalog filter includes widget, general-use and toolbar actions;
+selection-dependent actions remain opt-in through the context filter. This prevents
+components whose published actions belong to the toolbar from appearing empty on
+first open, while retaining explicit selection-context review.
+
+## Employee avatar and transient header bindings
+
+In **Configure widget → Appearance**, enable **Show avatar beside the title**.
+Enter a photo URL or `${transient.employee.avatarUrl}`, the accessible name (for
+example `${transient.employee.nomeCompleto}`), and optional fallback initials.
+The editor explains missing-photo behavior and uses a labeled illustrative identity
+for unresolved avatar bindings in its sample. Apply/save/reopen/reset preserve the
+same `WidgetShellConfig.avatar` fields; disabling the option removes that object.
+The existing identity-authoring capability controls these fields.
+
+For selection-driven headers, author the existing `composition.links` state-write
+from table `selectionChange` to `employee` in layer `transient`, selecting
+`payload.selectedRows.0`. Bind title and subtitle through `${transient.employee...}`.
+The connections editor preserves that layer when displaying/reconnecting ports,
+separates identical paths in distinct layers, and explains temporary data in the
+inspector. The shared visual state location is separate from each link endpoint:
+`writable:false` on one endpoint does not become a global restriction on other links.
+Inspecting/reconstructing a connection preserves its exact authored endpoint. That
+endpoint cannot receive writes if it is explicitly read-only; the `derived` layer
+always rejects writes.
+Creating a new state path/layer still belongs to canonical page/AI authoring; the
+connection canvas does not introduce a parallel state-definition form. There is no
+new shell input port or avatar-specific link kind. Existing ID-to-detail links remain
+independent. Clearing selection must be propagated, not filtered out.
+
+The public `widget.shell.configure` operation and Core capability catalog describe
+`avatar.imageSrc`, `avatar.name` and `avatar.initials`. The shell binding grammar
+remains the existing path interpolation; the explicit `transient` root is runtime-only.
+See the Core package's “Selection-driven widget headers” example for the full shape
+and formatting/field-access boundaries.
+
+The existing `/dynamic-page-lab` includes a lazy “Widget identity from selection”
+proof using the real Table and Dynamic Page with fictional records and local images.
+It exercises image load, missing image, selection switch/clear and JSON serialization
+followed by a fresh runtime mount. The corresponding `widget-shell-selection` browser
+spec also injects a browser network outage and proves same-URL recovery. It does not
+mock Praxis endpoints or certify remote persistence/LLM authoring.
+
+Remote persistence is covered separately by `widget-shell-persistence.playwright.spec.ts`
+with `PRAXIS_REAL_BACKEND_E2E=true`, using the existing remote persistence lab and
+an exclusive UUID record. It checks `If-Match`, unchanged authored bindings after
+selection, reload without selected data, and conditional cleanup.
+Check the target backend's active registry for other environments; neither a local
+editor preview nor a deterministic persistence test proves a live LLM authoring gate.
+
+
+### Action and preset integrity
+
+The editor preserves the complete authored `WidgetShellAction` and replaces only the
+fields it edits. Toggle state, ARIA relationships and explicit `payload: null` survive
+rename/reset/apply. Transient runtime actions are not added to the authored document.
+
+Action IDs are trimmed and validated for emptiness, sibling uniqueness and reserved
+shell controls through Core's `getWidgetShellActionIdError`. The settings application
+boundary also rejects these identities. Invalid drafts stay editable; users must repair
+old invalid IDs before applying widget settings. This is not validation of every JSON/AI
+import path or backend authorization.
+
+The catalog initially shows entries declaring `command`. Event-only entries require
+**Incluir eventos para conexão — avançado** and explain that they emit a notification,
+not execute the operation described. `payloadSchema.example` remains reference material;
+adding an entry never copies it into the button payload. Existing authored payloads are
+preserved. Declaring a command does not prove its handler, required context or authorization:
+those need component-specific execution tests before enterprise certification.
+
+Page-defined presets override built-in presets of the same ID. The selector presents
+one option per ID using that same precedence, matching the preview.
+
+Charts handles its existing `openConfigEditor`
+command and guards customization at execution time, including pending context resolution.
+Event-only entries in Table/List/CRUD/Tabs remain notifications, not proven operations.
+
+
+### Action availability in the current widget
+
+The shell catalog consults the live component through Core. For assessed commands it shows
+availability or the owner's localized reason; unavailable entries cannot be added. An
+existing selection can still be removed. For unassessed commands it explicitly says that
+availability has not been verified. This does not infer operations from names, execute
+commands, or copy transient `disabled`/`tooltip` into authored buttons. Availability may
+change after saving; runtime guards and backend authorization remain necessary.
+
+### Formatação explícita em conexões
+
+O inspetor de conexões oferece **Adicionar formatação**. Escolha data civil,
+máscara de dígitos ou formato numérico; localidade, máscara e moeda são
+configurações declarativas do Core. Configuração incompleta bloqueia Aplicar e
+a edição é preservada ao serializar/reabrir a página.
+Esta superfície usa `page.composition.links[].transform`; não amplia o shorthand
+`UiCompositionPlanTransform`.
+
+### Abas especializadas de configurações do widget
+
+O editor publica Cabeçalho, Estilos, Avatar, Vínculos de dados, Comportamento, Personalizar aparência e Ações pelo protocolo de assuntos de `SettingsValueProvider`. O host do Core reúne esses assuntos com Tamanho em uma única navegação, sem a aba intermediária Widget. A navegação permanece acessível durante a rolagem: abas fixas em painéis largos e um seletor compacto de assuntos em painéis estreitos. A troca de assunto revela o início da seção, preservando o foco e o rascunho. O formulário continua montado ao navegar; erros identificam a aba responsável e oferecem um atalho para correção.
+
+Vínculos de dados edita os mesmos controles canônicos de título, descrição e avatar, sem persistir um documento paralelo. As conexões recebidas em `compositionLinks` são uma projeção de consulta de `page.composition.links`, nunca parte do resultado do editor. Origens, propagação, condições e transformações continuam pertencendo ao editor de conexões da página. A amostra começa recolhida abaixo dos campos e não ocupa uma coluna fixa. Aplicar/Salvar/Redefinir mantêm o protocolo existente.
+
+As miniaturas de estilos projetam as cores de título/ícone do cabeçalho e o fundo/cor do corpo a partir do preset canônico. A opção selecionada usa borda e marcador visual, mantendo `aria-pressed` para tecnologia assistiva. A miniatura continua esquemática: dimensões, conteúdo real e ajustes individuais devem ser conferidos na amostra e em Ver resultado.
+
+O modo **Somente conteúdo** altera apenas `shell.kind`: título, descrição, avatar, estilo,
+aparência e ações continuam sendo editados e preservados em Aplicar/Salvar/Redefinir e na
+reabertura. Ocultar a moldura no runtime não autoriza descartar o rascunho dos demais campos.
+Os campos de aparência mantêm rótulos flutuantes visíveis mesmo quando estão vazios.