@praxisui/page-builder 8.0.0-beta.2 → 8.0.0-beta.20

package/README.md

@@ -11,10 +11,10 @@ Ferramentas de edicao para paginas dinamicas canonicas baseadas em `praxis-dynam
 ## When to use
 
 - Montar paginas dinamicas com widgets e layout visual sobre o runtime canonico
-- Entregar experiencia de configuracao de pagina/widget sem depender de editor visual de conexoes
+- Entregar experiencia de configuracao de pagina/widget com editor visual canonico de conexoes
 - Integrar page composition com IA, settings panel e contratos compartilhados do Praxis UI
 
-O pacote permanece focado no shell canonico de authoring em torno de `praxis-dynamic-page`: palette, page settings, widget shell e catalogos de IA. A composicao declarativa de conexoes deve ser feita exclusivamente via JSON/configuracao canonica no `@praxisui/core`; os editores visuais legados de conexoes sairam do escopo ativo desta fase.
+O pacote permanece focado no shell canonico de authoring em torno de `praxis-dynamic-page`: palette, page settings, widget shell, catalogos de IA e edicao visual de `composition.links`. A fonte de verdade das conexoes continua sendo o contrato `WidgetPageDefinition` do `@praxisui/core`; o editor visual apenas materializa esse contrato canonico.
 
 ## Instalacao
 
@@ -37,11 +37,16 @@ Peer dependencies (Angular v20):
 Este pacote expoe o shell ativo do builder canonico de pagina dinamica:
 - `ComponentPaletteDialogComponent` para adicionar widgets a pagina.
 - `FloatingToolbarComponent` e `TileToolbarComponent` para acoes rapidas de add/save/preview/configuracao.
-- visualizador inicial de conexoes somente leitura para inspecao de `composition.links`.
+- `ConnectionEditorComponent` para inspecionar, criar e remover conexoes canonicas em `composition.links`.
 - `WidgetShellEditorComponent` e `DynamicPageConfigEditorComponent` para authoring de shell/canvas sem redefinir a semantica canonica de composicao.
 
-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.
+Conexoes continuam pertencendo ao contrato `WidgetPageDefinition`. O editor visual do Page Builder cria, remove e edita links inline preservando o envelope canonico `page.composition.links`, incluindo `condition` em Json Logic, `policy` operacional e `transform` canônico, sem introduzir modelo paralelo de grafo. O historico de desfazer/refazer do editor e transitorio: ele reemite snapshots canonicos por `pageChange`, mas nao persiste estado de historico dentro da pagina.
+
+O roadmap tecnico para evoluir o editor radial esta registrado em [`connection-editor-reference-study.md`](./connection-editor-reference-study.md).
+
+Nested component ports devem ser modeladas no mesmo contrato `composition.links`, usando `component-port + nestedPath`.
+O editor 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
 
@@ -94,21 +99,47 @@ Registro via token:
 
 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`.
+O chrome conversacional do assistente usa `PraxisAiAssistantShellComponent` de `@praxisui/ai`, mas a presença minimizada deve ser renderizada pelo shell da aplicação com `PraxisAiAssistantSessionHostComponent`, lendo o `PraxisAssistantSessionRegistryService`. O Page Builder apenas registra sua sessão com identidade estável e contexto `Page Builder`; a identidade pública continua sendo o copiloto semântico Praxis. 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`.
+
+### Agentic Authoring Manifest
+
+`PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST` declara o contrato executável de authoring do pacote e é exportado pelo `public-api` de `@praxisui/page-builder`.
+
+O manifesto cobre as famílias de operação `page.configure`, `canvas.configure`, `widget.add`, `widget.remove`, `widget.moveResize`, `widget.shell.configure`, `composition.link.add`, `composition.link.remove`, `composition.plan.compile`, `state.set`, `page.preview.apply`, `page.persist.save` e `childOperation.delegate`.
+
+As fronteiras canônicas são:
+- o documento persistido continua sendo `WidgetPageDefinition`;
+- `UiCompositionPlan` é apenas o plano intermediário de IA e deve compilar antes do preview/apply local;
+- wiring persistido usa `page.composition.links`, incluindo `nestedPath` para component ports internas;
+- o Page Builder não redefine inputs de widgets filhos. Edições de `definition.inputs` devem delegar para o manifesto do componente filho ou para `ComponentDocMeta.configEditor`;
+- `pageIdentity` e ETag pertencem ao fluxo de persistência do `praxis-config-starter` e não entram no documento runtime da página.
 
 ```ts
 import { PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS } from '@praxisui/page-builder';
+import { DomainKnowledgeService, DomainRuleService } from '@praxisui/core';
 
 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',
-      }),
+    useFactory: () => {
+      const domainKnowledge = inject(DomainKnowledgeService);
+      const domainRules = inject(DomainRuleService);
+      return {
+        baseUrl: '/api/praxis/config/ai/authoring',
+        // Domain Knowledge change-sets stay governed by praxis-config-starter.
+        createProjectKnowledgeChangeSet: (request, options) => domainKnowledge.createChangeSet(request, options),
+        getProjectKnowledgeChangeSet: (changeSetId, options) => domainKnowledge.getChangeSet(changeSetId, options),
+        validateProjectKnowledgeChangeSet: (changeSetId, options) => domainKnowledge.validateChangeSet(changeSetId, options),
+        transitionProjectKnowledgeChangeSetStatus: (changeSetId, request, options) =>
+          domainKnowledge.transitionChangeSetStatus(changeSetId, request, options),
+        applyProjectKnowledgeChangeSet: (changeSetId, options) => domainKnowledge.applyChangeSet(changeSetId, options),
+        sharedRuleIntake: (request, options) => domainRules.intake(request, options),
+        headersFactory: () => ({
+          'X-Tenant-ID': tenantId,
+          'X-User-ID': userId,
+          'X-Env': 'local',
+        }),
+      };
     },
   },
 ]
@@ -116,12 +147,19 @@ providers: [
 
 Fluxo canônico:
 
-- `resolveIntent` envia prompt, pagina atual e widget selecionado para resolver operacao, recurso, schema, surface e elegibilidade.
+- `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`.
+- `DomainKnowledgeService` em `@praxisui/core` e o cliente canonico para continuar propostas de Project Knowledge como change-sets governados em `/api/praxis/config/domain-knowledge/change-sets`; o Page Builder pode acionar essa trilha como cockpit, mas nao deve materializar evidencias localmente nem tratar o frontend como fonte primaria da decisao.
+- 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.
-- `PageBuilderAiAdapter.applyCompiledFormPatch` aplica somente `compiledFormPatch.patch.page` no runtime do builder.
-- `applyPage` persiste o mesmo `patch.page` em `ui_user_config`, com `componentType`, `componentId`, `scope` e `If-Match` delegados ao backend canônico.
+- 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.
 
@@ -188,6 +226,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,
@@ -229,7 +270,7 @@ this.settingsPanel.open({
 
 - Trate `composition.links` como parte do contrato canonico salvo no JSON da pagina.
 - Use `composition.links[].condition` para guardas semanticas em Json Logic e `composition.links[].policy` para debounce/distinct/missing-value.
-- Quando precisar revisar ligacoes, prefira inspecao textual/versionada do contrato e do runtime, nao um editor visual legado.
+- Quando precisar revisar ligacoes, use o editor visual para interacao e mantenha a inspecao textual/versionada do contrato como fonte de auditoria.
 
 ## API (resumo)
 
@@ -238,10 +279,30 @@ Exports deste pacote:
 - `FloatingToolbarComponent`
 - `TileToolbarComponent`
 - `WidgetShellEditorComponent`
+- `ConnectionEditorComponent`
 - `DynamicPageConfigEditorComponent`
 - `DynamicPageBuilderComponent`
 - `PageBuilderAgenticAuthoringService`
 - `PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS`
+  - `createProjectKnowledgeChangeSet`, `getProjectKnowledgeChangeSet`, `validateProjectKnowledgeChangeSet`, `transitionProjectKnowledgeChangeSetStatus` e `applyProjectKnowledgeChangeSet` permitem que o cockpit continue Project Knowledge citado como `Domain Knowledge` governado por change-set canonico, sempre com validacao, aprovacao, aplicacao e readback seguro no backend.
+  - `sharedRuleIntake` permite abrir a trilha governada de `domain-rules/intake` quando o backend devolver `recommendedAuthoringFlow=shared_rule_authoring`; o handoff exportado preserva `endpoint`, `intakeEndpoint`, `nextEndpoint`, `routeGateStatus`, `routeFailureCode`, `routeDecisionSource` e `previewDisposition` para que hosts mostrem a rota canonica completa sem reinterpretar localmente a decisao.
+
+Campos de routing no handoff:
+- `routeGateStatus` vem do gate de resolucao de intencao retornado pelo backend, como `route_required`.
+- `routeFailureCode` preserva o motivo canonico, como `intent-resolution-shared-rule-route-required`.
+- `routeDecisionSource` indica se a fonte foi `contextHints.domainCatalog.recommendedAuthoringFlow` ou o gate de resolucao.
+- `previewDisposition` explicita que o preview visual foi bloqueado por rota governada, em vez de sugerir um `componentEditPlan`.
+
+Checkpoint operacional de review/publicacao:
+- O Page Builder emite o handoff canonico de `shared_rule_authoring` e oferece um cockpit governado para continuar a decisao sem assumir autoria primaria da regra de negocio.
+- O cockpit chama, por cliente real, a sequencia `definition/intake -> simulation -> governed review -> status transition -> semantic publication confirmation -> publication/materializations -> enforcement validation`.
+- Quando um preview traz `diagnostics.projectKnowledgeAudit`, o cockpit de Project Knowledge pode propor `add_evidence` via `/api/praxis/config/domain-knowledge/change-sets`, validar, aprovar, aplicar e reler a projecao segura sem expor o conteudo bruto da evidencia na UI.
+- Quando o prompt de authoring trouxer um caminho explicito como `/api/helpdesk/chamados`, a validacao do cockpit deve confirmar que o backend preservou esse alvo canonico no handoff, sem re-grounding por vocabulario solto do prompt.
+- Timeline e historico governado sao observabilidade derivada. O cockpit pode exibir indisponibilidade dessa projecao, mas nao deve tratar a timeline como fonte primaria ou bloquear create/simulate/approve/activate quando o backend antigo ainda nao expuser o endpoint.
+- A revisao deve exibir readiness, approvals, warnings, diagnostics e predicted materializations vindos do backend; nao reconstrua heuristicas de publicacao no frontend.
+- A publicacao deve ser uma acao deliberada e confirmada semanticamente antes de chamar `/domain-rules/publications`.
+- Materializacoes resultantes devem ser apresentadas como projecoes derivadas irmas (`option_source`, `backend_validation`, `workflow_action`, `approval_policy` ou futuras camadas), nao como novas regras primarias.
+- A validacao de enforcement no cockpit consulta materializacoes aplicadas e prepara a evidencia para o runtime consumidor; ela nao reimplementa localmente a politica publicada.
 
 Integracoes comuns:
 - `SettingsPanelService.open({ id, title, content: { component, inputs } })` para page settings e shell editors