@salsita-ai/sdk 0.50.0-develop.ae52227c7e → 0.50.0-develop.afbc5157e1

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 <workspace>` authorizes the CLI; local dev and deploy use that identity. 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 only, and enabling custom or Clerk auth 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\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,44 @@
+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.
+
+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;

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

@@ -0,0 +1,38 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A kitchen range preset, and a handler that sets the voltage from the host's region. Assume \`frontendData\` declares \`site\` (\`na\` or \`eu\`), \`KitchenRange\` has a numeric \`voltage\`, and its \`baseIds\` relation composes the bases. A second preset lists its own complete entities the same way.
+
+\`\`\`yaml
+# spec/presets.yaml
+presets:
+  - name: The Compact
+    description: 1600 mm, gas cooking, an oven and storage
+    img: /presets/compact.png
+    tags: [compact]
+    rootEntityType: KitchenRange
+    initialDomainEntities:
+      - id: KitchenRange-1
+        type: KitchenRange
+        color: NOIR_MATTE
+        baseIds: [Base-1, Base-2]
+      - id: Base-1
+        type: Base
+        kind: oven
+        width: 800
+      - id: Base-2
+        type: Base
+        kind: drawers
+        width: 800
+\`\`\`
+
+\`\`\`ts
+// src/handlers/on-preset-loaded.ts
+export default phx.frontend.createOnPresetLoadedHandler(() => {
+  const { site } = phx.frontend.useFrontendData()
+
+  return {
+    handler: async entities =>
+      entities.map(entity =>
+        phx.domain.model.KitchenRange.is(entity) ? { ...entity, voltage: site === 'na' ? 120 : 230 } : entity
+      ),
+  }
+})
+\`\`\``;export const generatePhoenixPresetsFeature=()=>e({path:"features/application-states/presets.md",title:"Presets",summary:"Starting configurations from the spec or Admin, keeping them valid, adjusting them at runtime and the route back to the preset screen; read when defining how a configuration starts.",whenToUse:"Read when defining the configurations users start from, changing a preset's entities at runtime before the configuration is created, or adding a way back to the preset screen. The preset screen itself, its cards and categories, belongs to [Project pages](../custom-layout/pages.md).",capabilities:"### Choose where presets come from\n\n- **Spec presets** — `presets:` in any configurator YAML file in `spec/`; the lists of several files are concatenated in file order. Use them for starting points that ship with the code.\n- **Admin presets** — `$adminPages: { presets: true }` in an Admin spec file (`$admin: true`) adds preset category pages to Project Admin. Once categories with presets are published, the preset screen shows them **instead of** the spec presets. Use them when the client's team curates starting points, with categories and thumbnails, without a deployment.\n- **How many** — with one preset, Phoenix creates the configuration at once and shows no preset screen; with several, users choose. The host can narrow the list to presets with matching `tags` through its `presetTags` property; a single match also skips the screen.\n- **Preset or recipe** — a preset is a whole starting configuration, created once; a recipe adds or replaces entities inside an open one. Offer the product variants users start from as presets and the parts they add while configuring as recipes.\n\n### Keep a preset valid\n\n- `rootEntityType` names a member of the `RootEntity` alias, and `initialDomainEntities` contains exactly one entity of that type.\n- Each entity has `id`, `type` and its attributes. Name ids `<Type>-<n>` (`Base-1`): an id whose text before the last dash is not the entity's type is an error.\n- Parsing the spec checks the types, the attribute schemas, references and relation cardinalities, and that every entity hangs from the root through `composedOf` relations, with one parent and no cycles.\n- Parsing does not check invariants. A configuration that opens with a `fatal` or `fixable` violation gets one repair pass from the transformers; if it is still invalid, it does not load. Open each preset in the preview; severities and repair are in [Validation and repair](../domain-model/validation-and-repair.md).\n- Display fields are optional plain strings (`$msg` is not accepted): `name`, `description`, `img` (a public path such as `/presets/compact.png` for `public/presets/compact.png`), `imgAlt`, `detailTitle`, `detailDescription`, plus the `tags` list. Without `name` the screen shows a generated label, so always set one.\n\n### Adjust the entities when a preset is chosen\n\n- Default-export `phx.frontend.createOnPresetLoadedHandler(() => ({ handler: async entities => entities }))` from a file in `src/handlers/`. After users pick a preset, spec or Admin, Phoenix migrates its entities to the current model, passes them to `handler` and creates the configuration from the list it returns. Return every entity, valid as a preset must be.\n- The outer function is a React hook that runs above the configuration: published, frontend and backend data and the session are available (`phx.frontend.useFrontendData()`, `phx.frontend.useSession()`), configuration hooks are not.\n- Use it for values known only at runtime, such as the host's region or the session's role. Differences known in advance belong in separate presets.\n\n### Route back to the preset screen\n\n- `phx.frontend.useConfiguratorRouting()` (beta) returns the routing service: `goToIndex()` leaves the configuration for the preset screen, `goToConfigurationDetail(configurationId, accessToken?)` opens another configuration.\n- A project layout's \"Start over\" or \"Other products\" action calls `goToIndex()`. Offer it only with more than one preset (the `presetCategories` of `phx.frontend.usePresetSelection()`). Saving is debounced by three seconds, so outside read mode save first, as the built-in back button does: take `configurationPersistSystem` from `phx.frontend.useDomainApplication()` and await its `save()`.\n- `phx.frontend.createOnGoToIndexHandler(() => ({ handler: ({ next }) => { … } }))`, default-exported from `src/handlers/`, intercepts every `goToIndex()`: the built-in back and previous-step buttons and a change of `presetTags` included. Call `next()` to continue; return without calling it to stay. Use it to confirm leaving or to send users to the host's product page instead. Its hook runs in the routing provider, outside the configuration.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/application-states.mdx`, section Presets — the basic YAML shape and `tags`.\n- `docs/phoenix/integration/preset-tags-external.mdx` — narrowing presets from the host.\n- `docs/ux-guidelines/presets.mdx` — a flat gallery or categories, and thumbnails.\n- `docs/layouts/preview/auto-presets.mdx` — the preview start screen before the presets, set with the top-level `preview:` and `alwaysExpand:` keys.\n- `docs/phoenix/configurator-interface.mdx` — "Data Handlers": both handler factories.',phxMembers:["frontend.createOnPresetLoadedHandler","frontend.createOnGoToIndexHandler","frontend.useConfiguratorRouting"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Selection and hover: what they drive, making entities selectable, their hooks, selection rules and highlight. */
+export declare const generatePhoenixSelectionFeature: () => PhoenixGuide;

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

@@ -0,0 +1,35 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`Cabinets are selectable in the scene while configuring, and the project layout shows an inspector for the selected cabinet. Assume a \`Cabinet\` with a numeric \`width\`, composed into a \`Wall\`.
+
+\`\`\`yaml
+# spec/domain/cabinet.yaml
+components:
+  Cabinet:
+    selectable:
+      main:
+        $filter:
+          navigationStates: [configure]
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/CabinetInspector.tsx, part of the project layout
+import { Button, Typography } from '@mui/material'
+
+export const CabinetInspector = () => {
+  const selectedId = phx.frontend.useSelectedDomainEntityId()
+  const cabinet = phx.frontend.useSelectedEntity(phx.domain.enhancedModel.$Cabinet)
+  const selectWall = phx.frontend.useSelectParent(selectedId)
+  const deselect = phx.frontend.useDeselect()
+
+  if (cabinet === null) {
+    return <Typography>Pick a cabinet in the scene to change it.</Typography>
+  }
+
+  return (
+    <>
+      <Typography variant="h6">Cabinet, {cabinet.width} mm</Typography>
+      <Button onClick={selectWall}>Select its wall</Button>
+      <Button onClick={deselect}>Done</Button>
+    </>
+  )
+}
+\`\`\``;export const generatePhoenixSelectionFeature=()=>e({path:"features/application-states/selection.md",title:"Selection and hover",summary:"What selection and hover drive, making entities selectable, the selection and hover hooks, selection rules and highlight; read when users pick parts in the scene or a list, or the UI, camera or highlight should follow the pick.",whenToUse:"Read when users should pick parts of the product, in the scene, from hotspots or from a list, and the controls, filters, camera or highlight should follow the pick.",capabilities:"### What selection drives\n\n- One entity is always selected: \"nothing selected\" means the root entity. A configuration opens with the root selected, and deselecting selects the root again.\n- A project layout reads the selection itself and renders the controls of the selected entity.\n- Filters: `selectedEntityIds` and `hoveredEntityIds` gate components, for example `selectedEntityIds: { $read: id }` for \"while this entity is selected\". Selection hotspots hide once their entity is selected (`showWhen`). A `fitSelectionPerspectiveCamera` or `fitSelectionOrthographicCamera` is active only while its entity is selected.\n- Highlight: by default the scene sets the selected entity, with its composed children, apart and marks the hovered one.\n\n### Make entities selectable\n\n- **In the scene** — add `selectable` to the entity type (`selectable: { main: {} }`). Clicking its geometry selects it; clicking empty canvas deselects. `hoverable: false` keeps the click without hover. Filter it like any component to allow picking only in some states.\n- **Small, hidden or grouped parts** — selection hotspots (`sceneEntitySelectHotspot`): [Scene controls](../domain-controls/scene-controls.md).\n- **From the UI** — a list, an outline or a \"next part\" button calls `phx.frontend.useSelectEntity()`.\n- Phoenix's auto-selection transformer (priority 100) selects a created entity, follows a replaced selection to its replacement and deselects a deleted one. A project transformer with the default priority runs after it.\n\n### Read and change the selection\n\n- `phx.frontend.useSelectedDomainEntityId()` returns the selected id: the root id when nothing is selected.\n- `phx.frontend.useSelectedEntityId(reflection)` returns the id while the selected entity has that type, else `null`; without a reflection it is always `null`.\n- `phx.frontend.useSelectedEntity(reflection)` returns the selected entity with its expressions, or `null` for another type. Pass the enhanced reflection, such as `phx.domain.enhancedModel.$Cabinet`.\n- `phx.frontend.useSelectEntity()` returns `(id) => void`; `phx.frontend.useDeselect()` returns `() => void`, which selects the root.\n- `phx.frontend.useSelectParent(id, fallback?)` returns `() => void`: select the composition parent of `id`, else `fallback`, else nothing.\n- Each call commits immediately, so transformers run on it.\n\n### Hover\n\n- `phx.frontend.useHoveredDomainEntityId()` returns the hovered id, or `null` while nothing is hovered.\n- `phx.frontend.useHoveredEntityId(reflection)` and `phx.frontend.useHoveredEntity(reflection)` narrow by type like their selection twins.\n- In the scene only `selectable` entities report hover. Hover is debounced and never committed: use it for labels and emphasis, not for changes.\n\n### Selection rules\n\n- Write them with `phx.frontend.transformerBuilder` (triggers, registration and order in [Transformers](../domain-model/transformers.md)):\n  - open a stage when a part is picked: `when.entity(['Door']).selected().then.navigateTo(state)`;\n  - step up the hierarchy on a click into empty canvas: `when.entity(['Console']).deselected({ inFavorOf: ['Room'] }).then.select.ancestorOfType(['ConsoleGroup'])`, with `Room` the root type;\n  - deselect on a second click: `when.entity(['Console']).selected({ occurrence: 'repeated' }).then.deselect()`.\n- For drill-down, filter the children's `selectable` or hotspots with `selectedEntityIds` read from an expression that lists their parent, so they become pickable once the parent is selected.\n\n### Highlight\n\n- One `canvasConfig` component configures it: `highlightingDisabled: true` turns the built-in highlight off, `enableFastHighlight: true` swaps it for a cheaper emissive one. `highlightingDisabled: true` on an object of `sceneEntityObjectProperties` exempts that object.\n- Outlines: turn the built-in highlight off, name an element in `canvasCustomEnvironment`, register it with `phx.frontend.createCustomPhoenixLayoutElement`, and render `SelectionOutline` and `HoverOutline` inside `Postprocessing` there, all three from `@salsita-ai/sdk/configurator`.\n- An effect of your own: `phx.frontend.useUpdateEntityObjectSelection(filter, selection)` keeps a postprocessing selection (any object with `set(objects)`) filled with the 3D objects of `filter.entityIds` and empties it on unmount. The other filter flags (`entityRoots`, `entityObjects`, `descendantEntities`, `recursiveObjects`, `objectInstanceNames`) choose which objects. It needs the canvas context, so call it only inside the canvas, such as in that environment element.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/selection-and-highlight/canvas.mdx`, `docs/selection-and-highlight/hotspots.mdx`, `docs/selection-and-highlight/group-highlighting.mdx` — `selectable`, selection hotspots and composed groups.\n- `docs/other-features/transformers.mdx` — the selection rules above with working examples; `docs/selection-and-highlight/hierarchy.mdx` — a selection hierarchy built from them.\n- `docs/selection-and-highlight/disable-highlight.mdx`, `docs/selection-and-highlight/disable-highlight-per-object.mdx`, `docs/selection-and-highlight/fast-emissive-highlight.mdx` — the built-in highlight.\n- `docs/selection-and-highlight/effects/outline.mdx`, `docs/selection-and-highlight/effects/overlay.mdx` — outline and overlay effects. Their Usage snippet passes the canvas settings to `buildConfig`; in a project use `canvasConfig` and `canvasCustomEnvironment` as above and as their Complete Implementation does.\n- `docs/3d-scene/cameras/fit-selection.mdx` — framing the selected entity.\n- `docs/phoenix/configurator-interface.mdx` — "Selection & Hover": the selection and hover hooks with a sample call each.',phxMembers:["frontend.useSelectedEntity","frontend.useSelectedEntityId","frontend.useSelectedDomainEntityId","frontend.useSelectEntity","frontend.useDeselect","frontend.useSelectParent","frontend.useHoveredEntity","frontend.useHoveredEntityId","frontend.useHoveredDomainEntityId","frontend.useUpdateEntityObjectSelection"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** View states for how the scene is shown and tool states for interaction modes, and how each is switched. */
+export declare const generatePhoenixViewsAndToolsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,61 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A table with a close-up view and a dimensions tool: the toolbar switches tools, a camera keyed to the view frames the edge, and the length options exist only in the dimensions tool. \`Table\` is the root entity type.
+
+\`\`\`yaml
+# spec/application.yaml
+viewStates: [overview, edge]
+toolStates: [Default, Dimensions]
+\`\`\`
+
+\`\`\`yaml
+# spec/domain/table.yaml
+components:
+  Table:
+    toolControls:
+      main:
+        items:
+          - { label: Finish, value: Default, icon: Palette }
+          - { label: Dimensions, value: Dimensions, icon: SlidersHorizontal }
+    fitRootPerspectiveCamera:
+      main:
+        priority: 1
+        distance: 5000
+      edge:
+        priority: 2
+        distance: 2000
+        azimuthAngle: 0.5
+        $filter:
+          viewStates: [edge]
+    distanceDimensionSelect:
+      length:
+        $filter:
+          toolStates: [Dimensions]
+        value:
+          $bind: length
+        options:
+          - value: 1600
+          - value: 2000
+\`\`\`
+
+The project layout draws its own view switch:
+
+\`\`\`tsx
+// src/_shared/ViewSwitch.tsx
+import { Button } from '@mui/material'
+
+const LABELS = { overview: 'Whole table', edge: 'Edge close-up' } as const satisfies Record<ViewState, string>
+
+export const ViewSwitch = () => {
+  const activeView = phx.frontend.useActiveViewState()
+  const setViewState = phx.frontend.useSetViewState()
+
+  return (
+    <>
+      {phx.applicationTypes.ViewState.values().map(view => (
+        <Button key={view} aria-pressed={view === activeView} onClick={() => setViewState(view)}>
+          {LABELS[view]}
+        </Button>
+      ))}
+    </>
+  )
+}
+\`\`\``;export const generatePhoenixViewsAndToolsFeature=()=>e({path:"features/application-states/views-and-tools.md",title:"View and tool states",summary:"View states for how the scene is shown, tool states for interaction modes, switching each and the cameras and filters keyed to them; read when adding camera views, scene presentations or modes such as dimensions, sketching or focus.",whenToUse:"Read when users switch how the scene is shown (a front or top view, a close-up, a room style) or which mode it is in (dimensions, sketching, editing one part), independently of the stage of the flow.",capabilities:"### Choose the kind of state\n\n- **Navigation state** — where users are in the flow; it changes controls and pages: [Navigation states](navigation.md).\n- **View state** — how the scene is presented: a camera, an environment, a close-up. The controls stay as they are.\n- **Tool state** — what users are doing in the scene: setting dimensions, sketching, a focus mode for editing one part. It swaps the in-scene controls.\n- The three lists are independent: one value of each is active, and a filter can combine them. A tool state does not change the selection, nor the selection the tool.\n\n### Declare them\n\n- `viewStates:` and `toolStates:` follow the rules of navigation states: identifier values, each list in one file, the first value active when a configuration opens, a single `Default` when undeclared.\n- `phx.applicationTypes.ViewState` and `phx.applicationTypes.ToolState` are their runtime enums (`ToolState.Dimensions === 'Dimensions'`, `.values()`, `.is(value)`); the global types `ViewState` and `ToolState` are the unions.\n\n### Switch the view\n\n- `phx.frontend.useActiveViewState()` returns the active view; `phx.frontend.useSetViewState()` returns `(state) => void`, which commits immediately.\n- Built-in switch: a `viewControls` component on the root entity, `items: [{ label, value, icon }]` with a view state as `value` and a PhxIcon name as `icon`. The built-in layout shows the first one. A project layout mounts `LayoutSlots.DesktopViewControls` or `MobileViewControls` ([Layout slots](../custom-layout/slots.md)), or draws its own buttons with the two hooks, which need no component.\n- Cameras: filter camera components with `viewStates`. Of the cameras whose filters pass, the highest `priority` (default 1) wins, so keep an unfiltered camera with the lowest priority as the default.\n- Transformers: `when.viewChanged({ from, to })` reacts to a switch, and `.then.changeView(state)` switches as a side effect.\n\n### Switch the tool\n\n- `phx.frontend.useActiveToolState()` returns the active tool. No hook sets it; switch tools with:\n  - a `toolControls` component on the root entity (`items: [{ label, value, icon }]`, `value` a tool state), shown by the built-in layout, or by `LayoutSlots.DesktopToolControls` and `MobileToolControls` in a project layout;\n  - the tool menu `toolMenuFab` in the scene ([Scene controls](../domain-controls/scene-controls.md)) and the exit button `exitToolModeFab` with `exitTo` in the call-to-action slot ([Layout slots](../custom-layout/slots.md));\n  - own UI: take `storeSystem` and `navigationSystem` from `phx.frontend.useDomain()` and call `storeSystem.stageAndCommit([navigationSystem.getToolUpdate(phx.applicationTypes.ToolState.Dimensions)])`, as the SDK's own controls do.\n- Filter each tool's controls with `toolStates`, and give the default tool controls of its own, so every mode offers something to do. A focus mode also hides navigation, tool and view controls and offers a labeled exit.\n- `when.toolChanged({ from, to })` reacts to a switch; the transformer builder has no action that changes the tool.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/application-states.mdx`, sections View States and Tool States — the declarations, filters, `viewControls` and `toolControls`.\n- `docs/layouts/view-controls.mdx` — one camera per view and the built-in view switch.\n- `docs/complex-use-cases/focus-mode.mdx` — a tool state entered from `toolMenuFab` and left with `exitToolModeFab`.\n- `docs/complex-use-cases/sketching.mdx` — tool states switching between drawing and selecting.\n- `docs/ux-guidelines/interaction-modes.mdx` — what each mode shows and hides.\n- `docs/phoenix/layout-slots.mdx` — the view and tool control slots.",phxMembers:["applicationTypes.ViewState","applicationTypes.ToolState","frontend.useActiveViewState","frontend.useSetViewState","frontend.useActiveToolState"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The custom project layout index followed by its guides: one per page-level feature of a project layout. */
+export declare const generatePhoenixCustomLayoutGuides: () => readonly PhoenixGuide[];

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

@@ -0,0 +1,7 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixFinalizationActionsFeature as o}from"./finalization-actions.js";import{generatePhoenixMessagesFeature as t}from"./messages.js";import{generatePhoenixProjectPagesFeature as s}from"./pages.js";import{generatePhoenixSceneAndSafeAreaFeature as a}from"./scene-and-safe-area.js";import{generatePhoenixLayoutSlotsFeature as r}from"./slots.js";import{generatePhoenixTabsAndStepsFeature as n}from"./tabs-and-steps.js";import{generatePhoenixToolbarActionsFeature as i}from"./toolbar-actions.js";import{generatePhoenixViewModeFeature as d}from"./view-mode.js";let l=`A layout element registered as \`ConfiguratorLayout\` replaces everything Phoenix renders for a loaded configuration, in owner and in read mode, finalization included. It shows only what it composes.
+
+- YAML keeps the domain and the structure the layout reads: control components, in-scene anchors, tabs, steps, toolbar entries and finalize actions. The layout reads them through \`phx.frontend\` hooks, or mounts a built-in slot that reads them.
+- The spec does not describe the page: the layout draws its own panels and renders the project's control elements in them.
+- Start every layout from the skeleton in [Scene and safe area](scene-and-safe-area.md), then read only the guides for the features it offers.
+- Each feature is either a built-in slot ([Layout slots](slots.md)) or the layout's own UI over hooks, which the other guides cover. No hook enforces read mode, so [View mode](view-mode.md) applies to all of them.
+- The controls inside the layout's panels and on the product, their YAML components and React elements, belong to [Domain controls](../domain-controls/index.md).`;export const generatePhoenixCustomLayoutGuides=()=>{let m=[a(),r(),n(),i(),t(),o(),d(),s()];return[e({path:"features/custom-layout/index.md",title:"Custom project layout",summary:"The project's page-level UI: the `ConfiguratorLayout` element with its canvas, built-in slots, tabs and steps, toolbar, messages, finalization and read mode, and the preset screen, loader and error pages; read when creating or changing a project layout or one of these pages.",intro:l,guides:m,notes:[]}),...m]};

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/finalization-actions.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The spec's `finalizeAction` components in a project layout: handlers, rendering, pending and error states. */
+export declare const generatePhoenixFinalizationActionsFeature: () => PhoenixGuide;