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

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-create-configurator-skill.js

@@ -71,7 +71,9 @@ Walk through the whole journey as the intended user: start, explore and change o
 
 Check representative valid and invalid combinations, boundaries, dependent changes, independent options on repeated parts, and hand-calculated prices where applicable. Include persistence/reload, undo/redo, exports, and integrations when implemented. Invalid configurations should produce the agreed handling, not an assumed universal blocking pattern.
 
-Fix gaps and regressions, update the specification, and present the complete experience for the client's final review. State what is implemented, what remains provisional or unverified, and whether it is a working draft or ready for its intended users. Publishing and connecting live systems remain separate actions governed by the client's authorization and the environment's rules; obtain any required approval against the concrete result.`,c=`## Verification evidence
+Fix gaps and regressions, update the specification, and present the complete experience for the client's final review. State what is implemented, what remains provisional or unverified, and whether it is a working draft or ready for its intended users. Publishing and connecting live systems remain separate actions governed by the client's authorization and the environment's rules; obtain any required approval against the concrete result.
+
+Once the client says they are done, or the configurator is live and they confirm the work is finished, follow the \`phoenix-feedback\` skill to interview them for an evaluation of the run. Ask for it once, and send it only with their approval.`,c=`## Verification evidence
 
 Use the project's documented verification commands and available tools throughout. Distinguish automated checks, your actual preview observations, and client feedback. A successful build does not prove preview access or interaction quality. Missing browser automation need not prevent the client from using a preview: offer a focused check and record their result as client feedback. Disclose anything you cannot test; a generic “OK” is not evidence that an untested interaction works.`,d=`# Phoenix UX guidance
 

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

@@ -4,7 +4,9 @@ Draft feedback for the Phoenix team when one of these happens while you work in
 - **Misleading guidance** — a doc page, a Phoenix skill or an error message sent you the wrong way, or did not say what you needed.
 - **Missing feature** — something the SDK does not support forced a workaround, or a routine task took far more steps than it should.
 
-Do not draft feedback for problems in this project's own specs or code, for a suspicion you have not checked, or twice for the same problem. Write one draft per distinct problem.`,o=`## Ask Before You Send
+Do not draft feedback for problems in this project's own specs or code, for a suspicion you have not checked, or twice for the same problem. Write one draft per distinct problem.
+
+The evaluation of a finished run is feedback too; the section "Evaluate the Run" says when to ask for it.`,o=`## Ask Before You Send
 Never send feedback on your own. Show the user a draft and send it only after they approve it.
 
 When to ask is your judgement:
@@ -12,20 +14,41 @@ When to ask is your judgement:
 - **At the end of the task** — everything else. Collect the details while you work and show all drafts together in your final message.
 - **When the user asks** you to send feedback — draft it and show it before sending.
 
-The draft is exactly what would be sent: the type, the message, the project if you name one with \`--projectSlug\`, and the contact if the user gave one. Send it unchanged after a yes; if the user edits it, send their version. If they decline, drop it and do not raise that problem again.`,a=`## Ask for a Rating After a Deploy
-When \`phoenix deploy\` reports that the configurator is live, tell the user the live URL first, then ask them to rate building with Phoenix so far:
-- Ask for a score from 0 to 10, where 10 is the best, and one optional sentence on what would have made it better. Say in the same question that the answer is sent to the Phoenix team as feedback.
-- Ask once per conversation, after the first deploy that goes live. Do not ask again after later deploys, and do not ask after a deploy that failed.
-- Never choose or guess the score yourself. If the user skips the question or declines, send nothing and do not ask again.
-
-A rating is feedback like any other, so the rules of this skill apply. Write the comment from the user's words, and take out anything the last section forbids: replace this project's product, customer and people names with generic words. Then show the user the three lines below exactly as they would be sent and send them only after a yes; if they edit the text, send their version. Use \`none\` when they gave no comment:
-\`\`\`bash
-pnpm phoenix feedback 'Rating: <score>/10
-Comment: <their comment, or none>
-Stage: after a deploy' --type other --agent '<your agent name>'
+The draft is exactly what would be sent: the type, the full message, the project if you name one with \`--projectSlug\`, and the contact if the user gave one. Send it unchanged after a yes; if the user edits it, send their version. If they decline, drop it and do not raise that problem again.`,n=`## Evaluate the Run
+When the work on the configurator is finished, interview the user for an evaluation of the run and send it as feedback. The run is finished when the user says they are done, or when \`phoenix deploy\` reported the configurator live and the user confirms they have nothing more to build; ask that once after a deploy goes live, and do not start the interview while they want to continue.
+
+Say first that the answers are sent to the Phoenix team as feedback, and that the user can decline. Then ask one question at a time, in this order, and wait for each answer before asking the next. Give the short explanation with each question. Every score is a whole number from 0 to 10, where 0 is catastrophic, 5 is passable and 10 is amazing:
+1. **Minutes spent** — roughly how many minutes the user spent on the run, from the first prompt to now. This one is a number of minutes, not a score.
+2. **Agent guidance** — how clear it was what to expect and what to do, how clearly you explained yourself, and how well they understood the consequences of their choices.
+3. **Functionality** — how complete the configurator is: whether it configures the full product with all its options, keeps the user from creating or submitting a wrong configuration, and offers a way to finalize one.
+4. **UX** — how easy the configurator is to understand and operate, how clear the choices are, and how understandable incompatibilities and the ways to resolve them are.
+5. **3D quality** — how realistic and attractive the configured object and its scene are: shapes, textures, surroundings, lighting and shadows.
+6. **UI visuals** — how good the user interface looks.
+7. **Overall** — the user's subjective verdict on the configurator as a whole.
+8. **Comments** — anything else about the experience, in their own words. This one is free text and may be empty.
+
+Rules of the interview:
+- Ask once per conversation. Do not run it again after a later deploy, and do not run it after a deploy that failed.
+- Never choose, guess or adjust a score, and never answer a question for the user. When they skip one, write \`skipped\` for it.
+- When the user declines the evaluation, send nothing and do not ask again.
+
+Compose the evaluation from the answers with exactly these labels, one per line, in this order. Write \`none\` when there are no comments, and fill \`Build\` and \`Configurator\` as the report template describes:
+\`\`\`text
+Evaluation
+Minutes spent: <minutes>
+Agent guidance: <score>/10
+Functionality: <score>/10
+UX: <score>/10
+3D quality: <score>/10
+UI visuals: <score>/10
+Overall: <score>/10
+Comments: <their comments, or none>
+Build: <build id> <Studio build page link>
+Configurator: <live configurator link>
 \`\`\`
-Keep the three labels and their order, so the ratings can be read out of the feedback list. A rating is not a bug report: when the comment names a concrete problem, offer to draft it as its own feedback as the sections above describe.`,n=`## What Never Goes Into Feedback
+Keep the labels and their order, so the scores can be read out of the feedback list and its export. Show the user the text exactly as it would be sent, and send it with \`--type other\` only after a yes; if they edit it, send their version. An evaluation is not a bug report: when a comment names a concrete problem, offer to draft it as its own report.`,a=`## What Never Goes Into Feedback
 The message leaves this project and is read by the Phoenix team. Never include:
-- secrets: API tokens, keys, passwords or \`.env\` values;
-- customer or end-user data, or personal data such as names and email addresses, other than a contact the user asked you to add;
-- this project's source code, specs or business rules. Describe the shape of the problem in words, or reduce it to a generic example that contains nothing of the project.`;export const generatePhoenixFeedbackSkill=()=>e({name:"phoenix-feedback",description:"Drafting feedback about the Phoenix SDK, CLI, documentation or Studio for the Phoenix team and sending it with the phoenix feedback command once the user approves the draft, covering when to raise it, how to write it, the rating asked for after a deploy and what must never be included. Use when the SDK or CLI misbehaves, a doc or skill misled you, a missing feature forced a workaround, the user asks to send feedback, or phoenix deploy has just gone live and the user should be asked to rate the experience from 0 to 10.",sections:[t,o,"## How to Send It\n```bash\npnpm phoenix feedback '<message>' --type bug --agent '<your agent name>'\n```\n- Put the message in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside the message as `'\\''`; in PowerShell, double it instead.\n- `--type` is `bug`, `idea` or `other` (default `other`). Use `idea` for a missing feature or an improvement.\n- `--agent` names you, the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the user wants a reply and gave you the contact to use.\n- The workspace, user, SDK version and the spec's `project` are attached automatically. `--projectSlug <slug>` names another project of the workspace.\n- A message holds at most 5000 characters.\n\nWrite the message for someone who cannot see this project: what you ran or called, what you expected, what happened instead with the error text, and the workaround if you found one. Before quoting an error, replace this project's names, file paths and values in it with generic placeholders, as the list below requires.\n\nThe command needs `phoenix login`. If it answers that you are not signed in, tell the user once and continue; do not sign in yourself, because the sign-in is approved in a browser.\n\nAfter sending, confirm it to the user in one line.",a,n]});
+- secrets and credentials: API tokens, keys, passwords or \`.env\` values, also when they appear inside an error or a log you quote. Replace each with \`<redacted>\`;
+- personal data, or data of the project's customers and end users, such as names, email addresses and orders, other than a contact the user asked you to add.
+
+Parts of this project may go into a message: file names and paths, snippets of its specs and code, and the user's own words. They are sent only as part of a draft the user saw and approved, which is why the draft you show is always the full text.`;export const generatePhoenixFeedbackSkill=()=>e({name:"phoenix-feedback",description:"Drafting feedback about the Phoenix SDK, CLI, documentation or Studio for the Phoenix team and sending it with the phoenix feedback command once the user approves the draft, covering when to raise it, the report template with the build and configurator links, the evaluation interview at the end of a run, how to send it and what must never be included. Use when the SDK or CLI misbehaves, a doc or skill misled you, a missing feature forced a workaround, the user asks to send feedback, or the user is done with the configurator and the run should be evaluated.",sections:[t,o,"## Report Template\nWrite a report as plain text with the labels below, in this order, so the Phoenix team reads every report the same way. Keep every label; write `none` or `not deployed yet` where you have nothing to put.\n```text\nBuild: <build id> <Studio build page link>\nConfigurator: <live configurator link>\n\nWhat I was doing:\n<the task and the step you were on>\n\nWhat happened and what I expected:\n<what you ran or called, the result you got, and the result you expected>\n\nExact error or agent output:\n<the error text or the output, copied unchanged>\n\nWorkaround:\n<what you did instead, or none>\n\nConversation log:\n<the conversation condensed to the turns that matter: what the user asked, what you tried, what failed>\n```\n- **Build** is the latest build of this project, the one whose sources show the problem. `pnpm phoenix deploy` prints its id as `Build <id> started` and its page as `Follow the build in Studio: <url>`. When that line is missing, compose the link as `https://<workspace>.<studio host>/builder/deployments/<build id>`: the workspace is the one named at `phoenix login`, and the host is `studio.eu.salsita.ai` for the `eu` region, `studio.salsita.ai` for `us` and `studio-staging.salsita.app` for staging. A Studio address passed to login with `--studioUrl` replaces the workspace and host. Never invent a build id: when the project was not deployed, write `not deployed yet`.\n- **Configurator** is the live address `pnpm phoenix deploy` prints once the build is live.\n- The team downloads the sources of the build from its Studio page, so do not paste whole files; quote only the lines that show the problem.\n- Quote errors and output exactly. A report that paraphrases an error cannot be searched for.\n- Condense the conversation log, do not dump it: keep the user's requests, your decisions and the failures, and leave out tool output that the other sections already carry.",n,"## How to Send It\nWrite a report or an evaluation to a text file and send the file, so the shell changes nothing in it:\n```bash\npnpm phoenix feedback --file <path> --type bug --agent '<your agent name>'\n```\nPut the file outside the project, in the system's temporary folder, and delete it after sending. A note of a line or two can go in as an argument instead:\n```bash\npnpm phoenix feedback '<message>' --type idea --agent '<your agent name>'\n```\n- Give either `--file` or the message argument, never both.\n- Put a message argument in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside the message as `'\\''`; in PowerShell, double it instead.\n- `--type` is `bug`, `idea` or `other` (default `other`). Use `idea` for a missing feature or an improvement, and `other` for an evaluation.\n- `--agent` names you, the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the user wants a reply and gave you the contact to use.\n- The workspace, user, SDK version and the spec's `project` are attached automatically. `--projectSlug <slug>` names another project of the workspace.\n- A message holds at most 100,000 characters. Shorten the conversation log first when a report is longer.\n\nThe command needs `phoenix login`. If it answers that you are not signed in, tell the user once and continue; do not sign in yourself, because the sign-in is approved in a browser.\n\nAfter sending, confirm it to the user in one line.",a]});

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\`.