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

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

@@ -21,15 +21,15 @@ The configurator interface is Phoenix's **public API** - a collection of React h
 
 **Auto-Generated Interface**:
 
-The configurator interface is generated in `.phoenix/configurator-interface.ts`:
+The configurator interface is generated in `.phoenix/configurator-globals.ts`, which sets `phx.frontend` before any file in `src/` loads, so project files use `phx.frontend` without importing it:
 
 ```typescript
-// .phoenix/configurator-interface.ts (AUTO-GENERATED - DO NOT EDIT)
+// .phoenix/configurator-globals.ts (AUTO-GENERATED - DO NOT EDIT), shortened
 import { createConfiguratorInterface } from '@salsita-ai/sdk/configurator'
 
-import { configuratorBuilder } from './domain.js'
+import { baseConfiguratorBuilder } from './domain-spec.js'
 
-export const configuratorInterface = createConfiguratorInterface(configuratorBuilder)
+export const configuratorInterface = createConfiguratorInterface(baseConfiguratorBuilder)
 
 // Initialize the globals
 globalThis.phx.frontend = configuratorInterface
@@ -48,8 +48,8 @@ Phoenix provides typed interfaces available globally via the `phx` namespace:
 
 Types are auto-generated in `.phoenix/` from your domain schema:
 
-- `.phoenix/configurator-interface.ts` - Configurator interface
-- `.phoenix/admin-interface.ts` - Admin interface
+- `.phoenix/configurator-globals.ts` - Configurator interface
+- `.phoenix/admin-globals.ts` - Admin interface
 - `.phoenix/globals.d.ts` - Global type definitions
 
 **Type Access**:
@@ -71,15 +71,15 @@ export const CustomComponent = () => {
 
   // Entity state hooks
   const rootEntity = phx.frontend.useRootEntityState()
-  const selectedEntity = phx.frontend.useSelectedEntity()
+  // The selected entity when it is a Cabinet, typed as $Cabinet, otherwise null
+  const selectedCabinet = phx.frontend.useSelectedEntity(phx.domain.enhancedModel.$Cabinet)
 
   // Selection hooks
   const selectEntity = phx.frontend.useSelectEntity()
 
   // Type-safe entity access
-  if (selectedEntity && Cabinet.is(selectedEntity)) {
-    // selectedEntity is now typed as $Cabinet
-    console.log(selectedEntity.width, selectedEntity.$area)
+  if (selectedCabinet) {
+    console.log(selectedCabinet.width, selectedCabinet.$area)
   }
 }
 ```
@@ -93,7 +93,7 @@ The configurator interface provides 100+ hooks organized by category. Use TypeSc
 ```typescript
 const ExampleComponent = () => {
   // Core domain systems
-  const { navigationSystem, storeSystem, entitySystem } = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem, domain } = phx.frontend.useDomain()
 
   // Domain application context
   const { configurationPersistSystem } = phx.frontend.useDomainApplication()
@@ -106,24 +106,24 @@ const ExampleComponent = () => {
 ### State Subscriptions
 
 ```typescript
-// Committed state (after validation)
+// Committed state (after validation): the state, or the whole emission with its validity
 const committedState = phx.frontend.useCommittedState()
-const committedSlice = phx.frontend.useCommittedSlice(selector)
+const committedSlice = phx.frontend.useCommittedSlice()
 
-// Rendered state (for display)
+// Rendered state (for display, including staged changes such as a drag in progress)
 const renderedState = phx.frontend.useRenderedState()
-const renderedSlice = phx.frontend.useRenderedSlice(selector)
+const renderedSlice = phx.frontend.useRenderedSlice()
 
-// Selectors
-const value = phx.frontend.useStoreSelector(selector)
-const renderedValue = phx.frontend.useRenderedSelector(selector)
+// Selectors: a callback that reads the emission, and its dependency list
+const value = phx.frontend.useStoreSelector(emission => emission.state.entities.length, [])
+const renderedValue = phx.frontend.useRenderedSelector(emission => emission.state.entities.length, [])
 ```
 
 ### Entity State
 
 ```typescript
-// Get typed entity state
-const cabinet = phx.frontend.useEntityState(Cabinet, cabinetId)
+// Get typed entity state: $Cabinet for a Cabinet id
+const cabinet = phx.frontend.useEntityState(cabinetId)
 const rootEntity = phx.frontend.useRootEntityState()
 const rootEntityId = phx.frontend.useRootEntityId()
 
@@ -134,21 +134,25 @@ const renderedRoot = phx.frontend.useRootEntityRenderedState()
 ### Selection & Hover
 
 ```typescript
-// Selection hooks
-const selectedEntity = phx.frontend.useSelectedEntity()
-const selectedEntityId = phx.frontend.useSelectedEntityId()
+// Selection hooks: the selected cabinet and its id, or null while the selection is not a Cabinet
+const selectedCabinet = phx.frontend.useSelectedEntity(phx.domain.enhancedModel.$Cabinet)
+const selectedCabinetId = phx.frontend.useSelectedEntityId(phx.domain.enhancedModel.$Cabinet)
+// The id of the selected entity of any type
 const selectedDomainEntityId = phx.frontend.useSelectedDomainEntityId()
 
 // Selection actions
-const selectEntity = phx.frontend.useSelectEntity()
-const deselect = phx.frontend.useDeselect()
-const selectParent = phx.frontend.useSelectParent()
-
-// Hover hooks
-const hoveredEntity = phx.frontend.useHoveredEntity()
-const hoveredEntityId = phx.frontend.useHoveredEntityId()
+const selectEntity = phx.frontend.useSelectEntity() // selectEntity(id)
+const deselect = phx.frontend.useDeselect() // deselect()
+const selectParent = phx.frontend.useSelectParent(entityId) // selectParent() selects the entity's parent
+
+// Hover hooks: the hovered cabinet and its id, or null
+const hoveredCabinet = phx.frontend.useHoveredEntity(phx.domain.enhancedModel.$Cabinet)
+const hoveredCabinetId = phx.frontend.useHoveredEntityId(phx.domain.enhancedModel.$Cabinet)
+const hoveredDomainEntityId = phx.frontend.useHoveredDomainEntityId()
 ```
 
+The hooks that return an entity or its id of one type take the enhanced reflection of that type, `phx.domain.enhancedModel.$<Type>`. `useSelectedEntityId` and `useHoveredEntityId` also accept no argument, but then always return `null`.
+
 ### Navigation, View & Tool State
 
 ```typescript
@@ -165,6 +169,10 @@ const popNavigate = phx.frontend.usePopNavigate() // popNavigate() returns to th
 // Fullscreen: a flag in the configurator's state that the layout honours; it does not put the browser into fullscreen
 const isFullscreen = phx.frontend.useIsFullscreenActive()
 const setFullscreen = phx.frontend.useSetFullscreen() // setFullscreen(true) or setFullscreen(false)
+
+// View state and camera
+const setViewState = phx.frontend.useSetViewState() // setViewState(state) makes one of the spec's viewStates active
+const resetCamera = phx.frontend.useResetCamera() // resetCamera() undoes the user's orbit, pan and zoom
 ```
 
 ### Controls
@@ -188,57 +196,68 @@ const updatedControl = phx.frontend.useUpdatedControl(updates)
 ### Recipes & Entity Creation
 
 ```typescript
-// Cook (prepare) recipes for adding children
-const cookRecipes = phx.frontend.useCookRecipes()
-const cookedRecipes = phx.frontend.useCookedRecipes()
-
-// Cook recipes for replacing entities
-const cookReplaceRecipes = phx.frontend.useCookReplaceRecipes()
-const cookedReplaceRecipes = phx.frontend.useCookedReplaceRecipes()
-
-// Recipe options
-const groupedOptions = phx.frontend.useGroupedRecipeOptions(entityId, recipeId)
+// Cook (prepare) recipes for adding children: { create, disabled, hints, recipes }
+const cookedRecipes = phx.frontend.useCookedRecipes(recipes, parentId)
+// The same as a function, for several sets of recipes: cookRecipes(recipes, collection?)
+const cookRecipes = phx.frontend.useCookRecipes(parentId)
+
+// Cook recipes for replacing an entity
+const cookedReplaceRecipes = phx.frontend.useCookedReplaceRecipes(entityId, recipes)
+const cookReplaceRecipes = phx.frontend.useCookReplaceRecipes(entityId)
+
+// Recipe options of the entity's childEntityRecipes components, grouped per component;
+// the optional second argument names the component instances to read
+const groupedOptions = phx.frontend.useGroupedRecipeOptions(entityId)
 const replaceOptions = phx.frontend.useReplaceEntityRecipeOptions(entityId)
 
-// Delete entity
+// Delete an entity: { remove, disabled, hints, trace }
+const deletedEntity = phx.frontend.useDeletedEntity(entityId)
+// The same as a function: deleteEntity(entityId)
 const deleteEntity = phx.frontend.useDeleteEntity()
-const deletedEntity = phx.frontend.useDeletedEntity()
 ```
 
 ### Validation & Violations
 
 ```typescript
-// Validity of the last committed state; a rejected change never becomes committed, so it is not seen here
-const validity = phx.frontend.useStateValidity()
+// Validity of the last committed state: severity is null, 'notice' or 'warning'; a rejected change never becomes
+// committed, so it is not seen here
+const { severity } = phx.frontend.useStateValidity()
 
-// Control violations: takes the violation types to ignore and returns a function that maps a prepared
-// state emission to { disabled, hints, violations }
+// Control violations: takes the violation types to leave out of the hints 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
+// Messages for the user: violations of a rejected change, side-effect hints, errors and failed saves, one call each
 phx.frontend.useConfiguratorMessages(message => showToast(message.text))
 
-// Map violations to hints
+// Map violations to one translated hint: takes the violation types to leave out and returns
+// (violations, stateEmission) => string, built from the violations at the highest priority among those
+// left after the ignored types are removed
 const mapViolationHints = phx.frontend.useMapViolationHints()
+const hint = mapViolationHints(violations, stateEmission)
 ```
 
 ### Components
 
 ```typescript
-// Get components attached to entities
-const component = phx.frontend.useComponent(filter)
-const components = phx.frontend.useComponents(filter)
-const firstComponent = phx.frontend.useFirstComponent(entityId, filter)
+import { detailComponent } from '@salsita-ai/sdk/domain'
+
+// The state of one component instance on an entity, or null; instanceName may be left out when the entity has
+// the component once
+const detail = phx.frontend.useComponent({ entityId, componentType: detailComponent, instanceName: 'main' })
+// Every matching instance as { componentInstance, state }; each filter field is optional
+const details = phx.frontend.useComponents({ componentTypes: [detailComponent], entityIds: [entityId] })
+const firstDetail = phx.frontend.useFirstComponent({ componentTypes: [detailComponent], entityIds: [entityId] })
 
-// Root entity components
-const rootComponents = phx.frontend.useRootComponents(filter)
-const firstRootComponent = phx.frontend.useFirstRootComponent(filter)
+// Root entity components: a component type or an array of them
+const rootDetails = phx.frontend.useRootComponents(detailComponent)
+const firstRootDetail = phx.frontend.useFirstRootComponent(detailComponent)
 
-// Rendered variants
-const renderedComponent = phx.frontend.useRenderedComponent(filter)
+// Rendered variants take the same arguments
+const renderedDetail = phx.frontend.useRenderedComponent({ entityId, componentType: detailComponent })
 ```
 
 ### Data & Services
@@ -348,16 +367,19 @@ const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(()
   }, [session.sessionPayload?.role])
 })
 
-// Runs after preset data is loaded
-const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {
-  // Can modify preset entities before rendering
-  return entities
-})
-
-// Intercept navigation to index/presets page
-const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {
-  // Custom logic before navigating
-})
+// Runs after preset data is loaded; the hook may call other hooks and returns the handler, which resolves to
+// the preset entities to start from, adjusted or as they are
+const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler(() => ({
+  handler: async entities => entities,
+}))
+
+// Intercept navigation to index/presets page: next() continues to it, and not calling it stays on the page
+const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => ({
+  handler: ({ next }) => {
+    // Custom logic before navigating
+    next()
+  },
+}))
 ```
 
 ### UI Components
@@ -368,9 +390,9 @@ const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement('MyLayoutE
   return <div>Custom Layout</div>
 })
 
-// Custom Phoenix entity element
-const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement('MyEntityElement', () => {
-  return <mesh>...</mesh>
+// Custom Phoenix entity element: receives the id of the entity it is rendered for
+const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement('MyEntityElement', ({ entityId }) => {
+  return <div>Custom control for {entityId}</div>
 })
 
 // Custom page when auth fails
@@ -387,24 +409,138 @@ Use these factories to customize the preset-selection screen without changing ho
 - `createPresetPageAction` adds project-specific content below the default preset cards.
 - `createPresetDeviceNotSupported` adds project-specific overlay content above the default preset cards.
 
+Without `createPresetUi`, Phoenix renders its built-in preset screen, which is the default `PresetUi` registration in `defaultConfiguratorElements`. The action and the overlay are parts of that built-in screen and render nothing until the project registers them. `createPresetUi` and the element's name, `PresetUiName`, are also exported from `@salsita-ai/sdk/react`.
+
 ```typescript
 const PresetScreen = phx.frontend.createPresetUi(CustomPresetScreen)
 const PresetAction = phx.frontend.createPresetPageAction(PresetHelpAction)
 const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNotice)
 ```
 
+### Configuration Not Found Page
+
+`phx.frontend.createConfigurationNotFoundPage` registers a page that replaces the one the configurator shows when it cannot open a configuration, as the layout element `ConfigurationNotFoundPage`. Without it, Phoenix renders its built-in "Configuration not accessible" page, which is the default `ConfigurationNotFoundPage` registration in `defaultConfiguratorElements`.
+
+```typescript
+// src/elements/ConfigurationNotFoundPage.tsx
+export default phx.frontend.createConfigurationNotFoundPage(({ onBack }) => (
+  <main>
+    <h1>We could not find this configuration</h1>
+    {onBack && <button onClick={onBack}>Start a new one</button>}
+  </main>
+))
+```
+
+The helper types the page's props as `ConfigurationNotFoundPageProps` from `@salsita-ai/sdk/react`, which also exports the helper and the element's name, `ConfigurationNotFoundPageName`. A layout element registered under the name `ConfigurationNotFoundPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
+
+- The page receives one optional prop, `onBack`, which returns to the start of the configurator. It is set when a configuration fails to load or is opened without a valid access key. It is not set on the start page itself, so a page that offers a way back shows it only when `onBack` is set.
+- The configurator renders the element in four cases: a configuration fails to load, for example because its ID does not exist or the server rejects its access key; a configuration is opened without an access key for it; a signed-in user whose role may not create configurations (`acl.canCreate`) opens the start page; the preset screen has no preset category to show, for example because the host's `presetTags` match no preset. The last case happens inside the built-in preset screen, so a project that replaces it with `createPresetUi` decides what to show itself.
+- The not-authenticated page, shown when session authentication fails or to an anonymous visitor who may not create a configuration, is its own element, which `createNotAuthenticatedPage` replaces. Its default, the `NotAuthenticatedPage` registration in `defaultConfiguratorElements`, renders the `ConfigurationNotFoundPage` element, so a project's not-found page shows there too.
+- The admin's not-authorized page still shows the built-in page directly, not the element.
+
+### Configurator Error Page
+
+`phx.frontend.createConfiguratorErrorPage` registers a page that replaces the one the configurator shows in production when it cannot go on, as the layout element `ConfiguratorErrorPage`. Without it, Phoenix renders its built-in "Whoops, something went wrong!" page, which is the default `ConfiguratorErrorPage` registration in `defaultConfiguratorElements`.
+
+```typescript
+// src/elements/ConfiguratorErrorPage.tsx
+export default phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => (
+  <main>
+    <h1>{reason === 'presetCreationFailed' ? 'We could not start your design' : 'Something went wrong'}</h1>
+    <button onClick={onRetry}>{reason === 'presetCreationFailed' ? 'Reload' : 'Try again'}</button>
+  </main>
+))
+```
+
+The helper types the page's props as `ConfiguratorErrorPageProps` from `@salsita-ai/sdk/react`, which also exports the helper and the element's name, `ConfiguratorErrorPageName`. A layout element registered under the name `ConfiguratorErrorPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
+
+- The page receives two props. `reason` says what failed: `uncaughtError` when rendering the configurator failed with an error nothing else handled, `presetCreationFailed` when starting a configuration from the only preset failed. `onRetry` tries again: after `uncaughtError` it renders the configurator again, after `presetCreationFailed` it reloads the page. The error itself is not passed; it is logged to the console.
+- The configurator renders the element in two cases: an error reaches the configurator's error boundary, which wraps everything from the scene resources and the session down to the pages, including a failure while the application starts; and creating a configuration fails on a start screen with a single preset. The element is available in both, because the spec and its elements are part of the application before the configurator renders.
+- A registered page that throws does not take the configurator down: the built-in page is shown in its place and the error is logged, until a hot reload replaces or removes the page.
+- Three cases do not show the element. In development the configurator shows its detailed error pages instead. A failed preset creation with more than one preset is a snackbar on the preset screen (see [Loaded Configuration UI](#loaded-configuration-ui) for how a project shows it). The admin's own error page stays the built-in one, while the configurator the admin embeds renders the element.
+
+### App Loader
+
+While the configurator loads, Phoenix shows the app loader: an overlay over the scene's safe area. A layout element registered under the name `AppLoaderContent` replaces what the overlay shows. It receives `phases`, the loading phases running now, each with an `id` and an optional `label` and `progress`; the list can be empty while the loader waits for the scene to start loading. `createAppLoader` registers a component under that name with the same `phases`:
+
+```typescript
+// src/elements/AppLoader.tsx
+export default phx.frontend.createAppLoader(({ phases }) => <span>{phases[0]?.label ?? 'Loading…'}</span>)
+```
+
+- Phoenix keeps the overlay, its place over the safe area and its fade-in; the element is only what it shows.
+- `createAppLoader`, the props type `AppLoaderContentProps` and the element's name, `AppLoaderContentName`, are also exported from `@salsita-ai/sdk/react`.
+- The overlay stays up while a loading phase runs: the session, the project's data, the configuration and the 3D scene. It waits for the scene only when the loaded configuration's layout mounts a canvas, as the built-in layouts and `LayoutSlots.SharedCanvas` do. A `ConfiguratorLayout` without a canvas is not held by the loader: the overlay leaves once the configuration is up.
+- The top-level `appLoader: legacy` key in the spec turns the overlay off.
+- The built-in content is the default `AppLoaderContent` registration in `defaultConfiguratorElements`, see below.
+
+### In-Scene Controls
+
+The spec's built-in controls on the product are rendered through entity elements, one name per control. A project element registered under one of the names replaces that control everywhere the spec places it, in the built-in layouts and in a project layout. Without it, Phoenix renders its built-in control, which is the default registration of the name in `defaultConfiguratorElements`.
+
+| Element name        | Rendered for                   | Props besides `entityId`                                                                                                   | Registration helper                    |
+| ------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `AddEntityFab`      | `sceneEntityAddFab`            | `instanceNames`, `fixableViolations`, `icon`, `label`, `title`, `tooltipVisibility`, `skipMenuWhenOnlyOne`, `hideWhenNone` | `phx.frontend.createAddEntityFab`      |
+| `DeleteEntityFab`   | `sceneEntityDeleteFab`         | `icon`, `label`, `title`, `tooltipVisibility`, `onDelete`, `disabled`, `disabledHint`, `trace`                             | `phx.frontend.createDeleteEntityFab`   |
+| `SelectionHotspot`  | `sceneEntitySelectHotspot`     | `title`, `tooltipVisibility`, `onSelect`                                                                                   | `phx.frontend.createSelectionHotspot`  |
+| `NavigationHotspot` | `sceneEntityNavigationHotspot` | `navigationState`, `title`, `tooltipVisibility`, `onNavigate`                                                              | `phx.frontend.createNavigationHotspot` |
+| `ToolMenuFab`       | `toolMenuFab`                  | `options`, `icon`, `title`, `tooltipVisibility`, `onSelectTool`                                                            | `phx.frontend.createToolMenuFab`       |
+
+```tsx
+// src/elements/SceneControls.tsx
+import { LocalizableMessage } from '@salsita-ai/sdk/react'
+
+const AddEntityButtons = phx.frontend.createAddEntityFab(({ entityId, instanceNames, fixableViolations }) => {
+  const recipes = phx.frontend
+    .useGroupedRecipeOptions(entityId, instanceNames, fixableViolations)
+    .flatMap(group => group.recipes)
+
+  return (
+    <div className="brand-scene-buttons">
+      {recipes.map((recipe, index) => (
+        <button
+          key={index}
+          disabled={recipe.disabled}
+          title={recipe.tooltipTitle}
+          onClick={event => {
+            event.stopPropagation()
+            recipe.handleClick()
+          }}
+        >
+          <LocalizableMessage>{recipe.title}</LocalizableMessage>
+        </button>
+      ))}
+    </div>
+  )
+})
+
+const DeleteEntityButton = phx.frontend.createDeleteEntityFab(({ onDelete, disabled, disabledHint }) => (
+  <button className="brand-scene-button" onClick={onDelete} disabled={disabled} title={disabledHint}>
+    Remove
+  </button>
+))
+
+export default [AddEntityButtons, DeleteEntityButton]
+```
+
+- Each helper registers the element under its name with the props typed by `AddEntityFabElementProps`, `DeleteEntityFabElementProps`, `SelectionHotspotElementProps`, `NavigationHotspotElementProps` or `ToolMenuFabElementProps`, exported with the helpers from `@salsita-ai/sdk/react` and `@salsita-ai/sdk/configurator`. `createCustomPhoenixEntityElement` with the same name works too, with only `entityId` and `children` typed. The component may return `null` to show nothing.
+- The props are the component's settings from the spec, with `tooltipVisibility` already defaulted to `on-hover`, and the actions the built-in control performs. `onDelete` deletes the entity, `onSelect` selects it and `onNavigate` goes to `navigationState`; each pushes the same analytics event as the built-in control, and each can be passed straight to `onClick`: given the click, it stops its propagation, so the click does not also reach the scene. `onSelectTool(toolState)` switches to the tool state of one of the `options`. `disabled` and `disabledHint` say whether deleting would cause a violation the component's `hiddenViolations` do not allow, and why. `trace` logs the deletion's dry run to the console.
+- The add FAB gets no recipes: it reads them with `phx.frontend.useGroupedRecipeOptions(entityId, instanceNames, fixableViolations)`. Each recipe has `handleClick`, which adds it, `disabled` and `tooltipTitle`. Every recipe is dry-run to tell whether it is allowed, so the built-in FAB reads them only while its menu is open, or up front when `skipMenuWhenOnlyOne` applies; a replacement with a menu does the same. Its `handleClick` does not stop the click's propagation, so the replacement does.
+- Where and when the control shows stays with the spec and the scene: the offsets, `showWhen`, the camera limits, `hideWhileDragging` and `occlude` apply to the element as they did to the built-in control. The element is rendered into the scene's HTML layer, with the theme and every `phx.frontend` hook.
+- A project's own control, one the SDK has no built-in for, is an `htmlHotspot` that names an element of the project, as the edge hotspot of [Custom Layout](?path=/docs/layouts-custom-layout--docs#put-a-control-on-the-product) is.
+
 ### Loaded Configuration UI
 
 A layout element registered under the name `ConfiguratorLayout` replaces the whole UI of a loaded configuration, in owner and in read mode, whatever `layout` the spec sets. Without it, Phoenix renders the layout the spec selects. [Custom Layout](?path=/docs/layouts-custom-layout--docs) is a worked example: a fully custom product page with its panel on the left, built from the scene, the safe-area hook and state hooks.
 
 ```typescript
 // src/elements/ConfiguratorLayout.tsx
-import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
 
 const SIDEBAR_WIDTH = 320
 
 export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', () => {
-  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
 
   return (
     <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
@@ -423,18 +559,20 @@ 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.
+- `phx.frontend.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). Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it.
+- With `LayoutSlots.SharedCanvas` mounted, the app loader stays on screen until the scene has loaded. A layout without a canvas is not held by the loader, see [App Loader](#app-loader).
 - 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. 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`.
+- 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 `phx.frontend.usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `phx.frontend.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`. Its composer offers Annotate, which freezes the view for the user to draw and comment on. The configurator page, not the layout, shows the annotation editor and the exporting overlay over whichever layout it renders, a project layout included, and makes the layout inert meanwhile; a layout without a canvas has no view to freeze, so Annotate there attaches nothing. It also shows an image of the assistant chat the user opened (a drawing or a project picture of a reply, or an image of a sent message), inside the safe area the layout measures with `phx.frontend.useSceneSafeArea()` (the gaps its own UI leaves, before any `canvasPadding` fractions scale them), so the panel beside it stays usable, or over the whole configurator where that area is under 240 px in either direction; a layout that measures none, such as a legacy layout, places it inside its canvas padding; that view makes nothing inert, and Close, Escape or loading another configuration closes it. Its Annotate closes it too and opens the annotation editor on the image, whose result is attached to the message being written; it is disabled while that message is full, another annotation shows, or the assistant has banned the user, and a picture whose server does not let the page read it (no CORS headers) offers none.
 - The layout reads the state it has to react to from hooks, listed with what each returns in [Hooks for a Project Layout](#hooks-for-a-project-layout).
-- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints and errors as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it. `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. Some messages stay snackbars either way: a failure to save the configuration and an error of the built-in finalize and other actions. They render into the snackbar root, so a layout that mounts none shows them outside the configurator, in the page's `body`. An error while a preset is applied appears on the preset screen, outside the layout.
+- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints, errors and failed saves as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it; the theme styles them, see [Layout Slots → Styling the snackbars](?path=/docs/phoenix-layout-slots--docs#styling-the-snackbars). `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. A failure to save the configuration, and the first successful save after it, are messages too, so a layout that mounts neither shows no sign of a failed save. An error of the built-in finalize and other actions stays a snackbar either way. It renders into the snackbar root, so a layout that mounts none shows it outside the configurator, in the page's `body`. A failure to start a configuration from a preset is not a message of the hook either: it happens on the preset screen, before any `ConfiguratorLayout` mounts. In production with more than one preset it is a snackbar there, also on a preset screen replaced with `createPresetUi` (see [Preset UI](#preset-ui)), which reads the error from `phx.frontend.usePresetSelection().selectionError` and mounts `PresetSnackbarsRoot` to keep the snackbar inside the configurator. With a single preset it is the [Configurator Error Page](#configurator-error-page). A finalize action the layout runs with `phx.frontend.useFinalizeActions` or `phx.frontend.useFinalizeAction` reports its error as the action'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, the built-in not-found page as a `ConfigurationNotFoundPage` registration, the built-in not-authenticated page as a `NotAuthenticatedPage` registration, the built-in preset screen as a `PresetUi` registration, the built-in error page as a `ConfiguratorErrorPage` registration, the app loader's built-in content as an `AppLoaderContent` registration, and the built-in in-scene controls under the names of [In-Scene Controls](#in-scene-controls). Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default. The list also holds the configurator's built-in controls and layout elements under the kinds the spec names them by, such as `attributeSelect` or `undoToolbarButton`, so a project element registered under one of those names replaces the built-in one wherever the spec names that kind. A config assembled by hand, without generated code, calls `withDefaultElements(defaultConfiguratorElements)` too; the lists are the only way the built-in elements are registered, so without it the page shows a "not found" box instead of the configurator, and a project layout shows one in place of every built-in control. The defaults also hold the configurator's visual providers and the error page and dialog its runtime renders, and a config without them runs the lifecycle without them, with a plain error message in place of the error page. Without them nothing provides the responsive context, so an SDK layout slot that reads it, for example `LayoutSlots.SharedCanvas`, stops the configurator with that plain error message instead of showing a "not found" box, and snackbar messages have no host. The admin mounts a full configurator, so its list, `defaultAdminElements` from `@salsita-ai/sdk/admin`, holds the configurator's defaults followed by the admin's built-in pages, sidebars and actions; generated admin code passes it to `withDefaultElements` in place of `defaultConfiguratorElements`, because each call replaces the defaults passed before.
+
 #### 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.
+A project layout reads the product and the configurator's state through hooks, and changes them through the functions the hooks return. Every hook in these tables is a member of `phx.frontend` and is also exported from `@salsita-ai/sdk/react` under the same name, unless its row names another export. 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**
 
@@ -443,7 +581,7 @@ A project layout reads the product and the configurator's state through hooks, a
 | `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.useComponents({ componentTypes?, entityIds?, instanceNames? })`   | Every matching component on any entity, an omitted field matching everything, 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**
@@ -457,101 +595,336 @@ The other control hooks in [Controls](#controls) take the same two arguments, `u
 
 **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).
+Texts from the spec, such as option titles and the `detail` fields, are `Localizable`, not `string`. `phx.frontend.useResolveLocalizable()` returns a function that turns one into a string in the current language, which suits a list; `phx.frontend.useLocalizable(text)` and `<LocalizableMessage>` from `@salsita-ai/sdk/react` 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.                                                                                                                                                                                                                                    |
-| `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The responsive breakpoints the configurator's container satisfies, as `Viewport[]`, or `null` before it is measured. It follows the container, not the window, so it is the switch between a desktop and a phone layout.                                                 |
+| Hook                                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `phx.frontend.usePreview()`                                                  | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `phx.frontend.useCloseAction()`                                              | The host's close action, `() => Promise<void>`, or `null` when the integration mode offers none. It dispatches the web component's `close` event and, depending on the integration mode, first leaves for the go-back URL of the page's query or puts the configurator on standby. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `phx.frontend.useUndoRedo()`                                                 | `{ canUndo, canRedo, undo, redo }`: whether the undo history has a change to undo or to redo, and two `() => void` functions that undo or redo it, as the toolbar's undo and redo buttons do, pushing the same analytics events; each does nothing while there is nothing to undo or redo. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `phx.frontend.useTabNavigation(options?)`                                    | `{ source, tabs, activeTab, select }` for the spec's tabs: `source` is `'sidebarTabs'` (every active `sidebarTabs` of the selected entity, in spec order) or `'horizontalTabs'` (the first active `horizontalTabs`), or `null` without tabs. Each tab is `{ index, label, icon, iconNode, navigationStates, state, isActive }`, with the label resolved, `icon` a PhxIcon name and `iconNode` a React node given by TypeScript spec code; `activeTab` is the first active tab or `null`. `select(index or navigation state)` enters the tab's first navigation state, as the built-in tabs do, pushing the same analytics event for `horizontalTabs`. `options.source` (`'auto'`, `'sidebarTabs'` or `'horizontalTabs'`) chooses the kind; `'auto'` prefers `sidebarTabs` when both are active, with a warning in development. `options.entityId` reads another entity's `sidebarTabs`. A tab without navigation states is left out, with a warning in development. It does not check read mode. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                   |
+| `phx.frontend.useStepNavigation()`                                           | `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`, read from the first active instance on the root entity, the one the built-in layout shows. Each step is `{ index, label, navigationStates, state, status }`, with the label resolved, `state` the navigation state that enters the step and `status` `'complete'`, `'active'` or `'upcoming'`; while the active navigation state belongs to no step, `activeStep` is `null`, `activeIndex` is -1, every step is `'upcoming'` and the next step is the first one. A single step is both first and last. `next()` and `previous()` enter the following or preceding step, as the built-in step buttons do, pushing the same analytics events; `goTo(index or navigation state)` enters any step, as the header's stepper does, pushing its event. Each does nothing without a step to enter. A step without navigation states is left out, with a warning in development. It enforces no order and does not check read mode. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it. |
+| `phx.frontend.useActiveViewports()`                                          | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+
+**Steps and tabs**
+
+A project layout builds its steps and tabs from the spec, so the structure stays in `navigationSteps`, `sidebarTabs` and `horizontalTabs`, where `$filter` switches it, and the layout decides how it looks. `phx.frontend.useStepNavigation()` gives a wizard its steps with a `status` each, and `next`, `previous` and `goTo`; `phx.frontend.useTabNavigation()` gives tabs with `isActive` each, and `select`. Both enter a navigation state, so controls, cameras and components filtered by `navigationStates` follow. Neither hides anything in read mode or blocks a step on violations: a layout that should not move on while the configuration has a problem requires `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`, because a change with a `fixable` or `fatal` violation is rejected and the committed configuration is never invalid, while a `warning` stays and blocks finalizing. A stepper that offers only earlier steps enables the steps whose `status` is `'complete'`.
+
+```tsx
+export const Wizard = () => {
+  const { steps, activeStep, canGoNext, canGoPrevious, next, previous, goTo } = phx.frontend.useStepNavigation()
+
+  return (
+    <nav aria-label="Steps">
+      <ol>
+        {steps.map(step => (
+          <li key={step.state} aria-current={step.status === 'active' ? 'step' : undefined}>
+            <button type="button" disabled={step.status === 'upcoming'} onClick={() => goTo(step.index)}>
+              {step.index + 1}. {step.label}
+            </button>
+          </li>
+        ))}
+      </ol>
+      <button type="button" disabled={!canGoPrevious} onClick={previous}>
+        Back
+      </button>
+      {canGoNext && (
+        <button type="button" onClick={next}>
+          Next: {steps[(activeStep?.index ?? -1) + 1]?.label}
+        </button>
+      )}
+    </nav>
+  )
+}
+```
+
+**Toolbar**
+
+A layout builds its toolbar from `phx.frontend.useToolbarActions()`, which returns the entries of the spec's `toolbar`, or of the default toolbar without one, as data with the function that runs each; or it places single actions with the per-action hooks below. Each hook does what the built-in toolbar button of the same action does and pushes the same analytics events; opening and closing the layout's own dialogs and popovers push none. `useToolbarActions`, `useMeasurements` and `useAssistantPanel` are exported from `@salsita-ai/sdk/configurator` besides `phx.frontend`, not from `@salsita-ai/sdk/react`. `useToolbarState()` from `@salsita-ai/sdk/configurator` is deprecated in favour of `useToolbarActions()`, or of mounting `LayoutSlots.DesktopToolbar` to keep project element overrides, and `useShareData()` and `useShareSettings()` in favour of `useShareLinks()`. Undo and redo for a single button are `phx.frontend.useUndoRedo()` above, fullscreen is `useIsFullscreenActive()` with `useSetFullscreen()`, and the camera reset is `useResetCamera()`.
+
+| Hook                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useToolbarActions(placement?)` | `{ groups, actions }` for `placement` `'desktop'` (the default), `'mobile'` or `'mobileMenu'`, the `toolbar` component's list of that name. `groups` follows the spec's `toolbarButtonGroup`s, an element outside a group being a group of one, and `actions` is the same entries flattened. Each entry has `key`, `kind`, `label` (the built-in button's title in the current language), and `icon` and `showTitle` from the element's props. By `kind`: `undo` and `redo` with `disabled` and `run`; `fullscreen` with `active` and `run`, which toggles the fullscreen flag; `resetCamera` with `run`; `share`, for which the layout opens its own dialog over `useShareLinks`; `measurements` with `measurements`, the result of `useMeasurements` with the element's `showIndicatorSwitch` applied, and `icons`, the element's icon per unit; `language` with `language`, the result of `useLocaleSwitch`; `help` with `Content`, a component that renders the element's children, which is how the spec declares help content (see [Toolbar](?path=/docs/layouts-toolbar--docs)), or else the help registered with the legacy `createToolbarHelp`; `assistant` with `assistant`, the result of `useAssistantPanel`, and `run`, which opens or closes the panel; `custom` with `name` and `Element`, which renders the project element a `customLayoutElement` names. It leaves out an entry with nothing to offer, such as share with sharing disabled or language with one locale, and an element that is not a toolbar entry. A project element registered under a built-in kind, such as `undoToolbarButton`, replaces that button in `LayoutSlots.DesktopToolbar` but not here. As with `LayoutSlots.DesktopToolbar`, the default toolbar leaves out share, undo and redo for a viewer, and a configured `toolbar` is returned as written. Four differences from the built-in toolbar: the entries keep the spec's order for every placement, where `LayoutSlots.MobileToolbar` renders the `mobile` list reversed; a `toolbarButtonGroup` nested in a group is flattened into it, where the built-in toolbar nests it; the assistant's `showTitle` is the spec's, where the built-in button also hides its title on a phone or tablet-sized layout; and a `helpMenuAction` without children shows the legacy registered help, where the built-in menu action shows an empty dialog. |
+| `phx.frontend.useMeasurements(options?)`     | `{ units, unit, setUnit, hasIndicatorSwitch, indicatorsShown, toggleIndicators, available }`: the units the dimension configuration offers, the one dimensions are shown in and a function that changes it; whether the dimension indicators can be switched (`options.showIndicatorSwitch`, else `applicationConfig.indicatorSwitch`, else `true`), whether they show and a function that switches them; and whether there is anything to set, more than one unit or the switch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `phx.frontend.useLocaleSwitch()`             | `{ locales, locale, setLocale, available }`: the root entity's `applicationConfig.availableLocales` (`['en']` without it) as `{ locale, displayName }`, each named in its own language, the active locale, a function that activates one, and whether there is more than one to choose from. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `phx.frontend.useShareLinks(options?)`       | `{ available, ownerLinkAvailable, readLinkAvailable, ownerLink, readLink, isLoading }`: whether sharing is offered and which kinds of link the application config enables, a link that opens the configuration for editing and one that opens its current revision for viewing, each `null` until generated, and whether one is still being generated. While enabled, each commit of the configuration generates a new read link. Generating a link saves the configuration, so a layout passes `{ enabled: open }` with whether its share dialog is open; `enabled` is `true` by default. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `phx.frontend.useAssistantPanel()`           | `{ available, open, hasUnreadReply, setOpen }`: whether the spec has an `assistant`, whether its panel is open, whether it replied while closed, and a function that opens or closes it. The panel renders only inside `LayoutSlots.DesktopSidebar`, so a layout without that slot does not offer it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+**Assistant**
+
+The assistant panel renders only inside `LayoutSlots.DesktopSidebar`. A project element that shows the conversation or takes a message itself, such as a thread in the layout's own drawer, reads the same state as the panel through two hooks, exported from `@salsita-ai/sdk/configurator` besides `phx.frontend`. They are separate so that a composer does not render again with every chunk of a reply.
+
+| Hook                                  | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `phx.frontend.useAssistantThread()`   | `{ items, earlierItems, isLoaded, isLoadingThread, isEmpty, isReplying, isThinking, isResuming, failure, retry, hasOlderMessages, isLoadingOlderMessages, loadOlderMessages, canLoadEarlierThread, isLoadingEarlierThread, loadEarlierThread, undoableToolCallId, undo, newestMessageKey, firstMessageId }`. `items` is the current thread in reading order, each a `user` message with its `text`, `imageIds`, `annotations` and `voice` (`'transcribing'` while the transcript of a voice message is on its way, `'spoken'` once its text is the transcript, `null` for a typed message), a stretch of assistant `text` with its `markdown` and `playableReplyId` (the id of the reply it ends, when the panel can read that reply aloud, else `null`), a row of `tools` calls in a row, or a `separator`; `earlierItems` are the closed threads loaded above it, oldest first, each ended by a separator. `isLoadingThread` is set while the thread is read and `isEmpty` when there is nothing to show, where the panel greets the user. `isThinking` is set while a reply runs and nothing in the thread shows it yet. `failure` is `{ kind, canRetry }` with `kind` `'notAvailable'`, `'busy'`, `'resting'` (with `minutes` to wait), `'exhausted'`, `'locked'`, `'networkLocked'`, `'unheard'` (nothing was heard in a voice message, which was dropped) or `'unavailable'`, and `retry()` reads the thread again where `canRetry` is set. `'locked'` means the assistant banned the user on this configuration, or on several of the customer's, and `'networkLocked'` that it is paused for the user's network address because of how it was used from there: both are failures even when the thread read succeeded, and neither offers a retry. `loadOlderMessages()` loads the previous page of the thread, which the panel does when its top scrolls into view, and `loadEarlierThread()` the closed thread before the loaded ones, offered by `canLoadEarlierThread` once the thread is loaded whole. `undoableToolCallId` is the tool call whose change a row may take back, never while a reply runs, and `undo(toolCallIds)` takes back a row's changes. A thread that scrolls follows two values: `newestMessageKey`, an opaque value compared by identity that changes with the newest message, also with every chunk of a reply, but not when an older page loads above it; and `firstMessageId`, which changes when one does, so the thread can keep the reader's place. It renders again with every chunk of a reply.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `phx.frontend.useAssistantComposer()` | `{ draft, setDraft, attachments, addFiles, annotate, annotateAttachment, removeAttachment, isPreparing, notice, maxAttachments, isBusy, isLocked, isReplying, canSend, send, stop, inputFocusHandlers, canRecord, recording, startRecording, sendRecording, cancelRecording }` for one message being written. `attachments` are `{ id, previewUrl, isAnnotation, pinCount }`; `addFiles(files)` prepares and attaches images up to `maxAttachments` (four) per message, annotations included, and `removeAttachment(id)` takes one off. `notice` is `'limit'` for a file or annotation too many and `'unreadable'` for a file that is not an image the browser can read, until the attachments change. `annotate()` opens the annotation editor over the configurator, in every layout, and attaches the annotation; it calls `assistantSystem.annotate()`, which attaches what the user made itself and resolves with the attachment's id, or `null`, and which takes `{ image, background }` to annotate an image instead of the view, as the Annotate of an opened image does. `annotateAttachment(id)` opens the editor on an attached image that is not an annotation, as the Annotate of the built-in composer's thumbnail does, and the annotation takes that image's place, so it needs no free slot; it calls `assistantSystem.annotate({ attachmentId, background })`. `isBusy` is set while a send waits for the thread to be resumed or the images to upload, when the input should be read-only. `isLocked` is set while the assistant has banned the user on this configuration, or is paused for the user's network; `canSend` is false then, and nothing should be written or attached. `send()` sends the message when `canSend`, clears it once the chat takes it, and puts it back, after what was written meanwhile, when the chat gives it back; `stop()` ends a reply. Spread `inputFocusHandlers` onto the message input so a phone layout makes room for it. The text of the message lives as long as the component that calls the hook; its attachments live in the assistant system (`assistantSystem.composerAttachments$`), so an annotation made outside the composer is attached too, and a configuration load takes them off. Enter-to-send, pasting and dropping images, Enter sending and Escape dropping a recording, and the cursor put in the input when the panel opens on a desktop are the built-in composer's own: a project composer calls `send` and `addFiles` from its handlers. `canRecord` is set when the user may speak the message instead: the session takes voice messages (see below), the browser can record and no ban refuses the user; the built-in composer then shows a mic in place of Send while the text is empty. `recording` is `{ status, elapsedMs, level }`, with `status` `'idle'`, `'requesting'` while the browser asks for the microphone, `'recording'`, `'recorded'` for a recording the server refused, which waits to be sent again or dropped, `'refused'` while the microphone is blocked for the page, or `'unavailable'` where the browser cannot record; `level` is the loudness of the microphone from 0 to 1. `startRecording()` starts a recording, asking for the microphone, also again after a refusal; `sendRecording()` stops it and sends it, with the attachments, as the message; `cancelRecording()` drops it. A recording that reaches two minutes is sent on its own. |
+
+The panel renders `useAssistantThread`'s items with components that `@salsita-ai/sdk/configurator` exports too. `AssistantThreadItemView({ item, isActive, undoableToolCallId, onUndo })` renders any item as the panel does; `isActive` is set for the newest item while a reply runs, and `undoableToolCallId` and `onUndo` take the hook's `undoableToolCallId` and `undo`. It dispatches to `AssistantUserMessage({ text, imageIds, annotations, voice })`, `AssistantMarkdown({ markdown, isStreaming, forms })` followed by the reply's play button when `playableReplyId` is set, `AssistantToolChips({ tools, isActive, canUndo, onUndo })` and `AssistantSeparator()`, which a project thread can use one by one. `AssistantMarkdown` renders the project's assistant form elements, entity and reference links, alerts, pictures and drawings wherever it is inside the configurator, without further wiring. A drawing is SVG the model wrote in a fenced code block with the language `svg`; it shows framed in the thread as an image, so nothing in it runs or loads, and a click opens it larger beside the panel, as it does a picture of a reply and an image of a sent message. The assistant's prompt lets the model draw when a schematic explains better than words or when it is asked to; a project asks for more drawings, or for particular ones, in its `assistant.instructions`, for example "After reading a photo, draw the layout you deduced and ask the user to confirm it." A spoken message shows a placeholder until its transcript arrives, then the transcript in italics with a mic mark. An entity link selects its entity; inside `EntityLinkSelectionProvider`, given the selection `useCreateEntityLinkSelection()` creates, the thread can call that selection's `release()` on a click elsewhere in the thread to deselect what a link selected, as the panel does.
+
+Voice messages are off unless the spec's `assistant.ai.voice` is `true`; the assistant setup handler can return `ai.voice` to turn them on or off per session, and the composer follows what the server resolved for the session, which the thread read reports. Under `phoenix dev`, an edit of `assistant.ai` reaches the server but not the open page: reload the page to see the mic come or go. A recording is sent as the message, and the server transcribes it once the ban, the monthly caps and the hourly limits accept the message, counting the transcription in the same usage; the transcript becomes the message's text, and the recording is never stored. The browser asks the user for the microphone the first time they record. A configurator embedded in an iframe can record only when the iframe allows it: `<iframe allow="microphone" …>`.
+
+With voice on, the panel also reads replies aloud. Every reply that has something to say, in at most 1,500 characters once its code blocks, tables and images are dropped, has a play button under its text, which reads it aloud and stops it; starting one reply stops the other. The reply to a voice message reads itself aloud once it has ended, unless the user muted that with the speaker button in the panel's header; the browser remembers the choice, and the play buttons work either way. A browser that does not let the page start audio on its own, such as Safari when the reply took long, leaves the reply's play button highlighted instead. The server synthesizes a reply's speech once, from its stored text, the first time it is asked for, holding it to the same ban, monthly caps and hourly limits as a message, and keeps it with the thread. A voice message also asks the model for a short reply written to be heard.
+
+A project thread or composer of its own drives the reading through `phx.frontend.useConfigurator().assistantSystem`: `playReply(messageId)` reads the reply with that id aloud, or stops it while it is read, `stopPlayback()` stops it, `playback$` holds `{ messageId, status }` with `status` `'idle'`, `'loading'`, `'playing'` or `'blocked'` (the browser did not start the reply on its own), and `muted$` and `setMuted(muted)` hold and change the user's choice to mute the replies that read themselves aloud. `isSpeakableReply(message)`, exported from `@salsita-ai/sdk/configurator`, tells whether the server reads a message aloud. A composer of its own calls `unlockPlayback()` on the tap that records or sends a voice message, so Safari lets the reply read itself aloud later, and `stopPlayback()` when the user starts to speak.
+
+**Assistant theme names and slots**
+
+Every part of the assistant panel has its own theme name, set under `components` in the theme a project returns from `phx.frontend.createGetThemeHandler`. Each name takes `styleOverrides` keyed by its element slots, and `defaultProps` with `slots`, a component per slot, and `slotProps`, props per element slot. The props type of each name is exported from `@salsita-ai/sdk/configurator` as `Themeable…Props`, such as `ThemeableAssistantComposerProps`. A theme that sets none of them renders the panel as built in.
+
+| Theme name                                                                 | Element slots                                                                                                                                                                                           | Component slots                                                                      |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `PhxAssistantPanel`                                                        | `root`                                                                                                                                                                                                  | `header`, `thread`, `composer`                                                       |
+| `PhxAssistantPanelHeader`                                                  | `root`, `title`, `muteButton`, `closeButton`                                                                                                                                                            |                                                                                      |
+| `PhxAssistantThread`                                                       | `root`, `messages`, `greeting`, `status`, `olderStatus`, `earlierButton`, `notice`, `newReplyButton`                                                                                                    | `userMessage`, `assistantMessage`, `toolChips`, `separator`                          |
+| `PhxAssistantUserMessage`, `PhxAssistantSeparator`, `PhxAssistantMarkdown` | `root`; `PhxAssistantUserMessage` also `voice` and `transcript`                                                                                                                                         |                                                                                      |
+| `PhxAssistantReplyPlayButton`                                              | `root`                                                                                                                                                                                                  |                                                                                      |
+| `PhxAssistantMessageImages`                                                | `root`, `image`                                                                                                                                                                                         |                                                                                      |
+| `PhxAssistantToolChips`                                                    | `root`, `activity`, `activityIcon`, `chip`, `chipLabel`, `screenshotsLink`, `undoButton`, `violation`, `fullLabel`                                                                                      |                                                                                      |
+| `PhxAssistantComposer`                                                     | `root`, `inputFrame`, `attachments`, `attachment`, `removeAttachment`, `annotateAttachment`, `input`, `toolButton`, `sendButton`, `micButton`, `recordingBar`, `stopButton`, `hint`, `attachmentNotice` |                                                                                      |
+| `PhxAssistantForm`                                                         | `root`, `submitButton`, `fixButton`, `note`                                                                                                                                                             | `group`, `choice`, `choices`, `reply`, `card`, `swatch`, `text`, `number`, `confirm` |
+| `PhxAssistantFormGroup`, `PhxAssistantFormOptions`                         | `root`, `label`; `PhxAssistantFormOptions` also `row`                                                                                                                                                   |                                                                                      |
+| `PhxAssistantFormReply`, `PhxAssistantFormNumber`                          | `root`                                                                                                                                                                                                  |                                                                                      |
+| `PhxAssistantFormCard`                                                     | `root`, `image`, `label`, `description`, `check`                                                                                                                                                        |                                                                                      |
+| `PhxAssistantFormSwatch`                                                   | `root`, `image`, `check`                                                                                                                                                                                |                                                                                      |
+| `PhxAssistantFormText`                                                     | `root`, `input`                                                                                                                                                                                         |                                                                                      |
+| `PhxAssistantFormConfirm`                                                  | `root`, `buttons`, `button`                                                                                                                                                                             |                                                                                      |
+| `PhxAssistantEntityLink`, `PhxAssistantAlert`, `PhxAssistantScreenshots`   | `root`                                                                                                                                                                                                  |                                                                                      |
+| `PhxAssistantReferenceLink`                                                | `root`, `details`                                                                                                                                                                                       |                                                                                      |
+| `PhxAssistantAnnotation`                                                   | `root`, `toolbar`                                                                                                                                                                                       |                                                                                      |
+| `PhxAssistantAnnotationComment`, `PhxAssistantAnnotationBadge`             | `root`                                                                                                                                                                                                  |                                                                                      |
+| `PhxAssistantDrawing`                                                      | `root`, `button`, `image`, `note`                                                                                                                                                                       |                                                                                      |
+| `PhxAssistantImage`                                                        | `root` (the picture), `button` (around it, none inside a link)                                                                                                                                          |                                                                                      |
+| `PhxAssistantImageView`                                                    | `root`, `header`, `title`, `actions`, `annotateButton`, `closeButton`, `image`                                                                                                                          |                                                                                      |
+
+A component slot replaces a whole piece:
+
+- The panel's `header`, `thread` and `composer` take no props. A replacement reads what it shows with `useAssistantPanel`, `useAssistantThread` or `useAssistantComposer`. The panel's shell stays the SDK's whatever replaces them, so the layouts still hide what the panel covers and stretch the sidebar, and a press on a control keeps the input's focus on a phone. A component in `PhxAssistantPanel`'s `root` slot has to pass on the props it gets, `data-sidebar` and `onMouseDown` among them.
+
+A component in an element slot gets that part's props and passes them on to the element it renders. Some slots also get a ref, which the replacement must forward to its element with `forwardRef`: the thread's `messages` (it scrolls), the composer's `input` (through `inputRef`, as an `InputBase`) and `stopButton`, the header's `closeButton`, the tool chips' `chip`, `chipLabel` and `screenshotsLink`, and the reference link's `root`. The controls with a tooltip or a popover are anchored by that ref, and a replacement that drops it loses scrolling, focus or the tooltip.
+
+- The thread's item slots get the props of their item, as `AssistantThreadItemView` passes them to the exported components above. `separator` gets none. `AssistantThreadItemView` also takes them as `slots`, for a project thread that uses it.
+- The form's slots are named after the built-in form elements, and each gets that element's props: `FormContainerProps` for `group`, `choice` and `choices`, `FormOptionProps` for `reply`, `card` and `swatch`, and `FormInputProps` for `text`, `number` and `confirm`, with the element's typed attributes. They change how a form looks, not what the assistant can write. The project's own form elements are registered with `createAssistantFormElement` instead.
+
+The names of the form elements, the links, the alert, the image, the screenshots and the annotation are read from the theme only: their components take no `slots` of their own. A few parts are shared, so their style overrides reach more than one place. The composer's `inputFrame`, `input`, `toolButton` and `sendButton` also draw the comment of an annotation's pin, and `toolButton` is the Attach, the Annotate and the comment's Delete control. `PhxAssistantMessageImages`' `image` also draws the thumbnails of a message's annotations. `PhxAssistantToolChips`' `root`, `activity` and `activityIcon` also draw the "Thinking…" line. State a part is styled by is on its element, such as `data-chip` on a chip, `data-chips` on a row of chips, `data-alert` on an alert, `data-dragging` on the input frame, `data-blocked` on a mic whose microphone is blocked and `aria-pressed` on a picked form option, so a style override targets it with a selector.
+
+```tsx
+import type { ThemeableAssistantThreadProps } from '@salsita-ai/sdk/configurator'
+
+type UserMessageSlot = NonNullable<NonNullable<ThemeableAssistantThreadProps['slots']>['userMessage']>
+
+const UserMessage: UserMessageSlot = ({ text }) => <p className="brand-bubble">{text}</p>
+
+export default phx.frontend.createGetThemeHandler(
+  () =>
+    ({
+      components: {
+        PhxAssistantComposer: { styleOverrides: { inputFrame: { borderRadius: 4 } } },
+        PhxAssistantThread: { defaultProps: { slots: { userMessage: UserMessage } } },
+        PhxAssistantPanel: { defaultProps: { slots: { composer: BrandComposer } } },
+      },
+    }) satisfies ThemeOptions
+)
+```
 
 **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`. |
+| Hook                                              | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useStateValidity()`                 | The validity of the last committed state: `{ valid: true, severity: null }` without violations, or `{ valid: true, severity, entityViolations }`, where `severity` is the most severe violation: `'notice'`, which restricts nothing, or `'warning'`, which blocks finalizing. `entityViolations` lists every violation. 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, `{ kind: 'error', error, text }` when an error is thrown while a change is validated, with `text` the generic "Oops, something went wrong", `{ kind: 'saveError', error, text }` each time saving the configuration fails, with `error` what the save rejected with and `text` a generic message, and `{ kind: 'saveRecovery', text }` when a save succeeds after a failed one, with `text` "Configuration updated". `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, nor is a save that failed before it mounted; 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.useConfigurationSaveState()`        | `{ revisionId, isSaving, failure }`, the save status of the configuration. An editable configuration saves every committed change on its own, three seconds after the last one, and a read-only one never saves. `revisionId` is the revision the configuration is at: the loaded one, then the one the latest save created. `isSaving` is `true` while a save runs. `failure` is `{ error, timestamp }` of the latest failed save, with `timestamp` in milliseconds since the epoch, and `null` once a later save succeeds or another configuration loads. A layout shows a save indicator with it; the messages of a failed save and of its recovery come from `useConfiguratorMessages`. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `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, does nothing while `disabled` or `isPending`, and returns a promise that resolves once the handler has settled and never rejects; `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `phx.frontend.useFinalizeActions()`               | `{ actions, primary, secondary, disabled, hints }`: every active `finalizeAction` of the spec in spec order, `primary` the first `'primary'` one, or else the first, or `null`, and `secondary` the others; see the Finalize paragraph below. Each action is `{ key, handler, variant, label, title, icon, run, isPending, error, disabled }`, with `label` and `title` resolved; `run()` records the finalize-button click for analytics and runs the action's handler, does nothing while `disabled` or `isPending`, and returns a promise that never rejects. `disabled` and `hints` are those of `useFinalizeViolations()`. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
-`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.
+`LayoutSlots.Services` shows every message of `useConfiguratorMessages` as a snackbar, `saveError` and `saveRecovery` included; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
 
 **Finalize**
 
-A project layout finalizes over the spec's `finalizeAction` components. `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`, with `finalizeActionComponent` from `@salsita-ai/sdk/domain`, lists them; each `state` is `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. The built-in footer offers the first `'primary'` action, or else the first action, as its button and the others in a menu, and disables them with `phx.frontend.useFinalizeViolations()`.
+A project layout finalizes over the spec's `finalizeAction` components, each `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. `phx.frontend.useFinalizeActions()` is the convenient way: it lists them with what a button needs, runs their handlers itself, and can be called anywhere in the layout, including a dialog the layout opens with `useModal`, as often as it likes; [Custom Layout](?path=/docs/layouts-custom-layout--docs#request-a-quote) offers its primary action this way in its review step. It returns:
 
-To offer the same buttons, a project layout mounts `<FinalizeActions />` from `@salsita-ai/sdk/configurator`: the built-in footer's finalize buttons, the primary action plus a menu of the others, disabled with the hints of `useFinalizeViolations()`, with a spinner while the handler runs and a snackbar when it fails. It renders nothing without a `finalizeAction`, and it does not check read mode, so a layout hides it while `accessInfo.viewMode` is `true`.
+- `actions`, every active `finalizeAction` in spec order, and `primary` and `secondary`, the same actions split as the built-in footer splits them: `primary` is the first `'primary'` action, or else the first action, or `null` without any, and `secondary` the others in spec order.
+- `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.
 
-To build its own buttons, a layout runs an action with `usePhoenixHandler(action.state.handler).handler()` from `@salsita-ai/sdk/react`, which returns a promise. `usePhoenixHandler` runs the project's handler factory, which calls hooks, so each action gets its own component that calls it once, never in a loop, and that component is wrapped in `<PhoenixHandlerBoundary name={action.state.handler}>` from the same import, so an edited handler takes effect without a reload. The layout then shows the pending state, the error and the disabled state from `useFinalizeViolations()` itself.
+Each action has `key`, a stable key for React, `handler`, `variant`, `label` and `title` resolved to the current language, `icon`, a `PhxIcon` name, and:
 
-## TransformerBuilder
+- `run()`, which records the finalize-button click for analytics and then runs the handler. It does nothing while `disabled` or `isPending`. It returns a promise that resolves once the handler has settled and never rejects, so a menu or a sheet can close after it.
+- `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. A handler that throws while it is loaded, for example because it calls a hook that needs a provider the configurator does not have, makes `error` that error and the action `disabled`.
+- `disabled`, `true` while finalizing is not possible, or when the handler could not be loaded.
 
-Use `transformerBuilder` to create entity transformers:
+```tsx
+export const Finalize = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const { primary, secondary, hints } = phx.frontend.useFinalizeActions()
 
-```typescript
-// Create a transformer that runs when specific conditions are met
-const cabinetTransformer = phx.frontend.transformerBuilder.when(Cabinet.is).do((cabinet, context) => {
-  // Transform cabinet data
-  return {
-    ...cabinet,
-    $computedField: calculateSomething(cabinet),
+  if (accessInfo.viewMode || !primary) {
+    return null
   }
-})
+
+  return (
+    <div>
+      <button
+        type="button"
+        disabled={primary.disabled || primary.isPending}
+        onClick={() => void primary.run()}
+        title={hints}
+      >
+        {primary.isPending ? 'Sending…' : primary.label}
+      </button>
+      {primary.error && <p role="alert">{primary.error.message}</p>}
+      {secondary.map(action => (
+        <button key={action.key} type="button" disabled={action.disabled} onClick={() => void action.run()}>
+          {action.label}
+        </button>
+      ))}
+    </div>
+  )
+}
 ```
 
-**Note**: The deprecated `createTransformer` function should not be used for new implementations.
+The configurator runs the handlers outside the layout, beside it, whenever a configuration is open, also in read mode and on every step. A handler can use what the configurator provides, such as `useModal`, but not a provider the layout itself adds; such a handler fails to load and shows as that action's `error`. An action's `isPending` and `error` are kept while the layout re-renders and while its components unmount and mount again.
 
-## Updates Factory
+To run a single action the layout already knows, `phx.frontend.useFinalizeAction(handler)` runs it in the layout itself and returns `{ run, isPending, error, disabled, hints }`, with the same meaning. It runs the project's handler factory, which calls hooks, so the layout calls it once per component, never in a loop or conditionally, and wraps that component in `<PhoenixHandlerBoundary name={handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload. Its `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`.
+
+Neither hook checks read mode, so the layout hides finalizing while `accessInfo.viewMode` is `true`, as above.
 
-The `updates` factory creates type-safe entity updates:
+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
+
+`transformerBuilder` creates a transformer: a rule that adds updates to a change before it is validated, for example to keep a cabinet's door count in step with its width.
 
 ```typescript
-const { storeSystem } = phx.frontend.useDomain()
+// src/transformers/fixCabinetDoors.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['Cabinet'])
+  .modified({ atFields: ['width'] })
+  .then.applySideEffect(ctx => [
+    phx.frontend.updates.DomainEntityModification({
+      entityId: ctx.update.entityId,
+      stateDelta: { doorCount: ctx.update.stateDelta.width > 600 ? 2 : 1 },
+      updateTag: 'fixCabinetDoors',
+    }),
+  ])
+  .build('fixCabinetDoors')
+```
 
-// Create new entity
-const createUpdates = phx.frontend.updates.create({
-  type: 'Cabinet',
-  width: 800,
-  height: 2000,
-})
+```yaml
+transformers:
+  - name: fixCabinetDoors
+```
 
-// Modify existing entity
-const modifyUpdates = phx.frontend.updates.modify(cabinetId, {
-  width: 1000,
+- `when` picks the updates the transformer reacts to, here a change of a cabinet's `width`, and `then.applySideEffect` returns the updates applied with each of them, built with the [updates factory](#updates-factory).
+- Default-export the transformer from a file in `src/transformers/` and list it in the spec's `transformers` section. The entry's `name` is the name passed to `build`, and the file carries the same name, with case and dashes ignored. A name without a matching file fails the spec check; a name that matches a file but not its `build` name fails when the configurator starts.
+- `priority` is optional, and a lower number runs earlier. The SDK's own transformers run at priorities 10 to 100, and a transformer without a priority runs after them, in spec order, and after the step that turns the controls' component writes into entity updates. Leave it out for a transformer like this one: with a priority it runs before that step, so a width set with a slider reaches it as a component write, which `modified` does not match, and it never fires. See the [transformer pipeline](?path=/docs/other-features-transformers--docs).
+- The transformer also runs when a control dry-runs an option to decide whether to disable it, so it only returns updates and stays cheap.
+
+[Transformers](?path=/docs/other-features-transformers--docs) explains the triggers, the context and the actions. `transformerBuilder` replaces the deprecated transformer factory of `phx.frontend`; do not use that factory for new transformers.
+
+## Updates Factory
+
+`phx.frontend.updates` builds the updates that change the configuration, typed by your domain model. Transformers return them, and a project control hands them to a control hook that commits them.
+
+| Member                                                                              | Update                                                                                                                                         |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DomainEntityModification({ entityId, stateDelta, updateTag })`                     | Sets the fields of `stateDelta` on the entity.                                                                                                 |
+| `DomainEntityCreation({ entity, parentId, collection?, updateTag })`                | Adds `entity`, with its own `id`, under the parent; `collection` names the parent's relation it joins, such as `'Cabinet.$shelves'`.           |
+| `DomainEntityReplacement({ entityId, replacementEntity, keepChildren, updateTag })` | Replaces the entity with `replacementEntity`, keeping its children when `keepChildren` is `true`.                                              |
+| `EntityDeletion({ entityId, updateTag })`                                           | Deletes the entity; the entities it is composed of are deleted with it.                                                                        |
+| `ComponentModification({ componentInstance, writableState, updateTag })`            | Writes a component's writable state, as the built-in controls do. Project code prefers the entity updates, which keep the intent in the model. |
+
+The factory also has `EphemeralRecordCreation`, `EphemeralRecordModification` and `EphemeralRecordDeletion`. Every update takes `updateTag`, a name for why it was made, which tracing shows and the [update type guards](#update-type-guards) match. An update can also take `hint`, a text shown to the user as a side-effect message once the change is committed, see `useConfiguratorMessages`.
+
+A UI applies updates through a control hook. It dry-runs them against the invariants and returns `{ disabled, hints, update, stage, trace }`: `disabled` is `true` when the change would be rejected, because it leaves a `fixable` or `fatal` violation, and `hints` says why; `update()` commits the change, `stage()` shows it without committing, and `trace()` logs the dry run. `useUpdatedControl(updates, fixableViolations?)` takes one set of updates:
+
+```tsx
+// src/elements/WidenCabinet.tsx
+import { useMemo } from 'react'
+
+export default phx.frontend.createCustomPhoenixEntityElement('WidenCabinet', () => {
+  const cabinet = phx.frontend.useSelectedEntity(phx.domain.enhancedModel.$Cabinet)
+
+  const updates = useMemo(
+    () =>
+      cabinet
+        ? [
+            phx.frontend.updates.DomainEntityModification({
+              entityId: cabinet.id,
+              stateDelta: { width: cabinet.width + 100 },
+              updateTag: 'widenCabinet',
+            }),
+          ]
+        : [],
+    [cabinet]
+  )
+  const { update, disabled, hints } = phx.frontend.useUpdatedControl(updates)
+
+  return (
+    <button type="button" disabled={!cabinet || disabled} title={hints} onClick={() => update()}>
+      Widen by 100 mm
+    </button>
+  )
 })
+```
 
-// Delete entity
-const deleteUpdates = phx.frontend.updates.delete(cabinetId)
+`useUpdateControl(fixableViolations?)` returns the same as a function, for a list of options each with its own updates:
 
-// Apply updates
-storeSystem.stageAndCommit(createUpdates)
+```typescript
+const prepare = phx.frontend.useUpdateControl()
+
+const widthOptions = [600, 800, 1000].map(width => ({
+  width,
+  ...prepare([
+    phx.frontend.updates.DomainEntityModification({
+      entityId: cabinet.id,
+      stateDelta: { width },
+      updateTag: 'setCabinetWidth',
+    }),
+  ]),
+}))
 ```
 
+- `fixableViolations` leaves those violation types out of `hints`; the control stays disabled while the change would leave them, unless a transformer repairs the change in the dry run.
+- To add entities from the UI, prefer recipes with `useGroupedRecipeOptions` and `useCookedRecipes`, and to replace one, `useReplaceEntityRecipeOptions` and `useCookedReplaceRecipes`; recipes give the new entities fresh ids.
+- `storeSystem.stageAndCommit(updates)` from `phx.frontend.useDomain()` commits updates without the dry run, so the UI cannot disable a change that would be rejected; the control hooks call it for you.
+
 ### Update Type Guards
 
 ```typescript
-// Check update types
-phx.frontend.isCreateEntityUpdate(update)
-phx.frontend.isReplaceEntityUpdate(update)
-phx.frontend.isDeleteEntityUpdate(update)
-phx.frontend.isAngleDimensionUpdate(update)
-phx.frontend.isDistanceDimensionUpdate(update)
-phx.frontend.isAttributeSelectionUpdate(update)
-phx.frontend.isSwatchSelectionUpdate(update)
+// Updates of the built-in recipe and delete controls, for the given entity types
+phx.frontend.isCreateEntityUpdate(update, ['Shelf'])
+phx.frontend.isReplaceEntityUpdate(update, ['Cabinet'])
+phx.frontend.isDeleteEntityUpdate(update, ['Shelf'])
+
+// Updates of a built-in control, for the given entity types and the instance name of its component
+phx.frontend.isAttributeSelectionUpdate(update, ['Cabinet'], 'finish')
+phx.frontend.isAttributeSwitchUpdate(update, ['Cabinet'], 'softClose')
+phx.frontend.isSwatchSelectionUpdate(update, ['Cabinet'], 'frontMaterial')
+phx.frontend.isTextValueUpdate(update, ['Cabinet'], 'engraving')
+phx.frontend.isDistanceDimensionUpdate(update, ['Cabinet'], 'width')
+phx.frontend.isAngleDimensionUpdate(update, ['Cabinet'], 'doorAngle')
+phx.frontend.isGenericDimensionUpdate(update, ['Cabinet'], 'shelfCount')
 ```
 
+Each guard also checks the `updateTag` the SDK's control or recipe sets, so it does not match an update a project builds with its own tag.
+
 ## Admin Interface
 
 For admin panel development, use `phx.frontend.admin`:
 
 ```typescript
 // Admin-specific hooks
-const entityState = phx.frontend.admin.useEntityState(AdminEntity, entityId)
+const entityState = phx.frontend.admin.useEntityState(entityId)
 const selectEntity = phx.frontend.admin.useSelectEntity()
 const domain = phx.frontend.admin.useDomain()
 ```
@@ -571,14 +944,14 @@ const NotAuthorizedAdminPage = phx.frontend.admin.createNotAuthorizedAdminPage((
 ```
 
 When no authentication-error page is registered, Phoenix falls back to the registered not-authorized page and then
-to the default configuration-not-found page.
+to the built-in configuration-not-found page. The admin shows the built-in page even when the project registers a `ConfigurationNotFoundPage`, see [Configuration Not Found Page](#configuration-not-found-page).
 
 ## What We Learned
 
 In this guide, we covered Phoenix's Configurator Interface:
 
 - **Global namespace** - Access via `phx.frontend` and `Phx` type namespace
-- **Auto-generation** - Interface is generated in `.phoenix/configurator-interface.ts`
+- **Auto-generation** - Interface is generated in `.phoenix/configurator-globals.ts`
 - **Core hooks** - State, selection, navigation, controls, validation, and more
 - **Handler functions** - Lifecycle providers and UI component factories
 - **TransformerBuilder** - Type-safe entity transformations