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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/README.md +19 -11
  2. package/dist/application-spec/errors/diagnostic-codes.d.ts +6 -0
  3. package/dist/application-spec/errors/diagnostic-codes.js +1 -1
  4. package/dist/application-spec/errors/diagnostic-messages.d.ts +6 -0
  5. package/dist/application-spec/errors/diagnostic-messages.js +1 -1
  6. package/dist/application-spec/generate-application/code/domain-runtime-files.js +1 -1
  7. package/dist/application-spec/generate-application/code/templates/application-types.js +6 -6
  8. package/dist/application-spec/generate-application/code/templates/configurator-domain-code.d.ts +1 -0
  9. package/dist/application-spec/generate-application/code/templates/configurator-domain-code.js +11 -8
  10. package/dist/application-spec/generate-application/code/templates/domain-spec/generate-domain-block.d.ts +3 -1
  11. package/dist/application-spec/generate-application/code/templates/domain-spec/generate-domain-block.js +70 -66
  12. package/dist/application-spec/generate-application/code/templates/domain-spec/generate-phx-globals.js +3 -0
  13. package/dist/application-spec/generate-application/code/templates/domain-spec.js +5 -5
  14. package/dist/application-spec/generate-application/code/templates/domain.js +2 -2
  15. package/dist/application-spec/generate-application/code/templates/global-definition/generate-action-types.d.ts +11 -0
  16. package/dist/application-spec/generate-application/code/templates/global-definition/generate-action-types.js +8 -0
  17. package/dist/application-spec/generate-application/code/templates/global-definition/index.d.ts +1 -0
  18. package/dist/application-spec/generate-application/code/templates/global-definition/index.js +1 -1
  19. package/dist/application-spec/generate-application/code/templates/globals.js +1 -0
  20. package/dist/application-spec/generate-application/code/templates/index.d.ts +6 -6
  21. package/dist/application-spec/generate-application/code/templates/index.js +1 -1
  22. package/dist/application-spec/generate-application/code/templates/skills/agents-md.js +2 -0
  23. package/dist/application-spec/generate-application/code/templates/skills/phoenix-cli-skill.js +1 -0
  24. package/dist/application-spec/generate-application/code/templates/{phoenix-create-configurator-skill.d.ts → skills/phoenix-create-configurator-skill.d.ts} +1 -1
  25. package/dist/application-spec/generate-application/code/templates/{phoenix-create-configurator-skill.js → skills/phoenix-create-configurator-skill.js} +4 -2
  26. package/dist/application-spec/generate-application/code/templates/skills/phoenix-feedback-skill.js +54 -0
  27. package/dist/application-spec/generate-application/code/templates/{phoenix-review-skill.js → skills/phoenix-review-skill.js} +6 -4
  28. package/dist/application-spec/generate-application/code/templates/skills/phoenix-skill.js +1 -0
  29. package/dist/application-spec/generate-application/code/templates/{common → skills}/sdk-content.d.ts +24 -1
  30. package/dist/application-spec/generate-application/code/templates/skills/sdk-content.js +67 -0
  31. package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.d.ts +2 -0
  32. package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.js +1 -1
  33. package/dist/application-spec/generate-application/runtime/sections/actions-runtime.d.ts +14 -0
  34. package/dist/application-spec/generate-application/runtime/sections/actions-runtime.js +1 -0
  35. package/dist/application-spec/generate-application/runtime/sections/index.d.ts +1 -0
  36. package/dist/application-spec/generate-application/runtime/sections/index.js +1 -1
  37. package/dist/application-spec/parse-application-files/categorize/categorize-files.d.ts +3 -1
  38. package/dist/application-spec/parse-application-files/categorize/categorize-files.js +1 -1
  39. package/dist/application-spec/parse-application-files/merge/index.d.ts +1 -0
  40. package/dist/application-spec/parse-application-files/merge/index.js +1 -1
  41. package/dist/application-spec/parse-application-files/merge/merged-actions.d.ts +11 -0
  42. package/dist/application-spec/parse-application-files/merge/merged-actions.js +1 -0
  43. package/dist/application-spec/parse-application-files/merge/merged-spec.d.ts +2 -0
  44. package/dist/application-spec/parse-application-files/merge/merged-spec.js +1 -1
  45. package/dist/application-spec/parse-application-files/raw-spec/index.d.ts +1 -0
  46. package/dist/application-spec/parse-application-files/raw-spec/index.js +1 -1
  47. package/dist/application-spec/parse-application-files/raw-spec/raw-actions.d.ts +18 -0
  48. package/dist/application-spec/parse-application-files/raw-spec/raw-actions.js +1 -0
  49. package/dist/application-spec/parse-application-files/raw-spec/raw-assistant.d.ts +14 -2
  50. package/dist/application-spec/parse-application-files/raw-spec/raw-assistant.js +1 -1
  51. package/dist/application-spec/parse-application-files/raw-spec/raw-spec-file.d.ts +2 -0
  52. package/dist/application-spec/parse-application-files/raw-spec/raw-spec-file.js +1 -1
  53. package/dist/application-spec/parse-application-files/resolve/resolve-import-modules.js +1 -1
  54. package/dist/application-spec/parse-application-files/spec/application/application-spec.js +1 -1
  55. package/dist/application-spec/parse-application-files/spec/application/configurator-spec/configurator-spec.d.ts +4 -2
  56. package/dist/application-spec/parse-application-files/spec/application/configurator-spec/configurator-spec.js +1 -1
  57. package/dist/application-spec/parse-application-files/spec/common/index.d.ts +1 -0
  58. package/dist/application-spec/parse-application-files/spec/common/index.js +1 -1
  59. package/dist/application-spec/parse-application-files/spec/common/schema-ref-resolver.d.ts +23 -0
  60. package/dist/application-spec/parse-application-files/spec/common/schema-ref-resolver.js +1 -0
  61. package/dist/application-spec/parse-application-files/spec/model/names/action-name.d.ts +10 -0
  62. package/dist/application-spec/parse-application-files/spec/model/names/action-name.js +1 -0
  63. package/dist/application-spec/parse-application-files/spec/model/names/index.d.ts +1 -0
  64. package/dist/application-spec/parse-application-files/spec/model/names/index.js +1 -1
  65. package/dist/application-spec/parse-application-files/spec/sections/actions.d.ts +35 -0
  66. package/dist/application-spec/parse-application-files/spec/sections/actions.js +1 -0
  67. package/dist/application-spec/parse-application-files/spec/sections/assistant/assistant-field-type.d.ts +3 -14
  68. package/dist/application-spec/parse-application-files/spec/sections/assistant/assistant-field-type.js +1 -1
  69. package/dist/application-spec/parse-application-files/spec/sections/assistant/assistant-schema.d.ts +12 -3
  70. package/dist/application-spec/parse-application-files/spec/sections/assistant/assistant-schema.js +1 -1
  71. package/dist/application-spec/parse-application-files/spec/sections/assistant/assistant.d.ts +5 -3
  72. package/dist/application-spec/parse-application-files/spec/sections/index.d.ts +1 -0
  73. package/dist/application-spec/parse-application-files/spec/sections/index.js +1 -1
  74. package/dist/client/phoenix-api.d.ts +5 -1
  75. package/dist/configurator/application-runtime/extensions/configurator-extension-systems.d.ts +2 -1
  76. package/dist/configurator/application-runtime/extensions/configurator-extension-systems.js +1 -1
  77. package/dist/configurator/application-runtime/extensions/selectors.d.ts +2 -1
  78. package/dist/configurator/application-runtime/extensions/selectors.js +1 -1
  79. package/dist/configurator/application-runtime/extensions/systems/assistant-system/assistant-system.d.ts +35 -0
  80. package/dist/configurator/application-runtime/extensions/systems/assistant-system/assistant-system.js +1 -0
  81. package/dist/configurator/{assistant → application-runtime/extensions/systems/assistant-system}/browser-details.d.ts +1 -1
  82. package/dist/configurator/application-runtime/extensions/systems/assistant-system/browser-details.js +1 -0
  83. package/dist/configurator/{assistant → application-runtime/extensions/systems/assistant-system}/graphql-tools.d.ts +13 -14
  84. package/dist/configurator/application-runtime/extensions/systems/assistant-system/graphql-tools.js +1 -0
  85. package/dist/configurator/application-runtime/extensions/systems/graphql-system/graphql-system.js +1 -1
  86. package/dist/configurator/application-runtime/extensions/systems/index.d.ts +1 -0
  87. package/dist/configurator/application-runtime/extensions/systems/index.js +1 -1
  88. package/dist/configurator/assistant/use-assistant-chat.js +1 -1
  89. package/dist/docs/index.json +12 -2
  90. package/dist/docs/other-features/domain-actions.mdx +418 -0
  91. package/dist/docs/phoenix/admin.mdx +2 -2
  92. package/dist/docs/phoenix/best-practices.mdx +1 -0
  93. package/dist/docs/phoenix/finalization.mdx +1 -1
  94. package/dist/docs/phoenix/integration/headless-mode-external.mdx +5 -5
  95. package/dist/docs/phoenix/integration/widget-mode-external.mdx +5 -5
  96. package/dist/docs/phoenix/migrations.mdx +45 -5
  97. package/dist/docs/phoenix/phoenix-cli.mdx +60 -20
  98. package/dist/docs/phoenix/project-structure.mdx +4 -1
  99. package/dist/docs/phoenix/sdk-builder-workflow.mdx +9 -6
  100. package/dist/domain/actions/action-factory.d.ts +10 -0
  101. package/dist/domain/actions/action-factory.js +1 -0
  102. package/dist/domain/actions/prepare-action-implementations.d.ts +15 -0
  103. package/dist/domain/actions/prepare-action-implementations.js +5 -0
  104. package/dist/domain/application/application-config.d.ts +3 -1
  105. package/dist/domain/application/assistant-mutations.d.ts +15 -14
  106. package/dist/domain/application/assistant-mutations.js +1 -1
  107. package/dist/domain/core/action.d.ts +67 -0
  108. package/dist/domain/core/action.js +1 -0
  109. package/dist/domain/core/domain-factory.d.ts +4 -0
  110. package/dist/domain/core/index.d.ts +1 -0
  111. package/dist/domain/domain-builder.d.ts +7 -0
  112. package/dist/domain/domain-builder.js +1 -1
  113. package/dist/domain/domain-context/action-system/action-system.d.ts +40 -0
  114. package/dist/domain/domain-context/action-system/action-system.js +1 -0
  115. package/dist/domain/domain-context/domain-context-systems.d.ts +5 -2
  116. package/dist/domain/domain-context/index.d.ts +1 -0
  117. package/dist/domain/domain-context/index.js +1 -1
  118. package/dist/domain/domain-runtime/domain-context/domain-context.js +1 -1
  119. package/dist/domain/domain-runtime/domain-context/selectors.d.ts +4 -0
  120. package/dist/domain/domain-runtime/domain-context/selectors.js +1 -1
  121. package/dist/domain/domain-runtime/domain-runtime.d.ts +12 -0
  122. package/dist/domain/domain-runtime/spec/initialize.js +1 -1
  123. package/dist/domain/domain-runtime/spec/types.d.ts +15 -1
  124. package/dist/domain/index.d.ts +2 -0
  125. package/dist/domain/index.js +1 -1
  126. package/dist/domain/mocks/create-mock-domain-runtime.d.ts +6 -0
  127. package/dist/editor/domain-editors/DomainSpecContext.js +1 -1
  128. package/dist/editor/domain-editors/apply-spec-update.js +1 -1
  129. package/dist/editor/domain-editors/use-implementation-files.d.ts +7 -3
  130. package/dist/editor/domain-editors/use-implementation-files.js +1 -1
  131. package/dist/phoenix/application-spec/generate-assistant-prompt.d.ts +2 -2
  132. package/dist/phoenix/application-spec/generate-assistant-prompt.js +1 -1
  133. package/dist/phoenix/cli.js +1 -1
  134. package/dist/phoenix/commands/build.d.ts +5 -0
  135. package/dist/phoenix/commands/build.js +1 -1
  136. package/dist/phoenix/commands/deploy.js +2 -2
  137. package/dist/phoenix/commands/feedback.d.ts +2 -1
  138. package/dist/phoenix/commands/feedback.js +1 -1
  139. package/dist/phoenix/commands/login.d.ts +24 -6
  140. package/dist/phoenix/commands/login.js +2 -2
  141. package/dist/phoenix/services/index.d.ts +1 -0
  142. package/dist/phoenix/services/index.js +1 -1
  143. package/dist/phoenix/services/phx-banner-plugin.d.ts +32 -0
  144. package/dist/phoenix/services/phx-banner-plugin.js +1 -0
  145. package/dist/phoenix/services/phx-licenses-plugin.d.ts +55 -0
  146. package/dist/phoenix/services/phx-licenses-plugin.js +8 -0
  147. package/dist/phoenix/services/vite-config.d.ts +2 -0
  148. package/dist/phoenix/services/vite-config.js +1 -1
  149. package/dist/phoenix/utils/index.d.ts +1 -0
  150. package/dist/phoenix/utils/index.js +1 -1
  151. package/dist/phoenix/utils/read-git-commit.d.ts +14 -0
  152. package/dist/phoenix/utils/read-git-commit.js +1 -0
  153. package/dist/react-sdk/application-runtime/runtime/create-application-runtime.d.ts +12 -0
  154. package/dist/react-sdk/domain-context/common-hooks/use-domain-context.d.ts +3 -0
  155. package/package.json +3 -3
  156. package/dist/application-spec/generate-application/code/templates/agents-md.js +0 -2
  157. package/dist/application-spec/generate-application/code/templates/common/sdk-content.js +0 -67
  158. package/dist/application-spec/generate-application/code/templates/phoenix-cli-skill.js +0 -1
  159. package/dist/application-spec/generate-application/code/templates/phoenix-feedback-skill.js +0 -31
  160. package/dist/application-spec/generate-application/code/templates/phoenix-skill.js +0 -1
  161. package/dist/configurator/assistant/browser-details.js +0 -1
  162. package/dist/configurator/assistant/graphql-tools.js +0 -1
  163. /package/dist/application-spec/generate-application/code/templates/{common → skills}/agent-skill.d.ts +0 -0
  164. /package/dist/application-spec/generate-application/code/templates/{common → skills}/agent-skill.js +0 -0
  165. /package/dist/application-spec/generate-application/code/templates/{agents-md.d.ts → skills/agents-md.d.ts} +0 -0
  166. /package/dist/application-spec/generate-application/code/templates/{phoenix-cli-skill.d.ts → skills/phoenix-cli-skill.d.ts} +0 -0
  167. /package/dist/application-spec/generate-application/code/templates/{phoenix-feedback-skill.d.ts → skills/phoenix-feedback-skill.d.ts} +0 -0
  168. /package/dist/application-spec/generate-application/code/templates/{phoenix-review-skill.d.ts → skills/phoenix-review-skill.d.ts} +0 -0
  169. /package/dist/application-spec/generate-application/code/templates/{phoenix-skill.d.ts → skills/phoenix-skill.d.ts} +0 -0
@@ -17,4 +17,6 @@ export declare const getViteDevConfig: (options?: {
17
17
  export declare const getViteBuildConfigs: (options: {
18
18
  enableEditor?: boolean;
19
19
  templateFiles: readonly string[];
20
+ sdkVersion: string;
21
+ banner: string | undefined;
20
22
  }) => Promise<InlineConfig[]>;
@@ -1 +1 @@
1
- import{lingui as e}from"@lingui/vite-plugin";import i from"@vitejs/plugin-react";import{mkdir as t,readFile as n,writeFile as r}from"fs/promises";import o from"lodash-es/camelCase.js";import{createRequire as a}from"node:module";import{dirname as s,resolve as m}from"path";import{createLogger as l}from"vite";import d from"vite-plugin-css-injected-by-js";import{isUsingLocalSdk as f}from"../utils/package-info.js";import{loadFrontendConfigModule as c}from"./frontend-config.js";import{phxCspNoncePlugin as p}from"./phx-csp-nonce-plugin.js";import{phxGlobalIsolationPlugin as g}from"./phx-global-isolation-plugin.js";let u=null;export const setViteLogSink=(e,i={})=>{u={sink:e,echo:i.echo??!1}};let h=["react","react-dom","three","@react-three/fiber","@react-three/drei","@react-three/postprocessing","its-fine","@emotion/react","@emotion/styled","@mui/material","@mui/system","@tanstack/react-query","rxjs"],S=e=>{let i=e.DEPLOYMENT_ID;if("string"!=typeof i)throw Error("DEPLOYMENT_ID is required in runtime config");return i};export const getViteDevConfig=async t=>{var n,r;let o,d,p=f(),y=c(),O=y.readRuntimeConfig(),b=y.frontendBuildConfig,D=Object.fromEntries((t?.templateFiles??[]).map(e=>[e,`.phoenix/${e}`]));return{...u&&{customLogger:(n=u.sink,r=u.echo,o=l(),{get hasWarned(){return o.hasWarned},info:(e,i)=>{n("info",e),r&&o.info(e,i)},warn:(e,i)=>{n("warn",e),r&&o.warn(e,i)},warnOnce:(e,i)=>{n("warn",e),r&&o.warnOnce(e,i)},error:(e,i)=>{n("error",e),r&&o.error(e,i)},clearScreen:e=>{r&&o.clearScreen(e)},hasErrorLogged:e=>o.hasErrorLogged(e)}),...u.echo?{}:{clearScreen:!1}},mode:"development",optimizeDeps:{exclude:["@swc/wasm-web"],...p&&{entries:["index.html","admin.html",...t?.templateFiles??[]],force:!0}},...p&&{resolve:{alias:(d=a(m(process.cwd(),"package.json")),h.flatMap(e=>{try{let i=s(d.resolve(`${e}/package.json`));return[{find:RegExp(`^${e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}(/|$)`),replacement:`${i}$1`}]}catch{return[]}}))}},plugins:[i({babel:{plugins:["macros"]}}),e(),{name:"vite:runtime-config",apply:(e,i)=>"build"===i.command||"development"===i.mode,config:e=>{let i=y.readRuntimeConfig(),t=y.frontendBuildConfig;return{...e,define:{...e.define,"phx.frontendEnv":JSON.stringify(i),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(t.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(t.gltfDecoder)}}}},g({getDeploymentId:()=>S(y.readRuntimeConfig())})],define:{"process.env":{},"import.meta.env.DEV":!0,"import.meta.env.PROD":!1,"phx.frontendEnv":JSON.stringify(O),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(b.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(b.gltfDecoder)},build:{rollupOptions:{input:{index:".phoenix/index.html",admin:".phoenix/admin.html",...D}}},root:m(process.cwd(),"./.phoenix"),server:{watch:{ignored:["./**/*.{ts,tsx}","./.swc/**","../spec/**","../src/**"]}}}};export const getViteBuildConfigs=async a=>{let l=c(),f=l.readRuntimeConfig(),u=l.frontendBuildConfig,h=[{name:"salsita-configurator",entryFile:"./configurator.ts",mainScriptPath:"./configurator.ts",htmlFiles:["./index.html",...{templateFiles:a.templateFiles}.templateFiles],main:!0,format:"iife"},{name:"salsita-admin",entryFile:"./admin.ts",mainScriptPath:"./admin.ts",htmlFiles:["./admin.html"],main:!1,format:"iife"},{name:"salsita-embedded-admin",entryFile:"./embedded-admin.ts",mainScriptPath:"./embedded-admin.ts",htmlFiles:[],main:!1,format:"es"},{name:"salsita-embedded-configurator",entryFile:"./embedded-configurator.ts",mainScriptPath:"./embedded-configurator.ts",htmlFiles:[],main:!1,format:"es"}].map(c=>({plugins:[i({babel:{plugins:["macros"]}}),e(),d({useStrictCSP:!0}),p(),g({getDeploymentId:()=>S(l.readRuntimeConfig())}),{name:"vite:lib-index",writeBundle:async()=>{if(!c.htmlFiles.length)return;let e="iife"===c.format?`${c.name}.iife.js`:`${c.name}.js`;for(let i of c.htmlFiles){if(c.main&&a.enableEditor&&"./index.html"===i)continue;let o=m("./.phoenix",i),l=m("./.phoenix/dist/frontend",i);await t(s(l),{recursive:!0});let d=(await n(o,"utf-8")).replace(c.mainScriptPath,e);await r(l,d,"utf-8")}}}],build:{outDir:"./dist/frontend",chunkSizeWarningLimit:4e3,lib:{entry:c.entryFile,name:o(c.name),formats:[c.format],fileName:()=>"iife"===c.format?`${c.name}.iife.js`:`${c.name}.js`},rollupOptions:{external:[],output:{assetFileNames:`${c.name}.[ext]`}},minify:!0,emptyOutDir:!1},root:m(process.cwd(),"./.phoenix"),define:{"process.env":{},"process.env.NODE_ENV":JSON.stringify("production"),"phx.frontendEnv":JSON.stringify(f),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(u.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(u.gltfDecoder)}}));return a.enableEditor?[...h,{plugins:[i({babel:{plugins:["macros"]}}),e(),d({useStrictCSP:!0}),p()],build:{outDir:"./dist/frontend",chunkSizeWarningLimit:4e3,rollupOptions:{external:[]},minify:!0,emptyOutDir:!1},root:m(process.cwd(),"./.phoenix"),define:{"process.env":{},"process.env.NODE_ENV":JSON.stringify("production"),"phx.frontendEnv":JSON.stringify(f),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(u.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(u.gltfDecoder)}}]:h};
1
+ import{lingui as e}from"@lingui/vite-plugin";import i from"@vitejs/plugin-react";import{mkdir as t,readFile as n,writeFile as r}from"fs/promises";import o from"lodash-es/camelCase.js";import{createRequire as a}from"node:module";import{dirname as s,resolve as m}from"path";import{createLogger as l}from"vite";import d from"vite-plugin-css-injected-by-js";import{isUsingLocalSdk as f}from"../utils/package-info.js";import{loadFrontendConfigModule as p}from"./frontend-config.js";import{phxBannerPlugin as c}from"./phx-banner-plugin.js";import{phxCspNoncePlugin as g}from"./phx-csp-nonce-plugin.js";import{phxGlobalIsolationPlugin as u}from"./phx-global-isolation-plugin.js";import{phxLicensesPlugin as h}from"./phx-licenses-plugin.js";let S=null;export const setViteLogSink=(e,i={})=>{S={sink:e,echo:i.echo??!1}};let b=["react","react-dom","three","@react-three/fiber","@react-three/drei","@react-three/postprocessing","its-fine","@emotion/react","@emotion/styled","@mui/material","@mui/system","@tanstack/react-query","rxjs"],y=e=>{let i=e.DEPLOYMENT_ID;if("string"!=typeof i)throw Error("DEPLOYMENT_ID is required in runtime config");return i};export const getViteDevConfig=async t=>{var n,r;let o,d,c=f(),g=p(),h=g.readRuntimeConfig(),O=g.frontendBuildConfig,x=Object.fromEntries((t?.templateFiles??[]).map(e=>[e,`.phoenix/${e}`]));return{...S&&{customLogger:(n=S.sink,r=S.echo,o=l(),{get hasWarned(){return o.hasWarned},info:(e,i)=>{n("info",e),r&&o.info(e,i)},warn:(e,i)=>{n("warn",e),r&&o.warn(e,i)},warnOnce:(e,i)=>{n("warn",e),r&&o.warnOnce(e,i)},error:(e,i)=>{n("error",e),r&&o.error(e,i)},clearScreen:e=>{r&&o.clearScreen(e)},hasErrorLogged:e=>o.hasErrorLogged(e)}),...S.echo?{}:{clearScreen:!1}},mode:"development",optimizeDeps:{exclude:["@swc/wasm-web"],...c&&{entries:["index.html","admin.html",...t?.templateFiles??[]],force:!0}},...c&&{resolve:{alias:(d=a(m(process.cwd(),"package.json")),b.flatMap(e=>{try{let i=s(d.resolve(`${e}/package.json`));return[{find:RegExp(`^${e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}(/|$)`),replacement:`${i}$1`}]}catch{return[]}}))}},plugins:[i({babel:{plugins:["macros"]}}),e(),{name:"vite:runtime-config",apply:(e,i)=>"build"===i.command||"development"===i.mode,config:e=>{let i=g.readRuntimeConfig(),t=g.frontendBuildConfig;return{...e,define:{...e.define,"phx.frontendEnv":JSON.stringify(i),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(t.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(t.gltfDecoder)}}}},u({getDeploymentId:()=>y(g.readRuntimeConfig())})],define:{"process.env":{},"import.meta.env.DEV":!0,"import.meta.env.PROD":!1,"phx.frontendEnv":JSON.stringify(h),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(O.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(O.gltfDecoder)},build:{rollupOptions:{input:{index:".phoenix/index.html",admin:".phoenix/admin.html",...x}}},root:m(process.cwd(),"./.phoenix"),server:{watch:{ignored:["./**/*.{ts,tsx}","./.swc/**","../spec/**","../src/**"]}}}};export const getViteBuildConfigs=async a=>{let l=p(),f=l.readRuntimeConfig(),S=l.frontendBuildConfig,b=h(),O=c({sdkVersion:a.sdkVersion,banner:a.banner}),x=[{name:"salsita-configurator",entryFile:"./configurator.ts",mainScriptPath:"./configurator.ts",htmlFiles:["./index.html",...{templateFiles:a.templateFiles}.templateFiles],main:!0,format:"iife"},{name:"salsita-admin",entryFile:"./admin.ts",mainScriptPath:"./admin.ts",htmlFiles:["./admin.html"],main:!1,format:"iife"},{name:"salsita-embedded-admin",entryFile:"./embedded-admin.ts",mainScriptPath:"./embedded-admin.ts",htmlFiles:[],main:!1,format:"es"},{name:"salsita-embedded-configurator",entryFile:"./embedded-configurator.ts",mainScriptPath:"./embedded-configurator.ts",htmlFiles:[],main:!1,format:"es"}].map(p=>({plugins:[i({babel:{plugins:["macros"]}}),e(),d({useStrictCSP:!0}),g(),u({getDeploymentId:()=>y(l.readRuntimeConfig())}),{name:"vite:lib-index",writeBundle:async()=>{if(!p.htmlFiles.length)return;let e="iife"===p.format?`${p.name}.iife.js`:`${p.name}.js`;for(let i of p.htmlFiles){if(p.main&&a.enableEditor&&"./index.html"===i)continue;let o=m("./.phoenix",i),l=m("./.phoenix/dist/frontend",i);await t(s(l),{recursive:!0});let d=(await n(o,"utf-8")).replace(p.mainScriptPath,e);await r(l,d,"utf-8")}}},b,O],build:{outDir:"./dist/frontend",chunkSizeWarningLimit:4e3,lib:{entry:p.entryFile,name:o(p.name),formats:[p.format],fileName:()=>"iife"===p.format?`${p.name}.iife.js`:`${p.name}.js`},rollupOptions:{external:[],output:{assetFileNames:`${p.name}.[ext]`}},minify:!0,emptyOutDir:!1},root:m(process.cwd(),"./.phoenix"),define:{"process.env":{},"process.env.NODE_ENV":JSON.stringify("production"),"phx.frontendEnv":JSON.stringify(f),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(S.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(S.gltfDecoder)}}));return a.enableEditor?[...x,{plugins:[i({babel:{plugins:["macros"]}}),e(),d({useStrictCSP:!0}),g(),b,O],build:{outDir:"./dist/frontend",chunkSizeWarningLimit:4e3,rollupOptions:{external:[]},minify:!0,emptyOutDir:!1},root:m(process.cwd(),"./.phoenix"),define:{"process.env":{},"process.env.NODE_ENV":JSON.stringify("production"),"phx.frontendEnv":JSON.stringify(f),"globalThis.PHX_SCHEMA_VALIDATOR":JSON.stringify(S.jsonSchemaValidator),"globalThis.PHX_GLTF_DECODER":JSON.stringify(S.gltfDecoder)}}]:x};
@@ -7,5 +7,6 @@ export { FileLogger } from './file-logger.js';
7
7
  export { type Logger, type CreateLoggerOptions, createLogger } from './logger.js';
8
8
  export { addWorkspaceOverrides, ensureWorkspaceInstallSettings, getLocalOverrides, getSdkPackages, getWorkspaceDir, hasLocalOverrides, readPackageJson, removeWorkspaceOverrides, } from './package-info.js';
9
9
  export { toPascalCase } from './pascal-case.js';
10
+ export { readGitCommit } from './read-git-commit.js';
10
11
  export { type RunCommandProps, runCommand } from './run-command.js';
11
12
  export { type FileUploadInfo, type UploadLinksData, uploadFilesWithPresignedUrls, readUploadLinks, } from './upload-utils.js';
@@ -1 +1 @@
1
- export{askQuestion}from"./ask-question.js";export{checkBundleSizeBudgets}from"./check-bundle-size-budgets.js";export{formatEnvContent,formatEnvLine}from"./env-file.js";export{parseChangelog,getLatestVersion,getVersion,paginateVersions,getVersionNumbers}from"./changelog-parser.js";export{createDirectoryFromYaml,exists,scanFolderForFiles,syncChangedFiles,syncExistingFolders,validateFolders,writeFileIfNotExists,writeFilesIfNotExists,writeRawFiles}from"./file-system.js";export{FileLogger}from"./file-logger.js";export{createLogger}from"./logger.js";export{addWorkspaceOverrides,ensureWorkspaceInstallSettings,getLocalOverrides,getSdkPackages,getWorkspaceDir,hasLocalOverrides,readPackageJson,removeWorkspaceOverrides}from"./package-info.js";export{toPascalCase}from"./pascal-case.js";export{runCommand}from"./run-command.js";export{uploadFilesWithPresignedUrls,readUploadLinks}from"./upload-utils.js";
1
+ export{askQuestion}from"./ask-question.js";export{checkBundleSizeBudgets}from"./check-bundle-size-budgets.js";export{formatEnvContent,formatEnvLine}from"./env-file.js";export{parseChangelog,getLatestVersion,getVersion,paginateVersions,getVersionNumbers}from"./changelog-parser.js";export{createDirectoryFromYaml,exists,scanFolderForFiles,syncChangedFiles,syncExistingFolders,validateFolders,writeFileIfNotExists,writeFilesIfNotExists,writeRawFiles}from"./file-system.js";export{FileLogger}from"./file-logger.js";export{createLogger}from"./logger.js";export{addWorkspaceOverrides,ensureWorkspaceInstallSettings,getLocalOverrides,getSdkPackages,getWorkspaceDir,hasLocalOverrides,readPackageJson,removeWorkspaceOverrides}from"./package-info.js";export{toPascalCase}from"./pascal-case.js";export{readGitCommit}from"./read-git-commit.js";export{runCommand}from"./run-command.js";export{uploadFilesWithPresignedUrls,readUploadLinks}from"./upload-utils.js";
@@ -0,0 +1,14 @@
1
+ export interface ReadGitCommitProps {
2
+ readonly directory: string;
3
+ /**
4
+ * A file of the project, relative to `directory`, that its repository tracks. git looks for a repository in every
5
+ * parent folder, so sources unpacked inside an unrelated checkout would otherwise report that checkout's commit.
6
+ */
7
+ readonly trackedFile: string;
8
+ }
9
+ /**
10
+ * Full SHA of the commit checked out in the project's own repository. Undefined when git cannot read one: no
11
+ * checkout, git missing or refusing the repository, no commit yet, or the project is not tracked by the repository
12
+ * around it. That is normal for a build from uploaded sources.
13
+ */
14
+ export declare const readGitCommit: (props: ReadGitCommitProps) => Promise<string | undefined>;
@@ -0,0 +1 @@
1
+ import{execFile as t}from"node:child_process";import{promisify as e}from"node:util";let r=e(t),i=/^[0-9a-f]{40,64}$/;export const readGitCommit=async t=>{let e={cwd:t.directory,timeout:5e3,windowsHide:!0};try{await r("git",["ls-files","--error-unmatch","--",t.trackedFile],e);let{stdout:o}=await r("git",["rev-parse","HEAD"],e),a=o.trim();return i.test(a)?a:void 0}catch{return}};
@@ -404,6 +404,8 @@ export declare function createApplicationRuntimeSlices<State extends Application
404
404
  getActiveConfigurationId: () => string;
405
405
  getFactory: () => import("#package/domain").AnyDomainFactory;
406
406
  getDomainExpressions: () => import("#package/domain").AnyExpressions;
407
+ getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
408
+ getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
407
409
  getModelVersion: () => number;
408
410
  getAliasMap: () => import("#package/domain").AnyAliasMap;
409
411
  getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -444,6 +446,7 @@ export declare function createApplicationRuntimeSlices<State extends Application
444
446
  getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
445
447
  getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
446
448
  getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
449
+ getActionSystem: () => import("#package/domain").AnyActionSystem;
447
450
  getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
448
451
  getExpressionContext: () => import("#package/domain").AnyExpressionContext;
449
452
  getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -510,6 +513,8 @@ export declare function createApplicationRuntimeSlices<State extends Application
510
513
  getActiveConfigurationId: () => string;
511
514
  getFactory: () => import("#package/domain").AnyDomainFactory;
512
515
  getDomainExpressions: () => import("#package/domain").AnyExpressions;
516
+ getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
517
+ getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
513
518
  getModelVersion: () => number;
514
519
  getAliasMap: () => import("#package/domain").AnyAliasMap;
515
520
  getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -550,6 +555,7 @@ export declare function createApplicationRuntimeSlices<State extends Application
550
555
  getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
551
556
  getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
552
557
  getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
558
+ getActionSystem: () => import("#package/domain").AnyActionSystem;
553
559
  getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
554
560
  getExpressionContext: () => import("#package/domain").AnyExpressionContext;
555
561
  getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -1058,6 +1064,8 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
1058
1064
  getActiveConfigurationId: () => string;
1059
1065
  getFactory: () => import("#package/domain").AnyDomainFactory;
1060
1066
  getDomainExpressions: () => import("#package/domain").AnyExpressions;
1067
+ getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
1068
+ getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
1061
1069
  getModelVersion: () => number;
1062
1070
  getAliasMap: () => import("#package/domain").AnyAliasMap;
1063
1071
  getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -1098,6 +1106,7 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
1098
1106
  getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
1099
1107
  getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
1100
1108
  getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
1109
+ getActionSystem: () => import("#package/domain").AnyActionSystem;
1101
1110
  getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
1102
1111
  getExpressionContext: () => import("#package/domain").AnyExpressionContext;
1103
1112
  getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -1164,6 +1173,8 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
1164
1173
  getActiveConfigurationId: () => string;
1165
1174
  getFactory: () => import("#package/domain").AnyDomainFactory;
1166
1175
  getDomainExpressions: () => import("#package/domain").AnyExpressions;
1176
+ getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
1177
+ getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
1167
1178
  getModelVersion: () => number;
1168
1179
  getAliasMap: () => import("#package/domain").AnyAliasMap;
1169
1180
  getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -1204,6 +1215,7 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
1204
1215
  getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
1205
1216
  getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
1206
1217
  getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
1218
+ getActionSystem: () => import("#package/domain").AnyActionSystem;
1207
1219
  getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
1208
1220
  getExpressionContext: () => import("#package/domain").AnyExpressionContext;
1209
1221
  getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -60,6 +60,8 @@ export declare const useDomainContextSelectors: () => {
60
60
  getActiveConfigurationId: () => string;
61
61
  getFactory: () => import("#package/domain").AnyDomainFactory;
62
62
  getDomainExpressions: () => import("#package/domain").AnyExpressions;
63
+ getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
64
+ getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
63
65
  getModelVersion: () => number;
64
66
  getAliasMap: () => import("#package/domain").AnyAliasMap;
65
67
  getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -100,6 +102,7 @@ export declare const useDomainContextSelectors: () => {
100
102
  getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
101
103
  getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
102
104
  getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
105
+ getActionSystem: () => import("#package/domain").AnyActionSystem;
103
106
  getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
104
107
  getExpressionContext: () => import("#package/domain").AnyExpressionContext;
105
108
  getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@salsita-ai/sdk",
3
- "version": "0.50.0-develop.da8d27f5d7",
3
+ "version": "0.50.0-develop.dfac20c66b",
4
4
  "description": "TypeScript SDK and CLI for building, running, and deploying Phoenix configurator applications.",
5
5
  "keywords": [
6
6
  "salsita",
@@ -295,8 +295,8 @@
295
295
  "yaml": "2.9.0",
296
296
  "yargs": "17.7.2",
297
297
  "zod": "3.25.76",
298
- "@salsita-ai/common": "0.50.0-develop.da8d27f5d7",
299
- "@salsita-ai/contracts": "0.50.0-develop.da8d27f5d7"
298
+ "@salsita-ai/common": "0.50.0-develop.dfac20c66b",
299
+ "@salsita-ai/contracts": "0.50.0-develop.dfac20c66b"
300
300
  },
301
301
  "devDependencies": {
302
302
  "@clerk/clerk-react": "5.61.8",
@@ -1,2 +0,0 @@
1
- import{sdkGuidanceSections as e}from"./common/sdk-content.js";export const generateAgentsMd=()=>`${[e.projectIntro,e.buildCommands,e.doNotEdit,"Phoenix SDK guidance lives in the `phoenix`, `phoenix-cli`, `phoenix-create-configurator`, `phoenix-feedback` and `phoenix-review` skills under `.claude/skills/` and `.agents/skills/`. Phoenix rewrites them on every sync, removes anything else inside their folders and removes other `phoenix`-prefixed skill folders, so to customise a skill, copy it to a folder whose name does not start with `phoenix`."].join("\n\n")}
2
- `;
@@ -1,67 +0,0 @@
1
- export const sdkGuidanceSections={projectIntro:`## Phoenix Configurator Project
2
-
3
- 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
4
- - Components: PascalCase (.tsx)
5
- - Utilities: kebab-case (.ts)
6
- - Expressions: entity-name.ts
7
- - Migrations: v*.ts (sequential)
8
- - Specs: kebab-case.yaml
9
- - Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:`## Export Rules
10
- 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",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
11
-
12
- Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
13
-
14
- **Prerequisites:** same as screenshot (dev server running + browser open)
15
-
16
- **Options:**
17
- - \`--output, -o\` — Output file path (prints to stdout if omitted)
18
- - \`--pretty\` — Pretty-print JSON (default: true)
19
- - \`--port\` — WebSocket server port (default: 3020)
20
-
21
- **Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties
22
-
23
- **Example:** \`pnpm phoenix inspect:data -o ./data.json\`
24
-
25
- **Tips:** Pipe through \`head\`/\`tail\` for partial output (e.g., \`pnpm phoenix inspect:data | head -30\`).
26
-
27
- **Use cases:** AI agent context, debugging published/session/access data`,inspectScene:`## Inspect: Scene
28
-
29
- Get the current Three.js scene graph as JSON via \`pnpm phoenix inspect:scene\`.
30
-
31
- **Prerequisites:** same as screenshot (dev server running + browser open)
32
-
33
- **Options:**
34
- - \`--output, -o\` — Output file path (prints to stdout if omitted)
35
- - \`--pretty\` — Pretty-print JSON (default: true)
36
- - \`--port\` — WebSocket server port (default: 3020)
37
-
38
- **Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.
39
-
40
- **Example:** \`pnpm phoenix inspect:scene -o ./scene.json\`
41
-
42
- **Tips:** Scene graphs can be large. Pipe through \`head\`/\`tail\` for partial output.
43
-
44
- **Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting`,playwrightMcpSetup:`## Playwright MCP Setup (for AI agents)
45
-
46
- To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to \`~/.claude/.mcp.json\`:
47
-
48
- \`\`\`json
49
- {
50
- "mcpServers": {
51
- "playwright": {
52
- "command": "npx",
53
- "args": [
54
- "@playwright/mcp@latest",
55
- "--headed",
56
- "--launch-options",
57
- "{\\"args\\":[\\"--use-gl=swiftshader\\",\\"--enable-webgl\\",\\"--ignore-gpu-blocklist\\"]}"
58
- ]
59
- }
60
- }
61
- }
62
- \`\`\`
63
-
64
- Key flags:
65
- - \`--headed\` — visible browser (required for GPU rendering)
66
- - \`--use-gl=swiftshader\` — software GPU fallback for environments without a physical GPU
67
- - \`--enable-webgl\` + \`--ignore-gpu-blocklist\` — ensure WebGL is available`};
@@ -1 +0,0 @@
1
- import{renderAgentSkill as n}from"./common/agent-skill.js";import{sdkGuidanceSections as e}from"./common/sdk-content.js";export const generatePhoenixCliSkill=()=>n({name:"phoenix-cli",description:"Phoenix CLI tooling for building and inspecting this configurator, covering build, dev and sync commands, dev logs, glTF asset inspection, screenshots, runtime state, data and scene inspection, and Playwright MCP setup. Use when building, debugging build or runtime errors, checking 3D assets, or inspecting the running configurator.",sections:[e.buildCommands,e.devLogs,e.assetInspection,e.screenshotCli,e.inspectState,e.inspectData,e.inspectScene,e.playwrightMcpSetup]});
@@ -1,31 +0,0 @@
1
- import{renderAgentSkill as e}from"./common/agent-skill.js";let t=`## When to Raise Feedback
2
- Draft feedback for the Phoenix team when one of these happens while you work in this project:
3
- - **Bug** — the SDK, the \`phoenix\` CLI or generated code crashes, produces wrong output or behaves differently from its documentation, and the cause is not in this project's own code.
4
- - **Misleading guidance** — a doc page, a Phoenix skill or an error message sent you the wrong way, or did not say what you needed.
5
- - **Missing feature** — something the SDK does not support forced a workaround, or a routine task took far more steps than it should.
6
-
7
- 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
8
- Never send feedback on your own. Show the user a draft and send it only after they approve it.
9
-
10
- When to ask is your judgement:
11
- - **Right away** — the problem is crucial: it blocks the task or forces a workaround the user should know about now. Interrupt the work, show the draft, and continue once the user has answered.
12
- - **At the end of the task** — everything else. Collect the details while you work and show all drafts together in your final message.
13
- - **When the user asks** you to send feedback — draft it and show it before sending.
14
-
15
- 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
16
- 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:
17
- - 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.
18
- - 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.
19
- - Never choose or guess the score yourself. If the user skips the question or declines, send nothing and do not ask again.
20
-
21
- 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:
22
- \`\`\`bash
23
- pnpm phoenix feedback 'Rating: <score>/10
24
- Comment: <their comment, or none>
25
- Stage: after a deploy' --type other --agent '<your agent name>'
26
- \`\`\`
27
- 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
28
- The message leaves this project and is read by the Phoenix team. Never include:
29
- - secrets: API tokens, keys, passwords or \`.env\` values;
30
- - customer or end-user data, or personal data such as names and email addresses, other than a contact the user asked you to add;
31
- - 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]});
@@ -1 +0,0 @@
1
- import{renderAgentSkill as e}from"./common/agent-skill.js";import{sdkGuidanceSections as t}from"./common/sdk-content.js";export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixSkill=({checkLatestCanary:n})=>e({name:"phoenix",description:`Phoenix SDK project conventions, covering project structure, architecture principles, key patterns, file and export rules, webhook membership, showing the user the dev preview and the build of a deploy, and how to search the SDK documentation${n?", and the internal-beta check for the latest canary SDK build":""}. Use before writing or changing specs or source code in this Phoenix configurator project.`,sections:[...n?["## Stay on the Latest Canary\nDuring the internal beta this project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before you change anything, compare the installed version with the newest canary:\n```bash\npnpm list @salsita-ai/sdk --depth 0\nnpm view @salsita-ai/sdk@canary version\n```\nWhen they differ, tell the user which version you are moving to, then update the project and regenerate its files:\n```bash\npnpm add @salsita-ai/sdk@canary\npnpm phoenix sync\n```\n`sync` rewrites the Phoenix skills, so read the ones you use again after it. When the user runs a globally installed `phoenix`, update that too with `npm install -g @salsita-ai/sdk@canary`. If the project no longer builds after the update, stop and tell the user; the `phoenix-feedback` skill covers reporting it."]:[],t.projectStructure,t.architecturePrinciples,t.keyPatterns,t.fileConventions,t.exportRules,t.webhookMembership,t.doNotEdit,"## Show the Preview While You Work\nThe user should see the configurator change as you build it. Before your first change in a conversation, make sure `pnpm phoenix dev` is running (start it in the background when it is not) and open the address it prints as `Preview: <url>` (also written to `.phoenix/phoenix-dev.log`) in the user's browser: `open '<url>'` on macOS, `xdg-open '<url>'` on Linux, `Start-Process '<url>'` in PowerShell, `start \"\" \"<url>\"` in cmd. Keep the quotes, the shell would otherwise read a `?` in the address as a pattern. The log keeps the lines of earlier runs, so when you have just started dev, wait for the `Preview:` line written after your start and use the last one. Open it once; the preview reloads on every change, so tell the user to keep that tab open instead of opening it again.","## Show the Build After a Deploy\n`pnpm phoenix deploy` starts a build on the server and waits for it to go live. Right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Run the deploy so that you can read its output while it runs, and open that link in the user's browser, quoted as above, as soon as it appears, so they can follow the build they just triggered. When the line is missing, the sign-in is older than the link: tell the user the build is listed under Deployments in Studio, and that `pnpm phoenix login <workspace>` brings the link back.","## Code Review\nUse the `phoenix-review` skill to review code changes before committing.",t.sdkDocumentation]});
@@ -1 +0,0 @@
1
- import{browserDetailsTool as e}from"@salsita-ai/contracts/assistant";let t=e=>{let t=[];for(let i=0;i<e.length;i+=64)t.push(e.slice(i,i+64));return t};export const browserDetailsClientTool=e.client(()=>{let e=(()=>{let e=[`User agent: ${navigator.userAgent}`,`Viewport: ${window.innerWidth} x ${window.innerHeight} px`,`Screen: ${window.screen.width} x ${window.screen.height} px`,`Device pixel ratio: ${window.devicePixelRatio}`,`Language: ${navigator.language}`,`Time zone: ${Intl.DateTimeFormat().resolvedOptions().timeZone}`].flatMap(t),i=document.createElement("canvas");i.width=720,i.height=48+26*e.length;let n=i.getContext("2d");if(!n)throw Error("The browser details capture failed because the canvas has no 2D context. Retry in another browser.");return n.fillStyle="#ffffff",n.fillRect(0,0,i.width,i.height),n.fillStyle="#111111",n.font="16px monospace",n.textBaseline="top",e.forEach((e,t)=>n.fillText(e,24,24+26*t)),i.toDataURL("image/png")})();return[{type:"image",source:{type:"data",value:e.slice(e.indexOf(",")+1),mimeType:"image/png"}}]});
@@ -1 +0,0 @@
1
- import{AssistantGraphQLToolInput as e,applyTool as t,queryTool as o}from"@salsita-ai/contracts/assistant";let a=e=>({results:[],committed:!1,message:e}),s=e=>JSON.parse(JSON.stringify(e)),i=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:a(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const queryClientTool=o.client(async(e,{context:t})=>{let o=i(e);return o.ok?t.storeSystem.isInitialized?s({results:(await t.graphQLSystem.prepare(t.storeSystem.stateSlices.committed.value.state,o.operations)).map(({result:e})=>e),committed:!1}):a("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading."):o.refusal});export const applyClientTool=t.client(async(e,{context:t})=>{if("owner"!==t.getActiveMode())return a("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it.");let o=i(e);return o.ok?s(await t.graphQLSystem.execute(o.operations)):o.refusal});