@salsita-ai/sdk 0.50.0-develop.b5468d6828 → 0.50.0-develop.b929a82a82

package/dist/docs/phoenix/deployments.mdx

@@ -329,7 +329,17 @@ export type RuntimeConfig = ReturnType<typeof readRuntimeConfig>
 2. **`.env.generated`** file (created by deployment process)
 3. **`.env`** file (lowest priority)
 
-This means you can override any environment variable by setting it directly in your shell, while still having defaults in `.env` files.
+Set a variable in your shell to override either file tier. In a pnpm workspace, a value in the current package wins over the workspace-root value within the same tier; a workspace generated value still wins over a package `.env` value. Each folder uses `.env.generated` when it exists, otherwise `.phoenix/.env.generated`; the two generated files are never merged.
+
+Only values from `.env` expand references such as `${API_HOST}` against the winning values. Process and generated values stay literal, including when a `.env` value references them. For a literal dollar sign in `.env`, escape it as `\$`:
+
+```dotenv
+API_HOST=https://api.example.com
+API_URL=${API_HOST}/v1
+PASSWORD=cost-\$5
+```
+
+Here `API_URL` becomes `https://api.example.com/v1` and `PASSWORD` becomes `cost-$5`. Generated values need no interpolation escaping. Reading the configuration does not modify `process.env`.
 
 ## Step-by-Step Deployment Guide
 

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

@@ -327,7 +327,9 @@ components:
           $read: $description # This will auto-generate $description expression
 ```
 
-The code generator will automatically create an expression with the same name and infer the return type based on usage context.
+The code generator creates an expression with the same name and infers its type from where it is read. The inferred expression is a custom expression like any declared one: implement it in `src/expressions/`, otherwise the application reports `MISSING_IMPLEMENTATION` when it loads.
+
+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
 
@@ -467,11 +469,9 @@ export default phx.domain.implementCustomExpressions({
 })
 ```
 
-> **Removed:** `$codeRef` with an inline `code:` block was previously documented for this purpose.
-> It was never evaluated — the parser carried it through as plain data — so specs using it silently
-> shipped an object where a number was expected. It now reports
-> `ENHANCED_JSON_VALUE_CODE_REF_NOT_SUPPORTED`. Replace `$codeRef: { code: 4 * 25.4 }` with
-> `$eval: '4 * 25.4'`.
+> `$codeRef` with an inline `code:` block is not supported and reports
+> `ENHANCED_JSON_VALUE_CODE_REF_NOT_SUPPORTED`. Write `$eval: '4 * 25.4'` instead of
+> `$codeRef: { code: 4 * 25.4 }`.
 
 ## Aliases
 
@@ -528,19 +528,21 @@ invariants:
   ChairParts: # Applied to all chair parts
     materialRequired:
       type: 'materialMissing'
-      severity: 'error'
+      severity: 'warning'
       message: 'Material must be selected for all chair parts'
 
 components:
   ChairParts: # Applied to all chair parts
-    materialSelector:
+    price:
       main:
-        value:
-          $bind: materialId
+        price:
+          $read: $price
 ```
 
 This approach reduces duplication and ensures consistent behavior across related entities.
 
+The invariant is a `warning` because a chair part without a material is a configuration in progress, not an impossible one: the user can keep configuring, and only finalizing is blocked until every part has a material. A `fatal` severity would reject every change while a part has no material, including the change that adds the part. See [Violation Severity](#violation-severity).
+
 ## Relations
 
 Relations connect your entities into a tree that represents both structure and ownership. This tree drives what appears under what in the scene, how selection and navigation move up and down, and which items get deleted together when you remove a parent. It must be a proper tree (no cycles) and every entity needs to belong to it.
@@ -645,10 +647,12 @@ invariants:
         - 'aspectRatioInvalid'
 ```
 
-Implementation returns an array of violations. Each violation object requires `type`, `severity`, and `message`. Optionally, you can add `controlViolationPriority` (same as in static YAML) and `formatControlViolationMessage` — a function that receives the current `stateEmission` and an `{ i18n }` context, enabling runtime-computed, translatable messages:
+Implementation returns an array of violations. Each violation object requires `type` and `severity`; `message` is optional and is the text users see for the violation. Optionally, you can add `controlViolationPriority` (same as in static YAML) and `formatControlViolationMessage` — a function that receives the current `stateEmission` and an `{ i18n }` context, enabling runtime-computed, translatable messages:
 
 ```typescript
 // src/invariants/cabinet.ts
+import { msg } from '@lingui/core/macro'
+
 export default phx.domain.implementCustomInvariants({
   Cabinet: {
     materialConstraints: self => {
@@ -716,11 +720,14 @@ For a full working example of priority-based filtering and runtime message forma
 
 ### Violation Severity
 
-Different severities have different behaviors:
+The severity decides what a violation blocks. An invariant takes one of four severities:
+
+- **`fatal`**: the change that causes the violation is never committed. It does not reach the scene, the undo stack or the saved configuration, and controls disable the options that would cause it, with the violation message as the hint.
+- **`fixable`**: rejected the same way as `fatal`. Use it for a situation your project repairs: a [transformer](?path=/docs/other-features-transformers--docs) that reacts to the violation returns the updates that fix it, so the change commits without the violation. Phoenix repairs nothing on its own; without such a transformer, `fixable` behaves exactly like `fatal`.
+- **`warning`**: the change is committed and saved, but the configuration cannot be finalized while the violation lasts. Its message shows on the finalize action.
+- **`notice`**: the change is committed and saved, and nothing is blocked. Its message shows on the finalize action as information.
 
-- **Warning**: Shows a warning but allows the configuration to continue
-- **Error**: Prevents certain actions but doesn't block finalization
-- **Fatal**: Prevents finalizing the configuration
+If the initial state already has a `fatal` or `fixable` violation, the transformers run once on it; when the violation remains, the configurator does not start. See the [Violation Severity example](?path=/docs/other-features-violation-severity--docs) to try each level.
 
 ### Common types
 
@@ -840,7 +847,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/expression-context.mdx

@@ -66,7 +66,7 @@ The `mode` property indicates the current operational context of the configurato
 
 Projections are SDK-defined expressions that provide reusable functionality across projects. They expose complex calculations and relationships that would otherwise require custom implementation.
 
-The Phoenix SDK includes projection systems for common tasks. Each projection system handles a specific domain like geometry, pricing, or layout. Projects can use these projections without implementing the underlying logic.
+The Phoenix SDK includes projection systems for common tasks. Each projection system handles one domain: positions, sketching, collisions, spatial constraints, snapping and projected entities, the `*Projections` members of the context listed above. Projects can use these projections without implementing the underlying logic.
 
 **Sketching Projections Example**:
 
@@ -82,7 +82,6 @@ export default phx.domain.implementCustomExpressions({
       const sketchingKey = 'floorplan'
       try {
         const shape = ctx.sketchingProjections.getEntityLine(line.id, state, sketchingKey)
-        const connections = ctx.sketchingProjections.getConnections(state, sketchingKey)
         return {
           isTerminal: shape.isTerminal,
           hasStartConnection: shape.start.connection !== null,
@@ -96,34 +95,9 @@ export default phx.domain.implementCustomExpressions({
 })
 ```
 
-This example shows different types of calculations with sketching projections. Connection checking tells you how shapes connect to each other. The traverse method lets you walk through connected shapes. Area calculations use coordinate data to compute geometric properties.
+This example reads how a line connects to the rest of the sketch: `getEntityLine` returns the line's shape with its start and end connections. `getSketching(state, key)` returns all shapes and connections of a sketch, and `getEntityShape` and `getEntityRectangle` return the shape of one entity.
 
-Each projection method handles error cases when entities aren't part of the sketching system. This makes expressions safe to use across different entity types.
-
-**Future Projection Systems (Hypothetical)**:
-
-> **Note**: The following projection systems are hypothetical and not yet implemented. They illustrate how the projection pattern could extend to other domains.
-
-Phoenix can extend projections to other domains. Future projection systems might handle pricing, layout, or other complex calculations:
-
-```typescript
-// HYPOTHETICAL: These projection systems do not exist yet
-export default phx.domain.implementCustomExpressions({
-  Product: {
-    // Pricing projections - calculate complex pricing across projects
-    $finalPrice: (product, state, ctx) => {
-      return ctx.pricingProjections?.calculatePrice(product.id, state)
-    },
-
-    // Layout projections - spatial arrangement calculations
-    $spatialRelations: (product, state, ctx) => {
-      return ctx.layoutProjections?.getNeighbors(product.id, state)
-    },
-  },
-})
-```
-
-These examples show how projections could work in other areas. A pricing projection might calculate discounts, taxes, and complex pricing rules. A layout projection might determine spatial arrangements and object relationships.
+A projection method throws when the entity has no shape of that kind in the sketching, so the expression catches the error and returns a default.
 
 Projections provide tested, optimized solutions for common problems that many configurators need to solve. They let you leverage sophisticated SDK functionality without reimplementing complex logic in each project.
 

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. A project layout (`ConfiguratorLayout`) offers the same actions with its own buttons through `phx.frontend.useFinalizeAction`, which runs an action's handler and returns its pending state, its error and the disabled state with hints; see the Finalize paragraph of [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+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,10 @@ 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
@@ -58,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
@@ -87,8 +89,6 @@ For inspiration and real-world implementation patterns, examine deployed Salsita
 
 When you encounter challenges or need to implement specific features, use these resources in order:
 
-**AI-Powered Assistance**: Every Phoenix project ships Phoenix agent skills, so coding agents in your project already know the SDK conventions and CLI. Start by using AI coding assistants in the `configurator-phoenix` project. While they may not solve complex problems directly, they can point you toward relevant examples or search terms that will help you find the right solution.
-
 **Storybook Documentation**: Search the Phoenix Storybook for functionality similar to what you need. When you find relevant examples, examine the corresponding code in the configurator-phoenix stories to understand the implementation details.
 
 **Repository Search Strategy**:

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. 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.
+- 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`. A finalize action the layout runs with `phx.frontend.useFinalizeAction` raises no snackbar; its error is the hook's `error`.
+- 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.
 
@@ -79,7 +100,7 @@ Instead of `DesktopViewControls` or `MobileViewControls`, a layout can build its
 | `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