@salsita-ai/sdk 0.50.0-develop.9db1e1f3bf → 0.50.0-develop.9eab66c5a9

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.
@@ -840,7 +842,10 @@ Phoenix automatically:
 During `phoenix dev`, schema-compatible configurator changes can refresh the mounted application in
 place. Changes to the domain model itself are rejected from live application and require a restart;
 this preserves the last valid runtime and loaded configuration until migration and deployment can be
-coordinated atomically.
+coordinated atomically. With server persistence, restart `phoenix dev` itself: it logs an error that
+asks for the restart, and registers the changed model with its development deployment when it starts
+again. Then open the preview address it prints rather than a tab whose address has `?cid=`, which
+loads a configuration saved with the earlier model.
 
 ### The phx Global Namespace
 

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.useFinalizeActions`, which lists them with the primary one picked as the footer picks it, each with its own `run`, pending state, error and disabled state, or through `phx.frontend.useFinalizeAction`, which runs one known action's handler and returns the same 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

@@ -22,10 +22,11 @@ The frontend SDK provides the core libraries and components for building configu
 
 The Phoenix CLI (`phoenix` command) is the unified tool for all configurator development. It combines domain code generation, webhook building, deployment management, and development workflows into a single interface:
 
-- `phoenix init` - Start a new project with a working starter spec
+- `phoenix init` - Start a new project: a working starter spec and a `package.json` with the SDK, the packages it requires next to it, ESLint and Prettier
 - `phoenix dev` - Start the development server with hot reload
 - `phoenix build` - Build the configurator for production
-- `phoenix sync` - Synchronize dependencies and generated code
+- `phoenix sync` - Regenerate the generated code and project files
+- `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,12 +58,14 @@ 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 **a package manager** - 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 installs with any package manager; with pnpm 11 it needs the settings in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager)
 - **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
 - **React Three Fiber** - Understanding of declarative 3D development and R3F component patterns
 
+The commands in this documentation use pnpm, as in `pnpm phoenix sync`. They work the same through any other package manager: `npx phoenix sync` with npm, `yarn phoenix sync` with Yarn, `bunx phoenix sync` with Bun.
+
 We assume you have working knowledge of these technologies before starting with Phoenix Platform. If you're new to any of these areas, we recommend familiarizing yourself with them first, as Phoenix Platform builds directly on these foundations.
 
 ### Your First Steps

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

@@ -26,36 +26,36 @@ 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.
+- Read mode means `phx.frontend.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: `phx.frontend.useActiveViewports()`, also exported 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
 
-| Member                 | Shows                                                                                                                                                                                                                                                                                                                        | Fed by                                                        | With nothing configured | Read mode |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------- | --------- |
-| `SharedCanvas`         | The 3D scene, in a container that is `position: absolute; inset: 0` with the scene's background colour. The scene is hidden for a moment while the preview expands or collapses.                                                                                                                                             | The scene of the spec, through `Canvas`                       | Always renders          | No change |
-| `Canvas`               | The WebGL canvas alone, or `GPUIssuePage` when the browser has no WebGL or no GPU acceleration. It reports the scene-assets loading phase the app loader waits for.                                                                                                                                                          | The scene, the canvas settings and the `CanvasLoader` element | Always renders          | No change |
-| `Services`             | Nothing visible: it mounts `InvariantViolations` and `SideEffects`, which show the messages of `useConfiguratorMessages()` as snackbars                                                                                                                                                                                      | The configurator's state                                      | Always mounted          | No change |
-| `InvariantViolations`  | When a change is rejected, a snackbar for each violation of the rejected state, including notices and warnings already present, as `<entity id>: <message>` (a `notice` as info, a `warning` as warning, `fixable` and `fatal` as error), and "Oops, something went wrong" for an error thrown while the state was validated | The spec's invariants                                         | Nothing                 | No change |
-| `SideEffects`          | An info snackbar for each committed update that carries a hint                                                                                                                                                                                                                                                               | The hints of committed updates                                | Nothing                 | No change |
-| `DesktopSnackbarsRoot` | The element the snackbars are rendered into: a stack anchored to its bottom edge, at most 320 pixels wide                                                                                                                                                                                                                    | Every snackbar the configurator raises                        | An empty element        | No change |
+| Member                 | Shows                                                                                                                                                                                                                                                                                                                        | Fed by                                                        | With nothing configured | Read mode                                                                                                            |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `SharedCanvas`         | The 3D scene, in a container that is `position: absolute; inset: 0` with the scene's background colour. The scene is hidden for a moment while the preview expands or collapses.                                                                                                                                             | The scene of the spec, through `Canvas`                       | Always renders          | No change                                                                                                            |
+| `Canvas`               | The WebGL canvas alone, or `GPUIssuePage` when the browser has no WebGL or no GPU acceleration. It reports the scene-assets loading phase the app loader waits for.                                                                                                                                                          | The scene, the canvas settings and the `CanvasLoader` element | Always renders          | No change                                                                                                            |
+| `Services`             | Nothing visible: it mounts `InvariantViolations` and `SideEffects`, which show the messages of `useConfiguratorMessages()` as snackbars, and shows a failed save of the configuration as a persistent error snackbar with **Dismiss**, followed by "Configuration updated" when a later save succeeds                        | The configurator's state                                      | Always mounted          | No change; the save-failure and "Configuration updated" snackbars are not shown, and one left from owner mode closes |
+| `InvariantViolations`  | When a change is rejected, a snackbar for each violation of the rejected state, including notices and warnings already present, as `<entity id>: <message>` (a `notice` as info, a `warning` as warning, `fixable` and `fatal` as error), and "Oops, something went wrong" for an error thrown while the state was validated | The spec's invariants                                         | Nothing                 | No change                                                                                                            |
+| `SideEffects`          | An info snackbar for each committed update that carries a hint                                                                                                                                                                                                                                                               | The hints of committed updates                                | Nothing                 | No change                                                                                                            |
+| `DesktopSnackbarsRoot` | The element the snackbars are rendered into: a stack anchored to its bottom edge, at most 320 pixels wide                                                                                                                                                                                                                    | Every snackbar the configurator raises                        | An empty element        | No change                                                                                                            |
 
-- 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`.
+- Mount `SharedCanvas`, not `Canvas`: `Canvas` suspends while it probes the GPU on its first mount, and `SharedCanvas` holds the boundary that catches it. `SharedCanvas` also tells the app loader to wait for the scene from the moment it mounts; `Canvas` alone does so only once the probe is done, so the loader can leave and come back. A layout with neither is not held by the loader for a scene.
 - `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`, for violations, side-effect hints, validation errors and a failed save, and also by the built-in finalize and footer actions when their handler fails. A layout that shows these messages its own way calls `phx.frontend.useConfiguratorMessages(onMessage)` instead of mounting `Services`, and then shows the failed save too, 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.useFinalizeActions` or `phx.frontend.useFinalizeAction` raises no snackbar; its error is the action's `error`.
 
 ## Desktop sidebar
 
-| Member                        | Shows                                                                                                                                                                                                                                                                                            | Fed by                                                                                                                                                                                                                                                                                                     | With nothing configured                                                                                                                                                                                                                                                                                                          | Read mode                                                                                                                                                                                                  |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DesktopSidebar`              | The whole built-in desktop sidebar: tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Props: `width`, and `side` (`'start'` or `'end'`, typed `DesktopSidebarSide`; `DesktopSidebarProps` types both)                | The members below                                                                                                                                                                                                                                                                                          | As its parts                                                                                                                                                                                                                                                                                                                     | As its parts. In fullscreen it stays in place, transparent and inert                                                                                                                                       |
-| `DesktopSidebarTabs`          | Tabs that switch the navigation state                                                                                                                                                                                                                                                            | The `sidebarTabs` components of the selected entity; the `horizontalTabs` component is not shown here                                                                                                                                                                                                      | Nothing; also nothing while the summary is shown                                                                                                                                                                                                                                                                                 | No change                                                                                                                                                                                                  |
-| `useSidebarTabs()`            | A hook, `{ tabs, activeTab, onChange }`: each tab is `{ label, icon, value, isActive }`, `activeTab` is the active tab's value or `'none'`, and `onChange(value)` switches to that tab's first navigation state                                                                                  | As `DesktopSidebarTabs`                                                                                                                                                                                                                                                                                    | `tabs` is empty                                                                                                                                                                                                                                                                                                                  | No change                                                                                                                                                                                                  |
-| `DesktopSidebarBackButton`    | A "Back" button. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxDesktopSidebarBackButton`; the application config's `sidebarBackIcon` takes precedence over both                                                                                                    | The sidebar's way back: a navigation state to pop, a stacked property page, or a selected entity other than the root, unless the application config sets `showSelectionBackButton` to `false` or sets `ignoreSelectionInSidebar`                                                                           | Nothing while there is no way back                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
-| `DesktopSidebarContent`       | The property pages of the selected entity with its entity header, a stacked page opened from them, or the summary page while the summary is shown. With the application config's `ignoreSelectionInSidebar` set, every `propertyPage` of every entity shows under the root, whatever is selected | `propertyPage`, `entityHeader`, `simpleSummary` and `customSummaryPage` components, and `ignoreSelectionInSidebar`                                                                                                                                                                                         | Nothing                                                                                                                                                                                                                                                                                                                          | **No change: the controls stay editable.** Limit them with `$filter.modes`, or render something else in read mode                                                                                          |
-| `useSidebarContent(options?)` | A hook, `{ content, goBack, hasMiniSidebar, hasSplitSidebar }`: `content` is what `DesktopSidebarContent` shows, `goBack` is the back action or `null`. `options` sets the `HeaderContainer` and `BodyContainer` components the content is wrapped in                                            | As `DesktopSidebarContent`                                                                                                                                                                                                                                                                                 | `content` is empty                                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
-| `EntityHeader`                | An entity's title, subtitle, description and thumbnail, with its primary and secondary buttons, such as delete or replace. Props, typed `EntityHeaderProps`: `entityId` and `headerComponent`                                                                                                    | The texts and thumbnail from the entity's `detail` component (the title falls back to the entity type); the buttons from the `entityHeader` component passed in                                                                                                                                            | —                                                                                                                                                                                                                                                                                                                                | No change                                                                                                                                                                                                  |
-| `DesktopSidebarFooter`        | The price and the actions                                                                                                                                                                                                                                                                        | `basicSidebarFooter`, `universalSidebarFooter`, `readSidebarFooter`, `hiddenSidebarFooter` or `customSidebarFooter`. The basic footer offers a `finalizeButton`, else a button for a `finalizePage`, else a disabled button; the universal footer offers the `finalizeAction` and `otherAction` components | The basic footer: the price and a finalize button. With a `navigationSteps` component of two or more steps, previous and next step buttons and the finalize button only on the last step; with a summary and no steps, a **Summary** button until the summary is shown; in a preset embed, **Save Template** instead of finalize | With nothing configured, the read footer: price only. The basic footer hides its buttons. **The universal footer still shows its finalize and other actions to a viewer**; limit them with `$filter.modes` |
+| Member                        | Shows                                                                                                                                                                                                                                                                                                                                                                                                                                   | Fed by                                                                                                                                                                                                                                                                                                     | With nothing configured                                                                                                                                                                                                                                                                                                          | Read mode                                                                                                                                                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DesktopSidebar`              | The whole built-in desktop sidebar: tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Props: `width`, and `side` (`'start'` or `'end'`, typed `DesktopSidebarSide`; `DesktopSidebarProps` types both)                                                                                                                                                       | The members below                                                                                                                                                                                                                                                                                          | As its parts                                                                                                                                                                                                                                                                                                                     | As its parts. In fullscreen it stays in place, transparent and inert                                                                                                                                       |
+| `DesktopSidebarTabs`          | Tabs that switch the navigation state                                                                                                                                                                                                                                                                                                                                                                                                   | The `sidebarTabs` components of the selected entity; the `horizontalTabs` component is not shown here                                                                                                                                                                                                      | Nothing; also nothing while the summary is shown                                                                                                                                                                                                                                                                                 | No change                                                                                                                                                                                                  |
+| `useSidebarTabs()`            | A hook, `{ tabs, activeTab, onChange }`: each tab is `{ label, icon, value, isActive }`, `activeTab` is the active tab's value or `'none'`, and `onChange(value)` switches to that tab's first navigation state. A project layout reads its tabs with `phx.frontend.useTabNavigation()` instead, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout) | As `DesktopSidebarTabs`                                                                                                                                                                                                                                                                                    | `tabs` is empty                                                                                                                                                                                                                                                                                                                  | No change                                                                                                                                                                                                  |
+| `DesktopSidebarBackButton`    | A "Back" button. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxDesktopSidebarBackButton`; the application config's `sidebarBackIcon` takes precedence over both                                                                                                                                                                                                                                           | The sidebar's way back: a navigation state to pop, a stacked property page, or a selected entity other than the root, unless the application config sets `showSelectionBackButton` to `false` or sets `ignoreSelectionInSidebar`                                                                           | Nothing while there is no way back                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
+| `DesktopSidebarContent`       | The property pages of the selected entity with its entity header, a stacked page opened from them, or the summary page while the summary is shown. With the application config's `ignoreSelectionInSidebar` set, every `propertyPage` of every entity shows under the root, whatever is selected                                                                                                                                        | `propertyPage`, `entityHeader`, `simpleSummary` and `customSummaryPage` components, and `ignoreSelectionInSidebar`                                                                                                                                                                                         | Nothing                                                                                                                                                                                                                                                                                                                          | **No change: the controls stay editable.** Limit them with `$filter.modes`, or render something else in read mode                                                                                          |
+| `useSidebarContent(options?)` | A hook, `{ content, goBack, hasMiniSidebar, hasSplitSidebar }`: `content` is what `DesktopSidebarContent` shows, `goBack` is the back action or `null`. `options` sets the `HeaderContainer` and `BodyContainer` components the content is wrapped in                                                                                                                                                                                   | As `DesktopSidebarContent`                                                                                                                                                                                                                                                                                 | `content` is empty                                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
+| `EntityHeader`                | An entity's title, subtitle, description and thumbnail, with its primary and secondary buttons, such as delete or replace. Props, typed `EntityHeaderProps`: `entityId` and `headerComponent`                                                                                                                                                                                                                                           | The texts and thumbnail from the entity's `detail` component (the title falls back to the entity type); the buttons from the `entityHeader` component passed in                                                                                                                                            | —                                                                                                                                                                                                                                                                                                                                | No change                                                                                                                                                                                                  |
+| `DesktopSidebarFooter`        | The price and the actions                                                                                                                                                                                                                                                                                                                                                                                                               | `basicSidebarFooter`, `universalSidebarFooter`, `readSidebarFooter`, `hiddenSidebarFooter` or `customSidebarFooter`. The basic footer offers a `finalizeButton`, else a button for a `finalizePage`, else a disabled button; the universal footer offers the `finalizeAction` and `otherAction` components | The basic footer: the price and a finalize button. With a `navigationSteps` component of two or more steps, previous and next step buttons and the finalize button only on the last step; with a summary and no steps, a **Summary** button until the summary is shown; in a preset embed, **Save Template** instead of finalize | With nothing configured, the read footer: price only. The basic footer hides its buttons. **The universal footer still shows its finalize and other actions to a viewer**; limit them with `$filter.modes` |
 
 A sidebar footer with `universalSidebarFooter` does not check read mode, although the component's own description says its buttons are hidden then. A viewer of a shared configuration sees its actions. The `custom` footer renders its children unchanged as well.
 
@@ -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                                                                                                                     |
@@ -77,7 +79,7 @@ A sidebar footer with `universalSidebarFooter` does not check read mode, althoug
 | `DesktopReadonlyBanner`                | "You're viewing a read-only configuration" with an **Edit configuration** button that opens `CloneToEditDialog`. Props: the MUI `Alert` props and `icon`, also settable in the theme as `PhxDesktopReadonlyBanner` | `useIsCloningAllowed()`; its icon from the application config's `readonlyBannerIcon`                                                                                                                                         | Nothing unless cloning is allowed | **It does not check read mode.** The layout renders it only in read mode, as the built-in layout does while not in fullscreen |
 | `MobileReadonlyBanner`                 | An **Edit** button that opens `CloneToEditDialog`. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxMobileReadonlyBanner`                                                               | As `DesktopReadonlyBanner`                                                                                                                                                                                                   | Nothing unless cloning is allowed | As `DesktopReadonlyBanner`                                                                                                    |
 | `CloneToEditDialog`                    | The "Edit configuration" dialog that creates an editable copy of the configuration and opens it. Props, typed `CloneToEditDialogProps`: `open` and `onClose`                                                       | The open configuration                                                                                                                                                                                                       | —                                 | —                                                                                                                             |
-| `useIsCloningAllowed()`                | A hook, `boolean`: `true` when the application config sets `shareCloneToEdit` and the session's role may create configurations                                                                                     | The application config and the session                                                                                                                                                                                       | `false`                           | Does not check read mode                                                                                                      |
+| `useIsCloningAllowed()`                | A hook, also `phx.frontend.useIsCloningAllowed()`, returning a `boolean`: `true` when the application config sets `shareCloneToEdit` and the session's role may create configurations                              | The application config and the session                                                                                                                                                                                       | `false`                           | Does not check read mode                                                                                                      |
 | `DesktopPoweredBy` / `MobilePoweredBy` | The "Powered by Salsita" mark, a link                                                                                                                                                                              | Its props `visible`, `variant` (`'black'` or `'white'`), `href`, `title`, `slots` and `slotProps`. All but `href` and `title` are also settable in the theme as `PhxDesktopBrandingPoweredBy` / `PhxMobileBrandingPoweredBy` | The mark                          | No change                                                                                                                     |
 
 ## Page footer

package/dist/docs/phoenix/localization.mdx

@@ -152,6 +152,8 @@ entities:
 
 This is the way to go when you're dealing with content that might evolve over time. The message ID stays the same, so your existing translations remain valid even when you tweak the wording. Plus, you can use dot notation to create nice, organized namespaces for your translations.
 
+A `$msg` compiles to a message descriptor. When an expression that holds one also declares a schema, the schema has to accept a message descriptor, such as `$ref: 'phx:Localizable'` or `$ref: 'phx:MessageDescriptor'`; a `$msg` declared as `type: string` or `type: number` is reported as `EXPRESSION_VALUE_TYPE_MISMATCH`.
+
 You can use both approaches throughout your domain specifications. Here are some common patterns that work well:
 
 ```yaml
@@ -408,7 +410,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 +425,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 +452,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 +549,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 +569,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 +599,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/`:
@@ -279,7 +292,7 @@ This will:
 
 Other useful commands:
 
-- `pnpm phoenix sync` - Sync dependencies in package.json
+- `pnpm phoenix sync` - Regenerate the generated code and project files
 - `pnpm phoenix gen` - Regenerate project files
 - `pnpm phoenix dev` - Start development server with hot reload
 - `pnpm phoenix deployment:prepare` - Prepare for deployment
@@ -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
 
@@ -427,19 +440,19 @@ Use this checklist to verify migration completeness:
 - [ ] Configurator renders correctly
 - [ ] Admin interface works
 - [ ] All imports updated to new paths
-- [ ] Node 24 and pnpm v10 installed
+- [ ] Node 24 and a package manager installed
 
 ## Removed Files
 
 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
 
@@ -473,7 +486,7 @@ Update imports to use these globals instead of importing from packages directly.
 ## Environment Requirements
 
 - Node 24
-- pnpm v10
+- A package manager; the commands in this guide use pnpm
 - `RESOURCES_URL` is an optional frontend environment variable; in local development it defaults to the Vite dev server at `http://localhost:5173`
 
 ## Next Steps