@praxisui/page-builder 8.0.0-beta.1 → 8.0.0-beta.12

package/fesm2022/praxisui-page-builder.mjs

@@ -25,13 +25,13 @@ import * as i6 from '@angular/material/divider';
 import { MatDividerModule } from '@angular/material/divider';
 import * as i6$1 from '@angular/material/select';
 import { MatSelectModule } from '@angular/material/select';
-import { BehaviorSubject, merge, firstValueFrom } from 'rxjs';
+import { BehaviorSubject, merge, switchMap, Observable, firstValueFrom, from, concatMap, catchError, of, lastValueFrom, tap } from 'rxjs';
 import { SETTINGS_PANEL_DATA } from '@praxisui/settings-panel';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import * as i7 from '@angular/material/tabs';
 import { MatTabsModule } from '@angular/material/tabs';
 import { HttpClient, HttpHeaders } from '@angular/common/http';
-import { PraxisAssistantTurnOrchestratorService, PraxisAiAssistantShellComponent } from '@praxisui/ai';
+import { AI_STREAM_EVENT_TYPES, PraxisAssistantTurnOrchestratorService, PraxisAiAssistantShellComponent } from '@praxisui/ai';
 
 const PLACEHOLDER = 1;
 
@@ -2345,6 +2345,7 @@ const PRAXIS_PAGE_BUILDER_EN_US = {
     'praxis.pageBuilder.agentic.quickReplies.formSuggestion': 'Form',
     'praxis.pageBuilder.agentic.quickReplies.masterDetailSuggestion': 'Master detail',
     'praxis.pageBuilder.agentic.quickReplies.confirmPromptSuffix': 'Confirmed:',
+    'praxis.pageBuilder.agentic.quickReplies.resourceSelectionPrompt': 'Use {label} ({resourcePath}) as the data source.',
     'praxis.pageBuilder.agentic.attachments.currentPage': 'Current page',
     'praxis.pageBuilder.agentic.suggestionPrompts.payrollExecutiveDashboard': 'Create a payroll dashboard with KPIs, payroll by department, monthly evolution, and a detail table.',
     'praxis.pageBuilder.agentic.suggestionPrompts.payrollDepartmentDrilldown': 'Create a payroll dashboard with a department chart that filters a detail table when a bar is selected.',
@@ -2358,6 +2359,12 @@ const PRAXIS_PAGE_BUILDER_EN_US = {
     'praxis.pageBuilder.agentic.exploratory.capability.table': 'tables',
     'praxis.pageBuilder.agentic.exploratory.capability.form': 'forms',
     'praxis.pageBuilder.agentic.exploratory.capability.masterDetail': 'master-detail pages',
+    'praxis.pageBuilder.agentic.resourceDiscovery.found': 'I found APIs that can feed this screen. Choose one before generating the preview.',
+    'praxis.pageBuilder.agentic.resourceDiscovery.empty': 'I did not find a matching API yet. Describe the business data this screen should use.',
+    'praxis.pageBuilder.agentic.resourceDiscovery.useResource': 'Use {resourcePath}',
+    'praxis.pageBuilder.agentic.diagnostics.title': 'LLM diagnostics',
+    'praxis.pageBuilder.agentic.diagnostics.badge': 'Debug',
+    'praxis.pageBuilder.agentic.diagnostics.description': 'Prompt, context bundle, and tool catalog returned by the backend for this turn.',
     'praxis.pageBuilder.agentic.dragHandleAria': 'Move AI assistant',
     'praxis.pageBuilder.agentic.resizeHandleAria': 'Resize AI assistant',
     'praxis.pageBuilder.agentic.resizeHandleTooltip': 'Resize',
@@ -2366,7 +2373,12 @@ const PRAXIS_PAGE_BUILDER_EN_US = {
     'praxis.pageBuilder.agentic.status.resolvingIntent': 'Resolving intent...',
     'praxis.pageBuilder.agentic.status.waitingRevision': 'Refine your prompt and preview again.',
     'praxis.pageBuilder.agentic.status.cancelled': 'Request cancelled.',
+    'praxis.pageBuilder.agentic.status.contextBundle': 'Preparing context...',
+    'praxis.pageBuilder.agentic.status.resourceDiscovery': 'Finding API resources...',
+    'praxis.pageBuilder.agentic.status.resourceDiscoveryBackend': 'Found API resources in the backend catalog.',
+    'praxis.pageBuilder.agentic.status.refinedCandidates': 'Reviewing the retrieved resources with the AI...',
     'praxis.pageBuilder.agentic.status.previewing': 'Generating preview...',
+    'praxis.pageBuilder.agentic.status.previewCompile': 'Compiling preview...',
     'praxis.pageBuilder.agentic.status.previewReady': 'Preview applied to the page.',
     'praxis.pageBuilder.agentic.status.acceptedAddLocalField': 'Local field added to the form.',
     'praxis.pageBuilder.agentic.status.acceptedRemoveLocalField': 'Local field removed from the form.',
@@ -2377,8 +2389,12 @@ const PRAXIS_PAGE_BUILDER_EN_US = {
     'praxis.pageBuilder.agentic.errors.componentId': 'Configure a component id before saving.',
     'praxis.pageBuilder.agentic.errors.invalidPreview': 'Generated preview is invalid.',
     'praxis.pageBuilder.agentic.errors.intentResolution': 'Intent could not be resolved.',
+    'praxis.pageBuilder.agentic.errors.streamTimeout': 'The assistant took too long to finish this request. Try again with a narrower request or review the active context.',
+    'praxis.pageBuilder.agentic.errors.streamProcessing': 'The assistant could not finish this authoring request. Try again or ask support to review the diagnostics.',
+    'praxis.pageBuilder.agentic.errors.streamConnection': 'The assistant stream was interrupted before the turn finished. Try again or ask support to check the stream connection.',
     'praxis.pageBuilder.agentic.errors.duplicateField': 'This field already exists in the selected form.',
     'praxis.pageBuilder.agentic.errors.nonLocalFieldRemoval': 'Only local fields created by AI can be removed in this flow.',
+    'praxis.pageBuilder.agentic.errors.invalidTableContract': 'I found the data source, but the generated plan used properties that are incompatible with the table component. I will adjust it to use only supported fields.',
     'praxis.pageBuilder.agentic.errors.generic': 'AI authoring failed.',
 };
 
@@ -2586,6 +2602,7 @@ const PRAXIS_PAGE_BUILDER_PT_BR = {
     'praxis.pageBuilder.agentic.quickReplies.formSuggestion': 'Formulário',
     'praxis.pageBuilder.agentic.quickReplies.masterDetailSuggestion': 'Master detail',
     'praxis.pageBuilder.agentic.quickReplies.confirmPromptSuffix': 'Confirmado:',
+    'praxis.pageBuilder.agentic.quickReplies.resourceSelectionPrompt': 'Usar {label} ({resourcePath}) como fonte de dados.',
     'praxis.pageBuilder.agentic.attachments.currentPage': 'Página atual',
     'praxis.pageBuilder.agentic.suggestionPrompts.payrollExecutiveDashboard': 'Crie um dashboard de folha de pagamento com KPIs, folha por departamento, evolução mensal e tabela de detalhes.',
     'praxis.pageBuilder.agentic.suggestionPrompts.payrollDepartmentDrilldown': 'Crie um dashboard de folha de pagamento com gráfico por departamento que filtre uma tabela detalhada ao selecionar uma barra.',
@@ -2599,6 +2616,12 @@ const PRAXIS_PAGE_BUILDER_PT_BR = {
     'praxis.pageBuilder.agentic.exploratory.capability.table': 'tabelas',
     'praxis.pageBuilder.agentic.exploratory.capability.form': 'formulários',
     'praxis.pageBuilder.agentic.exploratory.capability.masterDetail': 'páginas master-detail',
+    'praxis.pageBuilder.agentic.resourceDiscovery.found': 'Encontrei APIs que podem alimentar esta tela. Escolha uma antes de gerar a pré-visualização.',
+    'praxis.pageBuilder.agentic.resourceDiscovery.empty': 'Ainda não encontrei uma API correspondente. Descreva quais dados de negócio esta tela deve usar.',
+    'praxis.pageBuilder.agentic.resourceDiscovery.useResource': 'Usar {resourcePath}',
+    'praxis.pageBuilder.agentic.diagnostics.title': 'Diagnóstico do LLM',
+    'praxis.pageBuilder.agentic.diagnostics.badge': 'Debug',
+    'praxis.pageBuilder.agentic.diagnostics.description': 'Prompt, pacote de contexto e catálogo de ferramentas retornados pelo backend para este turno.',
     'praxis.pageBuilder.agentic.dragHandleAria': 'Mover assistente de IA',
     'praxis.pageBuilder.agentic.resizeHandleAria': 'Redimensionar assistente de IA',
     'praxis.pageBuilder.agentic.resizeHandleTooltip': 'Redimensionar',
@@ -2607,7 +2630,12 @@ const PRAXIS_PAGE_BUILDER_PT_BR = {
     'praxis.pageBuilder.agentic.status.resolvingIntent': 'Resolvendo intenção...',
     'praxis.pageBuilder.agentic.status.waitingRevision': 'Ajuste o prompt e pré-visualize novamente.',
     'praxis.pageBuilder.agentic.status.cancelled': 'Solicitação cancelada.',
+    'praxis.pageBuilder.agentic.status.contextBundle': 'Preparando contexto...',
+    'praxis.pageBuilder.agentic.status.resourceDiscovery': 'Buscando recursos de API...',
+    'praxis.pageBuilder.agentic.status.resourceDiscoveryBackend': 'Encontrei recursos de API no catálogo do backend.',
+    'praxis.pageBuilder.agentic.status.refinedCandidates': 'Estou revisando os recursos encontrados com a IA...',
     'praxis.pageBuilder.agentic.status.previewing': 'Gerando pré-visualização...',
+    'praxis.pageBuilder.agentic.status.previewCompile': 'Compilando pré-visualização...',
     'praxis.pageBuilder.agentic.status.previewReady': 'Pré-visualização aplicada à página.',
     'praxis.pageBuilder.agentic.status.acceptedAddLocalField': 'Campo local adicionado ao formulário.',
     'praxis.pageBuilder.agentic.status.acceptedRemoveLocalField': 'Campo local removido do formulário.',
@@ -2618,8 +2646,12 @@ const PRAXIS_PAGE_BUILDER_PT_BR = {
     'praxis.pageBuilder.agentic.errors.componentId': 'Configure um id de componente antes de salvar.',
     'praxis.pageBuilder.agentic.errors.invalidPreview': 'A pré-visualização gerada é inválida.',
     'praxis.pageBuilder.agentic.errors.intentResolution': 'A intenção não pôde ser resolvida.',
+    'praxis.pageBuilder.agentic.errors.streamTimeout': 'Ainda não consegui concluir este pedido. Tente novamente com um pedido mais específico ou revise o contexto ativo.',
+    'praxis.pageBuilder.agentic.errors.streamProcessing': 'Não consegui concluir este pedido de autoria. Tente novamente ou peça ao suporte para revisar o diagnóstico.',
+    'praxis.pageBuilder.agentic.errors.streamConnection': 'O stream do assistente foi interrompido antes de concluir o turno. Tente novamente ou acione o suporte para verificar a conexão do stream.',
     'praxis.pageBuilder.agentic.errors.duplicateField': 'Este campo já existe no formulário selecionado.',
     'praxis.pageBuilder.agentic.errors.nonLocalFieldRemoval': 'Somente campos locais criados pela IA podem ser removidos neste fluxo.',
+    'praxis.pageBuilder.agentic.errors.invalidTableContract': 'Encontrei a fonte de dados, mas o plano gerado usou propriedades incompatíveis com o componente de tabela. Vou ajustar para usar apenas os campos suportados.',
     'praxis.pageBuilder.agentic.errors.generic': 'Falha na autoria com IA.',
 };
 
@@ -4778,6 +4810,9 @@ const PAGE_BUILDER_AI_CAPABILITIES = {
         'Taxonomia editorial: condition usa Json Logic canonico; transform usa pipeline declarativo; policy cobre apenas comportamento operacional.',
         'Para criacao agentic de paginas, o preview pode trazer uiCompositionPlan como plano intermediario validavel; o page-builder compila esse plano para WidgetPageDefinition antes de aplicar.',
         'UiCompositionPlan usa widgets[].componentId e bindings declarativos. O JSON persistido continua sendo page.widgets[].definition.id e page.composition.links.',
+        'Nested component ports usam endpoint component-port com nestedPath. O owner em ref.widget, bindings[].from.widget ou bindings[].to.widget continua sendo o widget top-level; a porta real do filho fica em port/direction e o caminho ate o filho fica em nestedPath.',
+        'Nested component ports usam endpoint component-port com nestedPath. O owner em ref.widget ou bindings[].*.widget continua sendo o widget top-level; a porta real do filho fica em port/direction e o caminho ate o filho fica em nestedPath.',
+        'Nao gere links nested via owner.widgetEvent, bindingPath profundo, page.connections ou wrappers host-specific. widgetEvent e bridge legada/avancada, nao contrato principal de authoring.',
         'Payloads legados de layout ainda podem ser ingeridos, mas sao normalizados para canvas e nao devem ser reemitidos.',
         'pageIdentity identifica o escopo de persistencia e nao pertence ao objeto page.',
     ],
@@ -4796,6 +4831,18 @@ const PAGE_BUILDER_AI_CAPABILITIES = {
         { path: 'uiCompositionPlan.bindings[].id', category: 'connections', valueKind: 'string', description: 'Identificador estavel do binding planejado.' },
         { path: 'uiCompositionPlan.bindings[].from', category: 'connections', valueKind: 'object', description: 'Endpoint de origem: component-port ou state.' },
         { path: 'uiCompositionPlan.bindings[].to', category: 'connections', valueKind: 'object', description: 'Endpoint de destino: component-port ou state.' },
+        { path: 'uiCompositionPlan.bindings[].from.nestedPath', category: 'connections', valueKind: 'array', description: 'Caminho estruturado para porta nested de origem. Use apenas com endpoint component-port; o owner top-level continua em from.widget.' },
+        { path: 'uiCompositionPlan.bindings[].to.nestedPath', category: 'connections', valueKind: 'array', description: 'Caminho estruturado para porta nested de destino. Use apenas com endpoint component-port; o owner top-level continua em to.widget.' },
+        { path: 'uiCompositionPlan.bindings[].from.nestedPath[].kind', category: 'connections', valueKind: 'string', description: 'Tipo do segmento nested de origem, como tab, nav, link, expansion, panel ou widget. O ultimo segmento deve ser widget.' },
+        { path: 'uiCompositionPlan.bindings[].from.nestedPath[].id', category: 'connections', valueKind: 'string', description: 'Identificador estrutural estavel do container de origem no segmento nested, quando existir.' },
+        { path: 'uiCompositionPlan.bindings[].from.nestedPath[].key', category: 'connections', valueKind: 'string', description: 'Chave estavel do widget filho no segmento terminal widget de origem. Obrigatoria para endpoint nested persistido.', critical: true },
+        { path: 'uiCompositionPlan.bindings[].from.nestedPath[].index', category: 'connections', valueKind: 'number', description: 'Indice auxiliar de origem para contexto visual/diagnostico; nao use como identidade primaria persistida.' },
+        { path: 'uiCompositionPlan.bindings[].from.nestedPath[].componentType', category: 'connections', valueKind: 'string', description: 'Tipo do componente real do widget filho de origem, usado como verificacao auxiliar, nao como identidade primaria.' },
+        { path: 'uiCompositionPlan.bindings[].to.nestedPath[].kind', category: 'connections', valueKind: 'string', description: 'Tipo do segmento nested de destino, como tab, nav, link, expansion, panel ou widget. O ultimo segmento deve ser widget.' },
+        { path: 'uiCompositionPlan.bindings[].to.nestedPath[].id', category: 'connections', valueKind: 'string', description: 'Identificador estrutural estavel do container de destino no segmento nested, quando existir.' },
+        { path: 'uiCompositionPlan.bindings[].to.nestedPath[].key', category: 'connections', valueKind: 'string', description: 'Chave estavel do widget filho no segmento terminal widget de destino. Obrigatoria para endpoint nested persistido.', critical: true },
+        { path: 'uiCompositionPlan.bindings[].to.nestedPath[].index', category: 'connections', valueKind: 'number', description: 'Indice auxiliar de destino para contexto visual/diagnostico; nao use como identidade primaria persistida.' },
+        { path: 'uiCompositionPlan.bindings[].to.nestedPath[].componentType', category: 'connections', valueKind: 'string', description: 'Tipo do componente real do widget filho de destino, usado como verificacao auxiliar, nao como identidade primaria.' },
         { path: 'uiCompositionPlan.bindings[].intent', category: 'connections', valueKind: 'string', description: 'Intencao semantica do binding.' },
         { path: 'uiCompositionPlan.bindings[].condition', category: 'connections', valueKind: 'expression', description: 'Guarda opcional em Json Logic.' },
         { path: 'uiCompositionPlan.bindings[].transform', category: 'connections', valueKind: 'object', description: 'Transform declarativo: pick-path, query-context, template ou constant.' },
@@ -4847,6 +4894,10 @@ const PAGE_BUILDER_AI_CAPABILITIES = {
         { path: 'page.composition.links[].id', category: 'connections', valueKind: 'string', description: 'Identificador estavel do link.' },
         { path: 'page.composition.links[].from', category: 'connections', valueKind: 'object', description: 'Endpoint de origem do link.' },
         { path: 'page.composition.links[].to', category: 'connections', valueKind: 'object', description: 'Endpoint de destino do link.' },
+        { path: 'page.composition.links[].from.ref.nestedPath', category: 'connections', valueKind: 'array', description: 'NestedPath canonico em endpoint component-port de origem persistido. Omita para top-level; nao serialize nestedPath: [].' },
+        { path: 'page.composition.links[].from.ref.nestedPath[].key', category: 'connections', valueKind: 'string', description: 'Chave estavel do widget filho no segmento terminal widget de origem. Obrigatoria para endpoint nested persistido.', critical: true },
+        { path: 'page.composition.links[].to.ref.nestedPath', category: 'connections', valueKind: 'array', description: 'NestedPath canonico em endpoint component-port de destino persistido. Omita para top-level; nao serialize nestedPath: [].' },
+        { path: 'page.composition.links[].to.ref.nestedPath[].key', category: 'connections', valueKind: 'string', description: 'Chave estavel do widget filho no segmento terminal widget de destino. Obrigatoria para endpoint nested persistido.', critical: true },
         { path: 'page.composition.links[].intent', category: 'connections', valueKind: 'string', description: 'Intencao semantica do link.' },
         { path: 'page.composition.links[].transform', category: 'connections', valueKind: 'object', description: 'Pipeline de transformacao do link.' },
         { path: 'page.composition.links[].condition', category: 'connections', valueKind: 'expression', description: 'Guarda semantica opcional do link, expressa como um unico AST Json Logic canonico.' },
@@ -5026,6 +5077,12 @@ class PageBuilderAgenticAuthoringService {
     resolveIntent(request) {
         return this.http.post(`${this.baseUrl}/intent-resolution`, request, { headers: this.buildHeaders() });
     }
+    searchResourceCandidates(request) {
+        return this.http.post(`${this.baseUrl}/resource-candidates`, request, { headers: this.buildHeaders() });
+    }
+    streamTurn(request) {
+        return this.http.post(`${this.baseUrl}/turn/stream/start`, request, { headers: this.buildHeaders() }).pipe(switchMap((start) => this.connectTurnStream(start)));
+    }
     applyPage(request) {
         const { ifMatch, ...body } = request;
         return this.http.post(`${this.baseUrl}/page-apply`, {
@@ -5055,6 +5112,97 @@ class PageBuilderAgenticAuthoringService {
         }
         return new HttpHeaders(merged);
     }
+    connectTurnStream(start) {
+        return new Observable((observer) => {
+            const url = this.buildStreamUrl(start);
+            let source;
+            let closed = false;
+            let connectionErrorTimer = null;
+            const connectionErrorGraceMs = Math.max(0, this.options?.streamConnectionErrorGraceMs ?? 1500);
+            try {
+                source = this.createEventSource(url);
+            }
+            catch (error) {
+                observer.error(this.streamConnectionError(error));
+                return undefined;
+            }
+            const clearConnectionErrorTimer = () => {
+                if (connectionErrorTimer) {
+                    clearTimeout(connectionErrorTimer);
+                    connectionErrorTimer = null;
+                }
+            };
+            const closeSource = () => {
+                if (closed) {
+                    return;
+                }
+                closed = true;
+                clearConnectionErrorTimer();
+                source.close();
+            };
+            const failConnection = (event) => {
+                if (closed) {
+                    return;
+                }
+                observer.error(this.streamConnectionError(event));
+                closeSource();
+            };
+            const handleMessage = (event) => {
+                try {
+                    clearConnectionErrorTimer();
+                    const parsed = JSON.parse(event.data);
+                    observer.next(parsed);
+                    if (parsed.type === 'result' || parsed.type === 'error' || parsed.type === 'cancelled') {
+                        observer.complete();
+                        closeSource();
+                    }
+                }
+                catch (error) {
+                    observer.error(this.streamConnectionError(error));
+                    closeSource();
+                }
+            };
+            source.onmessage = handleMessage;
+            if (source.addEventListener) {
+                for (const type of AI_STREAM_EVENT_TYPES) {
+                    source.addEventListener(type, handleMessage);
+                }
+            }
+            source.onerror = (event) => {
+                if (closed || connectionErrorTimer) {
+                    return;
+                }
+                if (connectionErrorGraceMs === 0) {
+                    failConnection(event);
+                    return;
+                }
+                connectionErrorTimer = setTimeout(() => failConnection(event), connectionErrorGraceMs);
+            };
+            return () => closeSource();
+        });
+    }
+    streamConnectionError(cause) {
+        return {
+            praxisAgenticTurnStreamConnectionError: true,
+            cause,
+        };
+    }
+    buildStreamUrl(start) {
+        const url = new URL(`${this.baseUrl}/turn/stream/${start.streamId}`, typeof window !== 'undefined' ? window.location.origin : 'http://localhost');
+        if (start.streamAccessToken) {
+            url.searchParams.set('accessToken', start.streamAccessToken);
+        }
+        return /^https?:\/\//i.test(this.baseUrl)
+            ? url.toString()
+            : url.pathname + url.search;
+    }
+    createEventSource(url) {
+        const factory = this.options?.eventSourceFactory;
+        if (factory) {
+            return factory(url);
+        }
+        return new EventSource(url);
+    }
     formatEtag(etag) {
         const trimmed = etag.trim();
         return trimmed.startsWith('"') ? trimmed : `"${trimmed}"`;
@@ -5067,6 +5215,522 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
             args: [{ providedIn: 'root' }]
         }] });
 
+const pageSchema = {
+    type: 'object',
+    properties: {
+        title: { type: 'string' },
+        layoutPreset: { type: 'string' },
+        context: { type: 'object' },
+        metadata: { type: 'object' },
+    },
+};
+const canvasSchema = {
+    type: 'object',
+    properties: {
+        columns: { type: 'number' },
+        rowUnit: { type: 'number' },
+        gap: { type: 'number' },
+        items: { type: 'array' },
+    },
+};
+const widgetSchema = {
+    type: 'object',
+    required: ['widgetKey', 'componentId'],
+    properties: {
+        widgetKey: { type: 'string' },
+        componentId: { type: 'string' },
+        title: { type: 'string' },
+        inputs: { type: 'object' },
+        canvasItem: { type: 'object' },
+    },
+};
+const compositionLinkSchema = {
+    type: 'object',
+    required: ['linkId', 'from', 'to'],
+    properties: {
+        linkId: { type: 'string' },
+        from: { type: 'object' },
+        to: { type: 'object' },
+        condition: { type: 'object' },
+        policy: { type: 'object' },
+    },
+};
+const childOperationSchema = {
+    type: 'object',
+    required: ['widgetKey', 'childComponentId', 'childOperationId', 'reason'],
+    properties: {
+        widgetKey: { type: 'string' },
+        childComponentId: { type: 'string' },
+        childOperationId: { type: 'string' },
+        reason: { type: 'string' },
+        childTarget: { type: 'object' },
+        childParams: { type: 'object' },
+    },
+};
+const PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST = {
+    schemaVersion: '1.0.0',
+    componentId: 'praxis-page-builder',
+    ownerPackage: '@praxisui/page-builder',
+    configSchemaId: 'WidgetPageDefinition',
+    manifestVersion: '1.0.0',
+    runtimeInputs: [
+        { name: 'page', type: 'WidgetPageDefinition', description: 'Canonical renderable page document consumed by praxis-dynamic-page.' },
+        { name: 'pageIdentity', type: 'PageIdentity | null', description: 'Persistence identity for ui_user_config save/apply flows; not persisted inside page.' },
+        { name: 'enableCustomization', type: 'boolean', description: 'Enables page-builder authoring chrome around the runtime page.' },
+        { name: 'context', type: 'Record<string, unknown>', description: 'Opaque host context passed to catalog resolution and agentic authoring.' },
+        { name: 'pageChange', type: 'WidgetPageDefinition', description: 'Emitted after local apply/preview produces a renderable page.' },
+        { name: 'agenticAuthoringEnableStreaming', type: 'boolean', description: 'Opt-in flag for the canonical streaming turn endpoints.' },
+    ],
+    editableTargets: [
+        { kind: 'page', resolver: 'widget-page-definition-root', description: 'Root WidgetPageDefinition document: title, metadata, context and renderable page envelope.' },
+        { kind: 'canvas', resolver: 'widget-page-canvas', description: 'Canvas geometry and item placement for top-level widgets.' },
+        { kind: 'widget', resolver: 'widget-by-stable-key', description: 'Widget definitions addressed by stable widgetKey, never by array index.' },
+        { kind: 'widgetShell', resolver: 'widget-shell-by-widget-key', description: 'Dashboard-card shell metadata such as title, action chrome and visual preset.' },
+        { kind: 'compositionLink', resolver: 'composition-link-by-id', description: 'Declarative wiring in page.composition.links, including component-port nestedPath endpoints.' },
+        { kind: 'state', resolver: 'page-state-path', description: 'Page-level state entries referenced by composition links.' },
+        { kind: 'pageIdentity', resolver: 'page-builder-persistence-identity', description: 'ui_user_config identity, scope and ETag used by applyPage/save.' },
+        { kind: 'agenticPreview', resolver: 'agentic-preview-result', description: 'Compiled backend preview envelope whose patch.page is applied locally.' },
+        { kind: 'childOperation', resolver: 'widget-child-authoring-manifest-operation', description: 'Delegated operation owned by the child widget component manifest or configEditor.' },
+    ],
+    operations: [
+        {
+            operationId: 'page.configure',
+            title: 'Configure page metadata',
+            scope: 'global',
+            targetKind: 'page',
+            target: { kind: 'page', resolver: 'widget-page-definition-root', ambiguityPolicy: 'fail', required: false },
+            inputSchema: pageSchema,
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-page-configure', handlerContract: {
+                        reads: ['WidgetPageDefinition', 'DynamicPageConfigEditorComponent', 'SettingsPanelBridge'],
+                        writes: ['page.title', 'page.layoutPreset', 'page.context', 'page.metadata'],
+                        identityKeys: ['pageIdentity.componentId', 'pageIdentity.scope'],
+                        inputSchema: pageSchema,
+                        failureModes: ['page-not-loaded', 'context-not-json', 'settings-panel-bridge-missing'],
+                        description: 'Updates root page metadata while preserving the renderable WidgetPageDefinition shape.',
+                    } }],
+            validators: ['widget-page-definition-valid', 'no-legacy-grid-page-definition', 'page-context-json-valid', 'settings-panel-round-trip-valid'],
+            affectedPaths: ['title', 'layoutPreset', 'context', 'metadata'],
+            submissionImpact: false,
+            preconditions: ['page-loaded'],
+        },
+        {
+            operationId: 'canvas.configure',
+            title: 'Configure page canvas',
+            scope: 'layout',
+            targetKind: 'canvas',
+            target: { kind: 'canvas', resolver: 'widget-page-canvas', ambiguityPolicy: 'fail', required: true },
+            inputSchema: canvasSchema,
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-canvas-configure', handlerContract: {
+                        reads: ['WidgetPageDefinition.canvas', 'DynamicPageBuilderComponent'],
+                        writes: ['page.canvas.columns', 'page.canvas.rowUnit', 'page.canvas.gap', 'page.canvas.items'],
+                        identityKeys: ['canvas'],
+                        inputSchema: canvasSchema,
+                        failureModes: ['canvas-missing', 'canvas-item-references-missing-widget', 'invalid-grid-geometry'],
+                        description: 'Configures the top-level canvas without introducing legacy GridPageDefinition semantics.',
+                    } }],
+            validators: ['canvas-columns-integer', 'canvas-row-unit-valid', 'canvas-gap-valid', 'canvas-items-reference-existing-widgets'],
+            affectedPaths: ['canvas.columns', 'canvas.rowUnit', 'canvas.gap', 'canvas.items'],
+            submissionImpact: false,
+            preconditions: ['page-loaded'],
+        },
+        {
+            operationId: 'widget.add',
+            title: 'Add widget to page',
+            scope: 'layout',
+            targetKind: 'widget',
+            target: { kind: 'widget', resolver: 'widget-by-stable-key', ambiguityPolicy: 'fail', required: true },
+            inputSchema: widgetSchema,
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-widget-add', handlerContract: {
+                        reads: ['WidgetPageDefinition.widgets', 'WidgetPageDefinition.canvas', 'ComponentDocRegistry', 'PAGE_BUILDER_WIDGET_AI_CATALOGS'],
+                        writes: ['page.widgets[]', 'page.canvas.items[]'],
+                        identityKeys: ['widgetKey'],
+                        inputSchema: widgetSchema,
+                        failureModes: ['widget-key-duplicate', 'component-not-registered', 'canvas-item-invalid', 'child-input-contract-unknown'],
+                        description: 'Adds a registered component as a widget and places it on the canvas using a stable widgetKey.',
+                    } }],
+            validators: ['widget-key-unique', 'component-registered', 'canvas-item-valid', 'child-inputs-delegated', 'widget-key-not-array-index'],
+            affectedPaths: ['widgets[]', 'canvas.items[]'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'component-catalog-loaded'],
+        },
+        {
+            operationId: 'widget.remove',
+            title: 'Remove widget from page',
+            scope: 'layout',
+            targetKind: 'widget',
+            target: { kind: 'widget', resolver: 'widget-by-stable-key', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['widgetKey'], properties: { widgetKey: { type: 'string' }, confirmed: { type: 'boolean' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-widget-remove', handlerContract: {
+                        reads: ['WidgetPageDefinition.widgets', 'WidgetPageDefinition.canvas.items', 'WidgetPageDefinition.composition.links'],
+                        writes: ['page.widgets[]', 'page.canvas.items[]', 'page.composition.links[]'],
+                        identityKeys: ['widgetKey'],
+                        failureModes: ['widget-not-found', 'destructive-removal-not-confirmed', 'dangling-composition-link'],
+                        description: 'Removes a widget and cleans canvas items and composition links that reference it.',
+                    } }],
+            destructive: true,
+            requiresConfirmation: true,
+            validators: ['widget-exists', 'destructive-removal-confirmed', 'composition-links-cleaned', 'canvas-items-reference-existing-widgets'],
+            affectedPaths: ['widgets[]', 'canvas.items[]', 'composition.links[]'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'target-widget-exists'],
+        },
+        {
+            operationId: 'widget.moveResize',
+            title: 'Move or resize widget',
+            scope: 'layout',
+            targetKind: 'widget',
+            target: { kind: 'widget', resolver: 'widget-by-stable-key', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['widgetKey', 'canvasItem'], properties: { widgetKey: { type: 'string' }, canvasItem: { type: 'object' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-widget-move-resize', handlerContract: {
+                        reads: ['WidgetPageDefinition.canvas.items', 'WidgetPageDefinition.widgets'],
+                        writes: ['page.canvas.items[]'],
+                        identityKeys: ['widgetKey'],
+                        failureModes: ['widget-not-found', 'canvas-item-invalid', 'canvas-overlap-invalid'],
+                        description: 'Updates canvas placement for an existing widget using widgetKey as the stable identity.',
+                    } }],
+            validators: ['widget-exists', 'canvas-item-valid', 'canvas-item-targets-existing-widget', 'canvas-overlap-policy-valid'],
+            affectedPaths: ['canvas.items[]'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'target-widget-exists'],
+        },
+        {
+            operationId: 'widget.shell.configure',
+            title: 'Configure widget shell',
+            scope: 'templating',
+            targetKind: 'widgetShell',
+            target: { kind: 'widgetShell', resolver: 'widget-shell-by-widget-key', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['widgetKey'], properties: { widgetKey: { type: 'string' }, shell: { type: 'object' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-widget-shell-configure', handlerContract: {
+                        reads: ['WidgetPageDefinition.widgets', 'WidgetShellEditorComponent', 'SettingsPanelBridge'],
+                        writes: ['page.widgets[].shell'],
+                        identityKeys: ['widgetKey'],
+                        failureModes: ['widget-not-found', 'settings-panel-bridge-missing', 'shell-config-invalid'],
+                        description: 'Updates the page-builder-owned widget shell without editing child component inputs.',
+                    } }],
+            validators: ['widget-exists', 'widget-shell-shape-valid', 'settings-panel-bridge-available', 'child-inputs-not-mutated'],
+            affectedPaths: ['widgets[].shell'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'target-widget-exists'],
+        },
+        {
+            operationId: 'composition.link.add',
+            title: 'Add page composition link',
+            scope: 'dataBinding',
+            targetKind: 'compositionLink',
+            target: { kind: 'compositionLink', resolver: 'composition-link-by-id', ambiguityPolicy: 'fail', required: true },
+            inputSchema: compositionLinkSchema,
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-composition-link-add', handlerContract: {
+                        reads: ['WidgetPageDefinition.composition.links', 'WidgetPageDefinition.widgets', 'PAGE_BUILDER_AI_CAPABILITIES'],
+                        writes: ['page.composition.links[]'],
+                        identityKeys: ['linkId'],
+                        inputSchema: compositionLinkSchema,
+                        failureModes: ['link-id-duplicate', 'endpoint-not-found', 'nested-path-invalid', 'json-logic-invalid'],
+                        description: 'Adds canonical declarative wiring in page.composition.links, including component-port nestedPath endpoints.',
+                    } }],
+            validators: ['composition-link-id-unique', 'composition-endpoints-resolve', 'nested-path-terminal-widget-key-required', 'json-logic-condition-valid', 'no-legacy-connections-write'],
+            affectedPaths: ['composition.links[]'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'widgets-resolvable'],
+        },
+        {
+            operationId: 'composition.link.remove',
+            title: 'Remove page composition link',
+            scope: 'dataBinding',
+            targetKind: 'compositionLink',
+            target: { kind: 'compositionLink', resolver: 'composition-link-by-id', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['linkId'], properties: { linkId: { type: 'string' }, confirmed: { type: 'boolean' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-composition-link-remove', handlerContract: {
+                        reads: ['WidgetPageDefinition.composition.links'],
+                        writes: ['page.composition.links[]'],
+                        identityKeys: ['linkId'],
+                        failureModes: ['composition-link-not-found', 'destructive-removal-not-confirmed'],
+                        description: 'Removes a canonical composition link by stable linkId.',
+                    } }],
+            destructive: true,
+            requiresConfirmation: true,
+            validators: ['composition-link-exists', 'destructive-removal-confirmed', 'composition-links-still-valid'],
+            affectedPaths: ['composition.links[]'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'target-link-exists'],
+        },
+        {
+            operationId: 'composition.plan.compile',
+            title: 'Compile UI composition plan',
+            scope: 'rules',
+            targetKind: 'agenticPreview',
+            target: { kind: 'agenticPreview', resolver: 'agentic-preview-result', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['uiCompositionPlan'], properties: { uiCompositionPlan: { type: 'object' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-ui-composition-plan-compile', handlerContract: {
+                        reads: ['UiCompositionPlan', 'compileUiCompositionPlan', 'PAGE_BUILDER_WIDGET_AI_CATALOGS', 'ComponentDocMeta.configEditor'],
+                        writes: ['compiledFormPatch.patch.page'],
+                        identityKeys: ['uiCompositionPlan.id', 'widgetKey', 'linkId'],
+                        failureModes: ['ui-composition-plan-invalid', 'widget-catalog-missing', 'compiled-page-invalid', 'child-config-editor-missing'],
+                        description: 'Compiles the agentic intermediate UiCompositionPlan into a renderable WidgetPageDefinition patch.page.',
+                    } }],
+            validators: ['ui-composition-plan-valid', 'compiled-page-valid', 'widget-keys-unique', 'composition-endpoints-resolve', 'canvas-items-reference-existing-widgets'],
+            affectedPaths: ['uiCompositionPlan', 'compiledFormPatch.patch.page'],
+            submissionImpact: false,
+            preconditions: ['agentic-preview-loaded', 'component-catalog-loaded'],
+        },
+        {
+            operationId: 'state.set',
+            title: 'Set page state value',
+            scope: 'dataBinding',
+            targetKind: 'state',
+            target: { kind: 'state', resolver: 'page-state-path', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['path', 'value'], properties: { path: { type: 'string' }, value: {}, layer: { enum: ['page', 'session'] } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-state-set', handlerContract: {
+                        reads: ['WidgetPageDefinition.state', 'WidgetPageDefinition.composition.links'],
+                        writes: ['page.state'],
+                        identityKeys: ['path'],
+                        failureModes: ['state-path-invalid', 'state-json-invalid', 'composition-state-link-invalid'],
+                        description: 'Sets canonical page state used by composition links without creating host-only binding paths.',
+                    } }],
+            validators: ['state-path-valid', 'state-layer-valid', 'state-json-valid', 'composition-state-links-still-valid'],
+            affectedPaths: ['state'],
+            submissionImpact: false,
+            preconditions: ['page-loaded'],
+        },
+        {
+            operationId: 'page.preview.apply',
+            title: 'Apply agentic preview locally',
+            scope: 'interaction',
+            targetKind: 'agenticPreview',
+            target: { kind: 'agenticPreview', resolver: 'agentic-preview-result', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['previewId'], properties: { previewId: { type: 'string' }, compiledFormPatch: { type: 'object' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-preview-apply', handlerContract: {
+                        reads: ['PageBuilderAiAdapter.applyCompiledFormPatch', 'compiledFormPatch.patch.page', 'PraxisAssistantTurnViewState'],
+                        writes: ['DynamicPageBuilderComponent.page', 'pageChange'],
+                        identityKeys: ['previewId'],
+                        failureModes: ['preview-result-invalid', 'patch-page-missing', 'runtime-page-invalid', 'patch-envelope-persistence-attempted'],
+                        description: 'Applies only compiledFormPatch.patch.page to the local runtime page; the backend envelope remains diagnostic data.',
+                    } }],
+            validators: ['preview-result-valid', 'compiled-page-patch-present', 'no-envelope-runtime-persistence', 'runtime-page-valid'],
+            affectedPaths: ['compiledFormPatch.patch.page', 'page'],
+            submissionImpact: false,
+            preconditions: ['agentic-preview-loaded'],
+        },
+        {
+            operationId: 'page.persist.save',
+            title: 'Persist page through config API',
+            scope: 'interaction',
+            targetKind: 'pageIdentity',
+            target: { kind: 'pageIdentity', resolver: 'page-builder-persistence-identity', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['pageIdentity'], properties: { pageIdentity: { type: 'object' }, page: { type: 'object' }, etag: { type: 'string' } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-page-persist-save', handlerContract: {
+                        reads: ['pageIdentity', 'WidgetPageDefinition', 'PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS', 'ui_user_config ETag'],
+                        writes: ['POST/PUT /api/praxis/config/ui-user-config', 'If-Match'],
+                        identityKeys: ['pageIdentity.componentType', 'pageIdentity.componentId', 'pageIdentity.scope'],
+                        failureModes: ['page-identity-incomplete', 'etag-conflict', 'runtime-page-invalid', 'patch-envelope-persistence-attempted'],
+                        description: 'Persists the renderable WidgetPageDefinition with pageIdentity and ETag delegated to praxis-config-starter.',
+                    } }],
+            validators: ['page-identity-complete', 'etag-policy-valid', 'runtime-page-valid', 'no-envelope-runtime-persistence'],
+            affectedPaths: ['page', 'pageIdentity', 'etag'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'page-identity-known'],
+        },
+        {
+            operationId: 'childOperation.delegate',
+            title: 'Delegate widget child operation',
+            scope: 'global',
+            targetKind: 'childOperation',
+            target: { kind: 'childOperation', resolver: 'widget-child-authoring-manifest-operation', ambiguityPolicy: 'fail', required: false },
+            inputSchema: childOperationSchema,
+            effects: [{ kind: 'compile-domain-patch', handler: 'page-builder-child-operation-delegate', handlerContract: {
+                        reads: ['WidgetPageDefinition.widgets', 'ComponentDocMeta.configEditor', 'child ComponentAuthoringManifest', 'PAGE_BUILDER_WIDGET_AI_CATALOGS'],
+                        writes: ['page.widgets[].definition.inputs'],
+                        identityKeys: ['widgetKey', 'childComponentId', 'childOperationId'],
+                        inputSchema: childOperationSchema,
+                        failureModes: ['widget-not-found', 'child-manifest-missing', 'child-operation-unknown', 'local-child-input-write-attempted'],
+                        description: 'Delegates child widget input edits to the owning manifest or configEditor instead of redefining child semantics in page-builder.',
+                    } }],
+            validators: ['widget-exists', 'child-manifest-available', 'child-operation-known', 'component-config-editor-respected', 'no-local-child-input-write'],
+            affectedPaths: ['widgets[].definition.inputs'],
+            submissionImpact: false,
+            preconditions: ['page-loaded', 'target-widget-exists', 'child-authoring-contract-available'],
+        },
+    ],
+    validators: [
+        { validatorId: 'widget-page-definition-valid', level: 'error', code: 'PAGE_BUILDER_PAGE_VALID', description: 'The document must remain a renderable WidgetPageDefinition.' },
+        { validatorId: 'no-legacy-grid-page-definition', level: 'error', code: 'PAGE_BUILDER_NO_GRID_PAGE', description: 'Legacy GridPageDefinition semantics cannot be reintroduced.' },
+        { validatorId: 'page-context-json-valid', level: 'error', code: 'PAGE_BUILDER_CONTEXT_JSON', description: 'Page context must stay JSON-serializable.' },
+        { validatorId: 'settings-panel-round-trip-valid', level: 'error', code: 'PAGE_BUILDER_SETTINGS_ROUND_TRIP', description: 'Settings panel apply/save/reset/reopen must preserve the same page shape.' },
+        { validatorId: 'canvas-columns-integer', level: 'error', code: 'PAGE_BUILDER_CANVAS_COLUMNS', description: 'Canvas columns must be an integer grid count.' },
+        { validatorId: 'canvas-row-unit-valid', level: 'error', code: 'PAGE_BUILDER_CANVAS_ROW_UNIT', description: 'Canvas row unit must be a positive layout unit.' },
+        { validatorId: 'canvas-gap-valid', level: 'error', code: 'PAGE_BUILDER_CANVAS_GAP', description: 'Canvas gap must be a valid non-negative spacing value.' },
+        { validatorId: 'canvas-items-reference-existing-widgets', level: 'error', code: 'PAGE_BUILDER_CANVAS_WIDGET_REFS', description: 'Every canvas item must reference an existing widgetKey.' },
+        { validatorId: 'widget-key-unique', level: 'error', code: 'PAGE_BUILDER_WIDGET_KEY_UNIQUE', description: 'Widget keys must be unique.' },
+        { validatorId: 'component-registered', level: 'error', code: 'PAGE_BUILDER_COMPONENT_REGISTERED', description: 'Widget component id must exist in the component registry/catalog.' },
+        { validatorId: 'canvas-item-valid', level: 'error', code: 'PAGE_BUILDER_CANVAS_ITEM', description: 'Canvas item geometry must be valid.' },
+        { validatorId: 'child-inputs-delegated', level: 'error', code: 'PAGE_BUILDER_CHILD_INPUTS_DELEGATED', description: 'Child component input edits must delegate to the child owner.' },
+        { validatorId: 'widget-key-not-array-index', level: 'error', code: 'PAGE_BUILDER_WIDGET_KEY_INDEX', description: 'Array index is not a stable widget identity.' },
+        { validatorId: 'widget-exists', level: 'error', code: 'PAGE_BUILDER_WIDGET_EXISTS', description: 'Target widget must exist.' },
+        { validatorId: 'destructive-removal-confirmed', level: 'error', code: 'PAGE_BUILDER_DESTRUCTIVE_CONFIRMED', description: 'Destructive removals require explicit confirmation.' },
+        { validatorId: 'composition-links-cleaned', level: 'error', code: 'PAGE_BUILDER_LINKS_CLEANED', description: 'Removing a widget must remove dangling composition links.' },
+        { validatorId: 'canvas-item-targets-existing-widget', level: 'error', code: 'PAGE_BUILDER_CANVAS_ITEM_TARGET', description: 'Moved canvas item must target an existing widget.' },
+        { validatorId: 'canvas-overlap-policy-valid', level: 'warning', code: 'PAGE_BUILDER_CANVAS_OVERLAP', description: 'Canvas overlap policy must be respected.' },
+        { validatorId: 'widget-shell-shape-valid', level: 'error', code: 'PAGE_BUILDER_SHELL_SHAPE', description: 'Widget shell config must match the shell editor contract.' },
+        { validatorId: 'settings-panel-bridge-available', level: 'error', code: 'PAGE_BUILDER_SETTINGS_BRIDGE', description: 'Settings panel bridge must be available for shell/page editors.' },
+        { validatorId: 'child-inputs-not-mutated', level: 'error', code: 'PAGE_BUILDER_CHILD_INPUTS_NOT_MUTATED', description: 'Shell edits cannot mutate child inputs.' },
+        { validatorId: 'composition-link-id-unique', level: 'error', code: 'PAGE_BUILDER_LINK_ID_UNIQUE', description: 'Composition link ids must be unique.' },
+        { validatorId: 'composition-endpoints-resolve', level: 'error', code: 'PAGE_BUILDER_LINK_ENDPOINTS', description: 'Composition endpoints must resolve to known widgets, ports and nested paths.' },
+        { validatorId: 'nested-path-terminal-widget-key-required', level: 'error', code: 'PAGE_BUILDER_NESTED_PATH_WIDGET_KEY', description: 'Nested component-port paths must terminate at a stable widget key.' },
+        { validatorId: 'json-logic-condition-valid', level: 'error', code: 'PAGE_BUILDER_JSON_LOGIC', description: 'Composition link condition must be valid Json Logic.' },
+        { validatorId: 'no-legacy-connections-write', level: 'error', code: 'PAGE_BUILDER_NO_LEGACY_CONNECTIONS', description: 'Operations must write page.composition.links, not legacy connections.' },
+        { validatorId: 'composition-link-exists', level: 'error', code: 'PAGE_BUILDER_LINK_EXISTS', description: 'Target composition link must exist.' },
+        { validatorId: 'composition-links-still-valid', level: 'error', code: 'PAGE_BUILDER_LINKS_STILL_VALID', description: 'Remaining composition links must still validate after the operation.' },
+        { validatorId: 'ui-composition-plan-valid', level: 'error', code: 'PAGE_BUILDER_UI_PLAN_VALID', description: 'UiCompositionPlan must match the intermediate agentic plan contract.' },
+        { validatorId: 'compiled-page-valid', level: 'error', code: 'PAGE_BUILDER_COMPILED_PAGE_VALID', description: 'Compiled output must be a valid WidgetPageDefinition.' },
+        { validatorId: 'widget-keys-unique', level: 'error', code: 'PAGE_BUILDER_WIDGET_KEYS_UNIQUE', description: 'Compiled plan must produce unique widget keys.' },
+        { validatorId: 'state-path-valid', level: 'error', code: 'PAGE_BUILDER_STATE_PATH', description: 'State paths must be valid page state paths.' },
+        { validatorId: 'state-layer-valid', level: 'error', code: 'PAGE_BUILDER_STATE_LAYER', description: 'State layer must be page or session.' },
+        { validatorId: 'state-json-valid', level: 'error', code: 'PAGE_BUILDER_STATE_JSON', description: 'State values must be JSON-serializable.' },
+        { validatorId: 'composition-state-links-still-valid', level: 'error', code: 'PAGE_BUILDER_STATE_LINKS', description: 'State edits must not break composition links.' },
+        { validatorId: 'preview-result-valid', level: 'error', code: 'PAGE_BUILDER_PREVIEW_VALID', description: 'Agentic preview result must be structurally valid.' },
+        { validatorId: 'compiled-page-patch-present', level: 'error', code: 'PAGE_BUILDER_PATCH_PAGE_PRESENT', description: 'Preview envelope must include compiledFormPatch.patch.page.' },
+        { validatorId: 'no-envelope-runtime-persistence', level: 'error', code: 'PAGE_BUILDER_NO_ENVELOPE_PERSISTENCE', description: 'Runtime persistence cannot save the full preview envelope.' },
+        { validatorId: 'runtime-page-valid', level: 'error', code: 'PAGE_BUILDER_RUNTIME_PAGE_VALID', description: 'Runtime page must remain renderable by praxis-dynamic-page.' },
+        { validatorId: 'page-identity-complete', level: 'error', code: 'PAGE_BUILDER_PAGE_IDENTITY', description: 'Save requires component type, component id and scope identity.' },
+        { validatorId: 'etag-policy-valid', level: 'error', code: 'PAGE_BUILDER_ETAG_POLICY', description: 'Save must respect backend ETag/If-Match policy.' },
+        { validatorId: 'child-manifest-available', level: 'error', code: 'PAGE_BUILDER_CHILD_MANIFEST_AVAILABLE', description: 'Delegated child component must expose an authoring manifest or configEditor.' },
+        { validatorId: 'child-operation-known', level: 'error', code: 'PAGE_BUILDER_CHILD_OPERATION_KNOWN', description: 'Delegated child operation id must be known.' },
+        { validatorId: 'component-config-editor-respected', level: 'error', code: 'PAGE_BUILDER_CONFIG_EDITOR_RESPECTED', description: 'ComponentDocMeta.configEditor must remain the source for child input editing.' },
+        { validatorId: 'no-local-child-input-write', level: 'error', code: 'PAGE_BUILDER_NO_LOCAL_CHILD_INPUT_WRITE', description: 'Page-builder must not define child component input semantics locally.' },
+    ],
+    roundTripRequirements: [
+        'WidgetPageDefinition is the canonical persisted runtime page shape for page-builder.',
+        'UiCompositionPlan is an intermediate agentic plan and must compile before local preview/apply.',
+        'Widget keys and composition link ids are stable identities; array indexes are never canonical identities.',
+        'Persisted wiring uses page.composition.links and must not write legacy connections.',
+        'Nested component ports use component-port refs with nestedPath ending in a stable widget key.',
+        'Child widget definition.inputs edits delegate to the child manifest or ComponentDocMeta.configEditor.',
+        'Agentic preview applies only compiledFormPatch.patch.page to runtime; the full patch envelope is diagnostics/audit data.',
+        'Save uses pageIdentity and ETag policy from praxis-config-starter; pageIdentity is not persisted inside WidgetPageDefinition.',
+        'Settings panel apply/save/reset/reopen must preserve page settings and widget shell config without hidden normalization drift.',
+    ],
+    examples: [
+        {
+            id: 'configure-dashboard-page',
+            request: 'Set this page title to Payroll Overview and store payrollPeriod in the page context.',
+            operationId: 'page.configure',
+            params: { title: 'Payroll Overview', context: { payrollPeriod: 'current' } },
+            isPositive: true,
+        },
+        {
+            id: 'configure-canvas-grid',
+            request: 'Use a 12 column dashboard grid with compact gaps.',
+            operationId: 'canvas.configure',
+            target: 'canvas',
+            params: { columns: 12, rowUnit: 8, gap: 8 },
+            isPositive: true,
+        },
+        {
+            id: 'add-employees-table-widget',
+            request: 'Add an employees table widget to the left half of the first row.',
+            operationId: 'widget.add',
+            target: 'employees-table',
+            params: { widgetKey: 'employees-table', componentId: 'praxis-table', canvasItem: { x: 0, y: 0, w: 6, h: 8 } },
+            isPositive: true,
+        },
+        {
+            id: 'remove-summary-card',
+            request: 'Remove the summary-card widget and its links.',
+            operationId: 'widget.remove',
+            target: 'summary-card',
+            params: { widgetKey: 'summary-card', confirmed: true },
+            isPositive: true,
+        },
+        {
+            id: 'move-payroll-chart',
+            request: 'Move payroll-chart to the right column and make it taller.',
+            operationId: 'widget.moveResize',
+            target: 'payroll-chart',
+            params: { widgetKey: 'payroll-chart', canvasItem: { x: 6, y: 0, w: 6, h: 10 } },
+            isPositive: true,
+        },
+        {
+            id: 'configure-widget-shell',
+            request: 'Rename the employees widget card and enable the refresh shell action.',
+            operationId: 'widget.shell.configure',
+            target: 'employees-table',
+            params: { widgetKey: 'employees-table', shell: { title: 'Employees', actions: [{ id: 'refresh' }] } },
+            isPositive: true,
+        },
+        {
+            id: 'link-department-selection-to-table',
+            request: 'When department-list selection changes, filter employees-table by department id.',
+            operationId: 'composition.link.add',
+            target: 'department-selection-to-employees',
+            params: { linkId: 'department-selection-to-employees', from: { widget: 'department-list', port: 'selection' }, to: { widget: 'employees-table', port: 'filter' } },
+            isPositive: true,
+        },
+        {
+            id: 'remove-obsolete-link',
+            request: 'Remove the old payroll-filter-link composition link.',
+            operationId: 'composition.link.remove',
+            target: 'payroll-filter-link',
+            params: { linkId: 'payroll-filter-link', confirmed: true },
+            isPositive: true,
+        },
+        {
+            id: 'compile-resource-dashboard-plan',
+            request: 'Compile the resource-dashboard plan returned by the assistant into a renderable page preview.',
+            operationId: 'composition.plan.compile',
+            target: 'preview-payroll-dashboard',
+            params: { uiCompositionPlan: { layoutPreset: 'resource-dashboard' } },
+            isPositive: true,
+        },
+        {
+            id: 'set-selected-department-state',
+            request: 'Store selectedDepartmentId in page state for downstream links.',
+            operationId: 'state.set',
+            target: 'state.selectedDepartmentId',
+            params: { path: 'selectedDepartmentId', value: 'sales', layer: 'page' },
+            isPositive: true,
+        },
+        {
+            id: 'apply-agentic-preview',
+            request: 'Apply the current assistant preview to the local page.',
+            operationId: 'page.preview.apply',
+            target: 'preview-current',
+            params: { previewId: 'preview-current' },
+            isPositive: true,
+        },
+        {
+            id: 'persist-page',
+            request: 'Save this page configuration using the current ETag.',
+            operationId: 'page.persist.save',
+            target: 'tenant-dashboard-page',
+            params: { pageIdentity: { componentType: 'page-builder', componentId: 'tenant-dashboard', scope: 'tenant' }, etag: '"v7"' },
+            isPositive: true,
+        },
+        {
+            id: 'delegate-table-column-edit',
+            request: 'Add a salary column to the employees table widget.',
+            operationId: 'childOperation.delegate',
+            target: 'employees-table',
+            params: { widgetKey: 'employees-table', childComponentId: 'praxis-table', childOperationId: 'column.add', reason: 'TableConfig is owned by praxis-table.' },
+            isPositive: true,
+        },
+        {
+            id: 'reject-direct-dynamic-form-field-write',
+            request: 'Directly write a new dynamic-form field into the widget inputs from page-builder.',
+            operationId: 'childOperation.delegate',
+            target: 'employee-form',
+            params: { widgetKey: 'employee-form', childComponentId: 'praxis-dynamic-form', childOperationId: 'field.add', reason: 'Dynamic form fields are delegated.' },
+            isPositive: false,
+        },
+        {
+            id: 'reject-legacy-connections',
+            request: 'Create the widget link under the old connections collection.',
+            operationId: 'composition.link.add',
+            target: 'legacy-connection',
+            params: { linkId: 'legacy-connection', collection: 'connections' },
+            isPositive: false,
+        },
+    ],
+};
+
 function compileUiCompositionPlan(plan) {
     const diagnostics = validateUiCompositionPlan(plan);
     if (diagnostics.length) {
@@ -5080,8 +5744,8 @@ function compileUiCompositionPlan(plan) {
         valid: true,
         page: {
             layoutPreset: plan.layoutPreset,
-            canvas: clone(plan.canvas),
-            state: clone(plan.state),
+            canvas: clone$1(plan.canvas),
+            state: clone$1(plan.state),
             widgets: plan.widgets.map(toWidgetInstance),
             composition: {
                 version: '1.0.0',
@@ -5176,6 +5840,7 @@ function validateEndpoint(endpoint, widgetKeys, diagnostics, path) {
                 path: `${path}.port`,
             });
         }
+        validateNestedPath(endpoint.nestedPath, diagnostics, `${path}.nestedPath`);
         return;
     }
     if (!endpoint.path?.trim()) {
@@ -5186,14 +5851,26 @@ function validateEndpoint(endpoint, widgetKeys, diagnostics, path) {
         });
     }
 }
+function validateNestedPath(nestedPath, diagnostics, path) {
+    if (!nestedPath?.length)
+        return;
+    const terminal = nestedPath[nestedPath.length - 1];
+    if (terminal?.kind !== 'widget' || !terminal.key?.trim()) {
+        diagnostics.push({
+            code: 'endpoint-nested-terminal-widget-key-required',
+            message: 'Nested component endpoint must end with a widget segment with a stable key.',
+            path,
+        });
+    }
+}
 function toWidgetInstance(widget) {
     return {
         key: widget.key,
         definition: {
             id: widget.componentId,
             bindingOrder: widget.bindingOrder,
-            inputs: clone(widget.inputs ?? {}),
-            outputs: clone(widget.outputs ?? {}),
+            inputs: clone$1(widget.inputs ?? {}),
+            outputs: clone$1(widget.outputs ?? {}),
         },
     };
 }
@@ -5204,10 +5881,10 @@ function toCompositionLink(binding) {
         from: toCompositionEndpoint(binding.from),
         to: toCompositionEndpoint(binding.to),
         intent: binding.intent,
-        condition: clone(binding.condition),
+        condition: clone$1(binding.condition),
         transform,
-        policy: clone(binding.policy),
-        metadata: clone(binding.metadata),
+        policy: clone$1(binding.policy),
+        metadata: clone$1(binding.metadata),
     };
 }
 function toCompositionEndpoint(endpoint) {
@@ -5218,6 +5895,7 @@ function toCompositionEndpoint(endpoint) {
                 widget: endpoint.widget,
                 port: endpoint.port,
                 direction: endpoint.direction,
+                ...(endpoint.nestedPath?.length ? { nestedPath: clone$1(endpoint.nestedPath) } : {}),
             },
         };
     }
@@ -5265,7 +5943,7 @@ function toCompositionTransform(transform) {
                     phase: 'link-propagation',
                     input: { source: transform.inputSource ?? 'event' },
                     config: {
-                        template: clone(transform.template),
+                        template: clone$1(transform.template),
                     },
                 },
             ],
@@ -5282,7 +5960,7 @@ function toCompositionTransform(transform) {
                     kind: 'constant',
                     phase: 'link-propagation',
                     config: {
-                        value: clone(transform.value),
+                        value: clone$1(transform.value),
                     },
                 },
             ],
@@ -5305,7 +5983,7 @@ function toCompositionTransform(transform) {
         ],
     };
 }
-function clone(value) {
+function clone$1(value) {
     if (value == null || typeof value !== 'object')
         return value;
     try {
@@ -5387,7 +6065,11 @@ class PageBuilderAiAdapter {
                 error: 'CompiledFormPatch must contain patch.page.',
             };
         }
-        return this.applyPatch({ page }, 'agentic-authoring.compiled-form-patch');
+        const materializedPage = this.clone(page);
+        if (this.shouldPreserveLocalTransientFields(compiledFormPatch)) {
+            this.preserveLocalTransientFields(materializedPage);
+        }
+        return this.applyPatch({ page: materializedPage }, 'agentic-authoring.compiled-form-patch');
     }
     async applyUiCompositionPlan(plan) {
         const compiled = compileUiCompositionPlan(plan);
@@ -5526,6 +6208,76 @@ class PageBuilderAiAdapter {
         }
         return merged;
     }
+    shouldPreserveLocalTransientFields(compiledFormPatch) {
+        const warnings = compiledFormPatch['warnings'];
+        return Array.isArray(warnings) && warnings.includes('server-backed-field-labels-customized-locally');
+    }
+    preserveLocalTransientFields(patchPage) {
+        const basePage = this.normalizePageForAi(this.parsePage(this.host.page));
+        const baseWidgets = basePage?.widgets ?? [];
+        for (const patchWidget of patchPage.widgets ?? []) {
+            if (patchWidget.definition?.id !== 'praxis-dynamic-form')
+                continue;
+            const key = this.getWidgetKey(patchWidget);
+            if (!key)
+                continue;
+            const baseWidget = baseWidgets.find((widget) => this.getWidgetKey(widget) === key);
+            if (!baseWidget)
+                continue;
+            this.preserveLocalTransientFieldsForWidget(baseWidget, patchWidget);
+        }
+    }
+    preserveLocalTransientFieldsForWidget(baseWidget, patchWidget) {
+        const baseConfig = (baseWidget.definition?.inputs?.['config'] ?? {});
+        const patchInputs = patchWidget.definition.inputs ??= {};
+        const patchConfig = (patchInputs['config'] ??= {});
+        const baseFields = Array.isArray(baseConfig['fieldMetadata']) ? baseConfig['fieldMetadata'] : [];
+        const patchFields = Array.isArray(patchConfig['fieldMetadata'])
+            ? patchConfig['fieldMetadata']
+            : (patchConfig['fieldMetadata'] = []);
+        const preservedNames = [];
+        for (const field of baseFields) {
+            if (!this.isLocalTransientField(field) || patchFields.some((entry) => entry?.name === field.name))
+                continue;
+            patchFields.push(this.clone(field));
+            preservedNames.push(field.name);
+        }
+        if (preservedNames.length === 0)
+            return;
+        const baseSections = Array.isArray(baseConfig['sections']) ? baseConfig['sections'] : [];
+        const patchSections = Array.isArray(patchConfig['sections'])
+            ? patchConfig['sections']
+            : (patchConfig['sections'] = []);
+        for (const section of baseSections) {
+            if (!this.sectionContainsAnyField(section, preservedNames))
+                continue;
+            if (this.sectionContainsAnyField({ rows: [{ columns: [{ fields: this.flattenSectionFields(patchSections) }] }] }, preservedNames)) {
+                continue;
+            }
+            patchSections.push(this.clone(section));
+        }
+    }
+    isLocalTransientField(field) {
+        return field?.source === 'local' || field?.transient === true || field?.submitPolicy === 'omit';
+    }
+    sectionContainsAnyField(section, names) {
+        const fields = this.flattenSectionFields([section]);
+        return names.some((name) => fields.includes(name));
+    }
+    flattenSectionFields(sections) {
+        const fields = [];
+        for (const section of sections) {
+            for (const row of section?.rows ?? []) {
+                for (const column of row?.columns ?? []) {
+                    for (const field of column?.fields ?? []) {
+                        if (typeof field === 'string')
+                            fields.push(field);
+                    }
+                }
+            }
+        }
+        return fields;
+    }
     mergeLinks(baseLinks, patchLinks) {
         const base = baseLinks || [];
         const patch = patchLinks || [];
@@ -5646,20 +6398,37 @@ class PageBuilderAiAdapter {
     linkKey(link) {
         if (!link)
             return null;
-        const from = link.from.kind === 'component-port'
-            ? (link.from.ref.widget && link.from.ref.port
-                ? `widget:${link.from.ref.widget}::${link.from.ref.port}::${link.from.ref.direction}`
-                : null)
-            : (link.from.ref.path ? `state:${link.from.ref.path}::${link.from.ref.layer || 'values'}` : null);
-        const to = link.to.kind === 'component-port'
-            ? (link.to.ref.widget && link.to.ref.port
-                ? `widget:${link.to.ref.widget}::${link.to.ref.port}::${link.to.ref.direction}`
-                : null)
-            : (link.to.ref.path ? `state:${link.to.ref.path}::${link.to.ref.layer || 'values'}` : null);
+        const from = this.endpointKey(link.from);
+        const to = this.endpointKey(link.to);
         if (!from || !to)
             return null;
         return `${from}->${to}`;
     }
+    endpointKey(endpoint) {
+        if (endpoint.kind === 'component-port') {
+            if (!endpoint.ref.widget || !endpoint.ref.port)
+                return null;
+            return [
+                'widget',
+                endpoint.ref.widget,
+                endpoint.ref.port,
+                endpoint.ref.direction,
+                this.nestedPathKey(endpoint.ref.nestedPath),
+            ].filter((part) => part !== '').join('::');
+        }
+        return endpoint.ref.path ? `state:${endpoint.ref.path}::${endpoint.ref.layer || 'values'}` : null;
+    }
+    nestedPathKey(nestedPath) {
+        if (!nestedPath?.length)
+            return '';
+        return `nested:${JSON.stringify(nestedPath.map((segment) => ({
+            kind: segment.kind,
+            id: segment.id,
+            key: segment.key,
+            index: segment.index,
+            componentType: segment.componentType,
+        })))}`;
+    }
     pickLayoutOptions(options) {
         if (!options)
             return undefined;
@@ -5717,42 +6486,60 @@ class PageBuilderAgenticAuthoringTurnFlow {
         this.service = service;
         this.context = context;
     }
-    async submit(request) {
+    submit(request) {
         const prompt = request.prompt?.trim();
         if (!prompt) {
-            return {
+            return Promise.resolve({
                 state: 'listening',
                 phase: 'capture',
-            };
+            });
         }
+        if (this.isResourceDiscoveryTool(request)) {
+            return this.handleResourceDiscoveryTool(request, prompt);
+        }
+        if (this.context.enableTurnStream?.() === true && this.service.streamTurn) {
+            return this.submitWithTurnStream(request, prompt);
+        }
+        return this.submitSynchronously(request, prompt);
+    }
+    async submitSynchronously(request, prompt) {
         try {
             const authoringContext = this.buildAuthoringContext(request);
             const componentCapabilities = await this.context.loadComponentCapabilities();
             const selectedWidgetKey = this.context.selectedWidgetKey();
-            const intentResolution = await firstValueFrom(this.service.resolveIntent({
-                userPrompt: prompt,
-                targetApp: this.context.targetApp,
-                targetComponentId: this.context.targetComponentId,
-                currentPage: this.context.currentPage(),
-                selectedWidgetKey,
-                provider: this.context.provider(),
-                model: this.context.model(),
-                apiKey: this.context.apiKey(),
-                componentCapabilities,
-                ...authoringContext,
-            }));
+            const intentResolution = await firstValueFrom(this.service.resolveIntent(this.buildIntentResolutionRequest(prompt, selectedWidgetKey, componentCapabilities, authoringContext)));
             const intentAssistantMessage = this.resolveIntentAssistantMessage(intentResolution);
             if (intentAssistantMessage) {
+                const quickReplies = this.toShellQuickReplies(intentResolution.quickReplies ?? []);
+                const explicitPendingClarification = this.toShellPendingClarification(intentResolution.pendingClarification);
+                const intentClarification = this.resolveIntentClarification(intentResolution);
+                const pendingClarification = explicitPendingClarification
+                    ?? (intentClarification
+                        ? this.buildPendingClarificationForNextTurn(request, this.resolveEffectivePrompt(intentResolution, prompt), intentClarification)
+                        : null);
+                if (!this.hasPendingClarificationQuestion(pendingClarification) && quickReplies.length === 0) {
+                    return {
+                        state: 'success',
+                        phase: 'summarize',
+                        assistantMessage: intentAssistantMessage,
+                        quickReplies,
+                        canApply: false,
+                        statusText: '',
+                        errorText: '',
+                        preview: null,
+                        diagnostics: { intentResolution },
+                    };
+                }
                 return {
                     state: 'clarification',
                     phase: 'clarify',
                     assistantMessage: intentAssistantMessage,
-                    quickReplies: this.toShellQuickReplies(intentResolution.quickReplies ?? []),
+                    quickReplies,
                     canApply: false,
                     statusText: '',
                     errorText: '',
                     preview: null,
-                    pendingClarification: this.resolvePendingClarificationForNextTurn(intentResolution, request, this.resolveEffectivePrompt(intentResolution, prompt), intentAssistantMessage),
+                    pendingClarification,
                     diagnostics: { intentResolution },
                 };
             }
@@ -5827,6 +6614,7 @@ class PageBuilderAgenticAuthoringTurnFlow {
                 state: 'review',
                 phase: 'review',
                 assistantMessage: status,
+                quickReplies: [],
                 canApply: true,
                 statusText: status,
                 errorText: '',
@@ -5847,6 +6635,11 @@ class PageBuilderAgenticAuthoringTurnFlow {
             };
         }
     }
+    submitWithTurnStream(request, prompt) {
+        return from(this.buildTurnStreamRequest(request, prompt)).pipe(concatMap((streamRequest) => this.service.streamTurn(streamRequest)), concatMap((event) => from(this.toTurnResultFromStreamEvent(event))), catchError((error) => this.shouldFallbackFromTurnStreamError(error)
+            ? from(this.submitSynchronously(request, prompt))
+            : of(this.toTurnStreamTransportErrorResult(error))));
+    }
     async cancel() {
         return {
             state: 'listening',
@@ -5860,10 +6653,413 @@ class PageBuilderAgenticAuthoringTurnFlow {
             pendingPatch: null,
         };
     }
+    async buildTurnStreamRequest(request, prompt) {
+        const componentCapabilities = await this.context.loadComponentCapabilities();
+        const selectedWidgetKey = this.context.selectedWidgetKey();
+        return {
+            userPrompt: prompt,
+            targetApp: this.context.targetApp,
+            targetComponentId: this.context.targetComponentId,
+            currentRoute: null,
+            currentPage: this.context.currentPage(),
+            selectedWidgetKey,
+            provider: this.context.provider(),
+            model: this.context.model(),
+            apiKey: this.context.apiKey(),
+            componentCapabilities,
+            ...this.buildAuthoringContext(request),
+        };
+    }
+    async toTurnResultFromStreamEvent(event) {
+        const payload = this.toJsonObject(event.payload) ?? {};
+        if (event.type === 'result') {
+            return this.toResultTurnFromStreamPayload(payload);
+        }
+        if (event.type === 'error') {
+            const message = this.describeStreamError(payload);
+            return {
+                state: 'error',
+                phase: 'contextualize',
+                assistantMessage: message,
+                canApply: false,
+                statusText: '',
+                errorText: message,
+                preview: null,
+                diagnostics: { streamError: payload },
+            };
+        }
+        if (event.type === 'cancelled') {
+            return {
+                state: 'listening',
+                phase: 'capture',
+                assistantMessage: this.context.tx('agentic.status.cancelled', 'Request cancelled.'),
+                quickReplies: [],
+                canApply: false,
+                statusText: '',
+                errorText: '',
+                preview: null,
+                pendingPatch: null,
+            };
+        }
+        return {
+            state: 'processing',
+            phase: this.phaseForStreamPayload(payload),
+            assistantMessage: undefined,
+            canApply: false,
+            statusText: this.statusForStreamPayload(payload),
+            errorText: '',
+            preview: null,
+        };
+    }
+    async toResultTurnFromStreamPayload(payload) {
+        const intentResolution = payload['intentResolution'];
+        const preview = payload['preview'];
+        if (!intentResolution) {
+            const message = this.context.tx('agentic.errors.intentResolution', 'Intent could not be resolved.');
+            return {
+                state: 'error',
+                phase: 'contextualize',
+                assistantMessage: message,
+                canApply: false,
+                statusText: '',
+                errorText: message,
+                preview: null,
+            };
+        }
+        const assistantMessage = this.readString(payload, 'assistantMessage')
+            || this.resolveIntentAssistantMessage(intentResolution)
+            || (preview ? this.context.describePreviewStatus(preview) : '');
+        const quickReplies = Array.isArray(payload['quickReplies'])
+            ? this.toShellQuickReplies(payload['quickReplies'])
+            : [];
+        const canApply = payload['canApply'] === true && !!preview?.valid;
+        if (!canApply) {
+            const pendingClarification = this.toShellPendingClarification(intentResolution?.pendingClarification);
+            const requiresChoice = quickReplies.length > 0;
+            return {
+                state: pendingClarification || requiresChoice ? 'clarification' : 'success',
+                phase: pendingClarification || requiresChoice ? 'clarify' : 'summarize',
+                assistantMessage,
+                quickReplies,
+                canApply: false,
+                statusText: '',
+                errorText: '',
+                preview: null,
+                pendingClarification,
+                diagnostics: { intentResolution, preview },
+            };
+        }
+        const applied = await this.context.applyLocalPreview(preview);
+        if (!applied.success) {
+            const message = applied.error || this.context.tx('agentic.errors.applyLocal', 'Preview could not be applied.');
+            return {
+                state: 'error',
+                phase: 'preview',
+                assistantMessage: message,
+                canApply: false,
+                statusText: '',
+                errorText: message,
+                preview: null,
+                diagnostics: { intentResolution, preview },
+            };
+        }
+        const status = assistantMessage || this.context.describePreviewStatus(preview);
+        return {
+            state: 'review',
+            phase: 'review',
+            assistantMessage: status,
+            quickReplies: [],
+            canApply: true,
+            statusText: status,
+            errorText: '',
+            preview,
+            diagnostics: { intentResolution, preview },
+        };
+    }
+    phaseForStreamPayload(payload) {
+        const phase = this.readString(payload, 'phase');
+        if (phase === 'intent.resolve')
+            return 'contextualize';
+        if (phase === 'resource.discovery')
+            return 'contextualize';
+        if (phase.startsWith('preview.'))
+            return 'preview';
+        if (phase === 'review')
+            return 'review';
+        return 'contextualize';
+    }
+    statusForStreamPayload(payload) {
+        const phase = this.readString(payload, 'phase');
+        switch (phase) {
+            case 'context.bundle':
+                return this.context.tx('agentic.status.contextBundle', 'Preparing context...');
+            case 'intent.resolve':
+                if (this.isSecondPassStreamPayload(payload)) {
+                    return this.context.tx('agentic.status.refinedCandidates', 'Reviewing the retrieved resources with the AI...');
+                }
+                return this.context.tx('agentic.status.resolvingIntent', 'Resolving intent...');
+            case 'resource.discovery':
+                if (this.isBackendResourceDiscoveryPayload(payload)) {
+                    return this.context.tx('agentic.status.resourceDiscoveryBackend', 'Found API resources in the backend catalog.');
+                }
+                return this.context.tx('agentic.status.resourceDiscovery', 'Finding API resources...');
+            case 'preview.plan':
+                return this.context.tx('agentic.status.previewing', 'Generating preview...');
+            case 'preview.compile':
+                return this.context.tx('agentic.status.previewCompile', 'Compiling preview...');
+            default:
+                return this.readString(payload, 'summary') || this.readString(payload, 'message');
+        }
+    }
+    isBackendResourceDiscoveryPayload(payload) {
+        const diagnostics = this.toJsonObject(payload['diagnostics']);
+        return diagnostics?.['source'] === 'backend-resource-catalog';
+    }
+    isSecondPassStreamPayload(payload) {
+        const diagnostics = this.toJsonObject(payload['diagnostics']);
+        return diagnostics?.['secondPass'] === true;
+    }
+    describeStreamError(payload) {
+        const code = this.readString(payload, 'code');
+        if (code === 'agentic-authoring-timeout') {
+            return this.context.tx('agentic.errors.streamTimeout', 'The assistant took too long to finish this request. Try again with a narrower request or review the active context.');
+        }
+        if (code === 'agentic-authoring-processing-failed') {
+            return this.context.tx('agentic.errors.streamProcessing', 'The assistant could not finish this authoring request. Try again or ask support to review the diagnostics.');
+        }
+        return this.readString(payload, 'assistantMessage')
+            || this.context.tx('agentic.errors.generic', 'AI authoring failed.');
+    }
+    toTurnStreamTransportErrorResult(error) {
+        const message = this.isTurnStreamConnectionError(error)
+            ? this.context.tx('agentic.errors.streamConnection', 'The assistant stream was interrupted before the turn finished. Try again or ask support to check the stream connection.')
+            : this.context.describeError(error);
+        return {
+            state: 'error',
+            phase: 'contextualize',
+            assistantMessage: message,
+            canApply: false,
+            statusText: '',
+            errorText: message,
+            preview: null,
+            diagnostics: { streamTransportError: this.toJsonObject(error) ?? { reason: 'stream-transport-error' } },
+        };
+    }
+    shouldFallbackFromTurnStreamError(error) {
+        if (this.isTurnStreamConnectionError(error)) {
+            return false;
+        }
+        const status = this.readErrorStatus(error);
+        if (status === 401 || status === 403) {
+            return false;
+        }
+        return status === 404 || status === 501 || status === 503;
+    }
+    isTurnStreamConnectionError(error) {
+        return this.toJsonObject(error)?.['praxisAgenticTurnStreamConnectionError'] === true;
+    }
+    readErrorStatus(error) {
+        const status = this.toJsonObject(error)?.['status'];
+        return typeof status === 'number' && Number.isFinite(status) ? status : null;
+    }
+    async handleResourceDiscoveryTool(request, prompt) {
+        const contextHints = this.toJsonObject(request.action?.contextHints) ?? {};
+        const retrievalQuery = this.readString(contextHints, 'retrievalQuery') || prompt;
+        const artifactKind = this.readString(contextHints, 'artifactKind') || null;
+        const limit = this.readNumber(contextHints, 'limit');
+        const result = await firstValueFrom(this.service.searchResourceCandidates({
+            retrievalQuery,
+            userPrompt: prompt,
+            artifactKind,
+            limit,
+        }));
+        const quickReplies = result.quickReplies?.length
+            ? this.toShellQuickReplies(result.quickReplies)
+            : this.toResourceCandidateQuickReplies(result.candidates, result.artifactKind);
+        const assistantMessage = result.assistantMessage?.trim()
+            || (quickReplies.length
+                ? this.context.tx('agentic.resourceDiscovery.found', 'I found APIs that can feed this screen. Choose one before generating the preview.')
+                : this.context.tx('agentic.resourceDiscovery.empty', 'I did not find a matching API yet. Describe the business data this screen should use.'));
+        const intentResult = await this.resolveIntentAfterResourceDiscovery(request, request.pendingClarification?.sourcePrompt || prompt, contextHints, result, assistantMessage, quickReplies);
+        if (intentResult) {
+            return intentResult;
+        }
+        return {
+            state: 'clarification',
+            phase: 'clarify',
+            assistantMessage,
+            quickReplies,
+            canApply: false,
+            statusText: '',
+            errorText: '',
+            preview: null,
+            pendingClarification: {
+                sourcePrompt: request.pendingClarification?.sourcePrompt || prompt,
+                assistantMessage,
+                questions: [
+                    {
+                        id: 'resource',
+                        type: 'text',
+                        label: assistantMessage,
+                    },
+                ],
+                clientTurnId: request.clientTurnId,
+                diagnostics: {
+                    resourceDiscovery: {
+                        tool: result.tool,
+                        retrievalQuery: result.retrievalQuery,
+                        artifactKind: result.artifactKind,
+                        warnings: result.warnings,
+                    },
+                },
+            },
+            diagnostics: { resourceDiscovery: result },
+        };
+    }
+    async resolveIntentAfterResourceDiscovery(request, prompt, contextHints, result, fallbackAssistantMessage, fallbackQuickReplies) {
+        if (!result.valid || !result.candidates?.length) {
+            return null;
+        }
+        const componentCapabilities = await this.context.loadComponentCapabilities();
+        const authoringContext = this.buildAuthoringContext(request);
+        const intentResolution = await firstValueFrom(this.service.resolveIntent(this.buildIntentResolutionRequest(prompt, this.context.selectedWidgetKey(), componentCapabilities, {
+            ...authoringContext,
+            contextHints: this.resourceDiscoveryContextHints(contextHints, result),
+        })));
+        const assistantMessage = this.resolveIntentAssistantMessage(intentResolution)
+            || this.resolveIntentClarification(intentResolution)
+            || fallbackAssistantMessage;
+        const quickReplies = intentResolution.quickReplies?.length
+            ? this.toShellQuickReplies(intentResolution.quickReplies)
+            : fallbackQuickReplies;
+        const explicitPendingClarification = this.toShellPendingClarification(intentResolution.pendingClarification);
+        const pendingClarification = explicitPendingClarification
+            ?? this.buildPendingClarificationForNextTurn(request, this.resolveEffectivePrompt(intentResolution, prompt), assistantMessage);
+        if (!assistantMessage && quickReplies.length === 0) {
+            return null;
+        }
+        return {
+            state: quickReplies.length > 0 || this.hasPendingClarificationQuestion(pendingClarification)
+                ? 'clarification'
+                : 'success',
+            phase: quickReplies.length > 0 || this.hasPendingClarificationQuestion(pendingClarification)
+                ? 'clarify'
+                : 'summarize',
+            assistantMessage,
+            quickReplies,
+            canApply: false,
+            statusText: '',
+            errorText: '',
+            preview: null,
+            pendingClarification,
+            diagnostics: { resourceDiscovery: result, intentResolution },
+        };
+    }
+    resourceDiscoveryContextHints(contextHints, result) {
+        const { tool: _tool, ...baseContextHints } = contextHints;
+        return {
+            ...baseContextHints,
+            resourceDiscovery: {
+                tool: result.tool,
+                retrievalQuery: result.retrievalQuery,
+                artifactKind: result.artifactKind,
+                assistantMessage: result.assistantMessage ?? null,
+                candidates: result.candidates.map((candidate) => ({
+                    resourcePath: candidate.resourcePath,
+                    operation: candidate.operation,
+                    schemaUrl: candidate.schemaUrl,
+                    submitUrl: candidate.submitUrl,
+                    submitMethod: candidate.submitMethod,
+                    score: candidate.score,
+                    reason: candidate.reason,
+                    evidence: candidate.evidence,
+                })),
+                quickReplies: (result.quickReplies ?? []).map((reply) => ({
+                    id: reply.id,
+                    kind: reply.kind,
+                    label: reply.label,
+                    prompt: reply.prompt,
+                    description: reply.description ?? null,
+                    icon: reply.icon ?? null,
+                    tone: reply.tone ?? null,
+                    contextHints: this.toJsonObject(reply.contextHints) ?? null,
+                })),
+                warnings: result.warnings,
+            },
+        };
+    }
+    isResourceDiscoveryTool(request) {
+        const contextHints = this.toJsonObject(request.action?.contextHints);
+        return this.readString(contextHints, 'tool') === 'searchApiResources';
+    }
+    toResourceCandidateQuickReplies(candidates, artifactKind) {
+        return candidates
+            .filter((candidate) => !!candidate.resourcePath?.trim())
+            .map((candidate) => {
+            const resourcePath = candidate.resourcePath.trim();
+            const submitUrl = candidate.submitUrl?.trim() || resourcePath;
+            return {
+                id: this.resourceCandidateId(resourcePath),
+                kind: 'suggestion',
+                label: this.resourceCandidateLabel(resourcePath),
+                prompt: this.formatResourceCandidatePrompt(resourcePath),
+                description: this.resourceCandidateDescription(candidate),
+                icon: 'dataset',
+                tone: 'resource',
+                contextHints: {
+                    resourcePath,
+                    submitUrl,
+                    operation: candidate.operation,
+                    schemaUrl: candidate.schemaUrl,
+                    submitMethod: candidate.submitMethod,
+                    artifactKind,
+                },
+            };
+        });
+    }
+    formatResourceCandidatePrompt(resourcePath) {
+        return this.context
+            .tx('agentic.resourceDiscovery.useResource', 'Use {resourcePath}')
+            .replace('{resourcePath}', resourcePath);
+    }
+    resourceCandidateId(resourcePath) {
+        const slug = resourcePath
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+        return slug ? `resource-${slug}` : 'resource-candidate';
+    }
+    resourceCandidateLabel(resourcePath) {
+        const segment = resourcePath.split('/').filter((part) => !!part).pop() || resourcePath;
+        const label = segment
+            .replace(/[-_]+/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        return label
+            ? label.charAt(0).toUpperCase() + label.slice(1)
+            : resourcePath;
+    }
+    resourceCandidateDescription(candidate) {
+        const method = candidate.submitMethod?.trim();
+        const url = candidate.submitUrl?.trim();
+        return method && url ? `${method} ${url}` : url || undefined;
+    }
     resolveIntentAssistantMessage(intentResolution) {
+        if (this.isExecutableIntent(intentResolution)) {
+            return null;
+        }
         const message = intentResolution.assistantMessage?.trim();
         return message || null;
     }
+    isExecutableIntent(intentResolution) {
+        const operationKind = intentResolution.operationKind;
+        const artifactKind = intentResolution.artifactKind;
+        return !!intentResolution.valid
+            && intentResolution.gate?.status === 'eligible'
+            && !!intentResolution.selectedCandidate
+            && (artifactKind === 'form' || artifactKind === 'dashboard' || artifactKind === 'table' || artifactKind === 'page')
+            && (operationKind === 'create' || operationKind === 'modify' || operationKind === 'remove' || operationKind === 'compose');
+    }
     resolveIntentClarification(intentResolution) {
         const questions = intentResolution.clarificationQuestions?.filter((question) => !!question) ?? [];
         if (!intentResolution.valid && questions.length) {
@@ -5872,7 +7068,7 @@ class PageBuilderAgenticAuthoringTurnFlow {
         return null;
     }
     describeIntentResolutionFailure(intentResolution) {
-        if (intentResolution.valid && intentResolution.gate?.status === 'eligible' && intentResolution.selectedCandidate) {
+        if (this.isExecutableIntent(intentResolution)) {
             return null;
         }
         const questions = intentResolution.clarificationQuestions?.filter((question) => !!question) ?? [];
@@ -5897,6 +7093,10 @@ class PageBuilderAgenticAuthoringTurnFlow {
             kind: reply.kind,
             label: reply.label,
             prompt: reply.prompt,
+            description: reply.description,
+            icon: reply.icon,
+            tone: reply.tone,
+            contextHints: this.toJsonObject(reply.contextHints),
         }));
     }
     buildPendingClarificationForNextTurn(request, sourcePrompt, clarification) {
@@ -5947,16 +7147,47 @@ class PageBuilderAgenticAuthoringTurnFlow {
             diagnostics: this.toJsonObject(pending?.diagnostics) ?? undefined,
         };
     }
+    hasPendingClarificationQuestion(pending) {
+        return !!pending?.sourcePrompt?.trim() && pending.questions.some((question) => !!question.label?.trim());
+    }
     resolveEffectivePrompt(intentResolution, fallbackPrompt) {
         return intentResolution.effectivePrompt?.trim() || fallbackPrompt;
     }
     buildAuthoringContext(request) {
+        const contextHints = this.buildContextHints(request);
         return {
             sessionId: request.sessionId,
             clientTurnId: request.clientTurnId,
             conversationMessages: this.toConversationMessages(request.messages ?? []),
             pendingClarification: this.toPendingClarification(request.pendingClarification),
             attachmentSummaries: this.toAttachmentSummaries(request.attachments ?? []),
+            contextHints,
+        };
+    }
+    buildIntentResolutionRequest(prompt, selectedWidgetKey, componentCapabilities, authoringContext) {
+        return {
+            userPrompt: prompt,
+            targetApp: this.context.targetApp,
+            targetComponentId: this.context.targetComponentId,
+            currentPage: this.context.currentPage(),
+            selectedWidgetKey,
+            provider: this.context.provider(),
+            model: this.context.model(),
+            apiKey: this.context.apiKey(),
+            componentCapabilities,
+            ...authoringContext,
+        };
+    }
+    buildContextHints(request) {
+        const base = this.toJsonObject(request.action?.contextHints)
+            ?? this.toJsonObject(request.contextHints);
+        const includeLlmDiagnostics = this.context.includeLlmDiagnostics?.() === true;
+        if (!includeLlmDiagnostics) {
+            return base ?? undefined;
+        }
+        return {
+            ...(base ?? {}),
+            includeLlmDiagnostics: true,
         };
     }
     toAttachmentSummaries(attachments) {
@@ -6005,6 +7236,14 @@ class PageBuilderAgenticAuthoringTurnFlow {
             ? value
             : null;
     }
+    readString(value, key) {
+        const raw = value?.[key];
+        return typeof raw === 'string' ? raw.trim() : '';
+    }
+    readNumber(value, key) {
+        const raw = value?.[key];
+        return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+    }
 }
 
 function buildConnectionsViewerModel(page) {
@@ -6017,6 +7256,12 @@ function buildConnectionsViewerModel(page) {
     const edges = links.map((link) => {
         const fromWidgetId = link.from.kind === 'component-port' ? link.from.ref.widget : null;
         const toWidgetId = link.to.kind === 'component-port' ? link.to.ref.widget : null;
+        const fromNestedPath = link.from.kind === 'component-port' && link.from.ref.nestedPath?.length
+            ? clone(link.from.ref.nestedPath)
+            : null;
+        const toNestedPath = link.to.kind === 'component-port' && link.to.ref.nestedPath?.length
+            ? clone(link.to.ref.nestedPath)
+            : null;
         const toStatePath = link.to.kind === 'state' ? link.to.ref.path : null;
         const diagnosticReasons = [];
         if (fromWidgetId && !counts.has(fromWidgetId)) {
@@ -6039,9 +7284,17 @@ function buildConnectionsViewerModel(page) {
             id: link.id,
             fromKind: link.from.kind,
             fromWidgetId,
+            fromEndpointId: link.from.kind === 'component-port'
+                ? buildComponentEndpointId(link.from.ref.widget, link.from.ref.nestedPath)
+                : null,
+            fromNestedPath,
             fromPort: link.from.kind === 'component-port' ? link.from.ref.port : null,
             toKind: link.to.kind,
             toWidgetId,
+            toEndpointId: link.to.kind === 'component-port'
+                ? buildComponentEndpointId(link.to.ref.widget, link.to.ref.nestedPath)
+                : null,
+            toNestedPath,
             toPort: link.to.kind === 'component-port' ? link.to.ref.port : null,
             toStatePath,
             intent: link.intent,
@@ -6072,6 +7325,31 @@ function buildConnectionsViewerModel(page) {
         diagnosticLinks: edges.filter((edge) => edge.hasDiagnostics).length,
     };
 }
+function buildComponentEndpointId(ownerWidgetKey, nestedPath) {
+    if (!nestedPath?.length) {
+        return ownerWidgetKey;
+    }
+    return `${ownerWidgetKey}${nestedPath
+        .map((segment) => `/${formatPathSegment(segment)}`)
+        .join('')}`;
+}
+function formatPathSegment(segment) {
+    if (segment.kind === 'widget') {
+        const identity = segment.key
+            || segment.componentType
+            || (typeof segment.index === 'number' ? String(segment.index) : 'unknown');
+        return `widget:${identity}`;
+    }
+    return [
+        segment.kind,
+        segment.id || segment.key || segment.index,
+    ].filter((part) => part !== undefined && part !== '').join(':');
+}
+function clone(value) {
+    if (value == null || typeof value !== 'object')
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
 
 class ConnectionsViewerPanelComponent {
     i18n = inject(PraxisI18nService);
@@ -6522,6 +7800,8 @@ class DynamicPageBuilderComponent {
     agenticAuthoringComponentId;
     agenticAuthoringScope = 'user';
     agenticAuthoringEtag;
+    agenticAuthoringIncludeLlmDiagnostics = false;
+    agenticAuthoringEnableStreaming = false;
     pageChange = new EventEmitter();
     agenticAuthoringApplied = new EventEmitter();
     currentPage = signal({ widgets: [] }, ...(ngDevMode ? [{ debugName: "currentPage" }] : []));
@@ -6536,6 +7816,7 @@ class DynamicPageBuilderComponent {
     agenticAuthoringConversation = signal([], ...(ngDevMode ? [{ debugName: "agenticAuthoringConversation" }] : []));
     agenticAuthoringQuickReplies = signal([], ...(ngDevMode ? [{ debugName: "agenticAuthoringQuickReplies" }] : []));
     agenticAuthoringAttachments = signal([], ...(ngDevMode ? [{ debugName: "agenticAuthoringAttachments" }] : []));
+    agenticAuthoringLlmDiagnostics = signal(null, ...(ngDevMode ? [{ debugName: "agenticAuthoringLlmDiagnostics" }] : []));
     agenticAuthoringEditingMessageId = signal(null, ...(ngDevMode ? [{ debugName: "agenticAuthoringEditingMessageId" }] : []));
     agenticAuthoringPanelLayout = signal({
         left: 16,
@@ -6568,6 +7849,7 @@ class DynamicPageBuilderComponent {
         this.previewMode = !this.previewMode;
         if (this.previewMode) {
             this.connectionsViewerOpen.set(false);
+            this.agenticAuthoringLlmDiagnostics.set(null);
         }
     }
     toggleConnectionsViewer() {
@@ -6728,11 +8010,10 @@ class DynamicPageBuilderComponent {
         try {
             const controller = this.ensureAgenticTurnController();
             const editingMessageId = this.agenticAuthoringEditingMessageId();
-            const state = await firstValueFrom(editingMessageId
+            await this.consumeAgenticTurn(editingMessageId
                 ? controller.submitEditedMessage(editingMessageId, prompt)
                 : controller.submitPrompt(prompt));
             this.agenticAuthoringEditingMessageId.set(null);
-            this.applyAgenticTurnState(state);
         }
         catch (error) {
             this.agenticAuthoringStatus.set('');
@@ -6745,24 +8026,79 @@ class DynamicPageBuilderComponent {
         }
     }
     async submitAgenticQuickReply(reply) {
-        if (reply.kind !== 'cancel' && reply.kind !== 'revise' && reply.kind !== 'confirm' && reply.kind !== 'suggestion') {
-            return;
-        }
-        if (reply.kind === 'cancel') {
+        const replyKind = (reply.kind || 'suggestion').trim().toLowerCase();
+        if (replyKind === 'cancel') {
             this.agenticAuthoringEditingMessageId.set(null);
-            const state = await firstValueFrom(this.ensureAgenticTurnController().cancel());
-            this.applyAgenticTurnState(state);
+            await this.consumeAgenticTurn(this.ensureAgenticTurnController().cancel());
             return;
         }
-        if (reply.kind === 'revise') {
+        if (replyKind === 'revise') {
             this.agenticAuthoringEditingMessageId.set(null);
             this.agenticAuthoringQuickReplies.set([]);
             this.agenticAuthoringStatus.set(this.tx('agentic.status.waitingRevision', 'Refine your prompt and preview again.'));
             return;
         }
         this.agenticAuthoringEditingMessageId.set(null);
-        this.agenticAuthoringPrompt.set(reply.prompt);
-        await this.previewAgenticAuthoring();
+        const contextHints = reply.contextHints ? { ...reply.contextHints } : undefined;
+        const visiblePrompt = this.agenticQuickReplyVisiblePrompt(reply, contextHints);
+        this.agenticAuthoringPrompt.set(visiblePrompt);
+        this.agenticAuthoringBusy.set(true);
+        this.agenticAuthoringError.set('');
+        this.agenticAuthoringPreviewResult.set(null);
+        this.agenticAuthoringStatus.set(this.tx('agentic.status.resolvingIntent', 'Resolving intent...'));
+        try {
+            const controller = this.ensureAgenticTurnController();
+            await this.consumeAgenticTurn(controller.snapshot().state === 'clarification'
+                ? controller.answerClarification({
+                    id: reply.id,
+                    label: visiblePrompt,
+                    value: reply.prompt,
+                    description: reply.description ?? undefined,
+                    contextHints,
+                })
+                : controller.submitPrompt(visiblePrompt, {
+                    kind: replyKind || 'quick-reply',
+                    id: reply.id,
+                    value: reply.prompt,
+                    contextHints,
+                }));
+        }
+        catch (error) {
+            this.agenticAuthoringStatus.set('');
+            const message = this.describeAgenticError(error);
+            this.agenticAuthoringError.set(message);
+            this.appendAgenticMessage('error', message);
+        }
+        finally {
+            this.agenticAuthoringBusy.set(false);
+        }
+    }
+    agenticQuickReplyVisiblePrompt(reply, contextHints) {
+        if (!this.isResourceQuickReply(reply, contextHints)) {
+            return reply.prompt;
+        }
+        const label = (reply.label || this.describeResourceContext(contextHints) || reply.prompt).trim();
+        const resourcePath = String(contextHints?.['resourcePath'] || '').trim();
+        return this.tx('agentic.quickReplies.resourceSelectionPrompt', 'Use {label} ({resourcePath}) as the data source.')
+            .replace('{label}', label)
+            .replace('{resourcePath}', resourcePath);
+    }
+    isResourceQuickReply(reply, contextHints) {
+        return reply.kind === 'suggestion'
+            && typeof contextHints?.['resourcePath'] === 'string'
+            && !!String(contextHints['resourcePath']).trim();
+    }
+    describeResourceContext(contextHints) {
+        const resourcePath = typeof contextHints?.['resourcePath'] === 'string'
+            ? contextHints['resourcePath'].trim()
+            : '';
+        if (!resourcePath)
+            return '';
+        const segment = resourcePath.split('/').filter((part) => !!part).pop() || resourcePath;
+        return segment
+            .replace(/[-_]+/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
     }
     attachAgenticContext() {
         const controller = this.ensureAgenticTurnController();
@@ -6807,8 +8143,7 @@ class DynamicPageBuilderComponent {
         this.agenticAuthoringError.set('');
         this.agenticAuthoringPreviewResult.set(null);
         try {
-            const state = await firstValueFrom(this.ensureAgenticTurnController().resendMessage(message.id));
-            this.applyAgenticTurnState(state);
+            await this.consumeAgenticTurn(this.ensureAgenticTurnController().resendMessage(message.id));
         }
         catch (error) {
             this.agenticAuthoringStatus.set('');
@@ -6877,6 +8212,8 @@ class DynamicPageBuilderComponent {
                 provider: () => this.agenticAuthoringProvider,
                 model: () => this.agenticAuthoringModel,
                 apiKey: () => this.agenticAuthoringApiKey,
+                enableTurnStream: () => this.agenticAuthoringEnableStreaming,
+                includeLlmDiagnostics: () => this.agenticAuthoringIncludeLlmDiagnostics,
                 loadComponentCapabilities: () => this.loadAgenticComponentCapabilities(),
                 applyLocalPreview: (result) => this.applyAgenticPreviewLocally(result),
                 describePreviewFailure: (result) => this.describeAgenticPreviewFailure(result),
@@ -6898,20 +8235,55 @@ class DynamicPageBuilderComponent {
     }
     async applyAgenticPreviewLocally(result) {
         const adapter = new PageBuilderAiAdapter(this.createAdapterHost(), this.componentMetadata);
-        return result.uiCompositionPlan
+        const applied = await (result.uiCompositionPlan
             ? adapter.applyUiCompositionPlan(result.uiCompositionPlan)
-            : adapter.applyCompiledFormPatch(result.compiledFormPatch);
+            : adapter.applyCompiledFormPatch(result.compiledFormPatch));
+        if (!applied.success && this.isAgenticTableContractError(applied.error)) {
+            return {
+                ...applied,
+                error: this.tx('agentic.errors.invalidTableContract', 'I found the data source, but the generated plan used properties that are incompatible with the table component. I will adjust it to use only supported fields.'),
+            };
+        }
+        return applied;
     }
     applyAgenticTurnState(state) {
+        const preview = state.preview ?? null;
         this.agenticAuthoringConversation.set(state.messages);
-        this.agenticAuthoringQuickReplies.set(state.quickReplies);
+        this.agenticAuthoringQuickReplies.set(preview?.valid ? [] : state.quickReplies);
         this.agenticAuthoringStatus.set(state.statusText);
         this.agenticAuthoringError.set(state.errorText);
-        this.agenticAuthoringPreviewResult.set(state.preview ?? null);
+        this.agenticAuthoringPreviewResult.set(preview);
         this.agenticAuthoringAttachments.set(state.attachments);
+        this.agenticAuthoringLlmDiagnostics.set(this.resolveAgenticLlmDiagnostics(state.diagnostics));
+    }
+    consumeAgenticTurn(states$) {
+        return lastValueFrom(states$.pipe(tap((state) => this.applyAgenticTurnState(state))));
+    }
+    agenticAuthoringDiagnosticsTop() {
+        return Math.max(16, this.agenticAuthoringPanelLayout().top);
+    }
+    agenticAuthoringLlmDiagnosticsText() {
+        const diagnostics = this.agenticAuthoringLlmDiagnostics();
+        if (!this.agenticAuthoringIncludeLlmDiagnostics || !diagnostics) {
+            return '';
+        }
+        return JSON.stringify(diagnostics, null, 2);
+    }
+    resolveAgenticLlmDiagnostics(diagnostics) {
+        if (!this.agenticAuthoringIncludeLlmDiagnostics) {
+            return null;
+        }
+        const intentResolution = this.toRecord(diagnostics?.['intentResolution']);
+        return this.toRecord(intentResolution?.['llmDiagnostics']);
+    }
+    toRecord(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return null;
+        }
+        return value;
     }
     resolvePreviewCompiledFormPatch(preview) {
-        if (preview.uiCompositionPlan) {
+        if (preview.uiCompositionPlan || preview.compiledFormPatch?.patch?.page) {
             return {
                 ...preview.compiledFormPatch,
                 patch: {
@@ -6920,9 +8292,6 @@ class DynamicPageBuilderComponent {
                 },
             };
         }
-        if (preview.compiledFormPatch?.patch?.page) {
-            return preview.compiledFormPatch;
-        }
         return preview.compiledFormPatch;
     }
     focusCanvasWidget(widgetKey) {
@@ -6994,6 +8363,12 @@ class DynamicPageBuilderComponent {
         }
     }
     describeAgenticPreviewStatus(result) {
+        const assistantMessage = typeof result.assistantMessage === 'string'
+            ? result.assistantMessage.trim()
+            : '';
+        if (assistantMessage) {
+            return assistantMessage;
+        }
         switch (result.diagnostics?.fieldScopeDecision) {
             case 'accepted-add-local-field':
                 return this.tx('agentic.status.acceptedAddLocalField', 'Local field added to the form.');
@@ -7005,6 +8380,11 @@ class DynamicPageBuilderComponent {
                 return this.tx('agentic.status.previewReady', 'Preview applied to the page.');
         }
     }
+    isAgenticTableContractError(error) {
+        const message = typeof error === 'string' ? error.toLowerCase() : '';
+        return message.includes('praxis-table')
+            && (message.includes('unknown input') || message.includes('unknown inputs') || message.includes('unsupported'));
+    }
     appendAgenticMessage(role, text) {
         const normalized = text.trim();
         if (!normalized)
@@ -7043,7 +8423,7 @@ class DynamicPageBuilderComponent {
         return resolvePraxisPageBuilderText(this.i18n, key, fallback);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: DynamicPageBuilderComponent, deps: [{ token: i1.MatDialog }, { token: SETTINGS_PANEL_BRIDGE, optional: true }], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.17", type: DynamicPageBuilderComponent, isStandalone: true, selector: "praxis-dynamic-page-builder", inputs: { page: "page", context: "context", strictValidation: "strictValidation", autoPersist: "autoPersist", enableCustomization: "enableCustomization", showSettingsButton: "showSettingsButton", pageIdentity: "pageIdentity", componentInstanceId: "componentInstanceId", pageEditorComponent: "pageEditorComponent", enableAgenticAuthoring: "enableAgenticAuthoring", agenticAuthoringProvider: "agenticAuthoringProvider", agenticAuthoringModel: "agenticAuthoringModel", agenticAuthoringApiKey: "agenticAuthoringApiKey", agenticAuthoringComponentId: "agenticAuthoringComponentId", agenticAuthoringScope: "agenticAuthoringScope", agenticAuthoringEtag: "agenticAuthoringEtag" }, outputs: { pageChange: "pageChange", agenticAuthoringApplied: "agenticAuthoringApplied" }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.17", type: DynamicPageBuilderComponent, isStandalone: true, selector: "praxis-dynamic-page-builder", inputs: { page: "page", context: "context", strictValidation: "strictValidation", autoPersist: "autoPersist", enableCustomization: "enableCustomization", showSettingsButton: "showSettingsButton", pageIdentity: "pageIdentity", componentInstanceId: "componentInstanceId", pageEditorComponent: "pageEditorComponent", enableAgenticAuthoring: "enableAgenticAuthoring", agenticAuthoringProvider: "agenticAuthoringProvider", agenticAuthoringModel: "agenticAuthoringModel", agenticAuthoringApiKey: "agenticAuthoringApiKey", agenticAuthoringComponentId: "agenticAuthoringComponentId", agenticAuthoringScope: "agenticAuthoringScope", agenticAuthoringEtag: "agenticAuthoringEtag", agenticAuthoringIncludeLlmDiagnostics: "agenticAuthoringIncludeLlmDiagnostics", agenticAuthoringEnableStreaming: "agenticAuthoringEnableStreaming" }, outputs: { pageChange: "pageChange", agenticAuthoringApplied: "agenticAuthoringApplied" }, providers: [
             providePraxisPageBuilderI18n(),
             { provide: DYNAMIC_PAGE_SHELL_EDITOR, useValue: WidgetShellEditorComponent },
         ], viewQueries: [{ propertyName: "runtime", first: true, predicate: ["runtime"], descendants: true }], usesOnChanges: true, ngImport: i0, template: `
@@ -7107,6 +8487,26 @@ class DynamicPageBuilderComponent {
         (close)="toggleAgenticAuthoring()"
       />
 
+      <section
+        *ngIf="agenticAuthoringIncludeLlmDiagnostics && agenticAuthoringLlmDiagnosticsText()"
+        class="agentic-diagnostics-panel"
+        data-testid="page-builder-agentic-llm-diagnostics"
+        role="region"
+        [attr.aria-label]="tx('agentic.diagnostics.title', 'LLM diagnostics')"
+        [style.top.px]="agenticAuthoringDiagnosticsTop()"
+      >
+        <header class="agentic-diagnostics-panel__header">
+          <span>{{ tx('agentic.diagnostics.title', 'LLM diagnostics') }}</span>
+          <span class="agentic-diagnostics-panel__badge">
+            {{ tx('agentic.diagnostics.badge', 'Debug') }}
+          </span>
+        </header>
+        <p class="agentic-diagnostics-panel__description">
+          {{ tx('agentic.diagnostics.description', 'Prompt, context bundle, and tool catalog returned by the backend for this turn.') }}
+        </p>
+        <pre>{{ agenticAuthoringLlmDiagnosticsText() }}</pre>
+      </section>
+
       <praxis-floating-toolbar
         [visible]="showSettings()"
         [canUndo]="false"
@@ -7141,7 +8541,7 @@ class DynamicPageBuilderComponent {
         </button>
       </praxis-floating-toolbar>
     </div>
-  `, isInline: true, styles: [":host{display:block;position:relative;min-height:var(--pdx-page-builder-min-height, 420px)}.builder-shell{display:block;position:relative;min-height:inherit;height:100%}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2$1.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i2.MatMiniFabButton, selector: "button[mat-mini-fab], a[mat-mini-fab], button[matMiniFab], a[matMiniFab]", exportAs: ["matButton", "matAnchor"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i4.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i3.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }, { kind: "component", type: DynamicWidgetPageComponent, selector: "praxis-dynamic-page", inputs: ["page", "context", "strictValidation", "enableCustomization", "showPageSettingsButton", "shellEditorComponent", "pageEditorComponent", "autoPersist", "pageIdentity", "componentInstanceId"], outputs: ["pageChange", "widgetEvent", "widgetDiagnosticsChange"] }, { kind: "component", type: FloatingToolbarComponent, selector: "praxis-floating-toolbar", inputs: ["visible", "canUndo", "canRedo"], outputs: ["add", "undo", "redo", "settings", "preview", "save"] }, { kind: "component", type: ConnectionsViewerPanelComponent, selector: "praxis-connections-viewer-panel", inputs: ["open", "page"], outputs: ["focusWidget", "openPageSettings"] }, { kind: "component", type: PraxisAiAssistantShellComponent, selector: "praxis-ai-assistant-shell", inputs: ["labels", "mode", "state", "contextItems", "attachments", "messages", "quickReplies", "prompt", "statusText", "errorText", "testIdPrefix", "panelTestId", "submitTestId", "applyTestId", "busy", "canSubmit", "canApply", "submitOnEnter", "enableFileAttachments", "attachmentAccept", "attachmentMultiple", "draggable", "resizable", "minWidth", "minHeight", "margin", "layout"], outputs: ["promptChange", "submitPrompt", "apply", "close", "attach", "attachmentsPasted", "attachmentsSelected", "removeAttachment", "messageAction", "editMessage", "resendMessage", "quickReply", "layoutChange"] }] });
+  `, isInline: true, styles: [":host{display:block;position:relative;min-height:var(--pdx-page-builder-min-height, 420px)}.builder-shell{display:block;position:relative;min-height:inherit;height:100%}.agentic-diagnostics-panel{position:absolute;z-index:21;right:16px;width:min(520px,calc(100% - 32px));max-height:min(440px,calc(100% - 32px));overflow:auto;padding:12px;border:1px solid rgba(107,114,128,.28);border-radius:8px;background:#fffffff5;color:#111827;box-shadow:0 14px 36px #0000003d}.agentic-diagnostics-panel__header{display:flex;align-items:center;justify-content:space-between;gap:12px;font-size:13px;font-weight:700}.agentic-diagnostics-panel__badge{padding:2px 6px;border:1px solid rgba(107,114,128,.28);border-radius:8px;font-size:11px;font-weight:600;color:#4b5563}.agentic-diagnostics-panel__description{margin:8px 0 10px;color:#4b5563;font-size:12px;line-height:1.4}.agentic-diagnostics-panel pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;font-size:11px;line-height:1.45;color:#1f2937}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2$1.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i2.MatMiniFabButton, selector: "button[mat-mini-fab], a[mat-mini-fab], button[matMiniFab], a[matMiniFab]", exportAs: ["matButton", "matAnchor"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i4.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i3.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }, { kind: "component", type: DynamicWidgetPageComponent, selector: "praxis-dynamic-page", inputs: ["page", "context", "strictValidation", "enableCustomization", "showPageSettingsButton", "shellEditorComponent", "pageEditorComponent", "autoPersist", "pageIdentity", "componentInstanceId"], outputs: ["pageChange", "widgetEvent", "widgetDiagnosticsChange"] }, { kind: "component", type: FloatingToolbarComponent, selector: "praxis-floating-toolbar", inputs: ["visible", "canUndo", "canRedo"], outputs: ["add", "undo", "redo", "settings", "preview", "save"] }, { kind: "component", type: ConnectionsViewerPanelComponent, selector: "praxis-connections-viewer-panel", inputs: ["open", "page"], outputs: ["focusWidget", "openPageSettings"] }, { kind: "component", type: PraxisAiAssistantShellComponent, selector: "praxis-ai-assistant-shell", inputs: ["labels", "mode", "state", "contextItems", "attachments", "messages", "quickReplies", "prompt", "statusText", "errorText", "testIdPrefix", "panelTestId", "submitTestId", "applyTestId", "busy", "canSubmit", "canApply", "submitOnEnter", "enableFileAttachments", "attachmentAccept", "attachmentMultiple", "draggable", "resizable", "minWidth", "minHeight", "margin", "layout"], outputs: ["promptChange", "submitPrompt", "apply", "close", "attach", "attachmentsPasted", "attachmentsSelected", "removeAttachment", "messageAction", "editMessage", "resendMessage", "quickReply", "layoutChange"] }] });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: DynamicPageBuilderComponent, decorators: [{
             type: Component,
@@ -7219,6 +8619,26 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
         (close)="toggleAgenticAuthoring()"
       />
 
+      <section
+        *ngIf="agenticAuthoringIncludeLlmDiagnostics && agenticAuthoringLlmDiagnosticsText()"
+        class="agentic-diagnostics-panel"
+        data-testid="page-builder-agentic-llm-diagnostics"
+        role="region"
+        [attr.aria-label]="tx('agentic.diagnostics.title', 'LLM diagnostics')"
+        [style.top.px]="agenticAuthoringDiagnosticsTop()"
+      >
+        <header class="agentic-diagnostics-panel__header">
+          <span>{{ tx('agentic.diagnostics.title', 'LLM diagnostics') }}</span>
+          <span class="agentic-diagnostics-panel__badge">
+            {{ tx('agentic.diagnostics.badge', 'Debug') }}
+          </span>
+        </header>
+        <p class="agentic-diagnostics-panel__description">
+          {{ tx('agentic.diagnostics.description', 'Prompt, context bundle, and tool catalog returned by the backend for this turn.') }}
+        </p>
+        <pre>{{ agenticAuthoringLlmDiagnosticsText() }}</pre>
+      </section>
+
       <praxis-floating-toolbar
         [visible]="showSettings()"
         [canUndo]="false"
@@ -7253,7 +8673,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
         </button>
       </praxis-floating-toolbar>
     </div>
-  `, styles: [":host{display:block;position:relative;min-height:var(--pdx-page-builder-min-height, 420px)}.builder-shell{display:block;position:relative;min-height:inherit;height:100%}\n"] }]
+  `, styles: [":host{display:block;position:relative;min-height:var(--pdx-page-builder-min-height, 420px)}.builder-shell{display:block;position:relative;min-height:inherit;height:100%}.agentic-diagnostics-panel{position:absolute;z-index:21;right:16px;width:min(520px,calc(100% - 32px));max-height:min(440px,calc(100% - 32px));overflow:auto;padding:12px;border:1px solid rgba(107,114,128,.28);border-radius:8px;background:#fffffff5;color:#111827;box-shadow:0 14px 36px #0000003d}.agentic-diagnostics-panel__header{display:flex;align-items:center;justify-content:space-between;gap:12px;font-size:13px;font-weight:700}.agentic-diagnostics-panel__badge{padding:2px 6px;border:1px solid rgba(107,114,128,.28);border-radius:8px;font-size:11px;font-weight:600;color:#4b5563}.agentic-diagnostics-panel__description{margin:8px 0 10px;color:#4b5563;font-size:12px;line-height:1.4}.agentic-diagnostics-panel pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;font-size:11px;line-height:1.45;color:#1f2937}\n"] }]
         }], ctorParameters: () => [{ type: i1.MatDialog }, { type: undefined, decorators: [{
                     type: Optional
                 }, {
@@ -7294,6 +8714,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
                 type: Input
             }], agenticAuthoringEtag: [{
                 type: Input
+            }], agenticAuthoringIncludeLlmDiagnostics: [{
+                type: Input
+            }], agenticAuthoringEnableStreaming: [{
+                type: Input
             }], pageChange: [{
                 type: Output
             }], agenticAuthoringApplied: [{
@@ -7309,4 +8733,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { ComponentPaletteDialogComponent, ConfirmDialogComponent, DynamicPageBuilderComponent, DynamicPageConfigEditorComponent, FloatingToolbarComponent, PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, PAGE_BUILDER_AI_CAPABILITIES, PAGE_BUILDER_WIDGET_AI_CATALOGS, PLACEHOLDER, PageBuilderAgenticAuthoringService, PageConfigEditorComponent, TileToolbarComponent, WidgetShellEditorComponent, clearWidgetAiCatalogs, getPageAiCatalog, getWidgetAiCapabilities, providePageBuilderWidgetAiCatalogs, registerWidgetAiCatalog, registerWidgetAiCatalogs };
+export { ComponentPaletteDialogComponent, ConfirmDialogComponent, DynamicPageBuilderComponent, DynamicPageConfigEditorComponent, FloatingToolbarComponent, PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, PAGE_BUILDER_AI_CAPABILITIES, PAGE_BUILDER_WIDGET_AI_CATALOGS, PLACEHOLDER, PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST, PageBuilderAgenticAuthoringService, PageConfigEditorComponent, TileToolbarComponent, WidgetShellEditorComponent, clearWidgetAiCatalogs, getPageAiCatalog, getWidgetAiCapabilities, providePageBuilderWidgetAiCatalogs, registerWidgetAiCatalog, registerWidgetAiCatalogs };