@salsita-ai/sdk 0.50.0-develop.f16492b14e → 0.50.0-develop.f354d3576d

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
@@ -192,31 +196,35 @@ 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
@@ -225,24 +233,31 @@ const { disabled, hints } = phx.frontend.useFinalizeViolations()
 // 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 all of them,
+// leaving out the ignored types (so the hint is empty when only ignored types reach the top priority)
 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'
 
-// Root entity components
-const rootComponents = phx.frontend.useRootComponents(filter)
-const firstRootComponent = phx.frontend.useFirstRootComponent(filter)
+// 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] })
 
-// Rendered variants
-const renderedComponent = phx.frontend.useRenderedComponent(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 take the same arguments
+const renderedDetail = phx.frontend.useRenderedComponent({ entityId, componentType: detailComponent })
 ```
 
 ### Data & Services
@@ -352,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
@@ -372,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
@@ -545,12 +563,12 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - 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 `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`.
+- 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, only in the built-in layout, which hosts the annotation editor over the configurator; a project layout gets the panel without it.
 - 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, 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 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.
+`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
 
@@ -563,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**
@@ -633,19 +651,19 @@ export const Wizard = () => {
 
 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 or else the help registered with `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 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 spec's `availableLocales` 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 **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.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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -708,67 +726,129 @@ Instead of its own buttons, a project layout can mount `<FinalizeActions />` fro
 
 ## TransformerBuilder
 
-Use `transformerBuilder` to create entity transformers:
+`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
-// 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),
-  }
-})
+// 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')
 ```
 
-**Note**: The deprecated `createTransformer` function should not be used for new implementations.
+```yaml
+transformers:
+  - name: fixCabinetDoors
+```
+
+- `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
 
-The `updates` factory creates type-safe entity updates:
+`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.
 
-```typescript
-const { storeSystem } = phx.frontend.useDomain()
+| 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. |
 
-// Create new entity
-const createUpdates = phx.frontend.updates.create({
-  type: 'Cabinet',
-  width: 800,
-  height: 2000,
-})
+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)
 
-// Modify existing entity
-const modifyUpdates = phx.frontend.updates.modify(cabinetId, {
-  width: 1000,
+  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()
 ```
@@ -795,7 +875,7 @@ to the built-in configuration-not-found page. The admin shows the built-in page
 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

package/dist/docs/phoenix/deployments.mdx

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