@praxisui/page-builder 9.0.5-rc.2 → 9.0.5-rc.21

package/fesm2022/praxisui-page-builder.mjs

@@ -12541,7 +12541,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
  * Capabilities catalog for the canonical dynamic page builder/runtime.
  */
 const PAGE_BUILDER_AI_CAPABILITIES = {
-    version: 'v1.2',
+    version: 'v1.3',
     enums: {},
     targets: [
         'page-builder',
@@ -12558,7 +12558,7 @@ const PAGE_BUILDER_AI_CAPABILITIES = {
         'Canvas e o modelo espacial canonico da pagina quando houver posicionamento explicito.',
         '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.',
+        'UiCompositionPlan usa widgets[].componentId e bindings declarativos. UiCompositionPlanTemplateReference pode piná-lo por registryKey + configSha256, mas precisa ser resolvido pelo backend governado antes da compilação. 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 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.',
@@ -12568,6 +12568,9 @@ const PAGE_BUILDER_AI_CAPABILITIES = {
         { path: 'uiCompositionPlan', category: 'page', valueKind: 'object', description: 'Plano declarativo intermediario aceito em preview agentic antes do WidgetPageDefinition.' },
         { path: 'uiCompositionPlan.version', category: 'page', valueKind: 'string', description: 'Versao do plano. Valor atual: 1.0.' },
         { path: 'uiCompositionPlan.kind', category: 'page', valueKind: 'string', description: 'Discriminador do plano. Valor atual: praxis.ui-composition-plan.' },
+        { path: 'uiCompositionPlan.i18n', category: 'page', valueKind: 'object', description: 'Catalogo de textos de negocio da pagina, compilado para page.i18n. Descritores PraxisTextValue podem declarar apenas key quando a chave existir no dicionario do fallbackLocale; o compilador materializa text no documento executavel.' },
+        { path: 'uiCompositionPlan.context', category: 'context', valueKind: 'object', description: 'Contexto explicito da pagina, compilado para page.context; nao substitui contextScopes de autoria.' },
+        { path: 'uiCompositionPlan.layout', category: 'layout', valueKind: 'object', description: 'Layout responsivo canonico compilado para page.layout quando a pagina nao usa apenas canvas/preset.' },
         { path: 'uiCompositionPlan.layoutPreset', category: 'layout', valueKind: 'string', description: 'Preset semantico opcional da composicao planejada.' },
         { path: 'uiCompositionPlan.layoutPresetOptions', category: 'layout', valueKind: 'object', description: 'Opcoes semanticas opcionais do preset, como familia visual, estrategia responsiva e politica de densidade.' },
         { path: 'uiCompositionPlan.grouping', category: 'layout', valueKind: 'array', description: 'Agrupamentos semanticos opcionais para organizar widgets em hero, section, tabs ou rail no runtime.' },
@@ -12578,8 +12581,14 @@ const PAGE_BUILDER_AI_CAPABILITIES = {
         { path: 'uiCompositionPlan.widgets', category: 'widgets', valueKind: 'array', description: 'Widgets planejados antes da compilacao para page.widgets.' },
         { path: 'uiCompositionPlan.widgets[].key', category: 'widgets', valueKind: 'string', description: 'ID estavel do widget planejado.', critical: true },
         { path: 'uiCompositionPlan.widgets[].componentId', category: 'widgets', valueKind: 'string', description: 'Componente registrado que sera compilado para definition.id.', critical: true },
+        { path: 'uiCompositionPlan.widgets[].shell', category: 'widgets', valueKind: 'object', description: 'Moldura governada do widget, compilada para page.widgets[].shell sem enriquecimento do host.' },
         { path: 'uiCompositionPlan.widgets[].inputs', category: 'widgets', valueKind: 'object', description: 'Inputs canonicos do componente, compilados para definition.inputs.' },
         { path: 'uiCompositionPlan.widgets[].bindingOrder', category: 'widgets', valueKind: 'array', description: 'Ordem declarativa de binding, compilada para definition.bindingOrder.' },
+        { path: 'uiCompositionPlan.selectionSyncs', category: 'connections', valueKind: 'array', description: 'Atalhos declarativos para projetar o mesmo contexto de selecao a partir de varias portas; sempre compilam para links canonicos explicitos.' },
+        { path: 'uiCompositionPlan.contextScopes', category: 'context', valueKind: 'array', description: 'Escopos de autoria que distribuem contexto explicito a widgets top-level ou nested; nao criam heranca ambiente no runtime.' },
+        { path: 'uiCompositionPlan.contextScopes[].context', category: 'context', valueKind: 'object', description: 'Mapa input -> constant ou state. Constant e state.initial viram inputs explicitos; state tambem gera link state-read canonico.' },
+        { path: 'uiCompositionPlan.contextScopes[].context.<token>', category: 'context', valueKind: 'object', description: 'Descritor constant ou state. Em state, initial aceita um valor JSON opcional materializado no input antes da primeira propagacao; nao cria um segundo state store.' },
+        { path: 'uiCompositionPlan.contextScopes[].targets', category: 'context', valueKind: 'array', description: 'Destinos explicitos do escopo, identificados por widget owner e nestedPath canonico opcional.' },
         { path: 'uiCompositionPlan.bindings', category: 'connections', valueKind: 'array', description: 'Bindings declarativos que serao compilados para page.composition.links.' },
         { 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.' },
@@ -13226,12 +13235,13 @@ const PAGE_BUILDER_COMPONENT_CONTEXT_PACK = {
     },
     hints: [
         'For agentic page creation, prefer returning uiCompositionPlan in the preview envelope and let the page-builder compiler emit WidgetPageDefinition.',
+        'Carry page-owned i18n, explicit context, canonical layout and governed widget shell in uiCompositionPlan; when a PraxisTextValue key exists in the fallbackLocale dictionary, omit repeated text and let the compiler materialize the executable fallback.',
         'Use uiCompositionPlan.widgets[].componentId in plans; the compiler maps it to page.widgets[].definition.id.',
-        'Use uiCompositionPlan.bindings as the declarative source for wiring; the compiler emits page.composition.links.',
+        'Use uiCompositionPlan.selectionSyncs for repeated selection projections, contextScopes for repeated explicit widget context, and bindings for remaining wiring; constant values and state.initial become explicit inputs, while state references compile to page.composition.links.',
         'For nested component ports, use component-port endpoints with nestedPath in uiCompositionPlan.bindings; keep widget as the top-level owner and put the real child port in port/direction.',
         'NestedPath must be relative to the owner widget and must end with a widget segment containing a stable key. Do not use index as the only identity.',
         'Do not author nested links through owner.widgetEvent, deep bindingPath, page.connections, or host-specific wrapper outputs; those are legacy or bridge mechanisms.',
-        'Do not emit both uiCompositionPlan.bindings and hand-authored page.composition.links as competing sources of truth for the same preview.',
+        'Do not emit uiCompositionPlan shorthands/bindings and hand-authored page.composition.links as competing sources of truth for the same preview.',
         'Use page.widgets[].key as the merge key; avoid array indexes.',
         'Canvas items use 1-based col/row with integer spans.',
         'Widget definition id must match a registered component selector.',
@@ -13574,7 +13584,7 @@ const PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST = {
     componentId: 'praxis-page-builder',
     ownerPackage: '@praxisui/page-builder',
     configSchemaId: 'WidgetPageDefinition',
-    manifestVersion: '1.0.0',
+    manifestVersion: '1.1.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.' },
@@ -13765,11 +13775,11 @@ const PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST = {
             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', 'UiCompositionPlan.selectionSyncs', 'UiCompositionPlan.contextScopes', 'compileUiCompositionPlan', 'PAGE_BUILDER_WIDGET_AI_CATALOGS', 'ComponentDocMeta.configEditor'],
+                        reads: ['UiCompositionPlanAuthoringInput', 'UiCompositionPlan', 'UiCompositionPlanTemplateReference', 'UiCompositionPlanTemplateMaterialization', 'UiCompositionPlan.i18n', 'UiCompositionPlan.context', 'UiCompositionPlan.layout', 'UiCompositionPlan.selectionSyncs', 'UiCompositionPlan.contextScopes', 'resolveUiCompositionPlanTemplate', 'compileUiCompositionPlan', 'PAGE_BUILDER_WIDGET_AI_CATALOGS', 'ComponentDocMeta.configEditor'],
                         writes: ['compiledFormPatch.patch.page'],
                         identityKeys: ['uiCompositionPlan.id', 'widgetKey', 'uiCompositionPlan.bindings[].id', 'uiCompositionPlan.selectionSyncs[].id', 'uiCompositionPlan.contextScopes[].id'],
-                        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.',
+                        failureModes: ['ui-composition-plan-invalid', 'ui-composition-template-reference-invalid', 'ui-composition-template-not-found', 'ui-composition-template-hash-mismatch', 'ui-composition-template-overrides-unsupported', 'widget-catalog-missing', 'compiled-page-invalid', 'child-config-editor-missing'],
+                        description: 'Resolves an optional exact governed template reference and compiles the expanded 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'],
@@ -13904,8 +13914,9 @@ const PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST = {
     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.',
+        'UiCompositionPlan.i18n, context and layout compile into the corresponding WidgetPageDefinition fields so a complete page never depends on host-only enrichment. A key-only PraxisTextValue receives text from the fallbackLocale dictionary when available.',
         'UiCompositionPlan.selectionSyncs is an authoring shorthand that compiles into explicit canonical page.composition.links and is never persisted in WidgetPageDefinition.',
-        'UiCompositionPlan.contextScopes compiles constant context into explicit widget inputs and state context into explicit page.composition.links; runtime inheritance is never ambient.',
+        'UiCompositionPlan.contextScopes compiles constants and state.initial into explicit widget inputs, and state context into explicit page.composition.links; runtime inheritance is never ambient.',
         '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.',
@@ -14037,6 +14048,56 @@ const PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST = {
     ],
 };
 
+/**
+ * Pure, fail-closed normalization for an exact template reference.
+ *
+ * The function performs no HTTP, registry search or template selection. The governed backend must
+ * supply the exact materialization and its revision evidence before the existing compiler runs.
+ */
+function resolveUiCompositionPlanTemplate(input, materialization) {
+    if (!hasTemplateReference(input)) {
+        return { valid: true, referenced: false, plan: input, diagnostics: [] };
+    }
+    const diagnostics = validateTemplateReference(input);
+    if (diagnostics.length) {
+        return { valid: false, referenced: true, plan: null, diagnostics };
+    }
+    if (!materialization || materialization.registryKey !== input.templateRef.registryKey) {
+        return invalidTemplateResolution('ui-composition-template-not-found', 'The exact governed template was not supplied.');
+    }
+    if (!SHA_256_PATTERN.test(materialization.revision?.configSha256 ?? '')) {
+        return invalidTemplateResolution('ui-composition-template-revision-invalid', 'The governed template revision is invalid.');
+    }
+    if (materialization.revision.configSha256 !== input.templateRef.configSha256) {
+        return invalidTemplateResolution('ui-composition-template-hash-mismatch', 'The governed template content no longer matches the pinned hash.');
+    }
+    if (materialization.authoringPlan?.kind !== 'praxis.ui-composition-plan') {
+        return invalidTemplateResolution('ui-composition-template-authoring-plan-kind-invalid', 'The governed artifact is not a UI composition plan.');
+    }
+    if (materialization.authoringPlan.version !== '1.0') {
+        return invalidTemplateResolution('ui-composition-template-authoring-plan-version-invalid', 'The governed UI composition plan version is unsupported.');
+    }
+    const plan = clone(materialization.authoringPlan);
+    plan.diagnostics = {
+        ...(plan.diagnostics ?? {}),
+        templateResolution: {
+            registryKey: materialization.registryKey,
+            configSha256: materialization.revision.configSha256,
+            ...(materialization.revision.version == null ? {} : { version: materialization.revision.version }),
+            ...(materialization.revision.etag ? { etag: materialization.revision.etag } : {}),
+        },
+    };
+    return {
+        valid: true,
+        referenced: true,
+        plan,
+        diagnostics: [{
+                code: 'ui-composition-template-reference-resolved',
+                message: 'The exact governed template reference was resolved.',
+                path: 'templateRef',
+            }],
+    };
+}
 function compileUiCompositionPlan(plan) {
     const diagnostics = validateUiCompositionPlan(plan);
     if (diagnostics.length) {
@@ -14047,27 +14108,115 @@ function compileUiCompositionPlan(plan) {
         };
     }
     const bindings = expandedBindings(plan);
-    const widgets = materializeContextScopeConstants(plan, plan.widgets.map((widget) => toWidgetInstance(widget, bindings)));
+    const widgets = materializeContextScopeInputs(plan, plan.widgets.map((widget) => toWidgetInstance(widget, bindings)));
+    const page = {
+        i18n: clone(plan.i18n),
+        context: clone(plan.context),
+        layout: clone(plan.layout),
+        layoutPreset: plan.layoutPreset,
+        layoutPresetOptions: clone(plan.layoutPresetOptions),
+        canvas: resolveCanvas(plan),
+        deviceLayouts: clone(plan.deviceLayouts),
+        grouping: clone(plan.grouping),
+        slotAssignments: clone(plan.slotAssignments),
+        state: clone(plan.state),
+        themePreset: plan.themePreset,
+        widgets,
+        composition: {
+            version: '1.0.0',
+            links: bindings.map(toCompositionLink),
+        },
+    };
     return {
         valid: true,
-        page: {
-            layoutPreset: plan.layoutPreset,
-            layoutPresetOptions: clone(plan.layoutPresetOptions),
-            canvas: resolveCanvas(plan),
-            deviceLayouts: clone(plan.deviceLayouts),
-            grouping: clone(plan.grouping),
-            slotAssignments: clone(plan.slotAssignments),
-            state: clone(plan.state),
-            themePreset: plan.themePreset,
-            widgets,
-            composition: {
-                version: '1.0.0',
-                links: bindings.map(toCompositionLink),
-            },
-        },
+        page: materializeLocalizedFallbacks(page),
         diagnostics: [],
     };
 }
+const SHA_256_PATTERN = /^[0-9a-f]{64}$/;
+const TEMPLATE_REFERENCE_FIELDS = new Set(['version', 'kind', 'templateRef', 'overrides']);
+const TEMPLATE_REF_FIELDS = new Set(['registryKey', 'configSha256']);
+function hasTemplateReference(input) {
+    return input != null && typeof input === 'object' && 'templateRef' in input;
+}
+function validateTemplateReference(input) {
+    const diagnostics = [];
+    if (input.kind !== 'praxis.ui-composition-plan') {
+        diagnostics.push(templateDiagnostic('ui-composition-template-reference-kind-invalid', 'kind'));
+    }
+    if (input.version !== '1.0') {
+        diagnostics.push(templateDiagnostic('ui-composition-template-reference-version-invalid', 'version'));
+    }
+    if (!isRecord$1(input.templateRef)) {
+        diagnostics.push(templateDiagnostic('ui-composition-template-reference-object-required', 'templateRef'));
+        return diagnostics;
+    }
+    const registryKey = input.templateRef.registryKey;
+    if (typeof registryKey !== 'string' || !registryKey || registryKey !== registryKey.trim()) {
+        diagnostics.push(templateDiagnostic('ui-composition-template-registry-key-invalid', 'templateRef.registryKey'));
+    }
+    if (typeof input.templateRef.configSha256 !== 'string' || !SHA_256_PATTERN.test(input.templateRef.configSha256)) {
+        diagnostics.push(templateDiagnostic('ui-composition-template-config-sha256-invalid', 'templateRef.configSha256'));
+    }
+    if (Object.keys(input.templateRef).some((field) => !TEMPLATE_REF_FIELDS.has(field))
+        || Object.keys(input.templateRef).length !== TEMPLATE_REF_FIELDS.size) {
+        diagnostics.push(templateDiagnostic('ui-composition-template-reference-fields-invalid', 'templateRef'));
+    }
+    if (input.overrides !== undefined && (!isRecord$1(input.overrides) || Object.keys(input.overrides).length > 0)) {
+        diagnostics.push(templateDiagnostic('ui-composition-template-overrides-unsupported', 'overrides'));
+    }
+    if (Object.keys(input).some((field) => !TEMPLATE_REFERENCE_FIELDS.has(field))) {
+        diagnostics.push(templateDiagnostic('ui-composition-template-reference-mixed-plan'));
+    }
+    return diagnostics;
+}
+function invalidTemplateResolution(code, message) {
+    return {
+        valid: false,
+        referenced: true,
+        plan: null,
+        diagnostics: [{ code, message, path: 'templateRef' }],
+    };
+}
+function templateDiagnostic(code, path) {
+    return { code, message: 'The governed template reference is invalid.', path };
+}
+function isRecord$1(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Keeps authoring plans compact while preserving a portable executable page.
+ * A descriptor authored as `{ key }` inherits its runtime fallback from the
+ * page-owned fallback-locale dictionary. The source plan remains untouched.
+ */
+function materializeLocalizedFallbacks(page) {
+    const materialized = clone(page);
+    const fallbackLocale = materialized.i18n?.fallbackLocale?.trim() || 'pt-BR';
+    const dictionary = materialized.i18n?.dictionaries?.[fallbackLocale];
+    if (!dictionary)
+        return materialized;
+    const descriptorKeys = new Set(['key', 'text', 'params']);
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const record = value;
+        const keys = Object.keys(record);
+        const key = typeof record['key'] === 'string' ? record['key'].trim() : '';
+        if (key
+            && !Object.prototype.hasOwnProperty.call(record, 'text')
+            && keys.every((candidate) => descriptorKeys.has(candidate))
+            && typeof dictionary[key] === 'string') {
+            record['text'] = dictionary[key];
+        }
+        Object.values(record).forEach(visit);
+    };
+    visit(materialized);
+    return materialized;
+}
 function resolveCanvas(plan) {
     if (plan.canvas) {
         return clone(plan.canvas);
@@ -14075,6 +14224,13 @@ function resolveCanvas(plan) {
     if (!plan.widgets?.length) {
         return undefined;
     }
+    // An explicitly authored flow/grid layout is already a complete spatial
+    // decision. Synthesizing a canvas here would silently take precedence over
+    // that layout in the runtime. Preset- or role-driven plans still opt into
+    // automatic canvas materialization below.
+    if (plan.layout && !plan.layoutPreset?.trim() && !isMasterDetailPlan(plan)) {
+        return undefined;
+    }
     if (isMasterDetailPlan(plan)) {
         return masterDetailCanvas(plan.widgets);
     }
@@ -14247,7 +14403,14 @@ function validateSelectionSync(selectionSync, widgetKeys, diagnostics, path) {
     }
     for (const [sourceIndex, source] of (selectionSync.sources ?? []).entries()) {
         validateEndpoint(source, widgetKeys, diagnostics, `${path}.sources.${sourceIndex}`, false);
-        if (source?.kind === 'component-port' && source.direction !== 'output') {
+        if (source?.kind !== 'component-port') {
+            diagnostics.push({
+                code: 'selection-sync-source-component-port-required',
+                message: 'Selection sync sources must be component output ports.',
+                path: `${path}.sources.${sourceIndex}.kind`,
+            });
+        }
+        else if (source.direction !== 'output') {
             diagnostics.push({
                 code: 'selection-sync-source-direction-invalid',
                 message: 'Selection sync sources must be component output ports.',
@@ -14319,14 +14482,25 @@ function validateContextScope(contextScope, plan, widgetKeys, diagnostics, path)
                 path: `${path}.context`,
             });
         }
-        if (contextValue?.kind === 'state' && !contextValue.path?.trim()) {
-            diagnostics.push({
-                code: 'context-scope-state-path-required',
-                message: `Context value "${contextKey}" must declare a state path.`,
-                path: `${path}.context.${contextKey}.path`,
-            });
+        if (contextValue?.kind === 'state') {
+            if (!contextValue.path?.trim()) {
+                diagnostics.push({
+                    code: 'context-scope-state-path-required',
+                    message: `Context value "${contextKey}" must declare a state path.`,
+                    path: `${path}.context.${contextKey}.path`,
+                });
+            }
+        }
+        else if (contextValue?.kind === 'constant') {
+            if (!Object.prototype.hasOwnProperty.call(contextValue, 'value')) {
+                diagnostics.push({
+                    code: 'context-scope-constant-value-required',
+                    message: `Context value "${contextKey}" must declare a constant value.`,
+                    path: `${path}.context.${contextKey}.value`,
+                });
+            }
         }
-        else if (contextValue?.kind !== 'state' && contextValue?.kind !== 'constant') {
+        else {
             diagnostics.push({
                 code: 'context-scope-value-kind-invalid',
                 message: `Context value "${contextKey}" must be constant or state.`,
@@ -14634,7 +14808,7 @@ function expandContextScopeBindings(contextScope) {
         });
     });
 }
-function materializeContextScopeConstants(plan, sourceWidgets) {
+function materializeContextScopeInputs(plan, sourceWidgets) {
     const accessor = new NestedWidgetConfigAccessor();
     const widgets = sourceWidgets.map((widget) => clone(widget));
     for (const contextScope of plan.contextScopes ?? []) {
@@ -14647,10 +14821,17 @@ function materializeContextScopeConstants(plan, sourceWidgets) {
                 : Object.keys(contextScope.context);
             for (const contextKey of inheritedKeys) {
                 const contextValue = contextScope.context[contextKey];
-                if (!contextValue || contextValue.kind !== 'constant')
+                if (!contextValue)
+                    continue;
+                const hasInitial = contextValue.kind === 'state'
+                    && Object.prototype.hasOwnProperty.call(contextValue, 'initial');
+                if (contextValue.kind !== 'constant' && !hasInitial)
                     continue;
+                const inputValue = contextValue.kind === 'constant'
+                    ? contextValue.value
+                    : contextValue.initial;
                 if (target.nestedPath?.length) {
-                    const result = accessor.setNestedWidgetInput(widgets[widgetIndex], target.nestedPath, contextKey, contextValue.value);
+                    const result = accessor.setNestedWidgetInput(widgets[widgetIndex], target.nestedPath, contextKey, inputValue);
                     widgets[widgetIndex] = result.widget;
                 }
                 else {
@@ -14660,7 +14841,7 @@ function materializeContextScopeConstants(plan, sourceWidgets) {
                             ...widgets[widgetIndex].definition,
                             inputs: {
                                 ...(widgets[widgetIndex].definition.inputs ?? {}),
-                                [contextKey]: clone(contextValue.value),
+                                [contextKey]: clone(inputValue),
                             },
                         },
                     };
@@ -14678,6 +14859,7 @@ function toWidgetInstance(widget, bindings) {
     const outputs = linkedTopLevelOutputs(widget.key, widget.outputs, bindings);
     return {
         key: widget.key,
+        shell: clone(widget.shell),
         definition: {
             id: widget.componentId,
             bindingOrder: widget.bindingOrder,
@@ -25555,4 +25737,4 @@ function providePraxisPageBuilderMetadata() {
  * Generated bundle index. Do not edit.
  */
 
-export { ComponentPaletteDialogComponent, ConfirmDialogComponent, ConnectionEditorComponent, DynamicPageBuilderComponent, DynamicPageConfigEditorComponent, FloatingToolbarComponent, PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, PAGE_BUILDER_AI_CAPABILITIES, PAGE_BUILDER_COMPONENT_CONTEXT_PACK, PAGE_BUILDER_WIDGET_AI_CATALOGS, PLACEHOLDER, PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST, PRAXIS_PAGE_BUILDER_COMPONENT_METADATA, PageBuilderAgenticAuthoringService, PageConfigEditorComponent, TileToolbarComponent, WidgetShellEditorComponent, clearWidgetAiCatalogs, compileUiCompositionPlan, getPageAiCatalog, getWidgetAiCapabilities, providePageBuilderWidgetAiCatalogs, providePraxisPageBuilderMetadata, registerWidgetAiCatalog, registerWidgetAiCatalogs, validateUiCompositionPlan };
+export { ComponentPaletteDialogComponent, ConfirmDialogComponent, ConnectionEditorComponent, DynamicPageBuilderComponent, DynamicPageConfigEditorComponent, FloatingToolbarComponent, PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, PAGE_BUILDER_AI_CAPABILITIES, PAGE_BUILDER_COMPONENT_CONTEXT_PACK, PAGE_BUILDER_WIDGET_AI_CATALOGS, PLACEHOLDER, PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST, PRAXIS_PAGE_BUILDER_COMPONENT_METADATA, PageBuilderAgenticAuthoringService, PageConfigEditorComponent, TileToolbarComponent, WidgetShellEditorComponent, clearWidgetAiCatalogs, compileUiCompositionPlan, getPageAiCatalog, getWidgetAiCapabilities, providePageBuilderWidgetAiCatalogs, providePraxisPageBuilderMetadata, registerWidgetAiCatalog, registerWidgetAiCatalogs, resolveUiCompositionPlanTemplate, validateUiCompositionPlan };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/page-builder",
-  "version": "9.0.5-rc.2",
+  "version": "9.0.5-rc.21",
   "description": "Page and widget builder utilities for Praxis UI (grid, dynamic widgets, editors).",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -8,9 +8,9 @@
     "@angular/forms": "^21.0.0",
     "@angular/cdk": "^21.0.0",
     "@angular/material": "^21.0.0",
-    "@praxisui/ai": "^9.0.5-rc.2",
-    "@praxisui/core": "^9.0.5-rc.2",
-    "@praxisui/settings-panel": "^9.0.5-rc.2",
+    "@praxisui/ai": "^9.0.5-rc.21",
+    "@praxisui/core": "^9.0.5-rc.21",
+    "@praxisui/settings-panel": "^9.0.5-rc.21",
     "rxjs": "~7.8.0"
   },
   "dependencies": {

package/types/praxisui-page-builder.d.ts

@@ -1534,6 +1534,7 @@ interface UiCompositionPlanWidget {
     key: string;
     componentId: string;
     role?: string;
+    shell?: WidgetInstance['shell'];
     inputs?: Record<string, unknown>;
     outputs?: Record<string, unknown>;
     bindingOrder?: string[];
@@ -1575,6 +1576,8 @@ type UiCompositionPlanContextValue = {
     path: string;
     layer?: 'values' | 'derived' | 'transient';
     condition?: unknown;
+    /** Explicit value materialized before the first state propagation. */
+    initial?: unknown;
 };
 interface UiCompositionPlanContextScopeTarget {
     widget: string;
@@ -1583,8 +1586,9 @@ interface UiCompositionPlanContextScopeTarget {
 }
 /**
  * Groups reusable parent/resource context for one or more component targets.
- * Constants become explicit widget inputs and state values become explicit
- * canonical links during compilation; no hidden runtime inheritance remains.
+ * Constants and explicit state initial values become widget inputs, while
+ * state values become canonical links during compilation. No hidden runtime
+ * inheritance remains in the executable page.
  */
 interface UiCompositionPlanContextScope {
     id: string;
@@ -1596,6 +1600,12 @@ interface UiCompositionPlanContextScope {
 interface UiCompositionPlan {
     version: '1.0';
     kind: 'praxis.ui-composition-plan';
+    /** Page-owned business copy compiled verbatim into WidgetPageDefinition.i18n. */
+    i18n?: WidgetPageDefinition['i18n'];
+    /** Explicit page-wide context compiled into WidgetPageDefinition.context. */
+    context?: WidgetPageDefinition['context'];
+    /** Canonical responsive grid layout compiled into WidgetPageDefinition.layout. */
+    layout?: WidgetPageDefinition['layout'];
     layoutPreset?: string;
     layoutPresetOptions?: Record<string, unknown>;
     canvas?: WidgetPageCanvasLayout;
@@ -1608,7 +1618,43 @@ interface UiCompositionPlan {
     selectionSyncs?: UiCompositionPlanSelectionSync[];
     contextScopes?: UiCompositionPlanContextScope[];
     bindings?: UiCompositionPlanBinding[];
+    /** Non-executable authoring and resolution evidence; never copied into WidgetPageDefinition. */
+    diagnostics?: Record<string, unknown>;
 }
+interface UiCompositionPlanTemplateRef {
+    registryKey: string;
+    configSha256: string;
+}
+/** Compact intermediate authoring input. It is never a runtime persistence shape. */
+interface UiCompositionPlanTemplateReference {
+    version: '1.0';
+    kind: 'praxis.ui-composition-plan';
+    templateRef: UiCompositionPlanTemplateRef;
+    overrides?: Readonly<Record<string, never>>;
+}
+interface UiCompositionPlanTemplateRevision {
+    version?: number;
+    etag?: string;
+    configSha256: string;
+}
+/** Exact template body and revision evidence supplied by the governed backend. */
+interface UiCompositionPlanTemplateMaterialization {
+    registryKey: string;
+    revision: UiCompositionPlanTemplateRevision;
+    authoringPlan: UiCompositionPlan;
+}
+type UiCompositionPlanAuthoringInput = UiCompositionPlan | UiCompositionPlanTemplateReference;
+type UiCompositionPlanTemplateResolutionResult = {
+    valid: true;
+    referenced: boolean;
+    plan: UiCompositionPlan;
+    diagnostics: UiCompositionPlanDiagnostic[];
+} | {
+    valid: false;
+    referenced: true;
+    plan: null;
+    diagnostics: UiCompositionPlanDiagnostic[];
+};
 interface UiCompositionPlanDiagnostic {
     code: string;
     message: string;
@@ -1623,6 +1669,13 @@ type UiCompositionPlanCompileResult = {
     page: null;
     diagnostics: UiCompositionPlanDiagnostic[];
 };
+/**
+ * Pure, fail-closed normalization for an exact template reference.
+ *
+ * The function performs no HTTP, registry search or template selection. The governed backend must
+ * supply the exact materialization and its revision evidence before the existing compiler runs.
+ */
+declare function resolveUiCompositionPlanTemplate(input: UiCompositionPlanAuthoringInput, materialization?: UiCompositionPlanTemplateMaterialization): UiCompositionPlanTemplateResolutionResult;
 declare function compileUiCompositionPlan(plan: UiCompositionPlan): UiCompositionPlanCompileResult;
 declare function validateUiCompositionPlan(plan: UiCompositionPlan): UiCompositionPlanDiagnostic[];
 
@@ -2133,5 +2186,5 @@ declare const PRAXIS_PAGE_BUILDER_COMPONENT_METADATA: ComponentDocMeta;
 /** Provider para auto-registrar metadados do componente Page Builder. */
 declare function providePraxisPageBuilderMetadata(): Provider;
 
-export { ComponentPaletteDialogComponent, ConfirmDialogComponent, ConnectionEditorComponent, DynamicPageBuilderComponent, DynamicPageConfigEditorComponent, FloatingToolbarComponent, PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, PAGE_BUILDER_AI_CAPABILITIES, PAGE_BUILDER_COMPONENT_CONTEXT_PACK, PAGE_BUILDER_WIDGET_AI_CATALOGS, PLACEHOLDER, PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST, PRAXIS_PAGE_BUILDER_COMPONENT_METADATA, PageBuilderAgenticAuthoringService, PageConfigEditorComponent, TileToolbarComponent, WidgetShellEditorComponent, clearWidgetAiCatalogs, compileUiCompositionPlan, getPageAiCatalog, getWidgetAiCapabilities, providePageBuilderWidgetAiCatalogs, providePraxisPageBuilderMetadata, registerWidgetAiCatalog, registerWidgetAiCatalogs, validateUiCompositionPlan };
-export type { Capability, CapabilityCatalog, CapabilityCategory, ComponentPaletteData, ComponentPaletteSelection, ConfirmDialogData, PageBuilderAgenticAuthoringAttachmentSummary, PageBuilderAgenticAuthoringCandidate, PageBuilderAgenticAuthoringComponentCapabilitiesResult, PageBuilderAgenticAuthoringComponentCapability, PageBuilderAgenticAuthoringComponentCapabilityCatalog, PageBuilderAgenticAuthoringComponentCapabilityExample, PageBuilderAgenticAuthoringComponentFieldAlias, PageBuilderAgenticAuthoringConversationMessage, PageBuilderAgenticAuthoringGateResult, PageBuilderAgenticAuthoringIntentResolutionRequest, PageBuilderAgenticAuthoringIntentResolutionResult, PageBuilderAgenticAuthoringOptions, PageBuilderAgenticAuthoringPendingClarification, PageBuilderAgenticAuthoringPromptRequest, PageBuilderAgenticAuthoringProvider, PageBuilderAgenticAuthoringQuickReply, PageBuilderAgenticAuthoringResourceCandidatesRequest, PageBuilderAgenticAuthoringResourceCandidatesResult, PageBuilderAgenticAuthoringSharedRuleHandoff, PageBuilderAgenticAuthoringTarget, PageBuilderAgenticAuthoringTurnStreamConnectionError, PageBuilderAgenticAuthoringTurnStreamEvent, PageBuilderAgenticAuthoringTurnStreamRequest, PageBuilderAgenticAuthoringTurnStreamStartResponse, PageBuilderApplyRequest, PageBuilderApplyResult, PageBuilderCompiledFormPatch, PageBuilderMinimalFormPlanResult, PageBuilderPreviewDiagnostics, PageBuilderPreviewResult, PageBuilderProjectKnowledgeAudit, UiCompositionPlan, UiCompositionPlanBinding, UiCompositionPlanCompileResult, UiCompositionPlanComponentPortEndpoint, UiCompositionPlanContextScope, UiCompositionPlanContextScopeTarget, UiCompositionPlanContextValue, UiCompositionPlanDiagnostic, UiCompositionPlanEndpoint, UiCompositionPlanGlobalActionEndpoint, UiCompositionPlanInputSource, UiCompositionPlanSelectionSync, UiCompositionPlanSelectionSyncMapping, UiCompositionPlanSourceEndpoint, UiCompositionPlanStateEndpoint, UiCompositionPlanTargetEndpoint, UiCompositionPlanTransform, UiCompositionPlanWidget, ValueKind };
+export { ComponentPaletteDialogComponent, ConfirmDialogComponent, ConnectionEditorComponent, DynamicPageBuilderComponent, DynamicPageConfigEditorComponent, FloatingToolbarComponent, PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, PAGE_BUILDER_AI_CAPABILITIES, PAGE_BUILDER_COMPONENT_CONTEXT_PACK, PAGE_BUILDER_WIDGET_AI_CATALOGS, PLACEHOLDER, PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST, PRAXIS_PAGE_BUILDER_COMPONENT_METADATA, PageBuilderAgenticAuthoringService, PageConfigEditorComponent, TileToolbarComponent, WidgetShellEditorComponent, clearWidgetAiCatalogs, compileUiCompositionPlan, getPageAiCatalog, getWidgetAiCapabilities, providePageBuilderWidgetAiCatalogs, providePraxisPageBuilderMetadata, registerWidgetAiCatalog, registerWidgetAiCatalogs, resolveUiCompositionPlanTemplate, validateUiCompositionPlan };
+export type { Capability, CapabilityCatalog, CapabilityCategory, ComponentPaletteData, ComponentPaletteSelection, ConfirmDialogData, PageBuilderAgenticAuthoringAttachmentSummary, PageBuilderAgenticAuthoringCandidate, PageBuilderAgenticAuthoringComponentCapabilitiesResult, PageBuilderAgenticAuthoringComponentCapability, PageBuilderAgenticAuthoringComponentCapabilityCatalog, PageBuilderAgenticAuthoringComponentCapabilityExample, PageBuilderAgenticAuthoringComponentFieldAlias, PageBuilderAgenticAuthoringConversationMessage, PageBuilderAgenticAuthoringGateResult, PageBuilderAgenticAuthoringIntentResolutionRequest, PageBuilderAgenticAuthoringIntentResolutionResult, PageBuilderAgenticAuthoringOptions, PageBuilderAgenticAuthoringPendingClarification, PageBuilderAgenticAuthoringPromptRequest, PageBuilderAgenticAuthoringProvider, PageBuilderAgenticAuthoringQuickReply, PageBuilderAgenticAuthoringResourceCandidatesRequest, PageBuilderAgenticAuthoringResourceCandidatesResult, PageBuilderAgenticAuthoringSharedRuleHandoff, PageBuilderAgenticAuthoringTarget, PageBuilderAgenticAuthoringTurnStreamConnectionError, PageBuilderAgenticAuthoringTurnStreamEvent, PageBuilderAgenticAuthoringTurnStreamRequest, PageBuilderAgenticAuthoringTurnStreamStartResponse, PageBuilderApplyRequest, PageBuilderApplyResult, PageBuilderCompiledFormPatch, PageBuilderMinimalFormPlanResult, PageBuilderPreviewDiagnostics, PageBuilderPreviewResult, PageBuilderProjectKnowledgeAudit, UiCompositionPlan, UiCompositionPlanAuthoringInput, UiCompositionPlanBinding, UiCompositionPlanCompileResult, UiCompositionPlanComponentPortEndpoint, UiCompositionPlanContextScope, UiCompositionPlanContextScopeTarget, UiCompositionPlanContextValue, UiCompositionPlanDiagnostic, UiCompositionPlanEndpoint, UiCompositionPlanGlobalActionEndpoint, UiCompositionPlanInputSource, UiCompositionPlanSelectionSync, UiCompositionPlanSelectionSyncMapping, UiCompositionPlanSourceEndpoint, UiCompositionPlanStateEndpoint, UiCompositionPlanTargetEndpoint, UiCompositionPlanTemplateMaterialization, UiCompositionPlanTemplateRef, UiCompositionPlanTemplateReference, UiCompositionPlanTemplateResolutionResult, UiCompositionPlanTemplateRevision, UiCompositionPlanTransform, UiCompositionPlanWidget, ValueKind };