@salsita-ai/sdk 0.50.0-develop.b47f1774a2 → 0.50.0-develop.b5d443db78

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;

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

@@ -0,0 +1,79 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let n=`A secondary action that copies a read-only link next to the primary quote, both rendered by the layout and hidden for viewers.
+
+\`\`\`yaml
+components:
+  Desk:
+    finalizeAction:
+      quote:
+        variant: primary
+        label:
+          $msg: Request a quote
+        title:
+          $msg: Send the configuration to the shop
+        icon: PaperPlaneTilt
+        handler: requestQuote
+      link:
+        variant: secondary
+        label:
+          $msg: Copy a link
+        title:
+          $msg: Copy a read-only link to this configuration
+        icon: CopySimpleBold
+        handler: copyLink
+\`\`\`
+
+\`\`\`ts
+// src/handlers/copy-link.ts
+import { useCallback } from 'react'
+
+export default phx.frontend.createPhoenixHandler('copyLink', () => {
+  // The factory runs as a hook beside the layout: call hooks here, not inside \`handler\`
+  const generateShareLink = phx.frontend.useGenerateShareLink()
+
+  return {
+    handler: useCallback(async () => {
+      // Saves first; a rejection becomes the action's \`error\`
+      const { link } = await generateShareLink({ access: 'rr' })
+      await navigator.clipboard.writeText(link)
+    }, [generateShareLink]),
+  }
+})
+\`\`\`
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout
+export const Finalize = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const { primary, secondary, hints } = phx.frontend.useFinalizeActions()
+
+  if (accessInfo.viewMode || primary === null) {
+    return null
+  }
+
+  const actions = [primary, ...secondary]
+  const failed = actions.find(action => action.error !== null)
+
+  return (
+    <div>
+      {actions.map(action => (
+        <button
+          key={action.key}
+          type="button"
+          title={action.disabled ? hints : action.title}
+          disabled={action.disabled || action.isPending}
+          onClick={() => void action.run()}
+        >
+          {action.isPending ? 'Working…' : action.label}
+        </button>
+      ))}
+      {failed?.error && (
+        <p role="alert">
+          {failed.label}: {failed.error.message}
+        </p>
+      )}
+    </div>
+  )
+}
+\`\`\`
+
+\`requestQuote\` is registered the same way; the quote's server side follows the finalization process.`;export const generatePhoenixFinalizationActionsFeature=()=>e({path:"features/custom-layout/finalization-actions.md",title:"Finalization actions",summary:"The spec's `finalizeAction` components with their handlers, rendered by the layout with pending, error and disabled states, and hidden for viewers; read when a project layout offers quote, order, PDF, email, save or share buttons.",whenToUse:"Read when a project layout offers the buttons that complete a configuration, or when such a button does nothing, stays disabled or fails silently. [Finalization](../../processes/finalization.md) owns agreeing what completing means and the server side.",capabilities:"### Declare an action and its handler\n\n- Declare each completion as a `finalizeAction` component on the root entity, with `variant` (`primary` or `secondary`), `label`, `title`, `icon` (a PhxIcon name) and `handler`, all required.\n- Register the handler in a `src/handlers/` file as its default export, one or an array: `phx.frontend.createPhoenixHandler(name, () => ({ handler }))`.\n- The factory is a hook. Call hooks in it and return `{ handler }`, an async function without arguments wrapped in `useCallback`.\n- The YAML `handler` must equal the registered name. An unknown name only logs \"PhoenixHandler … not found\" to the console and resolves, so the button seems to do nothing.\n- Throw or reject to report a failure; the action's `error` then holds it.\n- A handler that finalizes on the server calls `finalize` and `waitForFinalizationToComplete` of `phx.frontend.useAuthorizedClient()`; [Finalization](../../processes/finalization.md) owns that side and the agreed journey.\n- `finalizePage` and `finalizeButton` are legacy, declared only in TypeScript; do not use them.\n\n### Render them with `useFinalizeActions`\n\n- `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`.\n- `actions` lists every active `finalizeAction` in spec order. `primary` is the first `'primary'` one, else the first, else `null`; `secondary` holds the others.\n- Each action is `{ key, handler, variant, label, title, icon, run, isPending, error, disabled }`, with `label` and `title` resolved.\n- `run()` pushes the finalize analytics event and runs the handler. It does nothing while `disabled` or `isPending`, and its promise never rejects.\n- `error` is what the last run rejected with, as an `Error`, cleared on the next run. No snackbar is raised: show it.\n- `disabled` is `true` while a `warning` or worse holds, a save failed or the handler failed to load. Show `hints` beside a disabled button; [Violations](../state/violations.md) owns the gating.\n- Call the hook anywhere in the layout and in dialogs it opens, as often as needed. `isPending` and `error` survive unmounts, such as a panel hidden by fullscreen during a run.\n\n### Handlers run outside the layout\n\n- The configurator runs the handlers itself, beside the layout, whenever a configuration is open, read mode included.\n- A handler can use what the configurator provides, such as every `phx.frontend` hook and opening dialogs, but not a provider the layout adds. Such a handler fails to load and shows as the action's `error`.\n\n### Other ways to run them\n\n- `phx.frontend.useFinalizeAction(handlerName)` runs one known action in the layout and returns `{ run, isPending, error, disabled, hints }`.\n- It calls the handler factory's hooks, so call it once per component, never in a loop or conditionally. Wrap that component in `<PhoenixHandlerBoundary name={handlerName}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload.\n- Its `isPending` and `error` belong to the mounted component and are lost when it unmounts.\n- `<FinalizeActions />` from `@salsita-ai/sdk/configurator` mounts the built-in buttons, the primary one and a menu of the others. It raises a snackbar on failure, so mount a snackbar root ([Messages](messages.md)).\n\n### Read mode and pending runs\n\n- Neither hook checks read mode. Hide finalization while `accessInfo.viewMode` is `true` ([View mode](view-mode.md)), or filter the components with `$filter.modes: [owner]` so they disappear in every layout.\n- While an action is pending, disable what changes the configuration, such as Back or undo, so it cannot change under the running request.",example:n,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — the "Finalize" paragraph of "Hooks for a Project Layout".\n- `docs/layouts/custom-layout.mdx` — "Request a quote": a review step, a pending button and the handler.\n- `docs/phoenix/finalization.mdx` — the server side, finalize data and result.\n- `docs/layouts/phoenix-handlers.mdx` — handler patterns, such as opening a dialog, each the default export of a file in `src/handlers/`.',phxMembers:["frontend.useFinalizeAction","frontend.useFinalizeActions","frontend.createPhoenixHandler"]});

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

@@ -0,0 +1 @@
+export * from './custom-layout.js';

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

@@ -0,0 +1 @@
+export*from"./custom-layout.js";

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Showing a project layout's messages: violations, hints, errors and save failures, and where snackbars render. */
+export declare const generatePhoenixMessagesFeature: () => PhoenixGuide;

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

@@ -0,0 +1,52 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`The layout's own toast in place of \`LayoutSlots.Services\`. A rejected change also reports the notices already present, so the toast keeps the most severe message while it shows.
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout, placed in the free area with pointerEvents: 'auto'
+import { Alert } from '@mui/material'
+import { useEffect, useState } from 'react'
+
+type Severity = 'error' | 'warning' | 'info'
+
+const VIOLATION_SEVERITY = { fatal: 'error', fixable: 'error', warning: 'warning', notice: 'info' } as const
+const RANK: Readonly<Record<Severity, number>> = { info: 0, warning: 1, error: 2 }
+
+interface Shown {
+  readonly text: string
+  readonly severity: Severity
+}
+
+export const MessageToast = () => {
+  const [shown, setShown] = useState<Shown | null>(null)
+
+  phx.frontend.useConfiguratorMessages(message => {
+    const severity: Severity =
+      message.kind === 'violation'
+        ? VIOLATION_SEVERITY[message.violation.severity]
+        : message.kind === 'error' || message.kind === 'saveError'
+          ? 'error'
+          : 'info'
+
+    setShown(current =>
+      current !== null && RANK[current.severity] > RANK[severity] ? current : { text: message.text, severity }
+    )
+  })
+
+  useEffect(() => {
+    if (shown === null) {
+      return
+    }
+
+    const timeout = setTimeout(() => setShown(null), 6000)
+
+    return () => clearTimeout(timeout)
+  }, [shown])
+
+  return shown === null ? null : (
+    <Alert severity={shown.severity} onClose={() => setShown(null)}>
+      {shown.text}
+    </Alert>
+  )
+}
+\`\`\`
+
+A failed save shows as an error and stays only six seconds here; a layout that must keep it visible reads \`useConfigurationSaveState().failure\` as well.`;export const generatePhoenixMessagesFeature=()=>e({path:"features/custom-layout/messages.md",title:"Messages",summary:"Showing rejected changes, side-effect hints, validation errors and failed saves with the built-in snackbars or the layout's own UI, the save status, and where snackbars render; read when composing a project layout or when its messages are missing, doubled or outside the configurator.",whenToUse:"Read when composing a project layout: it shows messages only through one of the two routes below. Read also when snackbars appear twice, unstyled or outside the configurator.",capabilities:"### Choose one route\n\n- **Built-in snackbars** — mount `LayoutSlots.Services`. It shows the violations of a rejected change, side-effect hints, validation errors, a failed save (persistent, with **Dismiss**) and \"Configuration updated\" once saving works again.\n- **The layout's own UI** — call `phx.frontend.useConfiguratorMessages(onMessage)` and show each message as a toast, a banner or inline text.\n- Mount one of the two, never both, or every message shows twice.\n- A layout with neither shows no reason for a rejected change and no sign of a failed save.\n\n### Message kinds\n\n`onMessage` is called once per message, with `text` resolved to the current language. It may be a new function on every render.\n\n- **`violation`** — `{ entityId, violation, text }`, one per violation of the rejected state, including notices and warnings already present. `violation.severity` `fixable` or `fatal` is the reason for the rejection, so keep the most severe message while one shows.\n- **`sideEffect`** — `{ text }`, the hint a committed update carried, for example from a transformer.\n- **`error`** — `{ error, text }`, an error thrown while a change was validated; `text` is a generic \"Oops, something went wrong\".\n- **`saveError`** — `{ error, text }`, each failed save. The configurator keeps saving later changes.\n- **`saveRecovery`** — `{ text }`, the first successful save after a failure.\n- A violation's `text` is its `message`, or its `type` without one. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types.\n- Hints committed and saves failed before the hook mounted are not delivered; the most recent rejected change is delivered again on mount.\n- What the violations mean and how controls show them belongs to [Violations](../state/violations.md).\n\n### Save status\n\n- `phx.frontend.useConfigurationSaveState()` returns `{ revisionId, isSaving, failure }` for a save indicator.\n- `failure` is `{ error, timestamp }` of the latest failed save, and `null` once a later save succeeds or another configuration loads.\n- An editable configuration saves every committed change about three seconds after the last one. A read-only one never saves.\n- The messages of a failed save still come from the route above; finalizing is blocked while the failure stands.\n\n### Snackbar roots\n\n- Snackbars render into the snackbar root the layout mounts. Without one they render into the page's `document.body`, outside the configurator and its theme.\n- Mount a root whenever the layout mounts `LayoutSlots.Services` or a built-in piece with actions, such as the toolbar or `FinalizeActions`. Their failures are snackbars even when the layout uses `useConfiguratorMessages`.\n- A layout drawn only from hooks, with `useConfiguratorMessages` and `useFinalizeActions`, raises no snackbars and needs no root.\n- `LayoutSlots.DesktopSnackbarsRoot` is a zero-height element the snackbars stack upward from, at most 320 px wide: place it where their bottom edge belongs.\n- `LayoutSlots.MobileSnackbarsRoot` leaves them fixed to the viewport's edge wherever it is mounted.\n- The preset screen renders before any layout; a project preset screen mounts its own root ([Project pages](pages.md)).\n- The theme restyles every snackbar under `components.PhxSnackbar`.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — the messages paragraph of "Loaded Configuration UI" and the "Violations" table of "Hooks for a Project Layout".\n- `docs/phoenix/layout-slots.mdx` — "Canvas and services" and "Styling the snackbars": the services, the roots and the `PhxSnackbar` theme slots.\n- `docs/layouts/custom-layout.mdx` — "Show messages", the toast this example follows.\n- `docs/other-features/side-effects.mdx`, `docs/other-features/violation-messages.mdx` — where hints and violation texts come from.',phxMembers:["frontend.useConfiguratorMessages","frontend.useConfigurationSaveState"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The project's pages outside the loaded configuration: preset screen, loader, failure pages and assistant form elements. */
+export declare const generatePhoenixProjectPagesFeature: () => PhoenixGuide;

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

@@ -0,0 +1,49 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A branded preset screen that keeps the preview branch, shows creation progress and errors, and mounts its snackbar root.
+
+\`\`\`tsx
+// src/elements/PresetScreen.tsx
+import { PresetPreviewLayout, PresetSnackbarsRoot } from '@salsita-ai/sdk/configurator'
+import { useResourceUrl } from '@salsita-ai/sdk/react'
+
+const PresetScreen = () => {
+  const { isPreview } = phx.frontend.usePreview()
+  const { presetCategories, selectPreset, creatingPresetId, selectionError } = phx.frontend.usePresetSelection()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const { getResourceUrl } = useResourceUrl()
+
+  // A phone embed with \`preview: auto\` starts here; the button expands it
+  if (isPreview) {
+    return <PresetPreviewLayout title="Design your sofa" startButtonLabel="Start designing" />
+  }
+
+  const presets = presetCategories.flatMap(category => category.presets)
+
+  return (
+    <main style={{ height: '100%', overflowY: 'auto', padding: 32 }}>
+      <h1>Choose a starting sofa</h1>
+      {selectionError !== null && <p role="alert">This sofa could not be opened. Try again.</p>}
+      <div style={{ display: 'grid', gap: 24, gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr))' }}>
+        {presets.map(preset => (
+          <button
+            key={preset.id}
+            type="button"
+            aria-busy={creatingPresetId === preset.id}
+            disabled={creatingPresetId !== null}
+            onClick={() => selectPreset(preset.id)}
+          >
+            {preset.img !== undefined && (
+              <img src={getResourceUrl(preset.img)} alt={resolve(preset.imgAlt ?? preset.name)} width="100%" />
+            )}
+            {resolve(preset.name)}
+          </button>
+        ))}
+      </div>
+      <PresetSnackbarsRoot />
+    </main>
+  )
+}
+
+export default phx.frontend.createPresetUi(PresetScreen)
+\`\`\`
+
+The app loader is as short: \`export default phx.frontend.createAppLoader(({ phases }) => <span role="status">{phases[0]?.label ?? 'Loading…'}</span>)\`.`;export const generatePhoenixProjectPagesFeature=()=>e({path:"features/custom-layout/pages.md",title:"Project pages",summary:"Replacing the preset screen and its action and overlay, the app loader, the not-authenticated, not-found and error pages, and the assistant's form elements; read when branding the first moments or the failure pages, or when the assistant needs a project form element.",whenToUse:"Read when a page outside the loaded configuration should carry the brand, such as the preset screen, the loader or a failure page, or when the assistant should offer a form element of the project.",capabilities:"Each page below is an element: default-export its registration from a file in `src/elements/`.\n\n### Preset screen\n\n- The preset screen shows at the start when there is more than one preset; with a single preset the configuration starts at once.\n- `phx.frontend.createPresetUi(Component)` replaces the whole screen. The built-in screen's categories, close button, action, overlay and empty state go with it.\n- Inside it, `phx.frontend.usePresetSelection()` returns `{ presetCategories, hasMultiplePresets, selectPreset, creatingPresetId, selectionError }`.\n- A category is `{ id, name, description?, img?, imgAlt?, presets }`; a preset is `{ id, name, description?, img?, imgAlt?, detailTitle?, detailDescription? }`. Texts are `Localizable`: resolve them with `phx.frontend.useResolveLocalizable()`.\n- `img` is a resource path: turn it into a URL with `useResourceUrl().getResourceUrl(img)` from `@salsita-ai/sdk/react`, as the built-in screen does.\n- `selectPreset(id)` creates the configuration and opens it. While `creatingPresetId` is set, mark that card busy and disable the others.\n- `selectionError` is the last failed creation: show it. In production with several presets the failure is also a snackbar, so mount `PresetSnackbarsRoot` from `@salsita-ai/sdk/configurator`, or it renders outside the configurator.\n- Keep the preview branch. While `phx.frontend.usePreview().isPreview` is `true`, return `PresetPreviewLayout` from `@salsita-ai/sdk/configurator` with `title` and `startButtonLabel`. Without it, a phone embed with `preview: auto` never expands and shows the whole screen in the collapsed preview.\n- With no categories, for example when the host's `presetTags` match none, the built-in screen shows the not-found page; a replacement decides itself.\n- What a preset is and how to declare one belongs to [Presets](../application-states/presets.md).\n\n### Preset action and overlay\n\nThese fill the built-in preset screen only; a `createPresetUi` screen renders its own instead.\n\n- `phx.frontend.createPresetPageAction(Component)` adds content below the cards, such as a link to request an unlisted product.\n- `phx.frontend.createPresetDeviceNotSupported(Component)` adds an overlay, such as a notice that the configurator works best on a larger screen.\n- The overlay renders as the last child of the screen, not over the cards, and at every width: make it a dialog or position it, and gate it on the condition it is for.\n\n### App loader\n\n- `phx.frontend.createAppLoader(({ phases }) => …)` replaces what the loading overlay shows. Phoenix keeps the overlay, its place over the safe area and its fade.\n- `phases` are the running loading phases, each `{ id, label?, progress? }` with `progress` from 0 to 1. The list can be empty while the loader waits for the scene.\n- The loader covers the session, the data, the configuration and the scene; it waits for the scene only when the layout mounts `LayoutSlots.SharedCanvas` ([Scene and safe area](scene-and-safe-area.md)).\n- `phx.frontend.useLoadingStateValue()` returns `{ isLoading, hasError, phases, expectedPhaseIds }` for loader content that needs more than `phases`.\n- `phx.frontend.useLoadingState()` returns `{ startPhase, endPhase }`, or `null` outside the loader's host. `startPhase({ id, label, progress })` holds the overlay for the project's own loading step; calling it again with the same `id` updates it.\n- End every started phase with `endPhase(id)`, on failure and on unmount too, or the overlay never leaves.\n- A top-level `appLoader: legacy` in the spec turns the overlay off.\n\n### Failure pages\n\n- `phx.frontend.createNotAuthenticatedPage(Component)` — shown when session authentication fails, and to an anonymous visitor of the start page when `acl.canCreate` excludes `anonymous`. It gets no props. Its default renders the not-found page, so a project not-found page shows there too.\n- `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)` — shown when a configuration fails to load, is opened without a valid access key, or a signed-in role may not create one. Offer a way back only when the optional `onBack` is set.\n- `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)` — the production error page. `reason` is `'uncaughtError'` or `'presetCreationFailed'` (the single preset failed to start); `onRetry` renders again or reloads.\n- Development shows detailed error pages instead, so check the error page in a production build. A page that throws falls back to the built-in one.\n- Use these helpers rather than `createCustomPhoenixLayoutElement` with the element's name: only the helpers type the props.\n\n### Assistant form elements\n\n- Declare an element under `assistant.formElements.<name>` with `description` (what the model reads), `role` (`group`, `choice`, `choices`, `option` or `input`), optional scalar `attributes` and `required`. Names are lowercase, such as `ralcolor`.\n- Implement it in one file: `export default phx.frontend.createAssistantFormElement('name', Component)`.\n- The name types the props by role through the global `AssistantFormElementProps<'name', STATE>`. Every element gets `attributes`, `label` and `disabled`; an option reports with `onSelect(answer)`, an input with `onChange(state, answer)`, and a container renders `children`.\n- A declared element without a registration, one registered twice, or a registration without a declaration stops the application with an implementation error, at start and on hot reload.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/layouts/presets/custom.mdx` — the complete branded preset screen with search and the preview branch.\n- `docs/layouts/presets/action-and-overlay.mdx` — the action and the overlay of the built-in screen.\n- `docs/phoenix/configurator-interface.mdx` — "Preset UI", "Configuration Not Found Page", "Configurator Error Page" and "App Loader".\n- `docs/other-features/not-found-404.mdx`, `docs/other-features/error-5xx.mdx` — worked failure pages.\n- `docs/ux-guidelines/presets.mdx` — what a good preset screen offers.',phxMembers:["frontend.createPresetUi","frontend.usePresetSelection","frontend.createPresetPageAction","frontend.createPresetDeviceNotSupported","frontend.createAppLoader","frontend.useLoadingState","frontend.useLoadingStateValue","frontend.createNotAuthenticatedPage","frontend.createConfigurationNotFoundPage","frontend.createConfiguratorErrorPage","frontend.createAssistantFormElement"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The layout element's registration, its canvas, the scene's safe area and the desktop/phone switch. */
+export declare const generatePhoenixSceneAndSafeAreaFeature: () => PhoenixGuide;