@salsita-ai/sdk 0.50.0-develop.a49722158a → 0.50.0-develop.a8cf9ffd01

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

@@ -26,36 +26,57 @@ 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. A finalize action the layout runs with `phx.frontend.useFinalizeAction` raises no snackbar; its error is the hook's `error`. 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`.
+
+### Styling the snackbars
+
+Every snackbar of the configurator and the admin, raised by `Services`, a failed save, a failed preset creation or a built-in action, renders as `PhxSnackbar` from `@salsita-ai/sdk/ui`: an MUI `Alert` with the snackbar's variant as its severity, inside notistack's `SnackbarContent`. A project restyles the configurator's snackbars in its theme, from [`createGetThemeHandler`](?path=/docs/layouts-custom-theme-handler--docs), under `components.PhxSnackbar` (the admin's snackbars follow the admin's own theme, which ignores the theme handler):
+
+```ts
+// Part of the ThemeOptions a theme handler returns
+const components: ThemeOptions['components'] = {
+  PhxSnackbar: {
+    styleOverrides: {
+      alert: ({ theme }) => ({ borderRadius: 0, boxShadow: theme.shadows[3] }),
+      actionButton: { fontWeight: 600, textTransform: 'none' },
+    },
+  },
+}
+```
+
+- `styleOverrides` styles three slots: `content`, notistack's outer element; `alert`, the `Alert` with the message; and `actionButton`, a button such as **Dismiss**.
+- `defaultProps.slotProps` passes props to the slots, such as `{ alert: { variant: 'filled' } }`, and `defaultProps.slots` replaces a slot's component. The `MuiAlert` and `MuiButton` overrides of the theme reach the snackbars too.
+- A snackbar's button is described as data, not as an element: the code that raises it passes `actionButton: { label, onClick }` to notistack's `enqueueSnackbar`, and `PhxSnackbar` renders it in the `actionButton` slot, an MUI `Button` with `color="inherit"` and `size="small"`, after the snackbar's notistack `action` if it has one. `onClick` receives the snackbar's key, to close it with `closeSnackbar`. A project's own snackbars take the same option, typed by `SnackbarActionButton` from `@salsita-ai/sdk/react`, so their buttons follow the theme; an element passed as `action` renders as it is.
+- Where the snackbars appear is the snackbar root's job, see `DesktopSnackbarsRoot` and `MobileSnackbarsRoot`.
 
 ## 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 +91,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 +100,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

@@ -19,13 +19,13 @@ Phoenix provides a localization system built on **Lingui** that enables multi-la
 
 The localization architecture has two layers that work together automatically. **SDK translations** provide the built-in platform UI components, error messages, and system text. **Project catalogs** contain your domain-specific translations for entities, validation messages, and custom UI components.
 
-These translation sources merge automatically at runtime. The system uses lazy loading where translation catalogs compile to TypeScript modules and load only when needed.
+These translation sources merge automatically at runtime. The translation catalogs compile to TypeScript modules that are bundled with the application.
 
 The translation workflow follows a clear pattern: Lingui extracts translatable strings from your code using `msg()` macros and `$msg` syntax, translators work with standard `.po` files for each language, those files compile into TypeScript modules for your application, and the SDK and project catalogs merge into a unified translation system during initialization.
 
 ## Getting Your Project Set Up
 
-Phoenix uses the **phx-cli** to automatically manage localization setup. When you configure `availableLocales` in your `spec/application.yaml`, the CLI creates and maintains the necessary i18n structure.
+The Phoenix CLI manages the localization setup. When you list the project's languages in the top-level `availableLocales` key of a spec file, such as `spec/application.yaml`, the CLI creates and maintains the necessary i18n structure.
 
 ### Enabling Localization
 
@@ -39,7 +39,7 @@ availableLocales:
   - cs
 ```
 
-Running `phx sync` automatically creates the i18n directory structure:
+Running `pnpm phoenix sync` creates the i18n directory structure:
 
 ```
 project-root/
@@ -57,68 +57,79 @@ project-root/
 ├── spec/
 │   └── application.yaml           # Contains availableLocales
 ├── .phoenix/
-│   ├── .lingui/                   # Compiled i18n catalogs
-│   └── i18n.ts                    # Auto-generated i18n initialization
+│   ├── .linguirc                  # Generated Lingui configuration
+│   └── domain-spec.ts             # Generated code that loads and merges the catalogs
 └── package.json
 ```
 
 **Key directories:**
 
-- `src/locales/<lang>/` - Auto-generated `.po` files for translators, compiled `.ts` files
-- `.phoenix/i18n.ts` - Auto-generated i18n initialization with catalog merging
+- `src/locales/<lang>/` - Generated `.po` files for translators, compiled `.ts` files
+- `.phoenix/domain-spec.ts` - Generated code that imports each locale's compiled catalog and merges it with the SDK's
 
-### Auto-Generated i18n Initialization
+### Generated i18n Initialization
 
-The `.phoenix/i18n.ts` file is auto-generated and handles catalog merging automatically:
+The generated `.phoenix/domain-spec.ts` imports the compiled catalog of every locale in `availableLocales` and merges it with the SDK catalog:
 
 ```typescript
-// .phoenix/i18n.ts (AUTO-GENERATED - DO NOT EDIT)
-import { mergeCatalogs, sdkCatalog } from '@salsita-ai/sdk/i18n'
-
+// .phoenix/domain-spec.ts (excerpt, generated - do not edit)
 import { messages as cs } from '../src/locales/cs/messages.js'
 import { messages as de } from '../src/locales/de/messages.js'
 import { messages as en } from '../src/locales/en/messages.js'
 
-export const catalog = { en, de, cs }
-export const availableLocales = Object.keys(catalog) as Array<keyof typeof catalog>
+const catalog = {
+  en,
+  de,
+  cs,
+}
+// Merges SDK and project catalogs, keeping only the project's locales
+const messages = mergeCatalogs([sdkCatalog, catalog], Object.keys(catalog))
+
+export const createI18n = () => setupI18n({ messages, locale: 'en' })
+```
 
-// Automatically merges SDK and project catalogs
-const messages = mergeCatalogs([sdkCatalog, catalog])
+### Choosing the Language
 
-export const createI18n = () =>
-  setupI18n({
-    messages,
-    locale: 'en',
-  })
+`availableLocales` decides which catalogs the project compiles and ships. The language the configurator shows is chosen separately:
+
+- **Starting language.** The configurator starts in the host's `locale` property (the `locale` attribute of the web component), `en` by default. When it is not in `availableLocales`, the configurator falls back to one that is, as described in [Locale Fallback Configuration](#locale-fallback-configuration).
+- **Language switch.** The toolbar's language button and the menu's language action offer the locales in `applicationConfig.availableLocales` on the root entity (`['en']` without it). Keep that list within the top-level `availableLocales`: picking a locale outside it activates the locale it falls back to, as a starting language does, not the picked one. A project layout builds its own switch with `phx.frontend.useLocaleSwitch()`, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+
+```yaml
+components:
+  Product: # the root entity type
+    applicationConfig:
+      default:
+        availableLocales:
+          - en
+          - de
+          - cs
 ```
 
 ### Overriding SDK Translations
 
 You can customize or override any SDK translation by adding the same message ID to your project's `.po` files. The `mergeCatalogs` function prioritizes project translations over SDK translations when merging.
 
-For example, to customize the finalize button text, add this to your `locales/en/messages.po`:
+The SDK's message IDs start with `sdk.`. For example, to customize the finalize button text and the save-template button, add this to your `src/locales/en/messages.po`:
 
 ```po
-#: src/configurator/ui/finalize/FinalizeButton.tsx:42
-#: src/configurator/ui/finalize/FinalizeButton.tsx:56
-msgid "Finalize"
+msgid "sdk.layout.sidebar.finalizePage.label"
 msgstr "Complete Order"
 
-#: src/configurator/ui/controls/save-configuration/SaveConfigurationButton.tsx:23
-msgid "Save Configuration"
+msgid "sdk.layout.button.saveTemplate.label"
 msgstr "Save My Design"
 ```
 
-After running `pnpm lingui:compile`, your custom translations will override the default SDK translations. This allows you to:
+Once the catalogs are compiled again, by `pnpm phoenix sync`, `pnpm phoenix build` or `pnpm phoenix dev --withLingui`, your custom translations override the default SDK translations. This allows you to:
 
 - Customize terminology to match your brand
 - Provide more context-specific wording
 - Adapt translations for your target audience
 - Maintain consistency with your existing product language
 
-**Frontend integration**: the generated `.phoenix` code creates the i18n service from `.phoenix/i18n.ts` and registers
-it with the application, so there is nothing to wire by hand. The languages come from `availableLocales` in
-`spec/application.yaml`.
+**Frontend integration**: the generated `.phoenix` code creates the i18n service from the catalogs in
+`.phoenix/domain-spec.ts` and registers it with the application, so there is nothing to wire by hand. The catalogs come
+from the top-level `availableLocales`.
 
 ## Working with YAML Domain Specifications
 
@@ -152,6 +163,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
@@ -241,12 +254,11 @@ Admin users can switch between different languages to input translations for eac
 
 ```typescript
 import { Stack } from '@mui/material'
-import type { AdminModel } from 'project-domain'
 
 import { LanguageSwitcher, MultilingualTextValueInput, TextValueInput } from '@salsita-ai/sdk/react'
 import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
-export const MaterialSidebar = (props: { id: AdminModel.Material['id'] }) => {
+export const MaterialSidebar = (props: { id: Phx['AdminModel']['Material']['id'] }) => {
   const { id } = props
 
   return (
@@ -327,11 +339,11 @@ publishedData: {
 
 ### Configurator Consumption
 
-In your configurator, use the `resolveLocalizable` function or `useLocalizable` hook to display the appropriate language:
+In your configurator, use the `phx.frontend.useLocalizable` hook or the resolver from `phx.frontend.useResolveLocalizable()` to display the appropriate language:
 
 ```typescript
 // In expressions
-const customExpressions = implementCustomExpressions({
+const customExpressions = phx.domain.implementCustomExpressions({
   Product: {
     $materialName: (product, state, ctx) => {
       const material = ctx.publishedData.materials.find(m => m.id === product.materialId)
@@ -342,7 +354,7 @@ const customExpressions = implementCustomExpressions({
 
 // In React components
 function MaterialDisplay({ materialData }) {
-  const name = useLocalizable(materialData.name)
+  const name = phx.frontend.useLocalizable(materialData.name)
   return <span>{name}</span>
 }
 ```
@@ -367,13 +379,11 @@ function ProductHeader({ product }) {
 }
 ```
 
-Sometimes you need the actual translated string for use in component logic or HTML attributes, rather than rendering it directly. That's where the `useLocalizable` hook comes in handy:
+Sometimes you need the actual translated string for use in component logic or HTML attributes, rather than rendering it directly. That's where the `phx.frontend.useLocalizable` hook comes in handy:
 
 ```tsx
-import { useLocalizable } from '@salsita-ai/sdk/react'
-
 function ValidationMessage({ invariant }) {
-  const message = useLocalizable(invariant.message)
+  const message = phx.frontend.useLocalizable(invariant.message)
 
   return (
     <div className="error" title={message}>
@@ -383,13 +393,13 @@ function ValidationMessage({ invariant }) {
 }
 ```
 
-For more complex scenarios where you need to resolve translations dynamically (like when sorting lists by translated names), there's `useResolveLocalizable`. This gives you a resolver function that you can use however you need:
+For more complex scenarios where you need to resolve translations dynamically (like when sorting lists by translated names), there's `phx.frontend.useResolveLocalizable`. This gives you a resolver function that you can use however you need:
 
 ```tsx
-import { useResolveLocalizable } from '@salsita-ai/sdk/react'
+import { LocalizableMessage } from '@salsita-ai/sdk/react'
 
 function EntityList({ entities }) {
-  const resolve = useResolveLocalizable()
+  const resolve = phx.frontend.useResolveLocalizable()
 
   const sortedEntities = entities.sort((a, b) => resolve(a.displayName).localeCompare(resolve(b.displayName)))
 
@@ -408,7 +418,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 +433,16 @@ 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.
+
+The request locale is the one the frontend passes as the fourth argument of `apiClient.finalize(configurationId, finalizationId, finalizeData, locale, frontendData)`, where `apiClient` comes from `phx.frontend.useAuthorizedClient()`. Pass the active locale, for example `phx.frontend.useLocaleSwitch().locale`, so the webhook renders in the language the user sees. Without a locale the webhook renders in `en`.
 
 ### 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 +462,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'
 
@@ -491,7 +503,8 @@ export const orderHttpTask = phx.webhooks.taskFactory.createSendHttpRequestTask(
 
   return {
     type: 'SendHttpRequest',
-    url: phx.runtimeConfig.ORDER_WEBHOOK_URL,
+    // ORDER_WEBHOOK_URL is declared under `env.webhook` in a spec file, with `type: url` and `required: true`
+    url: phx.webhooksEnv.ORDER_WEBHOOK_URL,
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
@@ -511,7 +524,7 @@ Legacy Handlebars PDF/email tasks remain supported for backwards compatibility,
 
 ## Your Day-to-Day Development Workflow
 
-The **phx-cli** handles most translation workflow automatically. The basic cycle is: sync to extract strings, translate `.po` files, build to compile.
+The Phoenix CLI handles most of the translation workflow. The basic cycle is: sync to extract and compile the strings, translate the `.po` files, then sync or build again to compile the translations.
 
 ### Development Workflow
 
@@ -519,7 +532,7 @@ For day-to-day development, opt into the Lingui watcher with `--withLingui` (or
 
 ```bash
 # Start development server with hot reload and i18n watch
-phx dev --withLingui
+pnpm phoenix dev --withLingui
 
 # This automatically:
 # - Watches for new translatable strings
@@ -527,26 +540,28 @@ phx dev --withLingui
 # - Compiles translations on change
 ```
 
-Lingui watching is disabled by default, and `phx dev` logs a warning when it is not enabled.
+Lingui watching is disabled by default: `phoenix dev` then only creates the catalogs that are missing at startup, leaves existing `.po` and compiled files as they are, and logs a warning.
 
-When you add new translatable content (using `$msg` in YAML or `msg()` in code), run `phx sync` to extract strings:
+When you add new translatable content (using `$msg` in YAML or `msg()` in code), run `phoenix sync` to extract and compile the strings:
 
 ```bash
-# Sync domain specs and extract i18n strings
-phx sync
+# Sync domain specs, extract and compile i18n strings
+pnpm phoenix sync
 ```
 
-This updates the `.po` files in `src/locales/<lang>/messages.po`. Translators fill in the `msgstr` values for each `msgid`.
+This updates the `.po` files in `src/locales/<lang>/messages.po` and the compiled `.ts` files beside them. Translators fill in the `msgstr` values for each `msgid`.
 
 ### Production Build
 
 When you're ready to ship:
 
 ```bash
-# Build for production (includes i18n compilation)
-phx build
+# Build for production (extracts and compiles the i18n catalogs)
+pnpm phoenix build
 ```
 
+With the application-spec pipeline, `phoenix dev` and `phoenix 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 +580,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 +610,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 `phoenix 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 top-level `availableLocales`.
 
 ## What We Learned