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

package/dist/docs/phoenix/components.mdx

@@ -273,6 +273,12 @@ components:
 
 `$bind` is essential for form controls that need to show current state and accept changes, any UI element that both displays and modifies data, and interactive controls like attribute selectors, toggles, sliders, and input fields.
 
+### Types of bound values
+
+The build checks that the field a `$read` or `$bind` reads fits the prop it is read into, the filter criterion, or, for `$filter: { $read: field }`, the whole filter. A `string` field read into a number prop, a nullable field read into a text, or an array read into a boolean is reported as `COMPONENT_BINDING_TYPE_MISMATCH` at the prop. A field whose schema gives its type only as `tsType` is not checked here. Expressions are checked where their type is settled.
+
+A prop or filter criterion that takes an entity id, such as the `value` of `childEntitySelection` or `selectedEntityIds`, cannot hold an id written in YAML: an entity id is a branded type that only comes from the domain state. Bind it to a field or expression that holds the id; a written id is reported as `COMPONENT_STATIC_ENTITY_ID`.
+
 ### `$eval` - Inline Expressions
 
 `$eval` allows simple dynamic calculations directly in YAML without defining separate `$expression` implementations in TypeScript. It can appear wherever `$read` is allowed — including in component filter `active` properties — and is mutually exclusive with `$read` on the same property, but both can coexist on the same component instance across different properties.

package/dist/docs/phoenix/configurator-interface.mdx

@@ -165,6 +165,10 @@ const popNavigate = phx.frontend.usePopNavigate() // popNavigate() returns to th
 // Fullscreen: a flag in the configurator's state that the layout honours; it does not put the browser into fullscreen
 const isFullscreen = phx.frontend.useIsFullscreenActive()
 const setFullscreen = phx.frontend.useSetFullscreen() // setFullscreen(true) or setFullscreen(false)
+
+// View state and camera
+const setViewState = phx.frontend.useSetViewState() // setViewState(state) makes one of the spec's viewStates active
+const resetCamera = phx.frontend.useResetCamera() // resetCamera() undoes the user's orbit, pan and zoom
 ```
 
 ### Controls
@@ -429,9 +433,11 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - `LayoutSlots.DesktopSidebar` is the built-in desktop sidebar as one piece: the spec's tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Use it when the spec's property pages are what the customer should see and only their place changes, for example a sidebar on the left; build the controls yourself when they have to look like the brand's own. Without `width` it fills its container, so the layout positions and sizes that container; `miniSidebar` does not shrink it, so a layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and lets the container take the sidebar's height. Its tabs sit outside it on the left; `side="start"` puts them on its right, for a sidebar on the left. In fullscreen it stays in place, transparent and inert, so a layout that wants the space back removes it while `phx.frontend.useIsFullscreenActive()` is set. See [Sidebar in a Custom Layout](?path=/docs/layouts-sidebar-in-a-custom-layout--docs).
 - Nothing of the built-in layouts is rendered for it. A project layout finalizes over the spec's `finalizeAction` components, see the finalize paragraph of [Hooks for a Project Layout](#hooks-for-a-project-layout). The `finalizePage` and `finalizeButton` components are legacy: they cannot be declared in YAML, only in TypeScript, and `Legacy.CommonFinalizePage`, which is deprecated, shows a `finalizePage` for projects that still have one. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is available to a project layout only inside `LayoutSlots.DesktopSidebar`.
 - The layout reads the state it has to react to from hooks, listed with what each returns in [Hooks for a Project Layout](#hooks-for-a-project-layout).
-- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints and errors as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it. `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. Some messages stay snackbars either way: a failure to save the configuration and an error of the built-in finalize and other actions. They render into the snackbar root, so a layout that mounts none shows them outside the configurator, in the page's `body`. An error while a preset is applied appears on the preset screen, outside the layout.
+- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints and errors as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it. `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. Some messages stay snackbars either way: a failure to save the configuration and an error of the built-in finalize and other actions. They render into the snackbar root, so a layout that mounts none shows them outside the configurator, in the page's `body`. An error while a preset is applied appears on the preset screen, outside the layout. A finalize action the layout runs with `phx.frontend.useFinalizeAction` reports its error as that hook's `error` instead, neither as a message nor as a snackbar.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
+`defaultConfiguratorElements`, exported from `@salsita-ai/sdk/configurator`, holds the built-in UI as a `ConfiguratorLayout` registration that renders the layout the spec selects. Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default. The list also holds the configurator's built-in controls and layout elements under the kinds the spec names them by, such as `attributeSelect` or `undoToolbarButton`, so a project element registered under one of those names replaces the built-in one wherever the spec names that kind. A config assembled by hand, without generated code, calls `withDefaultElements(defaultConfiguratorElements)` too; without it no `ConfiguratorLayout` is registered and the page shows a "not found" box instead of the configurator.
+
 #### Hooks for a Project Layout
 
 A project layout reads the product and the configurator's state through hooks, and changes them through the functions the hooks return. Each row names where its hook comes from; the `phx.frontend` hooks in these tables are also exported from `@salsita-ai/sdk/react` under the same name. No hook looks at read mode: the control hooks and the navigation and fullscreen setters keep working while `accessInfo.viewMode` is `true`, so the layout decides what a viewer can change.
@@ -461,15 +467,17 @@ Texts from the spec, such as option titles and the `detail` fields, are `Localiz
 
 **Mode, fullscreen, preview and navigation**
 
-| Hook                                                                         | Returns                                                                                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                               |
-| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                              |
-| `usePreview()` from `@salsita-ai/sdk/configurator`                           | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`.                                                                                                                              |
-| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state, one of the spec's `navigationStates`.                                                                                                                                                                                                       |
-| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | `(state) => void`, which enters a state and remembers the active one, and `() => void`, which returns to the remembered state and does nothing when there is none. `phx.frontend.useNavigate()` returns `(state) => void`, which enters a state and forgets the history. |
-| `phx.frontend.useActiveViewState()` and `phx.frontend.useActiveToolState()`  | The active view state and tool state.                                                                                                                                                                                                                                    |
-| `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The responsive breakpoints the configurator's container satisfies, as `Viewport[]`, or `null` before it is measured. It follows the container, not the window, so it is the switch between a desktop and a phone layout.                                                 |
+| Hook                                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                                                                                                                                                                                                                                                                                              |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `usePreview()` from `@salsita-ai/sdk/configurator`                           | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state, one of the spec's `navigationStates`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | `(state) => void`, which enters a state and remembers the active one, and `() => void`, which returns to the remembered state and does nothing when there is none. `phx.frontend.useNavigate()` returns `(state) => void`, which enters a state and forgets the history.                                                                                                                                                                                                                                                                |
+| `phx.frontend.useActiveViewState()` and `phx.frontend.useActiveToolState()`  | The active view state and tool state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `phx.frontend.useSetViewState()`                                             | `(state) => void`, which makes the given view state, one of the spec's `viewStates`, the active one; setting the active state again keeps it. Cameras and components filtered by `viewStates` follow the change.                                                                                                                                                                                                                                                                                                                        |
+| `phx.frontend.useResetCamera()`                                              | `() => void`, which moves the camera back to the framing of the active camera configuration, undoing the user's orbit, pan and zoom, as the toolbar's reset button does. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                |
+| `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The responsive breakpoints the configurator's container satisfies, as `Viewport[]`, or `null` before it is measured. It follows the container, not the window, so it is the switch between a desktop and a phone layout. `desktop` is a container wider than 768 pixels and `mobile` one at most 768 pixels wide; `phone` is narrower than 480 and `tablet` between 480 and 1024 pixels; `landscape` and `portrait` follow the browser window's orientation. The built-in layout uses its phone arrangement unless `desktop` is active. |
 
 **Violations**
 
@@ -478,16 +486,61 @@ Texts from the spec, such as option titles and the `detail` fields, are `Localiz
 | `phx.frontend.useStateValidity()`                 | The validity of the last committed state: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'notice' \| 'warning', entityViolations }`. A change that leaves a `fixable` or `fatal` violation is rejected and never committed, and neither is a change during which an error was thrown, so neither is seen here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `phx.frontend.useFinalizeViolations()`            | `{ disabled, hints, violations }`. `disabled` is `true` while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save; `hints` is the violations' text, or `undefined`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `phx.frontend.useConfiguratorMessages(onMessage)` | Nothing. It calls `onMessage(message)` once per message: `{ kind: 'violation', entityId, violation, text }` for each violation of the rejected state, including notices and warnings already present, so `violation.severity` tells the reason for the rejection (`fixable` or `fatal`) from them, `{ kind: 'sideEffect', text }` for each hint of a committed update, and `{ kind: 'error', error, text }` when an error is thrown while a change is validated, with `text` the generic "Oops, something went wrong". `text` is resolved to the current language; a violation's is its `message`, or its `type` without one, and the built-in snackbar prefixes it with `entityId`. Hints committed before the layout mounted are not delivered; when the most recent change was rejected or threw, its messages are delivered again when the hook mounts. `onMessage` may be a new function on every render. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types; from `@salsita-ai/sdk/react` the type is `ConfiguratorMessage`. |
+| `phx.frontend.useFinalizeAction(handler)`         | `{ run, isPending, error, disabled, hints }` for the `finalizeAction` whose `handler` it is given; see the Finalize paragraph below for how to call it. `run()` records the finalize-button click for analytics and runs the project's handler, and does nothing while `disabled` or `isPending`; `error` is what the handler's last run rejected with, or `null`; `disabled` and `hints` are those of `useFinalizeViolations()`. The type of the result is `UseFinalizeActionResult` from `@salsita-ai/sdk/configurator`, which also exports the hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 `LayoutSlots.Services` shows the messages of `useConfiguratorMessages` as snackbars; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
 
 **Finalize**
 
-A project layout finalizes over the spec's `finalizeAction` components. `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`, with `finalizeActionComponent` from `@salsita-ai/sdk/domain`, lists them; each `state` is `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. The built-in footer offers the first `'primary'` action, or else the first action, as its button and the others in a menu, and disables them with `phx.frontend.useFinalizeViolations()`.
+A project layout finalizes over the spec's `finalizeAction` components. `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`, with `finalizeActionComponent` from `@salsita-ai/sdk/domain`, lists them; each `state` is `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. The built-in footer offers the first `'primary'` action, or else the first action, as its button and the others in a menu; a project layout follows the same rule when it offers one action.
+
+Each action gets a component of its own that calls `phx.frontend.useFinalizeAction(action.state.handler)` once, never in a loop or conditionally, because the hook runs the project's handler factory, which calls hooks. The layout wraps that component in `<PhoenixHandlerBoundary name={action.state.handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload. The hook returns:
+
+- `run()`, which records the finalize-button click for analytics and then runs the handler. It does nothing while `disabled` or `isPending`.
+- `isPending`, `true` while the handler runs.
+- `error`, what the handler's last run rejected with, or `null`; a rejection that is not an `Error` is wrapped in one, with the value as its `cause`. It is cleared when the action runs again. No snackbar is raised; the layout shows the error its own way.
+- `disabled` and `hints`, those of `useFinalizeViolations()`: finalizing is not possible while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save, and `hints` says why.
+
+`isPending` and `error` belong to the mounted component: when it unmounts during a run, the handler keeps running, and a component mounted afterwards starts with `isPending` false and no `error`.
+
+```tsx
+import { finalizeActionComponent } from '@salsita-ai/sdk/domain'
+import { PhoenixHandlerBoundary, useResolveLocalizable } from '@salsita-ai/sdk/react'
+
+const FinalizeButton = ({ handler, label }: { handler: string; label: string }) => {
+  const { run, isPending, error, disabled, hints } = phx.frontend.useFinalizeAction(handler)
+
+  return (
+    <div>
+      <button type="button" disabled={disabled || isPending} onClick={run} title={hints}>
+        {isPending ? 'Sending…' : label}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </div>
+  )
+}
+
+export const Finalize = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const resolve = useResolveLocalizable()
+  const actions = phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] }) ?? []
+  const primary = actions.find(action => action.state.variant === 'primary') ?? actions[0]
+
+  if (accessInfo.viewMode || !primary) {
+    return null
+  }
+
+  return (
+    <PhoenixHandlerBoundary name={primary.state.handler}>
+      <FinalizeButton handler={primary.state.handler} label={resolve(primary.state.label)} />
+    </PhoenixHandlerBoundary>
+  )
+}
+```
 
-To offer the same buttons, a project layout mounts `<FinalizeActions />` from `@salsita-ai/sdk/configurator`: the built-in footer's finalize buttons, the primary action plus a menu of the others, disabled with the hints of `useFinalizeViolations()`, with a spinner while the handler runs and a snackbar when it fails. It renders nothing without a `finalizeAction`, and it does not check read mode, so a layout hides it while `accessInfo.viewMode` is `true`.
+The hook does not check read mode, so the layout hides finalizing while `accessInfo.viewMode` is `true`, as above. [Custom Layout](?path=/docs/layouts-custom-layout--docs#request-a-quote) runs a finalize action this way from its review step.
 
-To build its own buttons, a layout runs an action with `usePhoenixHandler(action.state.handler).handler()` from `@salsita-ai/sdk/react`, which returns a promise. `usePhoenixHandler` runs the project's handler factory, which calls hooks, so each action gets its own component that calls it once, never in a loop, and that component is wrapped in `<PhoenixHandlerBoundary name={action.state.handler}>` from the same import, so an edited handler takes effect without a reload. The layout then shows the pending state, the error and the disabled state from `useFinalizeViolations()` itself.
+Instead of its own buttons, a project layout can mount `<FinalizeActions />` from `@salsita-ai/sdk/configurator`: the built-in footer's finalize buttons, the primary action plus a menu of the others, disabled with the hints of `useFinalizeViolations()`, with a spinner while the handler runs and a snackbar when it fails. It renders nothing without a `finalizeAction`, and it does not check read mode either.
 
 ## TransformerBuilder
 

package/dist/docs/phoenix/deployments.mdx

@@ -281,9 +281,7 @@ Phoenix provides two helper functions for reading environment variables with val
 **`createEnvReader`** - General purpose environment reader used in frontend and deployment contexts:
 
 ```typescript
-import { bool, str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { bool, createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 // Create a reader function
 const readEnv = createEnvReader({
@@ -301,9 +299,7 @@ console.log(env.SERVER_URL) // Typed and validated
 
 ```typescript
 // webhooks/webhooks.config.ts
-import { str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 export const readRuntimeConfig = createEnvReader({
   AWS_S3_PUBLIC_RESOURCES_BUCKET: str(),

package/dist/docs/phoenix/domain-model.mdx

@@ -329,6 +329,8 @@ components:
 
 The code generator will automatically create an expression with the same name and infer the return type based on usage context.
 
+The type of an expression must share values with the type every component expects where it is read, and with its declared type. An expression declared as a number and read into a `title`, or one read both into a `title` and into `offsetX`, has no value its implementation could return, so the build reports `EXPRESSION_READ_TYPE_CONFLICT` at the expression and names each place it is read. A type given only as `tsType` is not checked here.
+
 ## Constants
 
 Constants are pre-generated expressions that return fixed values. Under the hood, they are implemented as expressions but are automatically generated by the Phoenix system, so you don't need to write TypeScript implementation code for them.

package/dist/docs/phoenix/finalization.mdx

@@ -15,7 +15,7 @@ Finalization is Phoenix's system for completing configurator sessions and proces
 
 > For integration-specific finalization flows — how host-specific data is passed in and how the host is notified on completion (event dispatch in `headless`, redirect in `handoff`) — see [Finalization (Internal)](?path=/docs/phoenix-integration-finalization-internal--docs) and [Finalization (External)](?path=/docs/phoenix-integration-finalization-external--docs).
 
-The universal sidebar footer offers the spec's `finalizeAction` components: Phoenix selects one primary footer action and places additional finalization actions in its menu. It never opens a `finalizePage`; the `finalizePage` and `finalizeButton` components are legacy, declared only in TypeScript, and used by the basic sidebar footer and the legacy layouts. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior.
+The universal sidebar footer offers the spec's `finalizeAction` components: Phoenix selects one primary footer action and places additional finalization actions in its menu. It never opens a `finalizePage`; the `finalizePage` and `finalizeButton` components are legacy, declared only in TypeScript, and used by the basic sidebar footer and the legacy layouts. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior. A project layout (`ConfiguratorLayout`) offers the same actions with its own buttons through `phx.frontend.useFinalizeAction`, which runs an action's handler and returns its pending state, its error and the disabled state with hints; see the Finalize paragraph of [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
 
 ## How Finalization Works
 

package/dist/docs/phoenix/getting-started.mdx

@@ -26,6 +26,7 @@ The Phoenix CLI (`phoenix` command) is the unified tool for all configurator dev
 - `phoenix dev` - Start the development server with hot reload
 - `phoenix build` - Build the configurator for production
 - `phoenix sync` - Synchronize dependencies and generated code
+- `phoenix deps` - Add the SDK's missing peer dependencies to `package.json` and move out-of-range ones into range
 - `phoenix check` - Validate domain configuration and code
 - `phoenix fix` - Auto-fix common issues in domain files
 
@@ -57,7 +58,7 @@ This section provides practical guidance for developers who are new to Phoenix P
 
 Before diving into Phoenix Platform development, ensure you have:
 
-- **Node.js** and **pnpm** - Required versions are set automatically in the project
+- **Node.js 22.13 or newer** and **pnpm** - The SDK and the Phoenix CLI run on Node.js 22.13 or newer (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)); a project generated by Phoenix pins the exact Node.js and pnpm versions it is developed with
 - **JavaScript/TypeScript** - Phoenix generates TypeScript code and uses modern JavaScript patterns
 - **React** - The platform builds on React components, hooks, and modern React patterns
 - **Three.js** - Basic knowledge of 3D graphics, scenes, cameras, and rendering concepts

package/dist/docs/phoenix/layout-slots.mdx

@@ -27,7 +27,7 @@ export const Toolbar = () => (
 - A slot takes no props unless its row names them, and reads what it shows from the spec and the configurator's state. It renders inside the configurator only, under a `ConfiguratorLayout`.
 - A slot brings its own look but not its place: it adds no padding or scrolling around itself, so the layout puts it in a container. Two members differ: `SharedCanvas` fills its nearest positioned ancestor, and `DesktopSidebar` brings the sidebar's spacing and scrolling with it.
 - Read mode means `useAccessService().accessInfo.viewMode` is `true`: a configuration shared for viewing is open, or the host sets the `readonly` property. "No change" in the read-mode column means the slot renders the same for a viewer, so the layout decides whether a viewer sees it.
-- `Desktop*` and `Mobile*` members are twins that differ in size and arrangement; [Phone layout](#phone-layout) lists the phone ones. The container's width, not the window's, decides which one fits: `useActiveViewports()` from `@salsita-ai/sdk/react` returns the breakpoints the container satisfies.
+- `Desktop*` and `Mobile*` members are twins that differ in size and arrangement; [Phone layout](#phone-layout) lists the phone ones. The container's width, not the window's, decides which one fits: `useActiveViewports()` from `@salsita-ai/sdk/react` returns the breakpoints the container satisfies. The built-in layout uses the `Desktop*` members while `desktop` is active, for a container wider than 768 pixels, and the `Mobile*` members otherwise, while `mobile` is active; `phone` means narrower than 480 pixels and `tablet` between 480 and 1024.
 
 ## Canvas and services
 
@@ -42,7 +42,7 @@ export const Toolbar = () => (
 
 - Mount `SharedCanvas`, not `Canvas`: `Canvas` suspends while it probes the GPU on its first mount, and `SharedCanvas` holds the boundary that catches it. Without either, the app loader stays on screen unless the project sets `appLoader: legacy`.
 - `SharedCanvas` fills its nearest positioned ancestor and paints an opaque background, so the layout positions its own UI after it in the markup.
-- Snackbars are raised by `Services`, and also by the built-in finalize and footer actions when their handler fails and when saving the configuration fails. A layout that shows violations, side-effect hints and validation errors its own way calls `phx.frontend.useConfiguratorMessages(onMessage)` instead of mounting `Services`, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout); the other snackbars still need a root. They render into the snackbar root the layout mounts; with no root mounted they render into the page's `document.body`, outside the configurator. The desktop root is a zero-height element the snackbars stack upwards from, so the layout places it where their bottom edge belongs. The phone root leaves them fixed to the viewport, see `MobileSnackbarsRoot`.
+- Snackbars are raised by `Services`, and also by the built-in finalize and footer actions when their handler fails and when saving the configuration fails. A layout that shows violations, side-effect hints and validation errors its own way calls `phx.frontend.useConfiguratorMessages(onMessage)` instead of mounting `Services`, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout); the other snackbars still need a root. They render into the snackbar root the layout mounts; with no root mounted they render into the page's `document.body`, outside the configurator. The desktop root is a zero-height element the snackbars stack upwards from, so the layout places it where their bottom edge belongs. The phone root leaves them fixed to the viewport, see `MobileSnackbarsRoot`. A finalize action the layout runs with `phx.frontend.useFinalizeAction` raises no snackbar; its error is the hook's `error`.
 
 ## Desktop sidebar
 
@@ -70,6 +70,8 @@ A sidebar footer with `universalSidebarFooter` does not check read mode, althoug
 | `ToolControls`        | The same component as `DesktopToolControls` and `MobileToolControls`                                                         | As `DesktopToolControls`                                                              | Nothing without the component                                                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
 | `DesktopCallToAction` | **The button that leaves a tool mode, not the finalize button.** Clicking it switches to the component's `exitTo` tool state | An `exitToolModeFab` component, usually filtered to the tool states it belongs to     | Nothing. It throws when more than one is active                                                                                                                                                                                                                                                                                                                                                 | Nothing                                                                                                              |
 
+Instead of `DesktopViewControls` or `MobileViewControls`, a layout can build its own view buttons with `phx.frontend.useActiveViewState()` and `phx.frontend.useSetViewState()`, which need no `viewControls` component, see [Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+
 ## Banners and branding
 
 | Member                                 | Shows                                                                                                                                                                                                              | Fed by                                                                                                                                                                                                                       | With nothing configured           | Read mode                                                                                                                     |

package/dist/docs/phoenix/localization.mdx

@@ -408,7 +408,7 @@ function EntityList({ entities }) {
 When you need to do more complex text formatting with placeholders or embedded elements, you can reach for Lingui's `Trans` macro directly:
 
 ```tsx
-import { Trans, msg } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 function WelcomeMessage({ userName, itemCount }) {
   return (
@@ -423,14 +423,14 @@ function WelcomeMessage({ userName, itemCount }) {
 
 ## Server-Side Translations for Webhooks
 
-The localization system isn't just for the frontend — it works in server-side webhook handlers too. PDF and email tasks render React templates with the same `@lingui/macro` toolchain (`<Trans>`, `msg`) you already use in UI components. The task context exposes `ctx.resolveLocalizable` already bound to the request locale and domain fallback chain, and the React builders use it for localizable subjects, attachment filenames, bodies, headers, footers, and watermark text.
+The localization system isn't just for the frontend — it works in server-side webhook handlers too. PDF and email tasks render React templates with the same Lingui macros (`<Trans>` from `@lingui/react/macro`, `msg` from `@lingui/core/macro`) you already use in UI components. The task context exposes `ctx.resolveLocalizable` already bound to the request locale and domain fallback chain, and the React builders use it for localizable subjects, attachment filenames, bodies, headers, footers, and watermark text.
 
 ### In the handler
 
 Use the `msg` template tag for one-off strings you pass into builder methods:
 
 ```tsx
-import { msg } from '@lingui/macro'
+import { msg } from '@lingui/core/macro'
 
 export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources, data, ctx) => {
   return ctx.emailTaskBuilder
@@ -450,7 +450,7 @@ export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources
 Use `<Trans>` for inline strings — exactly as in the frontend — and `<HtmlHelpers.Localized>` to render localizable values pulled from the domain (e.g. `$root.$summary[].title`, which are typed as `MessageDescriptor` or `MultilingualString`):
 
 ```tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { HtmlHelpers } from '@salsita-ai/sdk/webhook'
 
@@ -547,6 +547,8 @@ When you're ready to ship:
 phx build
 ```
 
+With the application-spec pipeline, `phx dev` and `phx build` compile the Lingui macros in your frontend code with the SDK's own Lingui macro plugin and the configuration in `.phoenix/.linguirc`, so the project installs no Babel macro packages for them (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)).
+
 ### Translation Files
 
 The `.po` files in `src/locales/` are standard GNU gettext format that most translation tools support:
@@ -565,7 +567,7 @@ During development, missing translations fall back to the message ID. In product
 
 ### Locale Fallback Configuration
 
-Phoenix automatically configures comprehensive locale fallbacks in the generated `.linguirc` file. When a translation is missing for a specific regional locale, it gracefully falls back to the base language before falling back to the default language (English).
+Phoenix automatically configures comprehensive locale fallbacks in the Lingui configuration it generates. When a translation is missing for a specific regional locale, it gracefully falls back to the base language before falling back to the default language (English).
 
 **Fallback Rules:**
 
@@ -595,7 +597,7 @@ User locale: de-AT (Austrian German)
 └─ Translation in en? → Use it (default fallback)
 ```
 
-The fallback configuration is generated by `phx sync` and stored in `.linguirc`. You don't need to configure this manually - it's handled automatically based on your `availableLocales` in `spec/application.yaml`.
+The fallback configuration is generated by `phx sync` and stored in `.phoenix/.linguirc` (in the project root on the legacy pipeline; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)). You don't need to configure this manually - it's handled automatically based on your `availableLocales` in `spec/application.yaml`.
 
 ## What We Learned
 

package/dist/docs/phoenix/migration-guide.mdx

@@ -251,8 +251,21 @@ rm src/frontend/frontend.tsx
 # Remove empty domain/frontend folders after moving all files
 rmdir src/domain/implementation src/domain/data src/domain
 rmdir src/frontend/systems/transformers src/frontend/systems src/frontend/ui src/frontend/admin-pages src/frontend
+
+# Remove the root TypeScript settings (sync writes the file again)
+rm tsconfig.json
+```
+
+With the application-spec pipeline (`phoenix.applicationFlow` in `package.json`; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the project's TypeScript settings are generated into `.phoenix/tsconfig.json`. Sync writes the root `tsconfig.json` only into a project that has none, as a single line that extends them:
+
+```json
+{ "extends": "./.phoenix/tsconfig.json" }
 ```
 
+A root `tsconfig.json` from the old multi-folder template, or one written by hand, stays as it is and does not pick up the generated settings or the global `phx` types in `.phoenix/globals.d.ts`, so `pnpm ts:check` fails. Delete it, or replace its content with the line above, before the first sync.
+
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), `eslint.config.js` and `prettier.config.js` are the project's. Sync replaces a file earlier SDK versions generated, the one under the "Auto-generated file. Do not modify this file manually." header that re-exports `eslintrc` or `prettierrc`, with a file that re-exports the same configuration from `@salsita-ai/sdk/common/eslint` or `@salsita-ai/sdk/common/prettier`, and writes that file into a project that has none. A file of your own stays as it is, and editors, `phoenix check` and `phoenix fix` use it; make sure it imports only packages the project still depends on, or delete it before the first sync. Without the file, `phoenix check` and `phoenix fix` use the SDK's configuration. The legacy pipeline rewrites both files on every sync.
+
 ### 10. Create Mocks (Optional)
 
 If you have mock files, move them to `mocks/`:
@@ -390,7 +403,7 @@ pnpm install
 
 1. Run type check: `pnpm ts:check`
 2. Update any broken type imports
-3. Ensure `tsconfig.json` paths are correct (auto-generated by Phoenix)
+3. With the application-spec pipeline (`phoenix.applicationFlow`; see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), check that the root `tsconfig.json` is the one-line file that extends `.phoenix/tsconfig.json` (see [step 9](#9-remove-auto-generated-files))
 
 ## Checklist
 
@@ -433,13 +446,13 @@ Use this checklist to verify migration completeness:
 
 The following files are no longer needed - they are auto-generated by the CLI:
 
-| File                        | Replacement                                  |
-| --------------------------- | -------------------------------------------- |
-| `src/domain/domain.ts`      | Auto-generated in `.phoenix/domain.ts`       |
-| `src/frontend/frontend.tsx` | Auto-generated in `.phoenix/configurator.ts` |
-| `tsconfig.json`             | Auto-generated by CLI                        |
-| `eslint.config.js`          | Auto-generated by CLI                        |
-| `prettier.config.js`        | Auto-generated by CLI                        |
+| File                        | Replacement                                                                                                                                                                                                                                                    |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/domain/domain.ts`      | Auto-generated in `.phoenix/domain.ts`                                                                                                                                                                                                                         |
+| `src/frontend/frontend.tsx` | Auto-generated in `.phoenix/configurator.ts`                                                                                                                                                                                                                   |
+| `tsconfig.json`             | Delete before the first sync; with the application-spec pipeline, sync writes a one-line file that extends `.phoenix/tsconfig.json`                                                                                                                            |
+| `eslint.config.js`          | With the application-spec pipeline, sync replaces the file earlier SDK versions generated with one that re-exports the SDK's ESLint configuration, or writes one when there is none; a file of your own stays (see [step 9](#9-remove-auto-generated-files))   |
+| `prettier.config.js`        | With the application-spec pipeline, sync replaces the file earlier SDK versions generated with one that re-exports the SDK's Prettier configuration, or writes one when there is none; a file of your own stays (see [step 9](#9-remove-auto-generated-files)) |
 
 ## Builder Options Moved to YAML
 

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -14,6 +14,8 @@ The Phoenix CLI (`phoenix` command) is the unified tool for all configurator dev
 
 ## Starting a New Project
 
+The SDK and its CLI run on Node.js 22.13 or newer, the range declared in `engines.node` of `@salsita-ai/sdk`. On an older Node.js, `phoenix` stops before it runs a command, names the running version and the required range, and exits with a non-zero code. The legacy binaries run no such check; package managers warn about the range when the SDK is installed.
+
 `phoenix init [folder]` starts a configurator project in `[folder]` (default: the working directory):
 
 ```bash
@@ -135,24 +137,35 @@ The same streams are available in the editor's **Logs** sidebar panel with per-s
 
 ### `phoenix check`
 
-Runs all code quality checks in sequence:
+Runs all code quality checks in sequence, with the TypeScript compiler, ESLint and Prettier the SDK installs as its own dependencies, so the versions in the project's `package.json` do not decide them:
 
-1. **TypeScript** — Type checking with `tsc`
-2. **ESLint** — Linting rules
-3. **Prettier** — Code formatting
+1. **TypeScript** — Type checking with the SDK's `tsc` (TypeScript 7), with the project's root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none (see [Project Structure](?path=/docs/phoenix-project-structure--docs#root-level-files))
+2. **ESLint** — Linting rules, over `src/`; a project with no files there passes. ESLint uses the project's `eslint.config.js`, or the SDK's configuration when the project has none; its type-aware rules then read the same TypeScript configuration as the type check
+3. **Prettier** — Code formatting, with the project's Prettier configuration, or the SDK's when the project has none
 
 ### `phoenix fix`
 
-Auto-fixes ESLint and Prettier issues. Equivalent to running `eslint --fix` and `prettier --write` together.
+Auto-fixes ESLint and Prettier issues, with the same tools and configurations as `phoenix check`. Equivalent to running the SDK's `eslint --fix` and `prettier --write` together.
 
 ## Environment Variables
 
-When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`.
+When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`. `phoenix dev` does the same for its development deployment when it starts.
+
+### The generated env file
+
+A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoenix/.env.generated`, unless the project has a `.env.generated` in its root, which then is the one that counts.
+
+- `phoenix dev` reads and writes `.phoenix/.env.generated` in a project without a root `.env.generated`, and creates no file in the project root. In a project that has a root `.env.generated`, it reads and writes that file and `.phoenix/.env.generated` is not used.
+- The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
+- Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
+- `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+
+This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix dev` always reads and writes `.env.generated` in the project root.
 
 ### Data Flow
 
 ```
-spec/application.yaml → Server prepares environment → CLI writes .env.generated → Frontend/Webhooks read it
+spec/application.yaml → Server prepares environment → CLI writes the generated env file → Frontend/Webhooks read it
 ```
 
 ### Project Scripts
@@ -173,7 +186,7 @@ A project may have other scripts than these five, such as `sync`, `test` or `ver
 
 ### Server-Generated Variables
 
-These are automatically computed by the server and written to `.env.generated`:
+These are automatically computed by the server and written to the generated env file:
 
 | Variable                         | Purpose                                                 |
 | -------------------------------- | ------------------------------------------------------- |
@@ -261,7 +274,7 @@ A development environment keeps the AI assistant's conversation when the assista
 Environment variables are resolved in this order (highest to lowest priority):
 
 1. Process environment variables (shell)
-2. `.env.generated` (created by deployment commands)
+2. [The generated env file](#the-generated-env-file): `.env.generated` in the project root when the project has one, otherwise `.phoenix/.env.generated`
 3. `.env` (manual overrides)
 
 ### Generated Config Files
@@ -292,13 +305,18 @@ Starts the full development environment: Vite dev server, development webhook tu
 | `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
 | `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
+With the application-spec pipeline, `phoenix dev` creates an empty `src/` folder when the project has none, so that it rebuilds when the first source file, such as `src/webhooks/index.ts`, is added.
+
+With the application-spec pipeline, the SDK's own Lingui CLI runs with the configuration in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
+
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
 The dev server watches for changes in:
 
 - `spec/**/*.yaml` — Domain specification files
 - `src/**/*.{ts,tsx,yaml,yml,json,html,css}` — Source files
-- `.env`, `.env.generated` — Environment files (triggers full Vite restart)
+- `.env` — Environment file; a change restarts the Vite dev server
+- `.env.generated`, `.phoenix/.env.generated` — Generated env files; a change rebuilds the project files. Only a file that exists when `phoenix dev` starts is watched: a root `.env.generated` that a deployment command creates while dev runs is not watched; restart `phoenix dev` to use it.
 
 When linked SDK packages are detected (`phoenix link`), changes to SDK dist files are also watched.
 
@@ -396,6 +414,24 @@ With the application-spec pipeline (see [Current and legacy project tooling](#cu
 | ---------------- | --------------- | ------- | ------------------------------ |
 | `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
 
+### `phoenix deps`
+
+Brings `package.json` in line with the SDK's peer dependencies: the packages the SDK's code imports and the project installs next to it, so the project and the SDK share one copy. The `peerDependencies` of the installed `@salsita-ai/sdk` decide which packages and which versions. `@clerk/clerk-react` is needed only when the spec sets `useClerk`.
+
+```bash
+pnpm phoenix deps
+pnpm install
+```
+
+- A missing peer is added at the lowest version of the SDK's range, as an exact version, in alphabetical order: type packages (`@types/*`) to `devDependencies`, the others to `dependencies`.
+- A peer declared with a version range whose lowest version falls outside the SDK's range is set to the lowest version of the SDK's range, in the field that declares it. The output says when that is a downgrade.
+- A peer declared with a specifier that is not a version range, such as `workspace:`, `npm:`, `catalog:`, `file:`, `link:` or a git URL, stays as it is.
+- `@salsita-ai/common`, `@salsita-ai/contracts`, `@salsita-ai/platform-project-sdk`, `@salsita-ai/platform-common` and `@salsita-ai/platform-contracts` are removed, because `@salsita-ai/sdk` replaces them. No other entry is removed.
+
+Every other part of `package.json` keeps its order and formatting. `phoenix deps` installs nothing: it lists each change and names `pnpm install` as the next step, or says that nothing needed to change. Running it again changes nothing. It reads the spec to learn whether the project uses Clerk, so it stops with the spec's errors when the spec does not parse.
+
+This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix deps` changes nothing and says that `phoenix sync` manages the dependencies.
+
 ### Current and legacy project tooling
 
 Use the `phoenix` binary for projects that still use domain-spec generation. The CLI selects a