@salsita-ai/sdk 0.50.0-develop.8c8c362f86 → 0.50.0-develop.8e3768cb11

package/dist/docs/layouts/header/fixed.mdx

@@ -145,7 +145,7 @@ interface HorizontalTab {
   /**
    * List of navigation states when the tab is active. First one will be used for activation.
    */
-  readonly navigationStates: string[]
+  readonly navigationStates: readonly string[]
 }
 ```
 
@@ -158,7 +158,7 @@ type HorizontalTabsComponentState = {
   /**
    * List of tabs in the horizontal tabs.
    */
-  readonly tabs: HorizontalTab[]
+  readonly tabs: readonly HorizontalTab[]
 }
 ```
 

package/dist/docs/layouts/header/floating.mdx

@@ -110,11 +110,11 @@ The configuration uses these component types:
 ```typescript
 export interface NavigationStep {
   readonly label: Localizable
-  readonly navigationStates: string[]
+  readonly navigationStates: readonly string[]
 }
 
 export type NavigationStepsComponentState = {
-  readonly steps: NavigationStep[]
+  readonly steps: readonly NavigationStep[]
 }
 ```
 

package/dist/docs/layouts/sidebar/in-a-custom-layout.mdx

@@ -90,8 +90,8 @@ The spec is a table with one property, its edge finish, on a **Design** tab and
 
 ## Known gaps
 
-- The finalize button is disabled unless the spec configures `finalizeButton` or `finalizePage`, as in the built-in layout. A `finalizePage` is not shown by a project layout unless the layout renders it.
-- `LayoutSlots.DesktopSidebar` is the desktop sidebar. At phone width a project layout needs its own arrangement, for example the `Mobile*` members of `LayoutSlots` in a drawer.
+- The footer is the basic sidebar footer, as in the built-in layout when the spec configures none. Its finalize button is disabled unless the spec configures the legacy `finalizeButton` or `finalizePage` components, which are declared only in TypeScript, and a project layout shows a `finalizePage` only if it renders it. New projects finalize over `finalizeAction` components, which the universal sidebar footer offers when the spec configures `universalSidebarFooter`.
+- `LayoutSlots.DesktopSidebar` is the desktop sidebar. At phone width a project layout needs its own arrangement, for example the `Mobile*` members of `LayoutSlots`, listed in [Layout Slots](?path=/docs/phoenix-layout-slots--docs#phone-layout), in a drawer.
 - The tabs overlap the scene beside the sidebar; the safe area in this example does not leave room for them.
 - `miniSidebar` does not shrink the sidebar: the built-in layout does that, and here the sidebar fills its container. A layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and gives the container no fixed height, anchored at the bottom for example, so the sidebar takes its content's height.
 

package/dist/docs/layouts/sidebar-footer/basic.mdx

@@ -41,11 +41,11 @@ The basic sidebar footer adapts its layout based on what's available. The finali
 
 For more control over the sidebar footer, see these related examples:
 
-- **[Phoenix Handlers](../?path=/docs/layouts-phoenix-handlers)**: Learn how to create custom action handlers for sidebar footer buttons
-- **[Read Sidebar Footer](../?path=/docs/layouts-sidebar-footer-read)**: Display price in read-only mode without action buttons
-- **[Universal Sidebar Footer](../?path=/docs/layouts-sidebar-footer-universal)**: Add custom text and multiple action buttons while keeping the standard layout
-- **[Custom Sidebar Footer](../?path=/docs/layouts-sidebar-footer-custom)**: Replace the sidebar footer with your own React components for complete control
-- **[Hidden Sidebar Footer](../?path=/docs/layouts-sidebar-footer-hidden)**: Remove the sidebar footer entirely for embedded or immersive experiences
+- **[Phoenix Handlers](?path=/docs/layouts-phoenix-handlers--docs)**: Learn how to create custom action handlers for sidebar footer buttons
+- **[Read Sidebar Footer](?path=/docs/layouts-sidebar-footer-read--docs)**: Display price in read-only mode without action buttons
+- **[Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs)**: Add custom text and multiple action buttons while keeping the standard layout
+- **[Custom Sidebar Footer](?path=/docs/layouts-sidebar-footer-custom--docs)**: Replace the sidebar footer with your own React components for complete control
+- **[Hidden Sidebar Footer](?path=/docs/layouts-sidebar-footer-hidden--docs)**: Remove the sidebar footer entirely for embedded or immersive experiences
 
 ## Guide
 
@@ -98,84 +98,39 @@ This configuration gives you a fully functional sidebar footer with price displa
 
 ### Customizing finalize behavior
 
-The sidebar footer's finalize button can be customized using two different component types. These components let you either replace the button itself or define what happens when the user clicks finalize.
+New projects finalize with `finalizeAction` components and the [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs), which runs the action's handler. The basic sidebar footer's own customization, the `finalizeButton` and `finalizePage` components, is legacy: the spec parser rejects both in YAML, so a project that keeps them declares them in TypeScript.
 
-#### Using finalizeButton component
+The basic sidebar footer checks for them in this order:
 
-The `finalizeButton` component replaces the default finalize button with your custom React component. This gives you complete control over the button's appearance and behavior.
+1. **finalizeButton**: if configured, its `button` React node is rendered instead of the finalize button, and implements the finalization and the disabled state itself
+2. **finalizePage**: if no custom button exists, a default button navigates to the first of the component's `finalizeNavigationStates`, and the built-in layout shows its `page` in a dialog while one of those states is active
+3. **No-op fallback**: if neither component is configured, a disabled button appears with the hint "Finalize feature is not configured"
 
-```yaml
-components:
-  Scene:
-    finalizeButton:
-      customFinalize:
-        button: <CustomFinalizeButtonComponent />
-```
-
-**TypeScript Interface**:
-
-```typescript
-/**
- * State for a custom finalize button component.
- */
-interface FinalizeButtonComponentState {
-  /**
-   * Custom React node to render as the finalize button.
-   * This completely replaces the default finalize button.
-   */
-  readonly button: ReactNode
-}
-```
+A legacy `finalizePage` is attached in TypeScript, as the [Universal](?path=/docs/layouts-universal--docs) example does in `src/components/components.tsx`:
 
-Your custom button component receives no special props. You must implement all the finalization logic yourself, including calling the appropriate handlers and managing the button's disabled state based on validation errors.
-
-#### Using finalizePage component
-
-The `finalizePage` component opens a modal page when the user clicks finalize. This is useful for multi-step checkout flows, order forms, or any scenario where you need to collect additional information before completing the order.
-
-```yaml
-components:
-  Scene:
-    finalizePage:
-      checkoutFlow:
-        finalizeNavigationStates: ['checkout', 'payment', 'confirmation']
-        page: <CheckoutFormComponent />
-```
+```tsx
+import { finalizePageComponent, memoEval } from '@salsita-ai/sdk/domain'
 
-**TypeScript Interface**:
+// CheckoutPage is the project's own React component
+import { CheckoutPage } from '../_shared/CheckoutPage.js'
 
-```typescript
-/**
- * State for a finalize page component that opens a modal.
- */
-interface FinalizePageComponentState {
-  /**
-   * The navigation states that are active when finalization is in progress.
-   * The first state in this array is used for initial navigation when the
-   * finalize button is clicked.
-   */
-  readonly finalizeNavigationStates: string[]
+// `phx` is a global in an application project; a Storybook example imports it from '../../.phoenix/phx.js'
 
-  /**
-   * React node to render as the page content in the finalize modal.
-   */
-  readonly page: ReactNode
-}
+export default phx.domain.attachComponent
+  .withComponent(finalizePageComponent, 'default')
+  .withEntity('Scene')
+  .attach(
+    memoEval(
+      () => [],
+      () => ({
+        finalizeNavigationStates: [phx.applicationTypes.NavigationState.finalize],
+        page: <CheckoutPage />,
+      })
+    )
+  )
 ```
 
-When the user clicks the finalize button, the system navigates to the first state in `finalizeNavigationStates`. Your page component can then navigate between these states to create a multi-step flow. All states must be defined in your navigation configuration.
-
-#### Priority and fallback behavior
-
-The sidebar footer checks for finalize components in this order:
-
-1. **finalizeButton**: If configured, this component is rendered as-is with no modifications
-2. **finalizePage**: If no custom button exists, a default button is shown that opens the specified page
-3. **No-op fallback**: If neither component is configured, a disabled button appears with the hint "Finalize feature is not configured"
-
-This priority system lets you customize either the button appearance or the finalization flow, but not both simultaneously. If you need both, use `finalizeButton` and implement the page navigation logic within your custom component.
-
-See the [Finalize Page Layout](../?path=/docs/layouts-simple-layout-finalize-page) example for a complete implementation of the finalize page pattern.
+The states in `finalizeNavigationStates` must be listed in the spec's `navigationStates`. The universal sidebar footer never opens a `finalizePage`.
 
 ### Navigation steps influence
 
@@ -278,7 +233,7 @@ Use `simpleSummary` for basic summaries that just need to display a list of conf
 
 Both component types require a `summaryNavigationState` that must exist in your navigation configuration. The sidebar footer checks the current navigation state against this property to determine whether the summary is currently active.
 
-See the [Summary Layout](../?path=/docs/layouts-simple-layout-summary) example for a complete summary implementation.
+See the [Sidebar Summary](?path=/docs/layouts-sidebar-summary--docs) example for a complete summary implementation.
 
 ### Custom price sidebar footer
 
@@ -317,11 +272,11 @@ When `customPriceSidebarFooter` is configured:
 - The sidebar footer layout remains unchanged - only the price display is replaced
 - Action buttons (finalize, next/previous, etc.) are not affected
 
-This component affects **only** the price display, not the overall sidebar footer structure. If you need to change the entire sidebar footer layout, use the [Universal Sidebar Footer](../?path=/docs/layouts-sidebar-footer-universal) or [Custom Sidebar Footer](../?path=/docs/layouts-sidebar-footer-custom) instead.
+This component affects **only** the price display, not the overall sidebar footer structure. If you need to change the entire sidebar footer layout, use the [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) or [Custom Sidebar Footer](?path=/docs/layouts-sidebar-footer-custom--docs) instead.
 
 The custom price node receives no special props. You must access price data yourself through the configurator hooks like `useRootEntityPrice()` or by reading entity attributes directly.
 
-See the [Custom Price Sidebar Footer](../?path=/docs/layouts-custom-price) example for implementation details and best practices.
+See the [Custom Price Sidebar Footer](?path=/docs/layouts-custom-price--docs) example for implementation details and best practices.
 
 ## Example
 

package/dist/docs/other-features/client-side-rendering/declarative.mdx

@@ -229,7 +229,7 @@ export type ClientSideImageComponentState = {
   /** Output format: PNG (with transparency) or JPEG */
   readonly fileFormat: 'PNG' | 'JPEG'
   /** Optional background color (hex string) */
-  readonly backgroundColor?: string
+  readonly backgroundColor?: HexColor
 
   /** Tool state the image is rendered in (pins component filters keyed on tool state) */
   readonly toolState: string

package/dist/docs/phoenix/application-states.mdx

@@ -223,22 +223,24 @@ components:
 
     staticPerspectiveCamera:
       overview:
-        position: [0, 10, 10]
-        target: [0, 0, 0]
+        distance: 14
+        polarAngle: 0.8
+        azimuthAngle: 0
         $filter:
           viewStates: ['overview']
 
       detail:
-        position: [2, 2, 2]
-        target: [0, 0, 0]
+        distance: 3.5
+        polarAngle: 0.95
+        azimuthAngle: 0.8
         $filter:
           viewStates: ['closeup']
 
     staticOrthographicCamera:
       blueprint:
-        position: [0, 20, 0]
-        target: [0, 0, 0]
-        zoom: 1.5
+        distance: 20
+        polarAngle: 0
+        frustumSize: 12
         $filter:
           viewStates: ['blueprint']
 

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

@@ -158,30 +158,35 @@ const viewState = phx.frontend.useActiveViewState()
 const toolState = phx.frontend.useActiveToolState()
 
 // Navigation actions
-const navigate = phx.frontend.useNavigate()
-const pushNavigate = phx.frontend.usePushNavigate()
-const popNavigate = phx.frontend.usePopNavigate()
+const navigate = phx.frontend.useNavigate() // navigate(state) replaces the active state and clears the history
+const pushNavigate = phx.frontend.usePushNavigate() // pushNavigate(state) remembers the active state for popNavigate
+const popNavigate = phx.frontend.usePopNavigate() // popNavigate() returns to the remembered state, if there is one
 
 // Fullscreen: a flag in the configurator's state that the layout honours; it does not put the browser into fullscreen
 const isFullscreen = phx.frontend.useIsFullscreenActive()
 const setFullscreen = phx.frontend.useSetFullscreen() // setFullscreen(true) or setFullscreen(false)
+
+// View state and camera
+const setViewState = phx.frontend.useSetViewState() // setViewState(state) makes one of the spec's viewStates active
+const resetCamera = phx.frontend.useResetCamera() // resetCamera() undoes the user's orbit, pan and zoom
 ```
 
 ### Controls
 
 ```typescript
-// Control hooks for UI inputs
-const swatchSelection = phx.frontend.useSwatchSelection(entityId, controlId)
-const textValue = phx.frontend.useTextValue(entityId, controlId)
-const attributeSelection = phx.frontend.useAttributeSelection(entityId, controlId)
-const attributeSwitch = phx.frontend.useAttributeSwitch(entityId, controlId)
-const distanceDimension = phx.frontend.useDistanceDimension(entityId, controlId)
-const angleDimension = phx.frontend.useAngleDimension(entityId, controlId)
-const genericDimension = phx.frontend.useGenericDimension(entityId, controlId)
+// Control hooks for UI inputs: the entity id and the instance name of the control component on it
+// useSwatchSelection requires its third argument, the fixable violation types
+const swatchSelection = phx.frontend.useSwatchSelection(entityId, instanceName, [])
+const textValue = phx.frontend.useTextValue(entityId, instanceName)
+const attributeSelection = phx.frontend.useAttributeSelection(entityId, instanceName)
+const attributeSwitch = phx.frontend.useAttributeSwitch(entityId, instanceName)
+const distanceDimension = phx.frontend.useDistanceDimension(entityId, instanceName)
+const angleDimension = phx.frontend.useAngleDimension(entityId, instanceName)
+const genericDimension = phx.frontend.useGenericDimension(entityId, instanceName)
 
 // Update control
 const updateControl = phx.frontend.useUpdateControl()
-const updatedControl = phx.frontend.useUpdatedControl(entityId, controlId)
+const updatedControl = phx.frontend.useUpdatedControl(updates)
 ```
 
 ### Recipes & Entity Creation
@@ -207,15 +212,19 @@ const deletedEntity = phx.frontend.useDeletedEntity()
 ### Validation & Violations
 
 ```typescript
-// State validity
+// Validity of the last committed state; a rejected change never becomes committed, so it is not seen here
 const validity = phx.frontend.useStateValidity()
 
-// Control violations
-const controlViolations = phx.frontend.useControlViolations(entityId, controlId)
+// Control violations: takes the violation types to ignore and returns a function that maps a prepared
+// state emission to { disabled, hints, violations }
+const controlViolations = phx.frontend.useControlViolations([])
 
 // Finalize violations
 const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
+// Messages for the user: violations of a rejected change, side-effect hints and errors, one call each
+phx.frontend.useConfiguratorMessages(message => showToast(message.text))
+
 // Map violations to hints
 const mapViolationHints = phx.frontend.useMapViolationHints()
 ```
@@ -420,12 +429,119 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - `LayoutSlots.SharedCanvas` renders the scene. It is absolutely positioned and fills its nearest positioned ancestor, so the layout's root is positioned and covers the page. The layout positions its own UI above the canvas and after it in the markup, as the `aside` does; unpositioned content is painted under the canvas.
 - `useSceneSafeArea()`, called without arguments, tells the camera which part of the canvas the UI leaves free. Attach `containerRef` to the element that covers the whole canvas and `safeAreaRef` to the region the scene should stay visible in: the hook measures the gap between the two and the camera frames the scene inside the safe area. Without it the scene is framed in the whole canvas. The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'` to leave orbiting and clicking to the scene. A `canvasPadding` component in the spec scales the measured gaps, see [Canvas Padding](?path=/docs/layouts-canvas-padding--docs).
 - The layout has to mount `LayoutSlots.SharedCanvas`, or the project sets `appLoader: legacy`. Otherwise the app loader stays on screen.
-- The layout composes the rest from what `@salsita-ai/sdk/configurator` exports: `LayoutSlots.Services` and the other members of `LayoutSlots`.
+- The layout composes the rest from what `@salsita-ai/sdk/configurator` exports: `LayoutSlots.Services` and the other members of `LayoutSlots`, which [Layout Slots](?path=/docs/phoenix-layout-slots--docs) lists with what each shows, what feeds it, what it renders when the spec configures nothing for it and what it does in read mode.
 - `LayoutSlots.DesktopSidebar` is the built-in desktop sidebar as one piece: the spec's tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Use it when the spec's property pages are what the customer should see and only their place changes, for example a sidebar on the left; build the controls yourself when they have to look like the brand's own. Without `width` it fills its container, so the layout positions and sizes that container; `miniSidebar` does not shrink it, so a layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and lets the container take the sidebar's height. Its tabs sit outside it on the left; `side="start"` puts them on its right, for a sidebar on the left. In fullscreen it stays in place, transparent and inert, so a layout that wants the space back removes it while `phx.frontend.useIsFullscreenActive()` is set. See [Sidebar in a Custom Layout](?path=/docs/layouts-sidebar-in-a-custom-layout--docs).
-- Nothing of the built-in layouts is rendered for it. `Legacy.CommonFinalizePage` shows the page of the `finalizePage` component in a dialog while one of its finalize navigation states is active, so a layout that shows a finalize button mounts it; without it the button changes the navigation state and nothing appears. It is marked deprecated and is the only exported piece that does this. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is available to a project layout only inside `LayoutSlots.DesktopSidebar`.
-- The layout reads the state it has to react to from hooks. Read mode: `phx.frontend.useAccessService().accessInfo.viewMode`. Fullscreen: `phx.frontend.useIsFullscreenActive()` reads it and `phx.frontend.useSetFullscreen()` sets it; the layout decides what to hide. Preview: `usePreview()` from `@salsita-ai/sdk/configurator`.
+- Nothing of the built-in layouts is rendered for it. A project layout finalizes over the spec's `finalizeAction` components, see the finalize paragraph of [Hooks for a Project Layout](#hooks-for-a-project-layout). The `finalizePage` and `finalizeButton` components are legacy: they cannot be declared in YAML, only in TypeScript, and `Legacy.CommonFinalizePage`, which is deprecated, shows a `finalizePage` for projects that still have one. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is available to a project layout only inside `LayoutSlots.DesktopSidebar`.
+- The layout reads the state it has to react to from hooks, listed with what each returns in [Hooks for a Project Layout](#hooks-for-a-project-layout).
+- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints and errors as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it. `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. Some messages stay snackbars either way: a failure to save the configuration and an error of the built-in finalize and other actions. They render into the snackbar root, so a layout that mounts none shows them outside the configurator, in the page's `body`. An error while a preset is applied appears on the preset screen, outside the layout. A finalize action the layout runs with `phx.frontend.useFinalizeAction` reports its error as that hook's `error` instead, neither as a message nor as a snackbar.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
+`defaultConfiguratorElements`, exported from `@salsita-ai/sdk/configurator`, holds the built-in UI as a `ConfiguratorLayout` registration that renders the layout the spec selects. Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default.
+
+#### Hooks for a Project Layout
+
+A project layout reads the product and the configurator's state through hooks, and changes them through the functions the hooks return. Each row names where its hook comes from; the `phx.frontend` hooks in these tables are also exported from `@salsita-ai/sdk/react` under the same name. No hook looks at read mode: the control hooks and the navigation and fullscreen setters keep working while `accessInfo.viewMode` is `true`, so the layout decides what a viewer can change.
+
+**The product**
+
+| Hook                                                                            | Returns                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useRootEntityId()`                                                | The id of the root entity, which the control hooks take.                                                                                                                                                                                                                                                                        |
+| `phx.frontend.useSelectedDomainEntityId()`                                      | The id of the selected entity, or the root entity's id while nothing is selected.                                                                                                                                                                                                                                               |
+| `phx.frontend.useFirstRootComponent(componentType)`                             | The first component of that type on the root entity as `{ componentInstance, state }`, or `null` without one. It takes a component type such as `detailComponent` from `@salsita-ai/sdk/domain`, or an array of them. The `detail` component's `state` is `{ title, subtitle, description, thumbnailUrl? }`, all `Localizable`. |
+| `phx.frontend.useComponents({ componentTypes, entityIds?, instanceNames? })`    | Every matching component on any entity, as `{ componentInstance, state }[]`. Its type on `phx.frontend` includes `null`, but it returns an empty array when nothing matches.                                                                                                                                                    |
+| `phx.frontend.useRootEntityPrice()` and `phx.frontend.useEntityPrice(entityId)` | The value of the entity's `price` component formatted as currency for the current locale, in the component's `currency` or `USD`, or `null` without a `price` component.                                                                                                                                                        |
+
+**Controls**
+
+| Hook                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useAttributeSelection(entityId, instanceName)` | `{ value, options }`. Each option has `title` and `description` (`Localizable`, the spec's `label` and `description`), `value`, `imageSrc` (the spec's `img`), `disabled`, `error`, `hint` (a `string` saying why it is disabled, or `undefined`) and `onSelect()`, which writes the option; the selected option's `onSelect` does nothing. It throws when the entity has no `attributeSelection` component named `instanceName`. |
+| `phx.frontend.useAttributeSwitch(entityId, instanceName)`    | `{ state, onChange, disabled, error, hint }`: `state.value` is the boolean and `onChange()` writes its opposite. It throws without the component.                                                                                                                                                                                                                                                                                 |
+
+The other control hooks in [Controls](#controls) take the same two arguments, `useSwatchSelection` a required third. `useSwatchSelection` returns `{ value, options }`, where `value` is the selected swatch key and each option is `{ swatchName, onClick, swatchKey, selected, thumbnailUrl, disabled, color, hint?, trace? }`; `useTextValue` and the dimension hooks return `{ value, hints, hasErrors, update, resolve, trace }` instead, where `update(value)` stages a value the scene shows at once (`useTextValue`'s is an `onChange` handler, `update(event, value)`) and `resolve()` commits it, or rolls it back when it breaks an invariant. Their TypeScript types give the exact shapes, and [Custom Controls](?path=/docs/controls-custom--docs) lists them.
+
+**Texts**
+
+Texts from the spec, such as option titles and the `detail` fields, are `Localizable`, not `string`. `useResolveLocalizable()` from `@salsita-ai/sdk/react` returns a function that turns one into a string in the current language, which suits a list; `useLocalizable(text)` and `<LocalizableMessage>` resolve a single text, see [Localization](?path=/docs/phoenix-localization--docs).
+
+**Mode, fullscreen, preview and navigation**
+
+| Hook                                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                                                                                                                                                                                                                                                                                              |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `usePreview()` from `@salsita-ai/sdk/configurator`                           | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state, one of the spec's `navigationStates`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | `(state) => void`, which enters a state and remembers the active one, and `() => void`, which returns to the remembered state and does nothing when there is none. `phx.frontend.useNavigate()` returns `(state) => void`, which enters a state and forgets the history.                                                                                                                                                                                                                                                                |
+| `phx.frontend.useActiveViewState()` and `phx.frontend.useActiveToolState()`  | The active view state and tool state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `phx.frontend.useSetViewState()`                                             | `(state) => void`, which makes the given view state, one of the spec's `viewStates`, the active one; setting the active state again keeps it. Cameras and components filtered by `viewStates` follow the change.                                                                                                                                                                                                                                                                                                                        |
+| `phx.frontend.useResetCamera()`                                              | `() => void`, which moves the camera back to the framing of the active camera configuration, undoing the user's orbit, pan and zoom, as the toolbar's reset button does. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                |
+| `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The responsive breakpoints the configurator's container satisfies, as `Viewport[]`, or `null` before it is measured. It follows the container, not the window, so it is the switch between a desktop and a phone layout. `desktop` is a container wider than 768 pixels and `mobile` one at most 768 pixels wide; `phone` is narrower than 480 and `tablet` between 480 and 1024 pixels; `landscape` and `portrait` follow the browser window's orientation. The built-in layout uses its phone arrangement unless `desktop` is active. |
+
+**Violations**
+
+| Hook                                              | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useStateValidity()`                 | The validity of the last committed state: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'notice' \| 'warning', entityViolations }`. A change that leaves a `fixable` or `fatal` violation is rejected and never committed, and neither is a change during which an error was thrown, so neither is seen here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `phx.frontend.useFinalizeViolations()`            | `{ disabled, hints, violations }`. `disabled` is `true` while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save; `hints` is the violations' text, or `undefined`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `phx.frontend.useConfiguratorMessages(onMessage)` | Nothing. It calls `onMessage(message)` once per message: `{ kind: 'violation', entityId, violation, text }` for each violation of the rejected state, including notices and warnings already present, so `violation.severity` tells the reason for the rejection (`fixable` or `fatal`) from them, `{ kind: 'sideEffect', text }` for each hint of a committed update, and `{ kind: 'error', error, text }` when an error is thrown while a change is validated, with `text` the generic "Oops, something went wrong". `text` is resolved to the current language; a violation's is its `message`, or its `type` without one, and the built-in snackbar prefixes it with `entityId`. Hints committed before the layout mounted are not delivered; when the most recent change was rejected or threw, its messages are delivered again when the hook mounts. `onMessage` may be a new function on every render. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types; from `@salsita-ai/sdk/react` the type is `ConfiguratorMessage`. |
+| `phx.frontend.useFinalizeAction(handler)`         | `{ run, isPending, error, disabled, hints }` for the `finalizeAction` whose `handler` it is given; see the Finalize paragraph below for how to call it. `run()` records the finalize-button click for analytics and runs the project's handler, and does nothing while `disabled` or `isPending`; `error` is what the handler's last run rejected with, or `null`; `disabled` and `hints` are those of `useFinalizeViolations()`. The type of the result is `UseFinalizeActionResult` from `@salsita-ai/sdk/configurator`, which also exports the hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+
+`LayoutSlots.Services` shows the messages of `useConfiguratorMessages` as snackbars; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
+
+**Finalize**
+
+A project layout finalizes over the spec's `finalizeAction` components. `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`, with `finalizeActionComponent` from `@salsita-ai/sdk/domain`, lists them; each `state` is `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. The built-in footer offers the first `'primary'` action, or else the first action, as its button and the others in a menu; a project layout follows the same rule when it offers one action.
+
+Each action gets a component of its own that calls `phx.frontend.useFinalizeAction(action.state.handler)` once, never in a loop or conditionally, because the hook runs the project's handler factory, which calls hooks. The layout wraps that component in `<PhoenixHandlerBoundary name={action.state.handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload. The hook returns:
+
+- `run()`, which records the finalize-button click for analytics and then runs the handler. It does nothing while `disabled` or `isPending`.
+- `isPending`, `true` while the handler runs.
+- `error`, what the handler's last run rejected with, or `null`; a rejection that is not an `Error` is wrapped in one, with the value as its `cause`. It is cleared when the action runs again. No snackbar is raised; the layout shows the error its own way.
+- `disabled` and `hints`, those of `useFinalizeViolations()`: finalizing is not possible while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save, and `hints` says why.
+
+`isPending` and `error` belong to the mounted component: when it unmounts during a run, the handler keeps running, and a component mounted afterwards starts with `isPending` false and no `error`.
+
+```tsx
+import { finalizeActionComponent } from '@salsita-ai/sdk/domain'
+import { PhoenixHandlerBoundary, useResolveLocalizable } from '@salsita-ai/sdk/react'
+
+const FinalizeButton = ({ handler, label }: { handler: string; label: string }) => {
+  const { run, isPending, error, disabled, hints } = phx.frontend.useFinalizeAction(handler)
+
+  return (
+    <div>
+      <button type="button" disabled={disabled || isPending} onClick={run} title={hints}>
+        {isPending ? 'Sending…' : label}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </div>
+  )
+}
+
+export const Finalize = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const resolve = useResolveLocalizable()
+  const actions = phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] }) ?? []
+  const primary = actions.find(action => action.state.variant === 'primary') ?? actions[0]
+
+  if (accessInfo.viewMode || !primary) {
+    return null
+  }
+
+  return (
+    <PhoenixHandlerBoundary name={primary.state.handler}>
+      <FinalizeButton handler={primary.state.handler} label={resolve(primary.state.label)} />
+    </PhoenixHandlerBoundary>
+  )
+}
+```
+
+The hook does not check read mode, so the layout hides finalizing while `accessInfo.viewMode` is `true`, as above. [Custom Layout](?path=/docs/layouts-custom-layout--docs#request-a-quote) runs a finalize action this way from its review step.
+
+Instead of its own buttons, a project layout can mount `<FinalizeActions />` from `@salsita-ai/sdk/configurator`: the built-in footer's finalize buttons, the primary action plus a menu of the others, disabled with the hints of `useFinalizeViolations()`, with a spinner while the handler runs and a snackbar when it fails. It renders nothing without a `finalizeAction`, and it does not check read mode either.
+
 ## TransformerBuilder
 
 Use `transformerBuilder` to create entity transformers:

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).
 
-Phoenix selects one primary footer action and places additional finalization actions in its menu. A configured `finalizePage` opens in a dialog. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior.
+The universal sidebar footer offers the spec's `finalizeAction` components: Phoenix selects one primary footer action and places additional finalization actions in its menu. It never opens a `finalizePage`; the `finalizePage` and `finalizeButton` components are legacy, declared only in TypeScript, and used by the basic sidebar footer and the legacy layouts. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior. A project layout (`ConfiguratorLayout`) offers the same actions with its own buttons through `phx.frontend.useFinalizeAction`, which runs an action's handler and returns its pending state, its error and the disabled state with hints; see the Finalize paragraph of [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
 
 ## How Finalization Works