@praxisui/page-builder 8.0.0-beta.0 → 8.0.0-beta.11

package/README.md

@@ -28,6 +28,7 @@ Peer dependencies (Angular v20):
 - `@angular/forms` `^20.0.0`
 - `@angular/cdk` `^20.0.0`
 - `@angular/material` `^20.0.0`
+- `@praxisui/ai` `*`
 - `@praxisui/core` `*`
 - `@praxisui/settings-panel` `*`
 
@@ -42,6 +43,10 @@ Este pacote expoe o shell ativo do builder canonico de pagina dinamica:
 Conexoes continuam pertencendo ao contrato `WidgetPageDefinition`, mas a criacao/manutencao delas nesta fase deve acontecer por JSON/configuracao canonica e nao por builder/graph/editor visual legado.
 O viewer ativo nesta fase existe apenas para inspecao contextual do contrato canonico e nao para editar links inline.
 
+Nested component ports devem ser modeladas no mesmo contrato `composition.links`, usando `component-port + nestedPath`.
+O viewer representa o endpoint nested como sub-identidade do owner top-level, sem criar um no de canvas separado para o widget filho.
+Planos de IA (`UiCompositionPlan`) tambem devem usar `nestedPath` para widgets internos; nao gere `widgetEvent`, wrappers host-specific ou `bindingPath` profundo como caminho principal para nested ports.
+
 ## AI Capabilities Registration
 
 Para que o assistente de IA consiga configurar os inputs dos widgets, registre os catalogos de capacidades no bootstrap da aplicacao.
@@ -89,6 +94,47 @@ registerWidgetAiCatalogs({
 Registro via token:
 - Use o InjectionToken `PAGE_BUILDER_WIDGET_AI_CATALOGS` para fornecer o mapa no host.
 
+## Agentic Authoring
+
+Para gerar uma página a partir de um prompt usando o backend canônico do `praxis-config-starter`, configure `PageBuilderAgenticAuthoringService` com o endpoint interno opt-in `/api/praxis/config/ai/authoring`.
+
+O chrome conversacional do assistente usa `PraxisAiAssistantShellComponent` de `@praxisui/ai`. O Page Builder continua dono da semântica agentic de página: resolução de intenção, preview, apply, save, reopen e compilação do plano validado para `WidgetPageDefinition`.
+
+```ts
+import { PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS } from '@praxisui/page-builder';
+
+providers: [
+  {
+    provide: PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS,
+    useValue: {
+      baseUrl: '/api/praxis/config/ai/authoring',
+      headersFactory: () => ({
+        'X-Tenant-ID': tenantId,
+        'X-User-ID': userId,
+        'X-Env': 'local',
+      }),
+    },
+  },
+]
+```
+
+Fluxo canônico:
+
+- `resolveIntent` envia todo prompt de authoring, pagina atual e widget selecionado para resolver operacao, recurso, schema, surface e elegibilidade no backend canonico. O Page Builder nao deve inferir intencao, recurso ou operacao por heuristica local antes dessa chamada.
+- `previewPage` envia o prompt junto de `intentResolution` elegivel e recebe `MinimalFormPlan` + `CompiledFormPatch`.
+- Hosts podem habilitar `[agenticAuthoringEnableStreaming]="true"` para usar `/api/praxis/config/ai/authoring/turn/stream/**`. O Page Builder consome eventos SSE de progresso e usa o `result` terminal como a mesma fonte de preview; se o endpoint de start ainda nao estiver disponivel, o fluxo pode voltar para `resolveIntent` + `previewPage`. Depois que a conexao SSE e iniciada, erros de transporte sao tolerados por uma janela curta de reconexao e, se persistirem, sao exibidos como falha do stream em vez de disparar uma segunda execucao sincrona silenciosa.
+- Em streaming, a conversa deve refletir estados intermediarios do turno, como resolucao de intencao, selecao de recurso, planejamento e geracao de preview. Nao trate o SSE apenas como transporte do resultado final: cada `PraxisAssistantTurnViewState` emitido precisa atualizar status, mensagens, anexos, respostas rapidas, diagnosticos e preview disponivel.
+- Para cenarios corporativos, mantenha streaming e diagnosticos como capacidades opt-in do host. Streaming melhora feedback percebido em prompts curtos ou ambiguos; diagnosticos exibem prompt/contexto/catalogos e devem ficar restritos a auditoria, suporte ou ambientes controlados.
+- `resolveIntent` e `previewPage` tambem aceitam `sessionId`, `clientTurnId`, `conversationMessages`, `pendingClarification` e `attachmentSummaries` para que respostas curtas e contexto anexado continuem o turno sem reescrever o prompt no frontend.
+- `attachmentSummaries` deve conter apenas metadados serializaveis (`id`, `name`, `kind`, `mimeType`, `sizeBytes`, `source`, `hasPreview`). O frontend nao envia `File`, bytes, base64 nem URLs locais `blob:`. Quando uma pergunta de clarificacao nasce de um turno com anexos, o backend pode ecoar esses resumos em `pendingClarification.diagnostics.attachmentSummaries`; o Page Builder reenvia esse estado no proximo turno.
+- Quando `resolveIntent` retornar candidatos ambiguos, o Page Builder deve preservar `quickReplies` como chips clicaveis ricos. Campos como `description`, `icon`, `tone` e `contextHints` pertencem ao contrato do backend e nao devem ser recriados ou descartados no frontend.
+- Hosts podem habilitar `[agenticAuthoringIncludeLlmDiagnostics]="true"` apenas em cenarios de auditoria/debug. O input adiciona `contextHints.includeLlmDiagnostics=true` nas chamadas `resolveIntent` e, quando o backend retorna `llmDiagnostics`, o Page Builder mostra esse JSON em um painel tecnico separado da conversa. O padrao permanece desligado para nao expor prompt/contexto operacional em fluxos comuns.
+- Para criacao de dashboard apos escolha de recurso, `previewPage` pode retornar `uiCompositionPlan.layoutPreset=resource-dashboard`; o builder deve aplicar esse plano como preview de pagina, nao tratar o artefato como fluxo restrito a formulario.
+- `PageBuilderAiAdapter.applyCompiledFormPatch` aplica somente `compiledFormPatch.patch.page` no runtime do builder, materializando uma cópia local antes de atualizar a página.
+- `applyPage` persiste a página renderizável corrente após o preview local em `ui_user_config`, com `componentType`, `componentId`, `scope` e `If-Match` delegados ao backend canônico.
+
+O frontend não deve persistir o envelope completo do patch como payload de runtime. O envelope fica para preview, auditoria e diagnóstico; o documento salvo é a página renderizável.
+
 ## Settings Panel Bridge
 
 Para abrir "Configuracoes da Pagina" e editores de shell no painel lateral, o host deve registrar o bridge do Settings Panel:
@@ -152,6 +198,9 @@ O builder canonico expoe authoring de shell/palette sobre `praxis-dynamic-page`.
 
 `page` e um `WidgetPageDefinition` (do `@praxisui/core`) contendo `widgets` e opcionalmente `composition.links`. O envelope `composition` e o caminho `composition.links` formam a superficie canonica persistida para wiring da pagina, com `condition` em Json Logic e `policy` para comportamento operacional.
 
+Para conectar portas de widgets internos em containers como `praxis-tabs` ou `praxis-expansion`, use `composition.links[].from/to.ref.nestedPath`.
+`ref.widget` continua sendo o owner top-level no canvas, e o ultimo segmento de `nestedPath` deve ser `kind: "widget"` com `key` estavel.
+
 Para conteudo editorial rico dentro da pagina, use um widget `praxis-rich-content`
 com `definition.inputs.document: RichContentDocument`. Isso evita criar uma DSL
 local de page-builder para cards, imagens, timelines ou blocos de apresentacao,
@@ -204,6 +253,8 @@ Exports deste pacote:
 - `WidgetShellEditorComponent`
 - `DynamicPageConfigEditorComponent`
 - `DynamicPageBuilderComponent`
+- `PageBuilderAgenticAuthoringService`
+- `PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS`
 
 Integracoes comuns:
 - `SettingsPanelService.open({ id, title, content: { component, inputs } })` para page settings e shell editors