@salsita-ai/sdk 0.50.0-develop.da56a0c6c3 → 0.50.0-develop.ea458ea381

package/dist/application-spec/generate-application/code/templates/domain-spec/generate-domain-block.js

@@ -1,87 +1,90 @@
-import{skipApplicationTypeImports as e}from"../../common/index.js";import{generateComponentOpticsCode as n}from"./generate-component-optics.js";import{generateDefaultsBlock as t}from"./generate-defaults.js";import{generateInvariantsBlock as a}from"./generate-invariants.js";import{generateRelationExpressionsCode as i}from"./generate-relation-expressions.js";import{generateStaticValueCode as o}from"./generate-static-value-code.js";import{generateValueExpressionsCode as s}from"./generate-value-expressions.js";let r="@salsita-ai/sdk/domain",l=(e,n,t)=>{let a=[],i=[];for(let o of e.modelVersion.entitySchemas){let e=JSON.stringify(o.shapeSchema,null,2);a.push(`${t}const ${o.entityType} = new DomainEntityReflection<${n}${o.entityType}>('${o.entityType}', [${e}])`),i.push(String(o.entityType))}return{entityDecls:a.join("\n"),entityNames:i}};export const generateDomainBlock=m=>{let{domainSpec:$,invariants:p,typePrefix:d,versionNsPrefix:c,isAdmin:u,modelVersionsExportName:y,relationExpressionsExportName:h,componentOpticsExportName:f,valueExpressionsExportName:E,createRecipeExportName:D,imports:R,registerApplicationTypeImports:g=e}=m;R.addImport(r,"$DomainEntityReflection"),R.addImport(r,"DomainBuilder"),R.addImport(r,"DomainComponentOpticBuilder"),R.addImport(r,"DomainEntityReflection"),R.addImport(r,"EnhancedAliasReflection"),R.addImport(r,"InvariantBuilder"),R.addImport(r,"RawAliasReflection"),R.addImport(r,"SchemaReflection"),R.addImport(r,"createCustomExpressionFactory"),R.addImport(r,"createCustomInvariantFactory"),u&&(R.addImport(r,"commonAdminCustomExpressions"),R.addImport(r,"commonAdminViolationExpressions"),R.addImport(r,"createMapPublishedRevisionDataHandlerFactory"),R.addImport(r,"createMapPublishedChunkedDataHandlerFactory"),R.addImport(r,"createDataRowValidatorHandler"),R.addImport(r,"createSheetValidatorHandler")),R.addTypeImport(r,"SchemaOfObject");let{entityTypes:S,entitySchemas:v}=$.latestModel,x=[...$.latestModel.aliases],j=x.map(([e])=>String(e)),C=j.includes("RootEntity")?"RootEntity":"AnyDomainEntity",{resolvedVersions:I}=$,M=I.latestVersion,A=d?`${d}.`:"",B=new Map([...$.expressions.constants].map(([e,n])=>[String(e),n])),w=(e,n)=>{let t=[...B.get(n)?.keys()??[]],a=t.length>0?`, ${t.map(e=>`'${e}'`).join(" | ")}`:"";return`${e}<${A}$${n}${a}>`},b=e=>{let n=B.get(e);if(!n)return"{}";let t=[...n].map(([e,n])=>{let t=o(n,R).replaceAll("\n","\n    ");return`    ${e}: ${t},`});return`{
+import{skipApplicationTypeImports as e}from"../../common/index.js";import{generateComponentOpticsCode as n}from"./generate-component-optics.js";import{generateDefaultsBlock as t}from"./generate-defaults.js";import{generateInvariantsBlock as i}from"./generate-invariants.js";import{generateRelationExpressionsCode as a}from"./generate-relation-expressions.js";import{generateStaticValueCode as o}from"./generate-static-value-code.js";import{generateValueExpressionsCode as s}from"./generate-value-expressions.js";let r="@salsita-ai/sdk/domain",m=(e,n,t)=>{let i=[],a=[];for(let o of e.modelVersion.entitySchemas){let e=JSON.stringify(o.shapeSchema,null,2);i.push(`${t}const ${o.entityType} = new DomainEntityReflection<${n}${o.entityType}>('${o.entityType}', [${e}])`),a.push(String(o.entityType))}return{entityDecls:i.join("\n"),entityNames:a}};export const generateDomainBlock=l=>{let{domainSpec:$,invariants:p,actions:c,typePrefix:d,versionNsPrefix:u,isAdmin:y,modelVersionsExportName:h,relationExpressionsExportName:f,componentOpticsExportName:D,valueExpressionsExportName:E,createRecipeExportName:S,imports:R,registerApplicationTypeImports:g=e}=l;R.addImport(r,"$DomainEntityReflection"),R.addImport(r,"DomainBuilder"),R.addImport(r,"DomainComponentOpticBuilder"),R.addImport(r,"DomainEntityReflection"),R.addImport(r,"EnhancedAliasReflection"),R.addImport(r,"InvariantBuilder"),R.addImport(r,"RawAliasReflection"),R.addImport(r,"SchemaReflection"),R.addImport(r,"createCustomExpressionFactory"),R.addImport(r,"createCustomInvariantFactory"),y&&(R.addImport(r,"commonAdminCustomExpressions"),R.addImport(r,"commonAdminViolationExpressions"),R.addImport(r,"createMapPublishedRevisionDataHandlerFactory"),R.addImport(r,"createMapPublishedChunkedDataHandlerFactory"),R.addImport(r,"createDataRowValidatorHandler"),R.addImport(r,"createSheetValidatorHandler")),R.addTypeImport(r,"SchemaOfObject"),c&&(R.addImport(r,"createActionFactory"),R.addTypeImport(r,"ActionDefinition"));let{entityTypes:v,entitySchemas:x}=$.latestModel,A=[...$.latestModel.aliases],j=A.map(([e])=>String(e)),C=j.includes("RootEntity")?"RootEntity":"AnyDomainEntity",{resolvedVersions:I}=$,M=I.latestVersion,w=d?`${d}.`:"",B=new Map([...$.expressions.constants].map(([e,n])=>[String(e),n])),b=(e,n)=>{let t=[...B.get(n)?.keys()??[]],i=t.length>0?`, ${t.map(e=>`'${e}'`).join(" | ")}`:"";return`${e}<${w}$${n}${i}>`},P=e=>{let n=B.get(e);if(!n)return"{}";let t=[...n].map(([e,n])=>{let t=o(n,R).replaceAll("\n","\n    ");return`    ${e}: ${t},`});return`{
 ${t.join("\n")}
-  }`},P=v.map(e=>{let n=JSON.stringify(e.shapeSchema,null,2);return`  const ${e.entityType} = new DomainEntityReflection<${A}${e.entityType}>('${e.entityType}', [${n}])`}),k=x.map(([e,n])=>{let t=n.map(String).join(", ");return`  const ${e} = new RawAliasReflection<${A}${e}>('${e}', [${t}])`}),H=[...$.latestModel.commonTypes],F=H.map(([e])=>String(e)),O=I.versionedModels.filter(e=>!e.isLatest).map(e=>`${c}${e.version}`);g(R,[...u?["Admin",...O]:[...S.map(String),...j,...F,...S.map(e=>`$${String(e)}`),...j.map(e=>`$${e}`),"Aliases","$Map",...O],"PublishedData","SessionData","FrontendData",...u?[]:["BackendData"]]);let V=H.map(([e,n])=>{let t=JSON.stringify(n.runtimeSchema,null,2);return n.schema.enum?.length&&n.schema.enum.every(e=>"string"==typeof e)?`  const ${e}: EnumLike<${A}${e}> = new EnumReflection('${e}', ${t}) as EnumLike<${A}${e}>`:`  const ${e}: SchemaReflection<${A}${e}> = new SchemaReflection('${e}', ${t})`}),T=[...$.latestModel.shapes],J=T.map(([e,n])=>{let t=JSON.stringify(n.runtimeSchema,null,2);return`  const ${e}Shape = new SchemaReflection('${e}Shape', ${t})`}),N=T.map(([e])=>`${e}Shape`),L=j.map(e=>`    ${e}: ${e}.types,`).join("\n"),_=j.map(e=>`    ${e},`).join("\n"),z=F.map(e=>`    ${e},`).join("\n"),G=N.map(e=>`    ${e},`).join("\n"),q=S.map(e=>`    ${e},`).join("\n"),K=[];for(let[e,n]of $.expressions.expressions)n.size>0&&K.push(`  const ${e}Expressions = ${JSON.stringify([...n.keys()])}`);let Q=S.map(e=>{let n=$.expressions.entityExpressions.get(e),t=(n?.shapeGroups??[]).map(e=>`${e}Expressions`),a=t.length>0?t.map(e=>`...${e}`).join(", "):"",i=w("$DomainEntityReflection",String(e));return`  const $${e}: ${i} = new ${i}('${e}', [${a}], ${b(String(e))})`}).join("\n"),U=S.map(e=>`    ${e}: $${e},`).join("\n"),W=x.map(([e,n])=>{let t=n.map(e=>JSON.stringify(String(e))).join(", "),a=w("EnhancedAliasReflection",String(e));return`  const $${e}: ${a} = new ${a}('$${e}', [${t}], ${b(String(e))})`}).join("\n"),X=[...S.map(String),...j].map(e=>`    $${e},`).join("\n"),Y=[],Z=[];for(let e of I.versionedModels)if(e.isLatest)Y.push(`  ${e.version}: entities,`),Z.push(`  readonly ${e.version}: {
-${S.map(e=>`    readonly ${String(e)}: DomainEntityReflection<${A}${String(e)}>`).join("\n")}
-  }`);else{let n=`${c}${e.version}.`,{entityDecls:t,entityNames:a}=l(e,n,"    "),i=a.map(e=>`      ${e},`).join("\n");Y.push(`  ${e.version}: (() => {
+  }`},k=x.map(e=>{let n=JSON.stringify(e.shapeSchema,null,2);return`  const ${e.entityType} = new DomainEntityReflection<${w}${e.entityType}>('${e.entityType}', [${n}])`}),F=A.map(([e,n])=>{let t=n.map(String).join(", ");return`  const ${e} = new RawAliasReflection<${w}${e}>('${e}', [${t}])`}),H=[...$.latestModel.commonTypes],V=H.map(([e])=>String(e)),O=I.versionedModels.filter(e=>!e.isLatest).map(e=>`${u}${e.version}`);g(R,[...y?["Admin",...O]:[...v.map(String),...j,...V,...v.map(e=>`$${String(e)}`),...j.map(e=>`$${e}`),"Aliases","$Map",...O,...c?["ActionTypes","NavigationState","ViewState","ToolState","ExportState"]:[]],"PublishedData","SessionData","FrontendData",...y?[]:["BackendData"]]);let T=H.map(([e,n])=>{let t=JSON.stringify(n.runtimeSchema,null,2);return n.schema.enum?.length&&n.schema.enum.every(e=>"string"==typeof e)?`  const ${e}: EnumLike<${w}${e}> = new EnumReflection('${e}', ${t}) as EnumLike<${w}${e}>`:`  const ${e}: SchemaReflection<${w}${e}> = new SchemaReflection('${e}', ${t})`}),N=[...$.latestModel.shapes],J=N.map(([e,n])=>{let t=JSON.stringify(n.runtimeSchema,null,2);return`  const ${e}Shape = new SchemaReflection('${e}Shape', ${t})`}),L=N.map(([e])=>`${e}Shape`),_=j.map(e=>`    ${e}: ${e}.types,`).join("\n"),z=j.map(e=>`    ${e},`).join("\n"),G=V.map(e=>`    ${e},`).join("\n"),q=L.map(e=>`    ${e},`).join("\n"),K=v.map(e=>`    ${e},`).join("\n"),Q=[];for(let[e,n]of $.expressions.expressions)n.size>0&&Q.push(`  const ${e}Expressions = ${JSON.stringify([...n.keys()])}`);let U=v.map(e=>{let n=$.expressions.entityExpressions.get(e),t=(n?.shapeGroups??[]).map(e=>`${e}Expressions`),i=t.length>0?t.map(e=>`...${e}`).join(", "):"",a=b("$DomainEntityReflection",String(e));return`  const $${e}: ${a} = new ${a}('${e}', [${i}], ${P(String(e))})`}).join("\n"),W=v.map(e=>`    ${e}: $${e},`).join("\n"),X=A.map(([e,n])=>{let t=n.map(e=>JSON.stringify(String(e))).join(", "),i=b("EnhancedAliasReflection",String(e));return`  const $${e}: ${i} = new ${i}('$${e}', [${t}], ${P(String(e))})`}).join("\n"),Y=[...v.map(String),...j].map(e=>`    $${e},`).join("\n"),Z=[],ee=[];for(let e of I.versionedModels)if(e.isLatest)Z.push(`  ${e.version}: entities,`),ee.push(`  readonly ${e.version}: {
+${v.map(e=>`    readonly ${String(e)}: DomainEntityReflection<${w}${String(e)}>`).join("\n")}
+  }`);else{let n=`${u}${e.version}.`,{entityDecls:t,entityNames:i}=m(e,n,"    "),a=i.map(e=>`      ${e},`).join("\n");Z.push(`  ${e.version}: (() => {
 ${t}
     return {
-${i}
+${a}
     } as const
-  })(),`),Z.push(`  readonly ${e.version}: {
-${a.map(e=>`    readonly ${e}: DomainEntityReflection<${n}${e}>`).join("\n")}
-  }`)}let ee=u?"adminDomainBuilder":"domainBuilder",en=u?"attachAdminComponent":"attachComponent",et=u?"implementAdminCustomExpressions":"implementCustomExpressions",ea=u?"implementCustomAdminInvariants":"implementCustomInvariants",ei=u?"adminInvariantBuilder":"invariantBuilder",eo=u?"adminModel":"model",es=u?"adminEnhancedModel":"enhancedModel",er=u?"implementAdminRelation":"implementRelation",el=u?"__adminDomain":"__configuratorDomain",em=`${A}AnyDomainEntity, ${A}RootEntity, ${A}$Map, PublishedData, SessionData, FrontendData, ${A}Aliases`,e$=`<${em}>`,ep=a(p,em,R),ed=(e,n)=>e===n?e:`${e}: ${n}`,ec=[...$.expressions.expressions.values()].some(e=>[...e.values()].some(e=>"relation"===e.implementation.kind));ec&&R.addImport(r,"createRelationFactory");let eu=ec?`
-  const ${er} = createRelationFactory${e$}(aliases)
-
-  const relationExpressions = ${i($.expressions,er)}`:"\n  const relationExpressions = {} as const",ey=`
-  const componentOptics = ${n($.components,R)}`,eh=`
-  const valueExpressions = ${s($.expressions,R,"implementCustomExpressions",u?{PresetCategory:"commonAdminCustomExpressions.PresetCategory"}:{})}`;R.addImport(r,"RecipeFactoryBuilder");let ef=t($.defaults,R),eE=`
-  const createRecipe = RecipeFactoryBuilder.forAliases<${A}AnyDomainEntity, ${A}Aliases>(aliases)
+  })(),`),ee.push(`  readonly ${e.version}: {
+${i.map(e=>`    readonly ${e}: DomainEntityReflection<${n}${e}>`).join("\n")}
+  }`)}let en=y?"adminDomainBuilder":"domainBuilder",et=y?"attachAdminComponent":"attachComponent",ei=y?"implementAdminCustomExpressions":"implementCustomExpressions",ea=y?"implementCustomAdminInvariants":"implementCustomInvariants",eo=y?"adminInvariantBuilder":"invariantBuilder",es=y?"adminModel":"model",er=y?"adminEnhancedModel":"enhancedModel",em=y?"implementAdminRelation":"implementRelation",el=y?"__adminDomain":"__configuratorDomain",e$="PublishedData, SessionData, FrontendData",ep=`${w}AnyDomainEntity, ${w}RootEntity, ${w}$Map, ${e$}, ${w}Aliases`,ec=`<${ep}>`,ed=i(p,ep,R),eu=(e,n)=>e===n?e:`${e}: ${n}`,ey=[...$.expressions.expressions.values()].some(e=>[...e.values()].some(e=>"relation"===e.implementation.kind));ey&&R.addImport(r,"createRelationFactory");let eh=ey?`
+  const ${em} = createRelationFactory${ec}(aliases)
+
+  const relationExpressions = ${a($.expressions,em)}`:"\n  const relationExpressions = {} as const",ef=`
+  const componentOptics = ${n($.components,R)}`,eD=`
+  const valueExpressions = ${s($.expressions,R,"implementCustomExpressions",y?{PresetCategory:"commonAdminCustomExpressions.PresetCategory"}:{})}`;R.addImport(r,"RecipeFactoryBuilder");let eE=t($.defaults,R),eS=[...c?.values()??[]].map(e=>({name:String(e.name),...void 0===e.description?{}:{description:e.description},params:e.paramsSchema})),eR=c?`
+  const actionDefinitions: readonly ActionDefinition[] = ${JSON.stringify(eS,null,2).replaceAll("\n","\n  ")}
+
+  const implementActions = createActionFactory<${w}AnyDomainEntity, ${w}RootEntity, ${w}$Map, ${e$}, NavigationState, ViewState, ToolState, ExportState, ActionTypes>()`:"",eg=`
+  const createRecipe = RecipeFactoryBuilder.forAliases<${w}AnyDomainEntity, ${w}Aliases>(aliases)
     .forEntities(AnyDomainEntity.reflections)
     .withDefaults(defaults)
-    .build()`,eD=[...S.map(e=>`  readonly ${String(e)}: DomainEntityReflection<${A}${String(e)}>`),...j.map(e=>`  readonly ${e}: RawAliasReflection<${A}${e}>`),...H.map(([e,n])=>{let t=n.schema.enum?.length&&n.schema.enum.every(e=>"string"==typeof e)?"EnumLike":"SchemaReflection";return`  readonly ${e}: ${t}<${A}${e}>`}),...N.map(e=>`  readonly ${e}: SchemaReflection<unknown>`)].join("\n"),eR=`{
-${eD}
-}`,eg=[...S.map(e=>`  readonly $${String(e)}: ${w("$DomainEntityReflection",String(e))}`),...j.map(e=>`  readonly $${e}: ${w("EnhancedAliasReflection",e)}`)].join("\n"),eS=`{
-${eg}
-}`,ev=`{
-${Z.join("\n")}
+    .build()`,ev=[...v.map(e=>`  readonly ${String(e)}: DomainEntityReflection<${w}${String(e)}>`),...j.map(e=>`  readonly ${e}: RawAliasReflection<${w}${e}>`),...H.map(([e,n])=>{let t=n.schema.enum?.length&&n.schema.enum.every(e=>"string"==typeof e)?"EnumLike":"SchemaReflection";return`  readonly ${e}: ${t}<${w}${e}>`}),...L.map(e=>`  readonly ${e}: SchemaReflection<unknown>`)].join("\n"),ex=`{
+${ev}
+}`,eA=[...v.map(e=>`  readonly $${String(e)}: ${b("$DomainEntityReflection",String(e))}`),...j.map(e=>`  readonly $${e}: ${b("EnhancedAliasReflection",e)}`)].join("\n"),ej=`{
+${eA}
+}`,eC=`{
+${ee.join("\n")}
 }`;return`const ${el} = (() => {
   const modelVersion = ${M}
 
-  ${ef}
-
-${P.join("\n")}
+  ${eE}
 
 ${k.join("\n")}
 
-${V.join("\n")}
+${F.join("\n")}
+
+${T.join("\n")}
 
 ${J.join("\n")}
 
   const aliases = {
-${L}
+${_}
   } as const
 
   const entities = {
-${q}
+${K}
   } as const
 
   const model = {
-${q}
-${_}
+${K}
 ${z}
 ${G}
+${q}
   } as const
 
-${K.length>0?K.join("\n")+"\n":""}
-${Q}
-${W}
-  const $entityReflections = {
+${Q.length>0?Q.join("\n")+"\n":""}
 ${U}
+${X}
+  const $entityReflections = {
+${W}
   }
 
   const enhancedModel = {
-${X}
+${Y}
   } as const
 
-  const implementCustomExpressions = createCustomExpressionFactory${e$}({})
-${eu}
-${eh}
+  const implementCustomExpressions = createCustomExpressionFactory${ec}({})
+${eR}${eh}
+${eD}
 
   const modelVersions = {
-${Y.join("\n")}
+${Z.join("\n")}
   } as const
-  const attachComponent = DomainComponentOpticBuilder.from${e$}(aliases)
-
-${ep}
-  const invariantBuilder = new InvariantBuilder${e$}(aliases)${u?"\n    .withInvariants(implementCustomInvariants(commonAdminViolationExpressions))":""}
-${u?`
-  const createMapPublishedRevisionDataHandler = createMapPublishedRevisionDataHandlerFactory<${A}AnyDomainEntity, ${A}RootEntity, ${A}$Map, PublishedData>()
-  const createMapPublishedChunkedDataHandler = createMapPublishedChunkedDataHandlerFactory<${A}AnyDomainEntity, ${A}RootEntity, ${A}$Map>()
-`:""}${ey}
-${eE}
+  const attachComponent = DomainComponentOpticBuilder.from${ec}(aliases)
+
+${ed}
+  const invariantBuilder = new InvariantBuilder${ec}(aliases)${y?"\n    .withInvariants(implementCustomInvariants(commonAdminViolationExpressions))":""}
+${y?`
+  const createMapPublishedRevisionDataHandler = createMapPublishedRevisionDataHandlerFactory<${w}AnyDomainEntity, ${w}RootEntity, ${w}$Map, PublishedData>()
+  const createMapPublishedChunkedDataHandler = createMapPublishedChunkedDataHandlerFactory<${w}AnyDomainEntity, ${w}RootEntity, ${w}$Map>()
+`:""}${ef}
+${eg}
 
   return {
-    domainBuilder: DomainBuilder.from${e$}(
+    domainBuilder: DomainBuilder.from${ec}(
       entities,
       aliases,
       $entityReflections,
@@ -90,13 +93,13 @@ ${eE}
       PublishedData,
       SessionData,
       FrontendData,
-      ${u?"undefined":"BackendData"},
-      ${u}
-    ).withExpressions(valueExpressions),
-    attachComponent,
+      ${y?"undefined":"BackendData"},
+      ${y}
+    ).withExpressions(valueExpressions)${c?".withActions(actionDefinitions)":""},
+    attachComponent,${c?"\n    implementActions,":""}
     implementCustomExpressions,
     implementCustomInvariants,
-    invariantBuilder,${u?`
+    invariantBuilder,${y?`
     createMapPublishedRevisionDataHandler,
     createMapPublishedChunkedDataHandler,`:""}
     model,
@@ -110,20 +113,21 @@ ${eE}
 })()
 
 const {
-  ${ed("domainBuilder",ee)},
-  ${ed("attachComponent",en)},
-  ${ed("implementCustomExpressions",et)},
-  ${ed("implementCustomInvariants",ea)},
-  ${ed("invariantBuilder",ei)},${u?`
+  ${eu("domainBuilder",en)},
+  ${eu("attachComponent",et)},
+  ${eu("implementCustomExpressions",ei)},
+  ${eu("implementCustomInvariants",ea)},
+  ${eu("invariantBuilder",eo)},${y?`
   createMapPublishedRevisionDataHandler,
-  createMapPublishedChunkedDataHandler,`:""}
-  ${ed("relationExpressions",h)},
-  ${ed("valueExpressions",E)},
-  ${ed("componentOptics",f)},
-  ${ed("createRecipe",D)},
+  createMapPublishedChunkedDataHandler,`:`
+  implementActions,`}
+  ${eu("relationExpressions",f)},
+  ${eu("valueExpressions",E)},
+  ${eu("componentOptics",D)},
+  ${eu("createRecipe",S)},
 } = ${el}
 
-const ${eo}: ${eR} = ${el}.model
-const ${es}: ${eS} = ${el}.enhancedModel
-const ${y}: ${ev} = ${el}.modelVersions
-export { ${ee}, ${en}, ${et}, ${ea}, ${ei}, ${eo}, ${es}, ${h}, ${E}, ${f}, ${y}, ${D}${u?", createMapPublishedRevisionDataHandler, createMapPublishedChunkedDataHandler, createDataRowValidatorHandler, createSheetValidatorHandler":""} }`};
+const ${es}: ${ex} = ${el}.model
+const ${er}: ${ej} = ${el}.enhancedModel
+const ${h}: ${eC} = ${el}.modelVersions
+export { ${en}, ${et}, ${ei}, ${ea}, ${eo}, ${es}, ${er}, ${f}, ${E}, ${D}, ${h}, ${S}${y?", createMapPublishedRevisionDataHandler, createMapPublishedChunkedDataHandler, createDataRowValidatorHandler, createSheetValidatorHandler":", implementActions"} }`};

package/dist/application-spec/generate-application/code/templates/domain-spec/generate-phx-globals.js

@@ -10,6 +10,7 @@ globalThis.phx.domain = {
   enhancedModel,
   implementCustomExpressions,
   implementCustomInvariants,
+  implementActions,
   attachComponent,
   createRecipe,
 
@@ -50,6 +51,7 @@ globalThis.phx.applicationTypes = {
   readonly enhancedModel: typeof enhancedModel
   readonly implementCustomExpressions: typeof implementCustomExpressions
   readonly implementCustomInvariants: typeof implementCustomInvariants
+  readonly implementActions: typeof implementActions
   readonly attachComponent: typeof attachComponent
   readonly createRecipe: typeof createRecipe
   readonly admin: {
@@ -69,6 +71,7 @@ globalThis.phx.applicationTypes = {
   enhancedModel,
   implementCustomExpressions,
   implementCustomInvariants,
+  implementActions,
   attachComponent,
   createRecipe,
 

package/dist/application-spec/generate-application/code/templates/domain-spec.js

@@ -1,5 +1,5 @@
-import{CodeImports as e,autoHeader as a,skipApplicationTypeImports as i}from"../common/index.js";import{generateApplicationMetadataBlock as o,generateAssistantBlock as n,generateBaseConfiguratorBuilder as t,generateChunksSpec as s,generateDataSchemaConstants as r,generateDataSpec as p,generateDomainBlock as m,generateLocaleCodegen as d,generatePhxGlobalsBlock as c,generateResourcesCodegen as l,generateStateConstants as x}from"./domain-spec/index.js";let u="@salsita-ai/sdk/domain",g="@salsita-ai/sdk/i18n";export const globalDomainSpecPhxBinding={generateBindingBlock:c,generateStateConstants:x,registerApplicationTypeImports:i};export const generateApplicationSpecDomainSpecFile=(i,c=globalDomainSpecPhxBinding)=>{let x=new e,{registerApplicationTypeImports:E}=c,f=m({domainSpec:i.configurator,invariants:i.configurator.invariants,typePrefix:"",versionNsPrefix:"ModelV",isAdmin:!1,modelVersionsExportName:"modelVersions",relationExpressionsExportName:"relationExpressions",componentOpticsExportName:"componentOptics",valueExpressionsExportName:"valueExpressions",createRecipeExportName:"createRecipe",imports:x,registerApplicationTypeImports:E}),S=m({domainSpec:i.admin,invariants:i.admin.invariants,typePrefix:"Admin",versionNsPrefix:"AdminV",isAdmin:!0,modelVersionsExportName:"adminModelVersions",relationExpressionsExportName:"adminRelationExpressions",componentOpticsExportName:"adminComponentOptics",valueExpressionsExportName:"adminValueExpressions",createRecipeExportName:"createAdminRecipe",imports:x,registerApplicationTypeImports:E}),{hasResources:$}=l(i);x.addImport(u,"ConfiguratorBuilder"),x.addImport(u,"EnumReflection"),x.addTypeImport(u,"AssistantManifest"),x.addTypeImport(u,"ChunksSpec"),x.addTypeImport(u,"DataSpec"),x.addTypeImport(u,"EnumLike"),$&&x.addImport(u,"ResourceBuilder"),x.addImport(g,"mergeCatalogs"),x.addImport(g,"sdkCatalog"),x.addImport("@lingui/core","setupI18n");let k=r(i.configurator.dataSchemas,x,E),I=c.generateStateConstants({configuratorStates:i.configurator.states,adminStates:i.admin.states},x,E),N=o(i),{importBlock:v,catalogBlock:h,createI18nExport:A}=d(i.configurator.ui.availableLocales),{preBlock:B,builderBlock:C}=t(i,x,E),y=c.generateBindingBlock();return`${a("domain-spec.ts","Domain builders, model schemas, component optics and expression definitions derived from the spec.")}
-${x.toString()}${v}
+import{CodeImports as e,autoHeader as a,skipApplicationTypeImports as i}from"../common/index.js";import{generateApplicationMetadataBlock as o,generateAssistantBlock as n,generateBaseConfiguratorBuilder as t,generateChunksSpec as s,generateDataSchemaConstants as r,generateDataSpec as p,generateDomainBlock as m,generateLocaleCodegen as d,generatePhxGlobalsBlock as c,generateResourcesCodegen as l,generateStateConstants as u}from"./domain-spec/index.js";let x="@salsita-ai/sdk/domain",g="@salsita-ai/sdk/i18n";export const globalDomainSpecPhxBinding={generateBindingBlock:c,generateStateConstants:u,registerApplicationTypeImports:i};export const generateApplicationSpecDomainSpecFile=(i,c=globalDomainSpecPhxBinding)=>{let u=new e,{registerApplicationTypeImports:f}=c,E=m({domainSpec:i.configurator,invariants:i.configurator.invariants,actions:i.configurator.actions,typePrefix:"",versionNsPrefix:"ModelV",isAdmin:!1,modelVersionsExportName:"modelVersions",relationExpressionsExportName:"relationExpressions",componentOpticsExportName:"componentOptics",valueExpressionsExportName:"valueExpressions",createRecipeExportName:"createRecipe",imports:u,registerApplicationTypeImports:f}),S=m({domainSpec:i.admin,invariants:i.admin.invariants,actions:void 0,typePrefix:"Admin",versionNsPrefix:"AdminV",isAdmin:!0,modelVersionsExportName:"adminModelVersions",relationExpressionsExportName:"adminRelationExpressions",componentOpticsExportName:"adminComponentOptics",valueExpressionsExportName:"adminValueExpressions",createRecipeExportName:"createAdminRecipe",imports:u,registerApplicationTypeImports:f}),{hasResources:$}=l(i);u.addImport(x,"ConfiguratorBuilder"),u.addImport(x,"EnumReflection"),u.addTypeImport(x,"AssistantManifest"),u.addTypeImport(x,"ChunksSpec"),u.addTypeImport(x,"DataSpec"),u.addTypeImport(x,"EnumLike"),$&&u.addImport(x,"ResourceBuilder"),u.addImport(g,"mergeCatalogs"),u.addImport(g,"sdkCatalog"),u.addImport("@lingui/core","setupI18n");let k=r(i.configurator.dataSchemas,u,f),v=c.generateStateConstants({configuratorStates:i.configurator.states,adminStates:i.admin.states},u,f),I=o(i),{importBlock:N,catalogBlock:h,createI18nExport:A}=d(i.configurator.ui.availableLocales),{preBlock:B,builderBlock:C}=t(i,u,f),y=c.generateBindingBlock();return`${a("domain-spec.ts","Domain builders, model schemas, component optics and expression definitions derived from the spec.")}
+${u.toString()}${N}
 
 // ---- Data schemas ----
 
@@ -11,7 +11,7 @@ ${S}
 
 // ---- Configurator domain ----
 
-${f}
+${E}
 
 // ---- i18n ----
 
@@ -21,11 +21,11 @@ ${A}
 
 // ---- Application metadata ----
 
-${N}
+${I}
 
 // ---- State enums ----
 
-${I}
+${v}
 
 const $dataSpec: DataSpec = ${p(i.dataSpec.entries)}
 

package/dist/application-spec/generate-application/code/templates/domain.js

@@ -1,9 +1,9 @@
-import{CodeImports as i}from"../common/code-imports.js";import{autoHeader as n}from"../common/file-headers.js";let o=/v(\d+)\.ts$/,t=(i,n)=>i.versionedModels.filter(i=>void 0!==i.migrationFile).map(i=>({version:i.version,file:i.migrationFile,importName:n?`${n}MigrateToV${i.version}`:`migrateToV${i.version}`})),s=i=>i.map(i=>{let n=i.file.replace(o,`v${i.version}.js`),t=`migrateToV${i.version}`,s=i.importName!==t?` as ${i.importName}`:"";return`import { ${t}${s} } from '../${n}'`}).join("\n"),e=(i,n,o,t)=>[`const ${t}Migrations = {`,...i.map(i=>`  ${i.version}: ${i.importName},`),"}","",`const ${t} = MigrateFunctionBuilder`,`  .fromVersions(${n})`,`  .to(${o})`,`  .using(${t}Migrations)`,"  .build()"].join("\n");export const generateApplicationSpecDomainFile=o=>{let r=new i,a="./domain-spec.js",m="./configurator-domain-code.js",d="./admin-domain-code.js",p=i=>[...i.expressions.values()].some(i=>[...i.values()].some(i=>"relation"===i.implementation.kind)),l=p(o.configurator.expressions),c=p(o.admin.expressions),u=t(o.configurator.resolvedVersions,""),I=t(o.admin.resolvedVersions,"admin"),g=u.length>0,h=I.length>0;r.addImport(a,"baseConfiguratorBuilder"),r.addImport(a,"domainBuilder"),r.addImport(a,"adminDomainBuilder"),r.addImport(a,"attachComponent"),r.addImport(a,"attachAdminComponent"),r.addImport(a,"implementCustomExpressions"),r.addImport(a,"implementAdminCustomExpressions"),r.addImport(a,"createI18n"),r.addImport(a,"componentOptics"),r.addImport(a,"adminComponentOptics"),r.addImport(a,"invariantBuilder"),r.addImport(a,"adminInvariantBuilder"),r.addImport(m,"customExpressions"),r.addImport(m,"customInvariants"),r.addImport(d,"customAdminExpressions"),r.addImport(d,"customAdminInvariants"),l&&r.addImport(a,"relationExpressions"),c&&r.addImport(a,"adminRelationExpressions"),(g||h)&&r.addImport("@salsita-ai/sdk/domain","MigrateFunctionBuilder"),g&&r.addImport(a,"modelVersions"),h&&r.addImport(a,"adminModelVersions");let x=[];g&&x.push(s(u)),h&&x.push(s(I));let v=x.length>0?"\n"+x.join("\n")+"\n":"",$=[];g&&$.push(e(u,"modelVersions",o.configurator.schemaVersion,"migrate")),h&&$.push(e(I,"adminModelVersions",o.admin.schemaVersion,"migrateAdmin"));let E=$.length>0?"\n"+$.join("\n\n")+"\n":"",f=["const domainFactory = domainBuilder",l?"  .withExpressions(relationExpressions)":null,"  .withExpressions(invariantBuilder.withInvariants(customInvariants).buildViolationExpressions())","  .withExpressions(customExpressions)",g?"  .withMigrate(migrate)":null,"  .build()"].filter(Boolean).join("\n"),w=["const adminDomainFactory = adminDomainBuilder",c?"  .withExpressions(adminRelationExpressions)":null,"  .withExpressions(adminInvariantBuilder.withInvariants(customAdminInvariants).buildViolationExpressions())","  .withExpressions(customAdminExpressions)",h?"  .withMigrate(migrateAdmin)":null,"  .build()"].filter(Boolean).join("\n");return`${n("domain.ts","Assembles domain and admin domain factories from builders, migrations, expressions and invariants.")}
+import{CodeImports as i}from"../common/code-imports.js";import{autoHeader as n}from"../common/file-headers.js";let o=/v(\d+)\.ts$/,t=(i,n)=>i.versionedModels.filter(i=>void 0!==i.migrationFile).map(i=>({version:i.version,file:i.migrationFile,importName:n?`${n}MigrateToV${i.version}`:`migrateToV${i.version}`})),s=i=>i.map(i=>{let n=i.file.replace(o,`v${i.version}.js`),t=`migrateToV${i.version}`,s=i.importName!==t?` as ${i.importName}`:"";return`import { ${t}${s} } from '../${n}'`}).join("\n"),e=(i,n,o,t)=>[`const ${t}Migrations = {`,...i.map(i=>`  ${i.version}: ${i.importName},`),"}","",`const ${t} = MigrateFunctionBuilder`,`  .fromVersions(${n})`,`  .to(${o})`,`  .using(${t}Migrations)`,"  .build()"].join("\n");export const generateApplicationSpecDomainFile=o=>{let r=new i,a="./domain-spec.js",m="./configurator-domain-code.js",d="./admin-domain-code.js",p=i=>[...i.expressions.values()].some(i=>[...i.values()].some(i=>"relation"===i.implementation.kind)),l=p(o.configurator.expressions),c=p(o.admin.expressions),u=t(o.configurator.resolvedVersions,""),I=t(o.admin.resolvedVersions,"admin"),g=u.length>0,h=I.length>0;r.addImport(a,"baseConfiguratorBuilder"),r.addImport(a,"domainBuilder"),r.addImport(a,"adminDomainBuilder"),r.addImport(a,"attachComponent"),r.addImport(a,"attachAdminComponent"),r.addImport(a,"implementCustomExpressions"),r.addImport(a,"implementAdminCustomExpressions"),r.addImport(a,"createI18n"),r.addImport(a,"componentOptics"),r.addImport(a,"adminComponentOptics"),r.addImport(a,"invariantBuilder"),r.addImport(a,"adminInvariantBuilder"),r.addImport(m,"customExpressions"),r.addImport(m,"customInvariants"),r.addImport(m,"customActions"),r.addImport(d,"customAdminExpressions"),r.addImport(d,"customAdminInvariants"),l&&r.addImport(a,"relationExpressions"),c&&r.addImport(a,"adminRelationExpressions"),(g||h)&&r.addImport("@salsita-ai/sdk/domain","MigrateFunctionBuilder"),g&&r.addImport(a,"modelVersions"),h&&r.addImport(a,"adminModelVersions");let x=[];g&&x.push(s(u)),h&&x.push(s(I));let v=x.length>0?"\n"+x.join("\n")+"\n":"",$=[];g&&$.push(e(u,"modelVersions",o.configurator.schemaVersion,"migrate")),h&&$.push(e(I,"adminModelVersions",o.admin.schemaVersion,"migrateAdmin"));let E=$.length>0?"\n"+$.join("\n\n")+"\n":"",f=["const domainFactory = domainBuilder",l?"  .withExpressions(relationExpressions)":null,"  .withExpressions(invariantBuilder.withInvariants(customInvariants).buildViolationExpressions())","  .withExpressions(customExpressions)","  .withActionImplementations(customActions)",g?"  .withMigrate(migrate)":null,"  .build()"].filter(Boolean).join("\n"),A=["const adminDomainFactory = adminDomainBuilder",c?"  .withExpressions(adminRelationExpressions)":null,"  .withExpressions(adminInvariantBuilder.withInvariants(customAdminInvariants).buildViolationExpressions())","  .withExpressions(customAdminExpressions)",h?"  .withMigrate(migrateAdmin)":null,"  .build()"].filter(Boolean).join("\n");return`${n("domain.ts","Assembles domain and admin domain factories from builders, migrations, expressions and invariants.")}
 ${r.toString()}
 ${v}export { attachComponent, attachAdminComponent, implementCustomExpressions, implementAdminCustomExpressions, createI18n }
 ${E}
 ${f}
-${w}
+${A}
 
 export const configuratorBuilder = baseConfiguratorBuilder
   .withDomainFactory(domainFactory)

package/dist/application-spec/generate-application/code/templates/global-definition/generate-action-types.d.ts

@@ -0,0 +1,11 @@
+import type { PhoenixDefinitions } from '../../../../core/phoenix-definitions.js';
+import type { Actions, ModelVersion } from '../../../../parse-application-files/index.js';
+import type { CodeImports } from '../../common/code-imports.js';
+/**
+ * Generates the `ActionTypes` map of the declared actions (name → `{ params, result }`) and the
+ * `ActionName`, `ActionParams<NAME>` and `ActionResult<NAME>` types derived from it. A nullable
+ * param is optional. The `description` of an action, a param and a result member becomes the doc
+ * comment of its property, so it shows wherever the types are used. Without actions the map is
+ * empty, so `ActionName` is `never`.
+ */
+export declare const generateActionTypeDecls: (actions: Actions, model: ModelVersion, phxDefinitions: PhoenixDefinitions, imports: CodeImports, indent: number, typeOnlyImports?: boolean) => string;

package/dist/application-spec/generate-application/code/templates/global-definition/generate-action-types.js

@@ -0,0 +1,8 @@
+import{schemaToTypeString as e}from"../common/schema-to-type-string.js";let t=(e,t)=>{let n=(e??"").trim().replaceAll("*/","*\\/").split("\n").map(e=>e.trim());return""===n[0]||void 0===n[0]?[]:1===n.length?[`${t}/** ${n[0]} */`]:[`${t}/**`,...n.map(e=>`${t} * ${e}`.trimEnd()),`${t} */`]};export const generateActionTypeDecls=(n,r,o,a,p,s=!1)=>{let i=" ".repeat(p),$=" ".repeat(p+2),c=" ".repeat(p+4),l=" ".repeat(p+6),m={phxDefinitions:o,commonTypeNames:new Set(r.commonTypes.keys()),imports:a,typeOnlyImports:s},y=[...n.values()].map(n=>{let r=Object.entries(n.params).flatMap(([n,{schema:r,required:o}])=>[...t(r.description,l),`${l}readonly ${n}${o?"":"?"}: ${e(r,m)}`]),o=Object.entries(n.result).flatMap(([n,r])=>[...t(r.description,l),`${l}readonly ${n}: ${e(r,m)}`]),a=e=>e.length>0?`{
+${e.join("\n")}
+${c}}`:"Record<string, never>";return[...t(n.description,$),`${$}readonly ${n.name}: {`,`${c}readonly params: ${a(r)}`,`${c}readonly result: ${a(o)}`,`${$}}`].join("\n")}),A=y.length>0?`{
+${y.join("\n")}
+${i}}`:"Record<never, never>";return`${i}type ActionTypes = ${A}
+${i}type ActionName = keyof ActionTypes
+${i}type ActionParams<NAME extends ActionName> = ActionTypes[NAME]['params']
+${i}type ActionResult<NAME extends ActionName> = ActionTypes[NAME]['result']`};

package/dist/application-spec/generate-application/code/templates/global-definition/index.d.ts

@@ -1,3 +1,4 @@
+export { generateActionTypeDecls } from './generate-action-types.js';
 export { generateModelTypeDecls } from './generate-model-types.js';
 export { generateExpressionTypeDecls, generateEntityExpressionComposites } from './generate-expression-types.js';
 export { generateDataSchemaTypeDecls } from './generate-data-schema-types.js';

package/dist/application-spec/generate-application/code/templates/global-definition/index.js

@@ -1 +1 @@
-export{generateModelTypeDecls}from"./generate-model-types.js";export{generateExpressionTypeDecls,generateEntityExpressionComposites}from"./generate-expression-types.js";export{generateDataSchemaTypeDecls}from"./generate-data-schema-types.js";
+export{generateActionTypeDecls}from"./generate-action-types.js";export{generateModelTypeDecls}from"./generate-model-types.js";export{generateExpressionTypeDecls,generateEntityExpressionComposites}from"./generate-expression-types.js";export{generateDataSchemaTypeDecls}from"./generate-data-schema-types.js";

package/dist/application-spec/generate-application/code/templates/globals.js

@@ -73,6 +73,7 @@ ${h}
       readonly enhancedModel: typeof import('./domain-spec.js').enhancedModel
       readonly implementCustomExpressions: typeof import('./domain-spec.js').implementCustomExpressions
       readonly implementCustomInvariants: typeof import('./domain-spec.js').implementCustomInvariants
+      readonly implementActions: typeof import('./domain-spec.js').implementActions
       readonly attachComponent: typeof import('./domain-spec.js').attachComponent
       readonly createRecipe: typeof import('./domain-spec.js').createRecipe
 

package/dist/application-spec/generate-application/code/templates/skills/phoenix-review-skill.js

@@ -7,13 +7,15 @@ import{renderAgentSkill as e}from"./agent-skill.js";let i=`Review all current gi
 - [ ] Relations properly define parent-child ownership (1-N, 0-1)
 - [ ] Expressions have matching implementations in src/expressions/
 - [ ] Invariants have matching implementations in src/invariants/
+- [ ] Actions declared under actions: have matching implementations in src/actions/ (a missing one fails the type check of the generated barrel)
 - [ ] Component bindings use correct entity types or aliases
 - [ ] $read/$write/$bind reference valid properties or expressions
 - [ ] A model that has been deployed is unchanged under its version: the change is in \`model.latest\`, the deployed model is kept as \`model.v<N>\`, and \`src/migrations/v<N+1>.ts\` migrates saved configurations
 
-### Expressions & Invariants (src/expressions/, src/invariants/)
+### Expressions, Actions & Invariants (src/expressions/, src/actions/, src/invariants/)
 
-- [ ] Use phx.domain.implementCustomExpressions() / implementCustomInvariants()
+- [ ] Use phx.domain.implementCustomExpressions() / implementActions() / implementCustomInvariants()
+- [ ] Actions only prepare: they return updates and a readResult reader, never stage or commit, and throw messages that say what to send instead
 - [ ] Expression names prefixed with $ in YAML match implementation
 - [ ] No side effects in expressions (pure computed values only)
 - [ ] Invariant violations return proper severity and messages

package/dist/application-spec/generate-application/code/templates/skills/sdk-content.d.ts

@@ -25,6 +25,7 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
     readonly projectStructure: `## Project Structure
 - \`spec/\` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)
 - \`src/expressions/\` — Computed/derived entity properties (\`phx.domain.implementCustomExpressions()\`)
+- \`src/actions/\` — Domain operations declared under \`actions:\` in the spec (\`phx.domain.implementActions()\`), run by controls and exposed to the assistant
 - \`src/invariants/\` — Business rule constraints (\`phx.domain.implementCustomInvariants()\`)
 - \`src/transformers/\` — Automatic state fixers (\`phx.frontend.transformerBuilder\`)
 - \`src/components/\` — ECS system components (\`phx.domain.attachComponent.withEntity()\`)
@@ -48,6 +49,7 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
     /** Expressions, invariants, transformers, components, webhooks, and filters at a glance. */
     readonly keyPatterns: `## Key Patterns
 - Expressions = computed properties on entities (prefix: \`$\`), implemented per-entity in src/expressions/
+- Actions = named domain operations (\`actions:\` in YAML with \`params\` and \`result\` schemas), implemented in src/actions/, prepared through \`actionSystem.prepareAction()\` and exposed as assistant mutations through \`assistant.actions\`
 - Invariants = validation rules returning violations, static or dynamic
 - Transformers = auto-fixers maintaining consistency after state changes
 - Components defined in YAML with \`$read\`/\`$bind\` bindings, or custom in src/components/ using attachComponent builder
@@ -63,7 +65,7 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
 - Underscore folders (_shared/, _utils/) are NOT auto-imported`;
     /** The default-export rule of the SDK auto-import system. */
     readonly exportRules: `## Export Rules
-All files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`;
+All files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`;
     /** Which components and handlers are bundled into the webhook. */
     readonly webhookMembership: `## Webhook Membership
 - User-authored components, admin components, and handlers are frontend-only by default.

package/dist/application-spec/generate-application/code/templates/skills/sdk-content.js

@@ -1,13 +1,13 @@
 export const sdkGuidanceSections={projectIntro:`## Phoenix Configurator Project
 
-Declarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.`,buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
+Declarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.`,buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/actions/` — Domain operations declared under `actions:` in the spec (`phx.domain.implementActions()`), run by controls and exposed to the assistant\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Actions = named domain operations (`actions:` in YAML with `params` and `result` schemas), implemented in src/actions/, prepared through `actionSystem.prepareAction()` and exposed as assistant mutations through `assistant.actions`\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
 - Components: PascalCase (.tsx)
 - Utilities: kebab-case (.ts)
 - Expressions: entity-name.ts
 - Migrations: v*.ts (sequential)
 - Specs: kebab-case.yaml
 - Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:`## Export Rules
-All files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`,webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files — compiled from .po files",modelVersioning:"## Version the Domain Model Once It Is Deployed\nA deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\nTo change a model that has been deployed as v<N>:\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n**Replacing the starter.** When the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` before writing any other migration.",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
+All files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`,webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files — compiled from .po files",modelVersioning:"## Version the Domain Model Once It Is Deployed\nA deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\nTo change a model that has been deployed as v<N>:\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n**Replacing the starter.** When the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` before writing any other migration.",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
 
 Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
 

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.d.ts

@@ -2,6 +2,7 @@ import { Branded } from '@salsita-ai/common/utils';
 import type { ImportedTransformer } from '#package/domain';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
+import { ActionsRuntime } from '../sections/actions-runtime.js';
 import { AssistantRuntime } from '../sections/assistant-runtime.js';
 import { ComponentOptics } from '../sections/component-optic.js';
 import { type ExpressionImplementations, ExpressionRuntime, type InvariantImplementations, type MissingExpression } from '../sections/expression-runtime.js';
@@ -20,6 +21,7 @@ export type ConfiguratorRuntime = Branded<'ConfiguratorRuntime', {
     readonly themeRuntime: ThemeRuntime;
     readonly transformersRuntime: TransformersRuntime;
     readonly assistantRuntime: AssistantRuntime;
+    readonly actionsRuntime: ActionsRuntime;
 }>;
 export type ConfiguratorRuntimeResult = {
     readonly ok: true;

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.js

@@ -1 +1 @@
-import{Branded as t}from"@salsita-ai/common/utils";import{AssistantRuntime as e}from"../sections/assistant-runtime.js";import{ComponentOptics as o}from"../sections/component-optic.js";import{ExpressionRuntime as r}from"../sections/expression-runtime.js";import{PresetRuntime as s}from"../sections/preset-runtime.js";import{ThemeRuntime as i}from"../sections/theme-runtime.js";import{TransformersRuntime as n}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as m}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as u}from"./states-runtime.js";export const ConfiguratorRuntime=(p,c,f,a,g)=>{let R=m(p.configurator,c),j=r(p.configurator,c,f,"configuratorExpressionRuntime",g);return j.ok?{ok:!0,runtime:t({modelRuntime:R,componentOptics:o(c,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:R}),presetRuntime:s(c,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:u(p,c),expressionRuntime:j.runtime,themeRuntime:i(p,c),transformersRuntime:n(p,c,a),assistantRuntime:e(p,c)})}:{ok:!1,missingExpressions:j.missing}};
+import{Branded as t}from"@salsita-ai/common/utils";import{ActionsRuntime as o}from"../sections/actions-runtime.js";import{AssistantRuntime as e}from"../sections/assistant-runtime.js";import{ComponentOptics as r}from"../sections/component-optic.js";import{ExpressionRuntime as s}from"../sections/expression-runtime.js";import{PresetRuntime as i}from"../sections/preset-runtime.js";import{ThemeRuntime as n}from"../sections/theme-runtime.js";import{TransformersRuntime as m}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as u}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as c}from"./states-runtime.js";export const ConfiguratorRuntime=(p,a,f,g,R)=>{let j=u(p.configurator,a),x=s(p.configurator,a,f,"configuratorExpressionRuntime",R);return x.ok?{ok:!0,runtime:t({modelRuntime:j,componentOptics:r(a,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:j}),presetRuntime:i(a,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:c(p,a),expressionRuntime:x.runtime,themeRuntime:n(p,a),transformersRuntime:m(p,a,g),assistantRuntime:e(p,a),actionsRuntime:o(p.configurator.actions,a)})}:{ok:!1,missingExpressions:x.missing}};

package/dist/application-spec/generate-application/runtime/sections/actions-runtime.d.ts

@@ -0,0 +1,14 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { ActionDefinitions } from '#package/domain';
+import type { RuntimeReferenceStore } from '../../../caching/index.js';
+import type { Actions } from '../../../parse-application-files/index.js';
+/**
+ * The declared actions as the runtime spec slice holds them, with change tracking: the definitions
+ * are rebuilt only when their declaration changes, so a hot reload of an unrelated section keeps
+ * the action system's compiled validators.
+ */
+export type ActionsRuntime = Branded<'ActionsRuntime', {
+    readonly definitions: ActionDefinitions;
+    readonly changed: boolean;
+}>;
+export declare const ActionsRuntime: (actions: Actions, referenceStore: RuntimeReferenceStore) => ActionsRuntime;

package/dist/application-spec/generate-application/runtime/sections/actions-runtime.js

@@ -0,0 +1 @@
+import i from"lodash-es/isEqual.js";import{Branded as e}from"@salsita-ai/common/utils";export const ActionsRuntime=(t,n)=>{let o=n.createBuilder("configuratorRuntime/actions",{build:i=>i.definition,getKey:i=>i.definition.name,compare:(e,t)=>i(e.definition,t.definition)}),a=!1,r=new Set,d={};for(let i of t.values()){let e={definition:{name:String(i.name),...void 0===i.description?{}:{description:i.description},params:i.paramsSchema}},t=o.build(e);t.changed&&(a=!0),r.add(o.getKey(e)),d[t.output.name]=t.output}return o.cleanup(r)&&(a=!0),e({definitions:d,changed:a})};

package/dist/application-spec/generate-application/runtime/sections/index.d.ts

@@ -1,3 +1,4 @@
+export { ActionsRuntime } from './actions-runtime.js';
 export { AssistantRuntime } from './assistant-runtime.js';
 export { ComponentOptics, type ComponentOptic } from './component-optic.js';
 export { DataRuntime } from './data-runtime.js';

package/dist/application-spec/generate-application/runtime/sections/index.js

@@ -1 +1 @@
-export{AssistantRuntime}from"./assistant-runtime.js";export{ComponentOptics}from"./component-optic.js";export{DataRuntime}from"./data-runtime.js";export{ExpressionRuntime}from"./expression-runtime.js";export{PresetRuntime}from"./preset-runtime.js";export{ThemeRuntime}from"./theme-runtime.js";export{TransformersRuntime}from"./transformers-runtime.js";export{evaluateStaticMemoEvalPlan,generateMemoEvalPlanRuntime}from"./generate-memo-eval-plan-runtime.js";export{evaluateReflectionConstants,findReflectionConstants}from"./reflection-constants-runtime.js";
+export{ActionsRuntime}from"./actions-runtime.js";export{AssistantRuntime}from"./assistant-runtime.js";export{ComponentOptics}from"./component-optic.js";export{DataRuntime}from"./data-runtime.js";export{ExpressionRuntime}from"./expression-runtime.js";export{PresetRuntime}from"./preset-runtime.js";export{ThemeRuntime}from"./theme-runtime.js";export{TransformersRuntime}from"./transformers-runtime.js";export{evaluateStaticMemoEvalPlan,generateMemoEvalPlanRuntime}from"./generate-memo-eval-plan-runtime.js";export{evaluateReflectionConstants,findReflectionConstants}from"./reflection-constants-runtime.js";

package/dist/application-spec/parse-application-files/categorize/categorize-files.d.ts

@@ -3,7 +3,7 @@ import { type RuntimeReferenceStore } from '../../caching/index.js';
 import type { ParseContext, RawProjectFiles, TextFile } from '../../core/index.js';
 import { type ModuleAnalysis, type ModuleAnalyzer, type WebhookMembership } from './module-analysis.js';
 /** Known file categories used for path-based sorting. */
-export type FileCategory = 'spec' | 'expressions' | 'handlers' | 'elements' | 'transformers' | 'components' | 'invariants' | 'migrations' | 'adminMigrations' | 'adminExpressions' | 'adminInvariants' | 'adminComponents' | 'adminElements' | 'webhooks' | 'locales' | 'mockTemplates' | 'projectFiles' | 'customCode';
+export type FileCategory = 'spec' | 'expressions' | 'actions' | 'handlers' | 'elements' | 'transformers' | 'components' | 'invariants' | 'migrations' | 'adminMigrations' | 'adminExpressions' | 'adminInvariants' | 'adminComponents' | 'adminElements' | 'webhooks' | 'locales' | 'mockTemplates' | 'projectFiles' | 'customCode';
 /**
  * A text file categorized by path pattern, with dep-aware change tracking.
  *
@@ -32,6 +32,8 @@ export type CategorizedFiles = Branded<'CategorizedFiles', {
     readonly specChanged: boolean;
     readonly expressions: readonly CategorizedFile[];
     readonly expressionsChanged: boolean;
+    readonly actions: readonly CategorizedFile[];
+    readonly actionsChanged: boolean;
     readonly handlers: readonly CategorizedFile[];
     readonly handlersChanged: boolean;
     readonly elements: readonly CategorizedFile[];

package/dist/application-spec/parse-application-files/categorize/categorize-files.js

@@ -1 +1 @@
-import e from"lodash-es/isEqual.js";import{Branded as n}from"@salsita-ai/common/utils";import{computeFileDepHashes as s}from"../../caching/index.js";import{DiagnosticCode as o,diagnosticMessages as a}from"../../errors/index.js";import{findWebhookHandlerRegistration as i}from"./module-analysis.js";import{findWebhookSafetyViolation as t}from"./webhook-safety.js";export const buildProjectFileIndex=e=>new Map([...e.spec,...e.expressions,...e.handlers,...e.elements,...e.transformers,...e.components,...e.invariants,...e.migrations,...e.adminMigrations,...e.adminExpressions,...e.adminInvariants,...e.adminComponents,...e.adminElements,...e.webhooks,...e.locales,...e.mockTemplates,...e.projectFiles,...e.customCode].map(e=>[e.file.name,e]));let r=e=>/\/_[^/]+\//.test(e),m=[{path:"spec/",key:"spec"},{path:"src/admin/expressions/",key:"adminExpressions"},{path:"src/admin/invariants/",key:"adminInvariants"},{path:"src/admin/components/",key:"adminComponents"},{path:"src/admin/elements/",key:"adminElements"},{path:"src/admin/migrations/",key:"adminMigrations"},{path:"src/expressions/",key:"expressions"},{path:"src/handlers/",key:"handlers"},{path:"src/elements/",key:"elements"},{path:"src/transformers/",key:"transformers"},{path:"src/components/",key:"components"},{path:"src/invariants/",key:"invariants"},{path:"src/migrations/",key:"migrations"},{path:"src/webhooks/",key:"webhooks"},{path:"src/locales/",key:"locales"},{path:"mocks/",key:"mockTemplates"}],l=new Set(["package.json",".gitignore","CLAUDE.md",".cursor/rules/phoenix.mdc"]),d=new Set(["migrations","adminMigrations"]),p=m.filter(({path:e,key:n})=>e.startsWith("src/")&&d.has(n)),c=(e,n)=>{let s=e.slice(n.length).split("/");return!(s.length<=1)&&s.slice(0,-1).some(e=>!e.startsWith("_"))},h=/\.(ts|tsx|js|jsx)$/,f=(e,n)=>{if("components"===e||"adminComponents"===e)return n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (no 'use webhook' directive)"};if("handlers"===e){let e=i(n);return void 0!==e?{membership:"named-handler",logSuffix:`webhook (the ${e} registration)`}:n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (not a named handler or pin)"}}};export const CategorizedFiles=(i,d,g,u)=>{let k={spec:[],expressions:[],handlers:[],elements:[],transformers:[],components:[],invariants:[],migrations:[],adminMigrations:[],adminExpressions:[],adminInvariants:[],adminComponents:[],adminElements:[],webhooks:[],locales:[],mockTemplates:[],projectFiles:[],customCode:[]},b=[];for(let e of i.files){if("text"!==e.kind)continue;if(r(e.name)){k.customCode.push({file:e,category:"customCode"});continue}if(l.has(e.name)){k.projectFiles.push({file:e,category:"projectFiles"});continue}let n=!1;for(let{path:s,key:o}of m)if(e.name.startsWith(s)){k[o].push({file:e,category:o}),n=!0;break}n||b.push(e.name)}for(let e of b)e.startsWith("src/")&&g.error(o.UNKNOWN_SRC_PATH,a.UNKNOWN_SRC_PATH(e));for(let{path:e,key:n}of p)for(let s of k[n])c(s.file.name,e)&&g.error(o.INVALID_SUBDIRECTORY,a.INVALID_SUBDIRECTORY(s.file.name,e));if(k.webhooks.length>0&&!k.webhooks.some(e=>"src/webhooks/index.ts"===e.file.name)&&g.error(o.MISSING_WEBHOOK_INDEX,a.MISSING_WEBHOOK_INDEX()),g.hasErrors)return;let C=[];for(let e of Object.values(k))for(let n of e)C.push(n.file.name);let v=s(i,C),{analyzer:x,logger:E}=u,y=d.createBuilder("categorizedFiles/moduleAnalysis",{build:e=>{try{return{analysis:x(e.name,e.content)}}catch(e){return{error:e instanceof Error?e.message:String(e)}}},getKey:e=>e.name,compare:(e,n)=>e.content===n.content}),I=new Set,w=e=>{if(!h.test(e.name))return;I.add(e.name);let n=y.build({name:e.name,content:e.content}).output;return void 0!==n.error?void g.error(o.MODULE_ANALYSIS_FAILED,a[o.MODULE_ANALYSIS_FAILED](e.name,n.error)):n.analysis},S={},j={};for(let[e,s]of Object.entries(k)){let o=d.createBuilder(`categorizedFiles/${e}`,{build:e=>e,getKey:e=>e.name,compare:(e,n)=>e.depHash===n.depHash}),a=new Set;S[e]=s.map(e=>{let s=v[e.file.name]??{deps:[],hash:""},{changed:i}=o.build({name:e.file.name,depHash:s.hash});a.add(e.file.name);let t=w(e.file),r=void 0===t?void 0:f(e.category,t);return void 0!==r&&E.debug(`Webhook membership: ${e.file.name} -> ${r.logSuffix}`),n({file:e.file,category:e.category,deps:s.deps,depHash:s.hash,changed:i,analysis:t,webhookMembership:r?.membership})}),j[e]=o.cleanup(a)}y.cleanup(I);let _=(e,n)=>n.some(e=>e.changed)||!0===j[e],F=d.createBuilder("categorizedFiles/envs",{build:e=>e.envs,getKey:()=>"singleton",compare:(n,s)=>e(n.envs,s.envs)}).build({envs:i.envs}),M=n({spec:S.spec,specChanged:_("spec",S.spec),expressions:S.expressions,expressionsChanged:_("expressions",S.expressions),handlers:S.handlers,handlersChanged:_("handlers",S.handlers),elements:S.elements,elementsChanged:_("elements",S.elements),transformers:S.transformers,transformersChanged:_("transformers",S.transformers),components:S.components,componentsChanged:_("components",S.components),invariants:S.invariants,invariantsChanged:_("invariants",S.invariants),migrations:S.migrations,migrationsChanged:_("migrations",S.migrations),adminMigrations:S.adminMigrations,adminMigrationsChanged:_("adminMigrations",S.adminMigrations),adminExpressions:S.adminExpressions,adminExpressionsChanged:_("adminExpressions",S.adminExpressions),adminInvariants:S.adminInvariants,adminInvariantsChanged:_("adminInvariants",S.adminInvariants),adminComponents:S.adminComponents,adminComponentsChanged:_("adminComponents",S.adminComponents),adminElements:S.adminElements,adminElementsChanged:_("adminElements",S.adminElements),webhooks:S.webhooks,webhooksChanged:_("webhooks",S.webhooks),locales:S.locales,localesChanged:_("locales",S.locales),mockTemplates:S.mockTemplates,mockTemplatesChanged:_("mockTemplates",S.mockTemplates),projectFiles:S.projectFiles,projectFilesChanged:_("projectFiles",S.projectFiles),customCode:S.customCode,customCodeChanged:_("customCode",S.customCode),envs:F.output,envsChanged:F.changed}),O=buildProjectFileIndex(M);for(let e of O.values()){if("pinned"!==e.webhookMembership&&"named-handler"!==e.webhookMembership)continue;let n=t(e,O);void 0!==n&&g.error(o.WEBHOOK_UNSAFE_IMPORT,a[o.WEBHOOK_UNSAFE_IMPORT](n.fileName,n.inclusionReason,n.importer,n.specifier))}return M};
+import e from"lodash-es/isEqual.js";import{Branded as n}from"@salsita-ai/common/utils";import{computeFileDepHashes as s}from"../../caching/index.js";import{DiagnosticCode as o,diagnosticMessages as a}from"../../errors/index.js";import{findWebhookHandlerRegistration as i}from"./module-analysis.js";import{findWebhookSafetyViolation as t}from"./webhook-safety.js";export const buildProjectFileIndex=e=>new Map([...e.spec,...e.expressions,...e.actions,...e.handlers,...e.elements,...e.transformers,...e.components,...e.invariants,...e.migrations,...e.adminMigrations,...e.adminExpressions,...e.adminInvariants,...e.adminComponents,...e.adminElements,...e.webhooks,...e.locales,...e.mockTemplates,...e.projectFiles,...e.customCode].map(e=>[e.file.name,e]));let r=e=>/\/_[^/]+\//.test(e),m=[{path:"spec/",key:"spec"},{path:"src/admin/expressions/",key:"adminExpressions"},{path:"src/admin/invariants/",key:"adminInvariants"},{path:"src/admin/components/",key:"adminComponents"},{path:"src/admin/elements/",key:"adminElements"},{path:"src/admin/migrations/",key:"adminMigrations"},{path:"src/expressions/",key:"expressions"},{path:"src/actions/",key:"actions"},{path:"src/handlers/",key:"handlers"},{path:"src/elements/",key:"elements"},{path:"src/transformers/",key:"transformers"},{path:"src/components/",key:"components"},{path:"src/invariants/",key:"invariants"},{path:"src/migrations/",key:"migrations"},{path:"src/webhooks/",key:"webhooks"},{path:"src/locales/",key:"locales"},{path:"mocks/",key:"mockTemplates"}],l=new Set(["package.json",".gitignore","CLAUDE.md",".cursor/rules/phoenix.mdc"]),d=new Set(["migrations","adminMigrations"]),c=m.filter(({path:e,key:n})=>e.startsWith("src/")&&d.has(n)),p=(e,n)=>{let s=e.slice(n.length).split("/");return!(s.length<=1)&&s.slice(0,-1).some(e=>!e.startsWith("_"))},h=/\.(ts|tsx|js|jsx)$/,f=(e,n)=>{if("components"===e||"adminComponents"===e)return n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (no 'use webhook' directive)"};if("handlers"===e){let e=i(n);return void 0!==e?{membership:"named-handler",logSuffix:`webhook (the ${e} registration)`}:n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (not a named handler or pin)"}}};export const CategorizedFiles=(i,d,g,u)=>{let k={spec:[],expressions:[],actions:[],handlers:[],elements:[],transformers:[],components:[],invariants:[],migrations:[],adminMigrations:[],adminExpressions:[],adminInvariants:[],adminComponents:[],adminElements:[],webhooks:[],locales:[],mockTemplates:[],projectFiles:[],customCode:[]},b=[];for(let e of i.files){if("text"!==e.kind)continue;if(r(e.name)){k.customCode.push({file:e,category:"customCode"});continue}if(l.has(e.name)){k.projectFiles.push({file:e,category:"projectFiles"});continue}let n=!1;for(let{path:s,key:o}of m)if(e.name.startsWith(s)){k[o].push({file:e,category:o}),n=!0;break}n||b.push(e.name)}for(let e of b)e.startsWith("src/")&&g.error(o.UNKNOWN_SRC_PATH,a.UNKNOWN_SRC_PATH(e));for(let{path:e,key:n}of c)for(let s of k[n])p(s.file.name,e)&&g.error(o.INVALID_SUBDIRECTORY,a.INVALID_SUBDIRECTORY(s.file.name,e));if(k.webhooks.length>0&&!k.webhooks.some(e=>"src/webhooks/index.ts"===e.file.name)&&g.error(o.MISSING_WEBHOOK_INDEX,a.MISSING_WEBHOOK_INDEX()),g.hasErrors)return;let C=[];for(let e of Object.values(k))for(let n of e)C.push(n.file.name);let v=s(i,C),{analyzer:x,logger:y}=u,E=d.createBuilder("categorizedFiles/moduleAnalysis",{build:e=>{try{return{analysis:x(e.name,e.content)}}catch(e){return{error:e instanceof Error?e.message:String(e)}}},getKey:e=>e.name,compare:(e,n)=>e.content===n.content}),I=new Set,w=e=>{if(!h.test(e.name))return;I.add(e.name);let n=E.build({name:e.name,content:e.content}).output;return void 0!==n.error?void g.error(o.MODULE_ANALYSIS_FAILED,a[o.MODULE_ANALYSIS_FAILED](e.name,n.error)):n.analysis},S={},j={};for(let[e,s]of Object.entries(k)){let o=d.createBuilder(`categorizedFiles/${e}`,{build:e=>e,getKey:e=>e.name,compare:(e,n)=>e.depHash===n.depHash}),a=new Set;S[e]=s.map(e=>{let s=v[e.file.name]??{deps:[],hash:""},{changed:i}=o.build({name:e.file.name,depHash:s.hash});a.add(e.file.name);let t=w(e.file),r=void 0===t?void 0:f(e.category,t);return void 0!==r&&y.debug(`Webhook membership: ${e.file.name} -> ${r.logSuffix}`),n({file:e.file,category:e.category,deps:s.deps,depHash:s.hash,changed:i,analysis:t,webhookMembership:r?.membership})}),j[e]=o.cleanup(a)}E.cleanup(I);let _=(e,n)=>n.some(e=>e.changed)||!0===j[e],F=d.createBuilder("categorizedFiles/envs",{build:e=>e.envs,getKey:()=>"singleton",compare:(n,s)=>e(n.envs,s.envs)}).build({envs:i.envs}),M=n({spec:S.spec,specChanged:_("spec",S.spec),expressions:S.expressions,expressionsChanged:_("expressions",S.expressions),actions:S.actions,actionsChanged:_("actions",S.actions),handlers:S.handlers,handlersChanged:_("handlers",S.handlers),elements:S.elements,elementsChanged:_("elements",S.elements),transformers:S.transformers,transformersChanged:_("transformers",S.transformers),components:S.components,componentsChanged:_("components",S.components),invariants:S.invariants,invariantsChanged:_("invariants",S.invariants),migrations:S.migrations,migrationsChanged:_("migrations",S.migrations),adminMigrations:S.adminMigrations,adminMigrationsChanged:_("adminMigrations",S.adminMigrations),adminExpressions:S.adminExpressions,adminExpressionsChanged:_("adminExpressions",S.adminExpressions),adminInvariants:S.adminInvariants,adminInvariantsChanged:_("adminInvariants",S.adminInvariants),adminComponents:S.adminComponents,adminComponentsChanged:_("adminComponents",S.adminComponents),adminElements:S.adminElements,adminElementsChanged:_("adminElements",S.adminElements),webhooks:S.webhooks,webhooksChanged:_("webhooks",S.webhooks),locales:S.locales,localesChanged:_("locales",S.locales),mockTemplates:S.mockTemplates,mockTemplatesChanged:_("mockTemplates",S.mockTemplates),projectFiles:S.projectFiles,projectFilesChanged:_("projectFiles",S.projectFiles),customCode:S.customCode,customCodeChanged:_("customCode",S.customCode),envs:F.output,envsChanged:F.changed}),O=buildProjectFileIndex(M);for(let e of O.values()){if("pinned"!==e.webhookMembership&&"named-handler"!==e.webhookMembership)continue;let n=t(e,O);void 0!==n&&g.error(o.WEBHOOK_UNSAFE_IMPORT,a[o.WEBHOOK_UNSAFE_IMPORT](n.fileName,n.inclusionReason,n.importer,n.specifier))}return M};