@salsita-ai/sdk 0.50.0-develop.bc08a38ffe → 0.50.0-develop.bc204720a8

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

@@ -1,17 +1,17 @@
-import{autoHeader as e}from"../common/file-headers.js";import{generateApplicationSpecTypeDeclarations as a}from"./application-types.js";export const generateApplicationSpecGlobals=(o,t)=>{let n,i,r,l,d,s,p,m,y,{declarations:c,imports:f}=a(o,t,2);f.addTypeImport("@salsita-ai/sdk/domain","EnumLike");let u=[c,(n=o.configurator.latestModel,i=o.admin.latestModel,r=n.entityTypes.map(String),l=[...n.aliases].map(([e])=>String(e)),d=[...n.commonTypes].map(([e])=>String(e)),s=i.entityTypes.map(String),p=[...i.aliases].map(([e])=>String(e)),m=[...i.commonTypes].map(([e])=>String(e)),y=(e,a)=>e.map(e=>`    ${a(e)}`).join("\n"),`  interface Model {
-${y([...r,...d,...l],e=>`readonly ${e}: ${e}`)}
+import{autoHeader as e}from"../common/file-headers.js";import{generateApplicationSpecTypeDeclarations as a}from"./application-types.js";import{generateGlobalPhxTypes as n}from"./global-definition/index.js";export const generateApplicationSpecGlobals=(t,o)=>{let i,l,d,r,s,p,c,y,m,{declarations:h,imports:f}=a(t,o,2);f.addTypeImport("@salsita-ai/sdk/domain","EnumLike");let g=n(t,f),S=[h,(i=t.configurator.latestModel,l=t.admin.latestModel,d=i.entityTypes.map(String),r=[...i.aliases].map(([e])=>String(e)),s=[...i.commonTypes].map(([e])=>String(e)),p=l.entityTypes.map(String),c=[...l.aliases].map(([e])=>String(e)),y=[...l.commonTypes].map(([e])=>String(e)),m=(e,a)=>e.map(e=>`    ${a(e)}`).join("\n"),`  interface Model {
+${m([...d,...s,...r],e=>`readonly ${e}: ${e}`)}
   }
 
   interface EnhancedModel {
-${y([...r,...l],e=>`readonly $${e}: $${e}`)}
+${m([...d,...r],e=>`readonly $${e}: $${e}`)}
   }
 
   interface AdminModel {
-${y([...s,...m,...p],e=>`readonly ${e}: Admin.${e}`)}
+${m([...p,...y,...c],e=>`readonly ${e}: Admin.${e}`)}
   }
 
   interface AdminEnhancedModel {
-${y([...s,...p],e=>`readonly $${e}: Admin.$${e}`)}
+${m([...p,...c],e=>`readonly $${e}: Admin.$${e}`)}
   }
 
   interface ApplicationTypes {
@@ -36,23 +36,33 @@ ${y([...s,...p],e=>`readonly $${e}: Admin.$${e}`)}
     readonly AdminModel: AdminModel
     readonly AdminEnhancedModel: AdminEnhancedModel
     readonly ApplicationTypes: ApplicationTypes
-  }`)].filter(Boolean).join("\n\n");return`${e("globals.d.ts","Global type declarations for the phx namespace, env configs and domain types.")}
+  }`)].filter(Boolean).join("\n\n"),D=(e,a)=>e.replaceAll("\n",`
+${a}`);return`${e("globals.d.ts","Global type declarations for the phx namespace, env configs and domain types.")}
 /* eslint-disable @typescript-eslint/triple-slash-reference, @typescript-eslint/consistent-type-imports */
-/// <reference types="vite/client" />
 /// <reference types="@salsita-ai/sdk/globals" />
+// The project's tsconfig includes \`.phoenix\`, but TypeScript checks a file under a dot folder only
+// when it is named or imported. These declarations import none of the generated modules, and the
+// project's own code need not either, so the modules are named here to keep them type-checked.
+/// <reference path="./spec-code.ts" />
+/// <reference path="./domain-spec.ts" />
+/// <reference path="./configurator-globals.ts" />
+/// <reference path="./admin-globals.ts" />
+/// <reference path="./webhook-builders.ts" />
 
 ${f.toTypeOnlyString(".phoenix/globals.d.ts")}
 
+${g.declarations}
+
 declare global {
-${u}
+${S}
 
   interface PhxGlobal {
     readonly frontendEnv: import('./frontend.config.js').RuntimeConfig
     readonly webhooksEnv: import('./webhooks.config.js').RuntimeConfig
 
     readonly applicationTypes: {
-      readonly ApplicationVersion: typeof import('./domain-spec.js').ApplicationVersion
-      readonly PublishedDataHash: typeof import('./domain-spec.js').PublishedDataHash
+      readonly ApplicationVersion: ${JSON.stringify(t.appMetadata.applicationVersion)}
+      readonly PublishedDataHash: ${JSON.stringify(t.configurator.dataSchemas.publishedDataHash)}
       readonly PublishedData: PublishedData
       readonly SessionData: SessionData
       readonly FrontendData: FrontendData
@@ -68,43 +78,13 @@ ${u}
       readonly AdminNavigationState: EnumLike<AdminNavigationState>
     }
 
-    readonly domain: {
-      readonly model: typeof import('./domain-spec.js').model
-      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 createAssistantSetupHandler: typeof import('./domain-spec.js').createAssistantSetupHandler
-      readonly attachComponent: typeof import('./domain-spec.js').attachComponent
-      readonly createRecipe: typeof import('./domain-spec.js').createRecipe
-
-      readonly admin: {
-        readonly model: typeof import('./domain-spec.js').adminModel
-        readonly enhancedModel: typeof import('./domain-spec.js').adminEnhancedModel
-        readonly implementCustomExpressions: typeof import('./domain-spec.js').implementAdminCustomExpressions
-        readonly implementCustomInvariants: typeof import('./domain-spec.js').implementCustomAdminInvariants
-        readonly attachComponent: typeof import('./domain-spec.js').attachAdminComponent
-        readonly createMapPublishedRevisionDataHandler: typeof import('./domain-spec.js').createMapPublishedRevisionDataHandler
-        readonly createMapPublishedChunkedDataHandler: typeof import('./domain-spec.js').createMapPublishedChunkedDataHandler
-        readonly createDataRowValidatorHandler: typeof import('./domain-spec.js').createDataRowValidatorHandler
-        readonly createSheetValidatorHandler: typeof import('./domain-spec.js').createSheetValidatorHandler
-        readonly createRecipe: typeof import('./domain-spec.js').createAdminRecipe
-      }
-    }
+    readonly domain: ${D(g.domainType,"    ")}
 
-    readonly frontend: typeof import('./configurator-globals.js').configuratorInterface & {
-      readonly admin: typeof import('./admin-globals.js').adminInterface
+    readonly frontend: ${g.configuratorInterfaceType} & {
+      readonly admin: ${g.adminInterfaceType}
     }
 
-    readonly webhooks: {
-      readonly authHandlerBuilder: typeof import('./webhook-builders.js').authHandlerBuilder
-      readonly webhookBuilder: typeof import('./webhook-builders.js').webhookBuilder
-      readonly taskFactory: typeof import('./webhook-builders.js').taskFactory
-      readonly finalizeHandlerBuilder: typeof import('./webhook-builders.js').finalizeHandlerBuilder
-      readonly callbackBuilder: typeof import('./webhook-builders.js').callbackBuilder
-      readonly prefetchBuilder: typeof import('./webhook-builders.js').prefetchBuilder
-      readonly dynamicResourcesFactory: typeof import('./webhook-builders.js').dynamicResourcesFactory
-    }
+    readonly webhooks: ${D(g.webhooksType,"    ")}
   }
 }
 `};

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

@@ -1 +1,12 @@
-export declare const generateApplicationSpecHtmlIndex: (webComponentTag?: string, enableEditor?: boolean, pageTitle?: string) => string;
+/**
+ * What the generated `index.html` puts around the configurator.
+ *
+ * `editor` mounts the Phoenix editor, which hosts the configurator; `agent` mounts the editor with
+ * its UI hidden, so it still serves the CLI's inspect commands, and runs agent mode, which shows the
+ * "Agent at work" screen in place of dev errors; `plain` mounts the configurator
+ * alone, as a build deploys it. `phoenix dev` picks one by the credentials and the editor setting;
+ * `phoenix sync`, `build` and `clean` keep an agent-mode page dev generated, and otherwise pick
+ * `editor` or `plain`.
+ */
+export type PageExperience = 'editor' | 'agent' | 'plain';
+export declare const generateApplicationSpecHtmlIndex: (webComponentTag: string | undefined, experience: PageExperience, pageTitle: string | undefined) => string;

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

@@ -1,16 +1,17 @@
-let t="Auto-generated file. Do not modify this file manually. Version: 1";export const generateApplicationSpecHtmlIndex=(e="salsita-configurator",i=!1,o="Phoenix configurator")=>i?`<!doctype html>
+let t="Auto-generated file. Do not modify this file manually. Version: 1";export const generateApplicationSpecHtmlIndex=(e,i,o)=>{let n=e??"salsita-configurator",r=o??"Phoenix configurator";return"plain"===i?`<!doctype html>
 <!-- ${t} -->
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" href="/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content" />
-    <title>${o} - Editor</title>
+    <title>${r}</title>
   </head>
   <body style="margin: 0">
-    <div id="root" style="block-size: 100dvb"></div>
+    <div style="block-size: 100dvb">
+      <${n}></${n}>
+    </div>
     <script type="module" src="./configurator.ts"></script>
-    <script type="module" src="./editor.tsx"></script>
   </body>
 </html>
 `:`<!doctype html>
@@ -20,13 +21,11 @@ let t="Auto-generated file. Do not modify this file manually. Version: 1";export
     <meta charset="UTF-8" />
     <link rel="icon" href="/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content" />
-    <title>${o}</title>
+    <title>${"editor"===i?`${r} - Editor`:r}</title>
   </head>
   <body style="margin: 0">
-    <div style="block-size: 100dvb">
-      <${e}></${e}>
-    </div>
-    <script type="module" src="./configurator.ts"></script>
+    <div id="root" style="block-size: 100dvb"></div>
+${("agent"===i?["./editor.tsx","./configurator.ts"]:["./configurator.ts","./editor.tsx"]).map(t=>`    <script type="module" src="${t}"></script>`).join("\n")}
   </body>
 </html>
-`;
+`};

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

@@ -35,21 +35,17 @@ export { generateApplicationSpecFrontendConfig } from './frontend-config.js';
 export { generateApplicationSpecGitignore } from './gitignore.js';
 export { generateApplicationSpecGlobals } from './globals.js';
 export { generateApplicationSpecHtmlAdminIndex } from './html-admin-index.js';
-export { generateApplicationSpecHtmlIndex } from './html-index.js';
+export { type PageExperience, generateApplicationSpecHtmlIndex } from './html-index.js';
 export { generateLinguiRcFile } from './lingui-rc.js';
-export { generateApplicationSpecNvmrc } from './nvmrc.js';
-export { generateApplicationSpecPackageJson } from './package-json.js';
-export { generatePhoenixCliSkill } from './skills/phoenix-cli-skill.js';
-export { generatePhoenixCreateConfiguratorSkill, generatePhoenixCreateConfiguratorSkillReferences, } from './skills/phoenix-create-configurator-skill.js';
-export { generatePhoenixFeedbackSkill } from './skills/phoenix-feedback-skill.js';
-export { generatePhoenixReviewSkill } from './skills/phoenix-review-skill.js';
-export { type PhoenixSkillOptions, followsCanaryBuilds, generatePhoenixSkill } from './skills/phoenix-skill.js';
-export { generatePhoenixVariantsSkill } from './skills/phoenix-variants-skill.js';
+export { generatePhoenixSkillBundle } from './skills/phoenix-skill-bundle.js';
+export { type PhoenixSkillOptions, followsCanaryBuilds } from './skills/processes/index.js';
 export { generateApplicationSpecPrettierConfig } from './prettier-config.js';
 export { generateApplicationSpecRobotsTxt } from './robots-txt.js';
+export { generateApplicationSpecRootTsconfig } from './root-tsconfig.js';
 export { generateApplicationSpecStoryDevDeclaration, generateApplicationSpecStoryPhxModule, generateApplicationSpecStoryRawProjectFiles, generateApplicationSpecStoryWrapper, } from './story/index.js';
+export { generateApplicationSpecCodeFile } from './spec-code/index.js';
+export { generateApplicationSpecMessagesFile } from './spec-messages/index.js';
 export { generateApplicationSpecTsconfig } from './tsconfig.js';
 export { generateApplicationSpecWebhookBuilders } from './webhook-builders.js';
-export { generateApplicationSpecWebhookImplementation } from './webhook-implementation.js';
 export { generateApplicationSpecWebhookIndex } from './webhook-index.js';
 export { generateApplicationSpecWebhooksConfig } from './webhooks-config.js';

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

@@ -1 +1 @@
-export{stripSdkMarkerContent}from"./common/strip-sdk-marker-content.js";export{generateApplicationSpecAdminConfig}from"./admin-config.js";export{generateApplicationSpecAdminCode}from"./admin-domain-code.js";export{generateApplicationSpecAdminFrontendCode}from"./admin-frontend-code.js";export{generateAdminGlobalBindingBlock,generateApplicationSpecAdminGlobals}from"./admin-globals.js";export{generateApplicationSpecTypesModule}from"./application-types.js";export{generateApplicationSpecAdminFile}from"./admin.js";export{generateApplicationSpecConfiguratorConfig}from"./configurator-config.js";export{generateApplicationSpecConfiguratorCode}from"./configurator-domain-code.js";export{generateApplicationSpecConfiguratorFrontendCode}from"./configurator-frontend-code.js";export{generateApplicationSpecConfiguratorGlobals,generateConfiguratorGlobalBindingBlock}from"./configurator-globals.js";export{generateApplicationSpecConfiguratorFile}from"./configurator.js";export{generateApplicationSpecDomainSpecFile}from"./domain-spec.js";export{generateImportedStateConstants,generatePhxExportsBlock,generatePhxGlobalsBlock,generateStateConstants}from"./domain-spec/index.js";export{generateApplicationSpecDomainFile}from"./domain.js";export{generateApplicationSpecEditorFile}from"./editor.js";export{generateApplicationSpecEmbeddedAdmin}from"./embedded-admin.js";export{generateApplicationSpecEmbeddedConfigurator}from"./embedded-configurator.js";export{generateApplicationSpecEslintConfig}from"./eslint-config.js";export{generateApplicationSpecFavicon}from"./favicon.js";export{generateApplicationSpecFrontendConfig}from"./frontend-config.js";export{generateApplicationSpecGitignore}from"./gitignore.js";export{generateApplicationSpecGlobals}from"./globals.js";export{generateApplicationSpecHtmlAdminIndex}from"./html-admin-index.js";export{generateApplicationSpecHtmlIndex}from"./html-index.js";export{generateLinguiRcFile}from"./lingui-rc.js";export{generateApplicationSpecNvmrc}from"./nvmrc.js";export{generateApplicationSpecPackageJson}from"./package-json.js";export{generatePhoenixCliSkill}from"./skills/phoenix-cli-skill.js";export{generatePhoenixCreateConfiguratorSkill,generatePhoenixCreateConfiguratorSkillReferences}from"./skills/phoenix-create-configurator-skill.js";export{generatePhoenixFeedbackSkill}from"./skills/phoenix-feedback-skill.js";export{generatePhoenixReviewSkill}from"./skills/phoenix-review-skill.js";export{followsCanaryBuilds,generatePhoenixSkill}from"./skills/phoenix-skill.js";export{generatePhoenixVariantsSkill}from"./skills/phoenix-variants-skill.js";export{generateApplicationSpecPrettierConfig}from"./prettier-config.js";export{generateApplicationSpecRobotsTxt}from"./robots-txt.js";export{generateApplicationSpecStoryDevDeclaration,generateApplicationSpecStoryPhxModule,generateApplicationSpecStoryRawProjectFiles,generateApplicationSpecStoryWrapper}from"./story/index.js";export{generateApplicationSpecTsconfig}from"./tsconfig.js";export{generateApplicationSpecWebhookBuilders}from"./webhook-builders.js";export{generateApplicationSpecWebhookImplementation}from"./webhook-implementation.js";export{generateApplicationSpecWebhookIndex}from"./webhook-index.js";export{generateApplicationSpecWebhooksConfig}from"./webhooks-config.js";
+export{stripSdkMarkerContent}from"./common/strip-sdk-marker-content.js";export{generateApplicationSpecAdminConfig}from"./admin-config.js";export{generateApplicationSpecAdminCode}from"./admin-domain-code.js";export{generateApplicationSpecAdminFrontendCode}from"./admin-frontend-code.js";export{generateAdminGlobalBindingBlock,generateApplicationSpecAdminGlobals}from"./admin-globals.js";export{generateApplicationSpecTypesModule}from"./application-types.js";export{generateApplicationSpecAdminFile}from"./admin.js";export{generateApplicationSpecConfiguratorConfig}from"./configurator-config.js";export{generateApplicationSpecConfiguratorCode}from"./configurator-domain-code.js";export{generateApplicationSpecConfiguratorFrontendCode}from"./configurator-frontend-code.js";export{generateApplicationSpecConfiguratorGlobals,generateConfiguratorGlobalBindingBlock}from"./configurator-globals.js";export{generateApplicationSpecConfiguratorFile}from"./configurator.js";export{generateApplicationSpecDomainSpecFile}from"./domain-spec.js";export{generateImportedStateConstants,generatePhxExportsBlock,generatePhxGlobalsBlock,generateStateConstants}from"./domain-spec/index.js";export{generateApplicationSpecDomainFile}from"./domain.js";export{generateApplicationSpecEditorFile}from"./editor.js";export{generateApplicationSpecEmbeddedAdmin}from"./embedded-admin.js";export{generateApplicationSpecEmbeddedConfigurator}from"./embedded-configurator.js";export{generateApplicationSpecEslintConfig}from"./eslint-config.js";export{generateApplicationSpecFavicon}from"./favicon.js";export{generateApplicationSpecFrontendConfig}from"./frontend-config.js";export{generateApplicationSpecGitignore}from"./gitignore.js";export{generateApplicationSpecGlobals}from"./globals.js";export{generateApplicationSpecHtmlAdminIndex}from"./html-admin-index.js";export{generateApplicationSpecHtmlIndex}from"./html-index.js";export{generateLinguiRcFile}from"./lingui-rc.js";export{generatePhoenixSkillBundle}from"./skills/phoenix-skill-bundle.js";export{followsCanaryBuilds}from"./skills/processes/index.js";export{generateApplicationSpecPrettierConfig}from"./prettier-config.js";export{generateApplicationSpecRobotsTxt}from"./robots-txt.js";export{generateApplicationSpecRootTsconfig}from"./root-tsconfig.js";export{generateApplicationSpecStoryDevDeclaration,generateApplicationSpecStoryPhxModule,generateApplicationSpecStoryRawProjectFiles,generateApplicationSpecStoryWrapper}from"./story/index.js";export{generateApplicationSpecCodeFile}from"./spec-code/index.js";export{generateApplicationSpecMessagesFile}from"./spec-messages/index.js";export{generateApplicationSpecTsconfig}from"./tsconfig.js";export{generateApplicationSpecWebhookBuilders}from"./webhook-builders.js";export{generateApplicationSpecWebhookIndex}from"./webhook-index.js";export{generateApplicationSpecWebhooksConfig}from"./webhooks-config.js";

package/dist/application-spec/generate-application/code/templates/lingui-rc.d.ts

@@ -1 +1,6 @@
+/**
+ * The project's Lingui configuration, generated to `.phoenix/.linguirc` and, for a Storybook story, to
+ * the story's root. Lingui resolves its paths against the directory it runs in, the project or story
+ * root, so they hold in either place; `<rootDir>` would be the folder that holds the file.
+ */
 export declare const generateLinguiRcFile: (availableLocales: readonly string[]) => string;

package/dist/application-spec/generate-application/code/templates/lingui-rc.js

@@ -6,14 +6,15 @@ ${(s=Object.entries(a).map(([e,a])=>{let o=Array.isArray(a)?`[${a.map(e=>`"${e}"
   },
   "catalogs": [
     {
-      "path": "<rootDir>/src/locales/{locale}/messages",
+      "path": "./src/locales/{locale}/messages",
       "include": [
         "./src",
         "./.phoenix"
       ],
       "exclude": [
         "**/node_modules/**",
-        "**/dist/**"
+        "**/dist/**",
+        "**/.phoenix/workspace/**"
       ]
     }
   ],

package/dist/application-spec/generate-application/code/templates/prettier-config.d.ts

@@ -1 +1,6 @@
+/**
+ * The project's `prettier.config.js`, written once when the project has none. It re-exports the SDK's
+ * shared Prettier configuration so editors find it in the project root; the project may change it
+ * afterwards. `phoenix check` and `phoenix fix` use the SDK's configuration when the file is missing.
+ */
 export declare const generateApplicationSpecPrettierConfig: () => string;

package/dist/application-spec/generate-application/code/templates/prettier-config.js

@@ -1,8 +1,7 @@
-let e=`/**
- * Auto-generated file.
- * Do not modify this file manually.
- * Version: 1
- */`;export const generateApplicationSpecPrettierConfig=()=>`${e}
+export const generateApplicationSpecPrettierConfig=()=>`/**
+ * The project's Prettier configuration. It re-exports the shared configuration of the Phoenix SDK;
+ * change it to adjust the formatting of this project.
+ */
 import { prettierrc } from '@salsita-ai/sdk/common/prettier'
 
 export default prettierrc

package/dist/application-spec/generate-application/code/templates/root-tsconfig.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The project's root `tsconfig.json`, written once when the project has none: it extends the
+ * generated settings in `.phoenix/tsconfig.json`, so editors and tools that look for a
+ * `tsconfig.json` in the project root find them. It is the project's afterwards, to add to.
+ */
+export declare const generateApplicationSpecRootTsconfig: () => string;

package/dist/application-spec/generate-application/code/templates/root-tsconfig.js

@@ -0,0 +1,2 @@
+export const generateApplicationSpecRootTsconfig=()=>`{ "extends": "./.phoenix/tsconfig.json" }
+`;

package/dist/application-spec/generate-application/code/templates/skills/core/cli.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixCliCore: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/core/cli.js

@@ -0,0 +1 @@
+import{createPhoenixTopicGuide as e}from"../guide.js";export const generatePhoenixCliCore=()=>e({path:"core/cli.md",title:"CLI",summary:"tooling, identity, project structure and ownership, local development and deployment",sections:["## Tooling and dependencies\n\nCommands use pnpm notation; use the project's package manager identified by its lockfile or `packageManager` in `package.json`, and ask when neither identifies it. Keep the SDK on its intended release channel: stable, PR beta and workspace-linked projects must not be moved to canary.\n\n`phoenix deps` aligns missing or out-of-range peer dependencies in `package.json` but installs nothing. Install with the project's package manager, then `phoenix sync` regenerates project files and guidance. Refresh changed guidance after sync. An install with pnpm 11 that skips build scripts leaves placeholder entries under `allowBuilds` in `pnpm-workspace.yaml`; decide them, `true` for `@swc/core` and `esbuild` and `false` for `es5-ext`, because the platform build stops on a placeholder and `phoenix deploy` refuses one. [CLI and setup documentation](../features/index.md#cli-access-and-deployment) owns flags and installation details.\n\n## Identity and authentication\n\nA workspace contains projects, and a project has target environments and deployments. Confirm ambiguous identity before mutations or deploys. `phoenix login` authorizes the CLI across currently permitted Builder projects; set an explicit project slug in the spec for dev and deploy. `phoenix whoami` shows current access. The legacy `phoenix login <workspace>` form keeps workspace-bound credentials. Consult [project and authentication documentation](../features/index.md#cli-access-and-deployment) for local versus remote setup.\n\n## Project structure\n\n- `spec/` — domain, relations, expressions, invariants, components and application YAML.\n- `src/expressions/`, `actions/`, `invariants/`, `transformers/` — typed implementations of domain behavior and consistency rules.\n- `src/components/`, `elements/`, `handlers/` — runtime components, custom UI and layout elements, event and lifecycle handlers. See [Custom project layout](../features/custom-layout/index.md) and [Domain controls](../features/domain-controls/index.md).\n- `src/webhooks/` — the server side. The entry is the default export of `index.ts`, the only file imported; it imports the others. Without it the SDK supplies anonymous auth, or invitation-only Phoenix auth when `useCognito: true`; enabling custom or Clerk auth without it reports `AUTH_WITHOUT_PROJECT_WEBHOOK`. See [Webhooks](../features/webhooks/index.md).\n- `src/migrations/` — versioned model migrations; `src/admin/` mirrors the main source structure for Admin.\n- `src/locales/` — authored PO catalogs and generated TS catalogs.\n- `src/_shared/`, `src/_utils/` and other `_`-prefixed folders — helpers and supporting modules. Phoenix skips these folders during auto-import; import their modules explicitly.\n- `public/` — static models, textures, images and fonts; `assets/` — uploadable resources such as templates and email assets.\n- `docs/` — rendered specification PDFs for the client.\n- `tools/` — reproducible project scripts, such as model conversion or rendering the specification PDFs. One-off scripts, screenshots and downloads stay in the agent's scratch space outside the project.\n- `.phoenix/` — generated files, with the project-owned exceptions below. The root `tsconfig.json` belongs to the project and extends `.phoenix/tsconfig.json`.\n\nDo not edit generated output or compiled locale TS. `.phoenix/workspace/` holds the specification sources and project records; application-spec sync, build and clean preserve it, and the generated Git ignore rules leave it available for version control. Deploy includes `.phoenix/workspace/` and `docs/` in the private deployment sources, outside application inputs and public assets. `.phoenix/variants/` option files survive rebuilds. Legacy tooling has a separate lifecycle.\n\nSync rewrites and prunes Phoenix's `phoenix` and `phoenix-*` skill folders under `.claude/skills/` and `.agents/skills/`; keep custom skills under another name. Root `AGENTS.md` and client source documents are client-owned. Components use PascalCase TSX, utilities kebab-case TS, expressions entity-name TS, migrations sequential `v*.ts` and specs kebab-case YAML. `docs/phoenix/project-structure.mdx` has the full reference; the [capability index](../features/index.md#project-and-customization) lists it.\n\n### Source conventions\n\n- Auto-imported expressions, actions, invariants, transformers, components, handlers and elements must default-export their folder's phx factory result, as one item or an array. Named exports are ignored.\n- `phx` is a global in every project: use it without importing it.\n- Keep plain helpers in underscore folders and import them explicitly.\n- Use relative imports: dev, build and webhook bundling do not resolve tsconfig `paths` aliases.\n\n## Local development\n\n`phoenix dev` runs the live preview, `sync` regenerates without bundling, `build` produces the production build, and `check` checks project quality.\n\n### Keep the preview in front of the client\n\nThe client should see the configurator change while it is built. Before the first change in a conversation, make sure `pnpm phoenix dev` is running, starting it in the background when it is not, and wait for the `Preview: <url>` line it prints and writes to `.phoenix/phoenix-dev.log`. The log keeps the lines of earlier runs, so use the last one written after the start.\n\nFor a new project, start by understanding the client’s product and what they want to configure before asking them to sign in; then make the preview reflect that before showing it, rather than presenting the generated starter scene.\n\nOpen the address where the client can see it: in the agent application's built-in browser when it has one the client sees, otherwise in the client's browser with `open '<url>'` on macOS, `xdg-open '<url>'` on Linux or `Start-Process '<url>'` in PowerShell. Keep the quotes; the shell would otherwise read a `?` in the address as a pattern. Then tell the client in one line where the preview is and that it updates by itself as the work goes on. Variant comparisons open in the same preview, so say there what to compare and how to choose.\n\nOpen it once: the preview reloads on every change. A domain model change is the exception. Dev registers the model with the server only when it starts and logs an error asking for a restart; restart it, wait for the new `Preview:` line and open that address in place of the old tab, whose `?cid=` names a configuration of the earlier model.\n\n### Logs and inspection\n\nLogs in `.phoenix/phoenix-dev.log` contain spec, build and runtime errors and watcher events; check them after changes. Signed in, `phoenix dev` runs in agent mode: the preview hides the editor, a corner badge shows when the latest change didn't build, and any dev error shows an \"Agent at work\" screen with no details, so the client never sees them. The details are only in the log; the page recovers by itself after the next successful rebuild. `--editor` shows the editor and the detailed error pages. [Inspection tools](../features/inspection.md) cover assets, state, data, scene and screenshots. Runtime inspection needs dev running and the preview open in a browser; a screenshot of the canvas does not verify the surrounding interface.\n\n## Deployment\n\n`pnpm phoenix deploy` sends the project sources for a server build and waits for the target environment to go live. Run it so its output can be read while it runs: right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Open that link where the client sees it, as with the preview, so they can follow the build. When the line is missing, the sign-in predates the link: the build is listed under Deployments in Studio, and `pnpm phoenix login <workspace>` brings the link back.\n\nA successful local preview does not establish deployed model compatibility. The deploy is refused before the upload when the domain model changed under a version that is already deployed, such as a starter deployed before the first draft; [Model migration](../processes/model-migration.md) handles that. When the build fails, tell the client the cause and the next step. Record each deploy and its outcome in the project record. [Deployment documentation](../features/index.md#cli-access-and-deployment) covers status and environment details.\n\n## Internal beta\n\nPhoenix is in an internal beta. Read [Beta](../processes/beta.md) before each deploy and when a deploy goes live; a project on the `canary` SDK build also reads it once per conversation before changing anything.\n\n## Interactive and support tools\n\n[Variants](../features/variants.md) compares frontend alternatives over the live preview and applies the choice. [Feedback](../processes/feedback/index.md) submits an approved issue or evaluation. The [workflow](workflow.md) owns when either is useful and how much client interaction fits the task."]});

package/dist/application-spec/generate-application/code/templates/skills/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './workflow.js';
+export * from './sdk.js';
+export * from './cli.js';

package/dist/application-spec/generate-application/code/templates/skills/core/index.js

@@ -0,0 +1 @@
+export*from"./workflow.js";export*from"./sdk.js";export*from"./cli.js";

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

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixSdkCore: () => PhoenixGuide;

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

@@ -0,0 +1,89 @@
+import{createPhoenixTopicGuide as e}from"../guide.js";let t=`## Project and customization
+
+Phoenix turns YAML in \`spec/\` into a typed domain, configured components and a running configurator.
+
+- Define domain and component behavior in YAML first.
+- Compose the UI through a custom project layout, using Phoenix elements, slots and hooks.
+- For other custom implementations, verify an SDK capability gap and explain the proposed approach. Missing documentation does not establish a missing capability.
+
+### The \`phx\` global
+
+Project code reaches the SDK through the \`phx\` global: \`phx.domain\` for model reflections and the implementations of expressions, invariants and actions, \`phx.frontend\` for elements, handlers, hooks, updates and transformers, and \`phx.webhooks\` for server builders and tasks. Each [feature guide](../features/index.md) teaches its part as \`phx.<namespace>.<member>\`; a few things \`phx\` does not carry, such as \`memoEval\`, are SDK subpath imports.
+
+### Entity-component-system model
+
+- **Entities** store product state, such as a cabinet and its width.
+- **Components** attach configurable data or behavior definitions, such as a scene object or width control, to entities or aliases.
+- **Systems** consume those components to apply domain or UI behavior, such as rendering the scene.
+
+Stable references drive change detection. Use memoEval to reuse result objects and arrays while inputs are unchanged; return new references for changed outputs. Mutating results in place can hide changes; recreating equivalent results causes unnecessary updates.
+
+[Capability index](../features/index.md#project-and-customization) \xb7 [Project structure](cli.md#project-structure)
+
+## Model
+
+| Concept | Responsibility | Guide |
+| --- | --- | --- |
+| Entity, alias, relation | Saved product state and choices, shared views over entity types, and ownership, such as a cabinet's width and its shelves | [Entities and relations](../features/domain-model/entities-and-relations.md) |
+| Component | Configured data or behavior bound to an entity or alias, shown by filters | [Components](../features/domain-model/components.md) |
+| Expression | Pure derived value with a \`$\` prefix, such as \`$price\` | [Expressions](../features/domain-model/expressions.md) |
+| Invariant, transformer | Validation and violations, such as an unsupported width and finish, and repair after a change | [Validation and repair](../features/domain-model/validation-and-repair.md), [Transformers](../features/domain-model/transformers.md) |
+| Action | Prepared named domain operation, such as adding a shelf | [Actions](../features/domain-model/actions.md) |
+
+Keep a deployed model unchanged under its version. When it changes, retain the old version and migrate saved configurations with [Model migration](../processes/model-migration.md).
+
+## Runtime state
+
+- **Store** — every change is a set of updates. Transformers run first, then validation; a change with a \`fatal\` or \`fixable\` violation is rejected, and controls dry-run their options the same way to disable those that would fail: [State](../features/state/index.md).
+- **Application states** — presets, navigation, view and tool states and the selection decide what the configurator shows and which filtered components apply: [Application states](../features/application-states/index.md).
+
+## Frontend runtime
+
+Build the interface from elements and handlers, connected through \`phx.frontend\`.
+
+| Surface | Use for | Guide |
+| --- | --- | --- |
+| Layout elements | The project layout, loading and error pages, preset screen, assistant forms | [Custom project layout](../features/custom-layout/index.md) |
+| Entity elements and control hooks | Controls the layout renders or anchors in the scene | [Domain controls](../features/domain-controls/index.md) |
+| Handlers | Event and lifecycle behavior, registered finalization actions | [Finalization actions](../features/custom-layout/finalization-actions.md) |
+| Spec texts | Translated texts and the language switch | [Localization](../features/localization.md) |
+| Scene objects built in code | Geometry a loaded model cannot express, such as a worktop with cut-outs | [Scene objects built in code](../features/scene-objects.md) |
+
+Prefer a custom \`ConfiguratorLayout\` composed from Phoenix controls, slots and hooks; it owns the canvas, messages, read mode and finalization. Register the React component with the supported factory:
+
+\`\`\`tsx
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+\`\`\`
+
+[Scene and safe area](../features/custom-layout/scene-and-safe-area.md) has the minimal complete layout.
+
+## Webhooks and finalization
+
+The webhook is the project's server side: \`src/webhooks/index.ts\` and the handler modules that join it run on the platform, hold the credentials and never import browser code. The platform calls it to sign configurator users in, fetch backend data, finalize a configuration and return its result, publish Admin content and set up the assistant; \`phx.webhooks\` holds its builders.
+
+- Finalization runs tasks connected by named resources: configuration links, server renders, PDFs, CSVs, emails, HTTP requests, WooCommerce carts and spreadsheet rows. The platform runs them by type, not in registration order, and retries and rolls back nothing.
+- For a quote, generate a configuration link and a render, include them in a PDF, send it by email and return the links from the callback. Test without real messages or orders until the client authorizes them.
+
+[Webhooks](../features/webhooks/index.md) \xb7 [Finalization process](../processes/finalization.md)
+
+## Data sources
+
+Choose data by ownership and lifetime.
+
+| Source | Ownership / lifetime |
+| --- | --- |
+| Entity state | Saved configuration choices |
+| Published data | Released catalogue/content revision |
+| Frontend data | Values from the embedding frontend |
+| Session data | Authentication/session context |
+| Backend data | Values fetched through the webhook |
+
+[Expressions](../features/domain-model/expressions.md) shows how expressions and elements read these sources \xb7 [Backend data](../features/webhooks/backend-data.md) \xb7 [Data sources and connected data](../features/index.md#data-sources)
+
+## Admin and Studio
+
+- Use **Project Admin** to manage domain content and publish it for configurators.
+- Use **Studio** to manage platform workspaces, projects, environments and deployments.
+
+[Admin and Studio documentation](../features/index.md#admin-and-studio)
+`;export const generatePhoenixSdkCore=()=>e({path:"core/sdk.md",title:"SDK",summary:"the SDK mental model, capabilities, invariants and supported customization",sections:[t]});

package/dist/application-spec/generate-application/code/templates/skills/core/workflow.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixWorkflowCore: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/core/workflow.js

@@ -0,0 +1,46 @@
+import{createPhoenixTopicGuide as e}from"../guide.js";let t=`The client creates the configurator; its users may be buyers, salespeople or designers. The aim is a useful, polished product that fits the client's purpose, preferences and agreed effort.
+
+These practices usually lead there; adapt them to the client, the product and the task rather than following a script.`,n=`## Where to start
+
+- **A new project** — nothing in \`.phoenix/workspace/specification/\` and still the starter spec, or a first draft the project record shows in progress — usually starts with a [First draft](../processes/first-draft/index.md): a convincing first version, quickly.
+- **Normal mode** — everything after that, and every existing project — builds on the specification and the next increments in the project record. A small fix usually goes straight to the affected behavior.
+
+A request to complete a project does not waive the workflow’s client-choice checkpoints. Present the choices and wait for feedback before continuing with work that depends on them, unless the client explicitly asks to skip those checkpoints.
+
+The client can always redirect; follow their lead without nagging or repeated approval requests.`,a=`## Working with the client
+
+Be a warm, direct expert who listens, recommends an approach and takes responsibility for SDK and tooling choices. Look at supplied materials before asking, and keep the conversation about the product rather than setup questionnaires or jargon. When uncertainty affects the next result, such as a blocking ambiguity, a business decision needed now or a departure from accepted design, ask with a recommendation; otherwise state reversible defaults and keep going. Keep facts, explicit preferences and provisional assumptions distinct.
+
+Talk about the client's product: what they can try, see or decide. Modes, processes, stages, records and guide names are internal and mean nothing to the client. Say "next, I'll add the desk range", not "switching to normal mode and starting an increment".
+
+Small problems met along the way, such as a type error, a misaligned part or a font that did not load, are usually best fixed quietly; mention one only when it changes what the client sees or decides. Messages land better when they stay light: one decision at a time is easier to answer than a list of questions, and a long list, such as provisional defaults, reads better as a link to the document that holds it. When you create or change a client document, open it or link it in the message that announces it.`,i=`## Preferences
+
+Preferences shape how much effort and autonomy fit the work; note them in the project record as they emerge:
+
+- **Cost** — token and money sensitivity: subagent reviews, parallel agents, heavy rendering.
+- **Time** — fast feedback in small steps, or thorough and slower increments.
+- **Autonomy** — decide and report, or check in before choices; how large an autonomous batch may be.
+- **Quality bar** — demo grade or ready for real users; it sets review depth.
+- **Communication** — detail, technical depth and update frequency.
+
+A first draft runs no reviews or parallel agents, so it needs none of these answers. Ask once, briefly and with a recommendation, at a natural pause after the first draft or when work on an existing project starts without them. With a cost- or time-sensitive client, offer an expensive action with what it would add and wait for a yes rather than starting it.`,s=`## Keeping the client oriented
+
+Clients do best when they know what is happening, what comes next and whether anything is blocked. Share the next steps before longer work, update briefly during long builds, and when stuck, name the dependency and what can continue. Records do not replace these updates.
+
+Reports work best at a high level: what the client can now try, what is still open and what comes next. The details of what was changed belong in the changelog. A good handoff separates what is done, what is unverified and what remains, and usually ends with a recommended next step, sometimes with an alternative such as a [Phoenix capability](../features/index.md) the client may not know about. Note declined suggestions so they do not come back.`,r=`## Building in increments
+
+After the first draft, a short **Next increments** list in the project record keeps the way ahead visible: one line per increment saying what the client will be able to do and what it waits on, such as a model, a price list or a business answer, with postponed scope below it. Ordering by what users decide first and by real product dependencies usually works, with core interactions before more options and finalization once the configuration it submits is stable. Present it in product language with a recommended next increment; the client agrees on the next step, not on the whole list. Keep it current as increments land or the scope changes; an existing project without one writes it when its work goes beyond a single fix.
+
+Work then goes best in small, useful increments: choose an outcome with observable checks; extend the [specification](../processes/specification/index.md) only as far as the increment needs; build it within the branding and UX guidelines, where they exist, using the [SDK guidance](sdk.md); exercise the changed interaction and what it affects, such as control targets, selection context and global versus per-part behavior; review it as the [review strategy](#review-strategy) suggests; then show the client what to try and fold their feedback into the specification and the next increments.
+
+Habits that help: wait for feedback before expanding an increment unless the client asked for a larger batch; settle core interactions before multiplying options; keep agreed scope visible until it is built or deferred; preserve selections and accepted behavior; and when rules change, keep model, scene, controls, dimensions, pricing and checks consistent.`,o=`## Visual choices
+
+When taste, branding or interaction has several reasonable answers that the client's materials do not settle, alternatives usually help: explain the tradeoffs and recommend one. They help most when they really differ and each is finished as well as it can be, so the client chooses between good options rather than between variations. Accepted choices stay settled, facts are not the client's to pick, and routine reversible details need no approval. [Variants](../features/variants.md) shows alternatives in the live preview.`,c=`## Review strategy
+
+The first draft skips review processes; a quick look at the running preview before showing each result keeps broken work away from the client.
+
+Later, review changed work before committing or handing it over with the [review processes](../processes/review/index.md), scaled to impact, uncertainty, the quality bar and the cost preference. A self-review is usually enough; an independent subagent adds a fresh view of visual fidelity, complex rules or broad interactions when the preferences allow it. Note whether review was independent and what remains unverified; a passing build does not prove product quality.`,d=`## Feedback and completion
+
+Client feedback shapes the direction and the records; confirm material departures. Phoenix feedback is a separate, external report: [Feedback](../processes/feedback/index.md) covers SDK problems and the client's evaluation of the run, and only approved content is sent.
+
+Some lines stay firm: publishing, real orders, real messages and connecting live systems need the client's authorization against the concrete result. [Deployment](cli.md#deployment) covers running a deploy.`;export const generatePhoenixWorkflowCore=()=>e({path:"core/workflow.md",title:"Workflow",summary:"where to start, working with the client, preferences, increments, records and review strategy",sections:[t,n,a,i,s,r,o,"## Records\n\n- **Specification** — client-facing documents: branding, UX guidelines, product definition and catalogs, with sources in `.phoenix/workspace/specification/` and rendered PDFs in `docs/`. [Specification](../processes/specification/index.md) describes them; later work follows them, and changing an accepted rule is the client's call.\n- **Project record** — `.phoenix/workspace/project.md` is the current snapshot: preferences, approach, decisions with rationale, declined suggestions, progress, deploys and their outcome, next increments, open questions and SDK problems worth reporting, rewritten as they change. `.phoenix/workspace/changelog/` keeps the history: append a dated entry for each meaningful change, decision, verification, deploy or piece of client feedback, and continue in a new numbered file when the current one gets long.\n\nReuse records when resuming; they are not a client task or an approval gate. Leave out secrets, unrelated personal information and raw transcripts; [project structure](cli.md#project-structure) describes how records are kept and deployed.",c,d]});

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/application-states.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The application states index followed by its guides. */
+export declare const generatePhoenixApplicationStatesGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/application-states.js

@@ -0,0 +1,3 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixNavigationFeature as t}from"./navigation.js";import{generatePhoenixPresetsFeature as o}from"./presets.js";import{generatePhoenixSelectionFeature as s}from"./selection.js";import{generatePhoenixViewsAndToolsFeature as n}from"./views-and-tools.js";export const generatePhoenixApplicationStatesGuides=()=>{let i=[o(),t(),n(),s()];return[e({path:"features/application-states/index.md",title:"Application states",summary:"Presets, navigation, view and tool states, selection and hover; read when choosing how a configuration starts, how users move through it, or what the scene and UI follow.",intro:`Application states are the configurator's context beside the product's entities: the preset a configuration starts from, the stage users are at (navigation state), how the scene is shown (view state), what users are doing in it (tool state), and which entity is selected or hovered. Navigation, view and tool states are independent lists declared in YAML; their active values, the selection and the hover feed component filters, whose mechanism [Components](../domain-model/components.md) owns.
+
+Only the entities are saved with a configuration: it opens at the first declared value of each list, with the root entity selected. Changing them alone is not an undo step, but undoing a change restores them as they were just before it, with the hover cleared; [Updates and dry runs](../state/updates.md) owns undo.`,guides:i,notes:[]}),...i]};

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/index.d.ts

@@ -0,0 +1 @@
+export * from './application-states.js';

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/index.js

@@ -0,0 +1 @@
+export*from"./application-states.js";

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/navigation.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Navigation states: declaring them, what they drive, replace, push and pop, and reacting to navigation. */
+export declare const generatePhoenixNavigationFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/navigation.js

@@ -0,0 +1,48 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`Three stages: legs are selectable only while configuring, the layout pushes the review and pops back, and a transformer clears the selection on entering the review.
+
+\`\`\`yaml
+# spec/application.yaml
+navigationStates: [configure, checkout, requested]
+transformers:
+  - name: clearSelectionOnCheckout
+\`\`\`
+
+\`\`\`yaml
+# spec/domain/table.yaml
+components:
+  Leg:
+    selectable:
+      main:
+        $filter:
+          navigationStates: [configure]
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/ReviewButton.tsx, part of the project layout
+import { Button } from '@mui/material'
+
+export const ReviewButton = () => {
+  const { NavigationState } = phx.applicationTypes
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const pushNavigate = phx.frontend.usePushNavigate()
+  const popNavigate = phx.frontend.usePopNavigate()
+
+  if (navigationState === NavigationState.configure) {
+    return <Button onClick={() => pushNavigate(NavigationState.checkout)}>Review</Button>
+  }
+
+  if (navigationState === NavigationState.checkout) {
+    return <Button onClick={popNavigate}>Back to the configuration</Button>
+  }
+
+  return null
+}
+\`\`\`
+
+\`\`\`ts
+// src/transformers/clear-selection-on-checkout.ts
+export default phx.frontend.transformerBuilder.when
+  .navigated({ to: [phx.applicationTypes.NavigationState.checkout] })
+  .then.deselect()
+  .build('clearSelectionOnCheckout')
+\`\`\``;export const generatePhoenixNavigationFeature=()=>e({path:"features/application-states/navigation.md",title:"Navigation states",summary:"Declaring the stages of the flow, what they drive, replacing, pushing and popping them, and transformers, undo resets and guards around navigation; read when building a staged flow or reacting to where users are.",whenToUse:"Read when splitting the configurator into stages (configure, review, checkout), showing different controls per stage, or reacting when users enter or leave one. The tab and step UI that navigates belongs to [Tabs and steps](../custom-layout/tabs-and-steps.md).",capabilities:"### Declare the states\n\n- `navigationStates:` lists identifiers (a letter, then letters, digits or `_`) in one configurator YAML file; declaring the list in a second file is an error. The first value is active when a configuration opens; without the list there is a single state, `Default`.\n- Declare one state per stage that changes which controls or pages show. A change of only the camera or of the scene's mode is a view or tool state: [View and tool states](views-and-tools.md).\n- `phx.applicationTypes.NavigationState` is a runtime enum of the declared values: `NavigationState.checkout === 'checkout'`, `NavigationState.values()` lists them and `NavigationState.is(value)` checks one. The global type `NavigationState` is their union.\n- Use the enum in TypeScript, so a renamed state fails type-checking. YAML filters are not checked against the list: a misspelled state never matches.\n\n### What the active state drives\n\n- **Filters** — `$filter: { navigationStates: [configure] }` keeps a component active only in those states: control components, hotspots, `selectable`, cameras. [Components](../domain-model/components.md) owns filters.\n- **Tabs and steps** — each tab of `horizontalTabs` or `sidebarTabs` and each step of `navigationSteps` lists `navigationStates`: it is active while one of them is, and choosing it navigates to the first.\n- **Scene** — `sceneEntityNavigationHotspot` navigates from the scene, replacing the state or pushing it: [Scene controls](../domain-controls/scene-controls.md).\n\n### Read and change the state\n\n- `phx.frontend.useActiveNavigationState()` returns the active state.\n- `phx.frontend.useNavigate()` returns `(state) => void`: replace the state and clear the history. Use it for tabs, steps and leaving a finished flow.\n- `phx.frontend.usePushNavigate()` returns `(state) => void`: put the active state on the history stack, then go. Use it for a review or detail screen users come back from.\n- `phx.frontend.usePopNavigate()` returns `() => void`: go back to the last pushed state; with an empty stack it does nothing.\n- Each call commits immediately, so transformers and invariants run on it as on any change.\n- Viewers in read mode can navigate too; hide what they must not reach.\n\n### React to navigation\n\n- Transformers: `phx.frontend.transformerBuilder.when.navigated({ from, to })`, both optional, with actions such as `.then.deselect()`, `.then.select.entity(ctx => …)` and `.then.changeView(state)`. To navigate when a part is picked: `when.entity(['Door']).selected().then.navigateTo(state)`. File, registration and priority: [Transformers](../domain-model/transformers.md).\n- Clear the undo history when users enter a state, so earlier stages can no longer be undone: mount `ResetUndoListener` from `@salsita-ai/sdk/configurator` with `navigationStates={[…]}` in an element made with `phx.frontend.createOnConfiguratorReadyProvider`.\n- Ask before a navigation: `docs/complex-use-cases/navigation-guard.mdx` holds the commit with `storeSystem.onBeforeCommit` from `phx.frontend.useDomain()` and lets it through once users confirm.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/application-states.mdx`, section Navigation States — the declaration, steps and tabs, and `$filter` examples.\n- `docs/ux-guidelines/choosing-navigation.mdx` — tabs or steps for the client's decisions.\n- `docs/other-features/navigation-hotspot.mdx` — pushing from the scene and `canStackOnto`.\n- `docs/other-features/transformers.mdx` — navigation and selection triggers with working examples.\n- `docs/complex-use-cases/navigation-reset-selection.mdx` — a `navigated` transformer that deselects.\n- `docs/complex-use-cases/navigation-reset-undo.mdx`, `docs/complex-use-cases/navigation-guard.mdx` — `ResetUndoListener`, and a commit hook that asks before a navigation.",phxMembers:["applicationTypes.NavigationState","frontend.useActiveNavigationState","frontend.useNavigate","frontend.usePushNavigate","frontend.usePopNavigate"]});

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/presets.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Presets as starting configurations, the handler adjusting them and the route back to the preset screen. */
+export declare const generatePhoenixPresetsFeature: () => PhoenixGuide;