@salsita-ai/sdk 0.50.0-develop.ae52227c7e → 0.50.0-develop.ae9a830ef0

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

@@ -158,26 +158,31 @@ const viewState = phx.frontend.useActiveViewState()
 const toolState = phx.frontend.useActiveToolState()
 
 // Navigation actions
-const navigate = phx.frontend.useNavigate()
-const pushNavigate = phx.frontend.usePushNavigate()
-const popNavigate = phx.frontend.usePopNavigate()
+const navigate = phx.frontend.useNavigate() // navigate(state) replaces the active state and clears the history
+const pushNavigate = phx.frontend.usePushNavigate() // pushNavigate(state) remembers the active state for popNavigate
+const popNavigate = phx.frontend.usePopNavigate() // popNavigate() returns to the remembered state, if there is one
+
+// Fullscreen: a flag in the configurator's state that the layout honours; it does not put the browser into fullscreen
+const isFullscreen = phx.frontend.useIsFullscreenActive()
+const setFullscreen = phx.frontend.useSetFullscreen() // setFullscreen(true) or setFullscreen(false)
 ```
 
 ### Controls
 
 ```typescript
-// Control hooks for UI inputs
-const swatchSelection = phx.frontend.useSwatchSelection(entityId, controlId)
-const textValue = phx.frontend.useTextValue(entityId, controlId)
-const attributeSelection = phx.frontend.useAttributeSelection(entityId, controlId)
-const attributeSwitch = phx.frontend.useAttributeSwitch(entityId, controlId)
-const distanceDimension = phx.frontend.useDistanceDimension(entityId, controlId)
-const angleDimension = phx.frontend.useAngleDimension(entityId, controlId)
-const genericDimension = phx.frontend.useGenericDimension(entityId, controlId)
+// Control hooks for UI inputs: the entity id and the instance name of the control component on it
+// useSwatchSelection requires its third argument, the fixable violation types
+const swatchSelection = phx.frontend.useSwatchSelection(entityId, instanceName, [])
+const textValue = phx.frontend.useTextValue(entityId, instanceName)
+const attributeSelection = phx.frontend.useAttributeSelection(entityId, instanceName)
+const attributeSwitch = phx.frontend.useAttributeSwitch(entityId, instanceName)
+const distanceDimension = phx.frontend.useDistanceDimension(entityId, instanceName)
+const angleDimension = phx.frontend.useAngleDimension(entityId, instanceName)
+const genericDimension = phx.frontend.useGenericDimension(entityId, instanceName)
 
 // Update control
 const updateControl = phx.frontend.useUpdateControl()
-const updatedControl = phx.frontend.useUpdatedControl(entityId, controlId)
+const updatedControl = phx.frontend.useUpdatedControl(updates)
 ```
 
 ### Recipes & Entity Creation
@@ -203,15 +208,19 @@ const deletedEntity = phx.frontend.useDeletedEntity()
 ### Validation & Violations
 
 ```typescript
-// State validity
+// Validity of the last committed state; a rejected change never becomes committed, so it is not seen here
 const validity = phx.frontend.useStateValidity()
 
-// Control violations
-const controlViolations = phx.frontend.useControlViolations(entityId, controlId)
+// Control violations: takes the violation types to ignore and returns a function that maps a prepared
+// state emission to { disabled, hints, violations }
+const controlViolations = phx.frontend.useControlViolations([])
 
 // Finalize violations
 const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
+// Messages for the user: violations of a rejected change, side-effect hints and errors, one call each
+phx.frontend.useConfiguratorMessages(message => showToast(message.text))
+
 // Map violations to hints
 const mapViolationHints = phx.frontend.useMapViolationHints()
 ```
@@ -386,7 +395,7 @@ const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNot
 
 ### 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.
+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
@@ -416,10 +425,70 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - `LayoutSlots.SharedCanvas` renders the scene. It is absolutely positioned and fills its nearest positioned ancestor, so the layout's root is positioned and covers the page. The layout positions its own UI above the canvas and after it in the markup, as the `aside` does; unpositioned content is painted under the canvas.
 - `useSceneSafeArea()`, called without arguments, tells the camera which part of the canvas the UI leaves free. Attach `containerRef` to the element that covers the whole canvas and `safeAreaRef` to the region the scene should stay visible in: the hook measures the gap between the two and the camera frames the scene inside the safe area. Without it the scene is framed in the whole canvas. The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'` to leave orbiting and clicking to the scene. A `canvasPadding` component in the spec scales the measured gaps, see [Canvas Padding](?path=/docs/layouts-canvas-padding--docs).
 - The layout has to mount `LayoutSlots.SharedCanvas`, or the project sets `appLoader: legacy`. Otherwise the app loader stays on screen.
-- The layout composes the rest from what `@salsita-ai/sdk/configurator` exports: `LayoutSlots.Services` and the other members of `LayoutSlots`.
-- Nothing of the built-in layouts is rendered for it. The finalize page is `Legacy.CommonFinalizePage`, the dialog is `LayoutDialog`, and 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 not available to a project layout.
+- 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`.
+- 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.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
+#### Hooks for a Project Layout
+
+A project layout reads the product and the configurator's state through hooks, and changes them through the functions the hooks return. Each row names where its hook comes from; the `phx.frontend` hooks in these tables are also exported from `@salsita-ai/sdk/react` under the same name. No hook looks at read mode: the control hooks and the navigation and fullscreen setters keep working while `accessInfo.viewMode` is `true`, so the layout decides what a viewer can change.
+
+**The product**
+
+| Hook                                                                            | Returns                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useRootEntityId()`                                                | The id of the root entity, which the control hooks take.                                                                                                                                                                                                                                                                        |
+| `phx.frontend.useSelectedDomainEntityId()`                                      | The id of the selected entity, or the root entity's id while nothing is selected.                                                                                                                                                                                                                                               |
+| `phx.frontend.useFirstRootComponent(componentType)`                             | The first component of that type on the root entity as `{ componentInstance, state }`, or `null` without one. It takes a component type such as `detailComponent` from `@salsita-ai/sdk/domain`, or an array of them. The `detail` component's `state` is `{ title, subtitle, description, thumbnailUrl? }`, all `Localizable`. |
+| `phx.frontend.useComponents({ componentTypes, entityIds?, instanceNames? })`    | Every matching component on any entity, as `{ componentInstance, state }[]`. Its type on `phx.frontend` includes `null`, but it returns an empty array when nothing matches.                                                                                                                                                    |
+| `phx.frontend.useRootEntityPrice()` and `phx.frontend.useEntityPrice(entityId)` | The value of the entity's `price` component formatted as currency for the current locale, in the component's `currency` or `USD`, or `null` without a `price` component.                                                                                                                                                        |
+
+**Controls**
+
+| Hook                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useAttributeSelection(entityId, instanceName)` | `{ value, options }`. Each option has `title` and `description` (`Localizable`, the spec's `label` and `description`), `value`, `imageSrc` (the spec's `img`), `disabled`, `error`, `hint` (a `string` saying why it is disabled, or `undefined`) and `onSelect()`, which writes the option; the selected option's `onSelect` does nothing. It throws when the entity has no `attributeSelection` component named `instanceName`. |
+| `phx.frontend.useAttributeSwitch(entityId, instanceName)`    | `{ state, onChange, disabled, error, hint }`: `state.value` is the boolean and `onChange()` writes its opposite. It throws without the component.                                                                                                                                                                                                                                                                                 |
+
+The other control hooks in [Controls](#controls) take the same two arguments, `useSwatchSelection` a required third. `useSwatchSelection` returns `{ value, options }`, where `value` is the selected swatch key and each option is `{ swatchName, onClick, swatchKey, selected, thumbnailUrl, disabled, color, hint?, trace? }`; `useTextValue` and the dimension hooks return `{ value, hints, hasErrors, update, resolve, trace }` instead, where `update(value)` stages a value the scene shows at once (`useTextValue`'s is an `onChange` handler, `update(event, value)`) and `resolve()` commits it, or rolls it back when it breaks an invariant. Their TypeScript types give the exact shapes, and [Custom Controls](?path=/docs/controls-custom--docs) lists them.
+
+**Texts**
+
+Texts from the spec, such as option titles and the `detail` fields, are `Localizable`, not `string`. `useResolveLocalizable()` from `@salsita-ai/sdk/react` returns a function that turns one into a string in the current language, which suits a list; `useLocalizable(text)` and `<LocalizableMessage>` resolve a single text, see [Localization](?path=/docs/phoenix-localization--docs).
+
+**Mode, fullscreen, preview and navigation**
+
+| Hook                                                                         | Returns                                                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                               |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                              |
+| `usePreview()` from `@salsita-ai/sdk/configurator`                           | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`.                                                                                                                              |
+| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state, one of the spec's `navigationStates`.                                                                                                                                                                                                       |
+| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | `(state) => void`, which enters a state and remembers the active one, and `() => void`, which returns to the remembered state and does nothing when there is none. `phx.frontend.useNavigate()` returns `(state) => void`, which enters a state and forgets the history. |
+| `phx.frontend.useActiveViewState()` and `phx.frontend.useActiveToolState()`  | The active view state and tool state.                                                                                                                                                                                                                                    |
+| `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.                                                 |
+
+**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`. |
+
+`LayoutSlots.Services` shows the messages of `useConfiguratorMessages` as snackbars; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
+
+**Finalize**
+
+A project layout finalizes over the spec's `finalizeAction` components. `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`, with `finalizeActionComponent` from `@salsita-ai/sdk/domain`, lists them; each `state` is `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. The built-in footer offers the first `'primary'` action, or else the first action, as its button and the others in a menu, and disables them with `phx.frontend.useFinalizeViolations()`.
+
+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`.
+
+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.
+
 ## TransformerBuilder
 
 Use `transformerBuilder` to create entity transformers:

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

@@ -565,9 +565,13 @@ A relation pair can have at most one composition owner. For an ownership relatio
 Relations are validated when the application spec is parsed:
 
 - **Every relation must be declared from both sides.** A relation on `A` targeting `B` needs a counterpart declared on `B` (or on an alias containing `B`) pointing back at `A` — with the opposite kind (`direct` ↔ `indirect`, `allOfType` ↔ `allOfType`) and the same `field`. A missing or mismatched counterpart fails parsing with `RELATION_MISSING_COUNTERPART`. Self‑referencing relations (target is the declaring type) act as their own counterpart and are exempt.
+- **The field of a relation must hold references to the entities the relation relates to.** A `direct` relation reads a field of the entity it is declared on, and the field must reference exactly the entity types of the target. An `indirect` relation reads a field of the target, and the field must reference exactly the entity types the relation is declared on. A field that is not a `DomainEntityId` with `references` fails parsing with `RELATION_FIELD_NOT_REFERENCE`, and one that references other entity types with `RELATION_FIELD_REFERENCES_OTHER_TYPES`.
+- **The field of a `direct` relation must hold its references the way the cardinality needs.** `1-1` needs one reference that is never `null`, `0-1` one reference or `null`, and `0-N` or `1-N` an array of references. Anything else fails parsing with `RELATION_FIELD_CARDINALITY_MISMATCH`. An `indirect` relation takes any of the three, because its cardinality counts the entities that point back.
 - **At most one side may carry `composedOf: true`.** A pair may have one owner or no owner. Two owning sides fail parsing with `RELATION_COUNTERPART_COMPOSED_OF_MISMATCH` because the pair would define ownership in both directions.
 - **Every entity type must be reachable from the root** through `composedOf` edges, otherwise parsing fails with `RELATION_ENTITY_NOT_IN_COMPOSITION_TREE`.
 
+**What the field checks leave out.** A field whose schema states its type as text (`tsType`) or combines schemas with `allOf` is not checked, because the parser cannot tell what it holds. With a wrong field of that kind a `direct` relation fails when it is read, and an `indirect` relation finds no related entities and fails only if its cardinality requires one. When an alias holds the field, the relation is accepted if the field fits in at least one entity type of the alias.
+
 **Why both sides?** The two declarations feed two different runtime systems. The `direct` side owns the id field and generates the reference bookkeeping: dangling ids are pruned when the referenced entity is deleted, and ids are written on create and replace. The `composedOf: true` side generates the composition edge: cascade deletes, the scene hierarchy, and the reachability check. Because these can be different entities — a parent may collect children by reverse lookup (`indirect` + `composedOf: true`) while each child stores the id — dropping either declaration silently disables one of the systems: without the parent side, deleting the parent leaves its children orphaned; without the child side, deleted entities leave dangling ids behind. The missing side also cannot be generated automatically, because the stored id field is compatible with many different relations: the reverse accessor's name is public API, and its cardinality (`0-N`, `1-N`, or a `0-1` slot) changes the generated types, state validation, and UI affordances without changing the stored data at all. Requiring both declarations turns these mistakes into parse errors instead of runtime surprises, and the redundancy lets the parser cross‑check the pair — a typo in `field` or a doubled owner is caught immediately.
 
 ### Picking a relation kind

package/dist/docs/phoenix/finalization.mdx

@@ -15,7 +15,7 @@ Finalization is Phoenix's system for completing configurator sessions and proces
 
 > For integration-specific finalization flows — how host-specific data is passed in and how the host is notified on completion (event dispatch in `headless`, redirect in `handoff`) — see [Finalization (Internal)](?path=/docs/phoenix-integration-finalization-internal--docs) and [Finalization (External)](?path=/docs/phoenix-integration-finalization-external--docs).
 
-Phoenix selects one primary footer action and places additional finalization actions in its menu. A configured `finalizePage` opens in a dialog. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior.
+The universal sidebar footer offers the spec's `finalizeAction` components: Phoenix selects one primary footer action and places additional finalization actions in its menu. It never opens a `finalizePage`; the `finalizePage` and `finalizeButton` components are legacy, declared only in TypeScript, and used by the basic sidebar footer and the legacy layouts. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior.
 
 ## How Finalization Works
 

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

@@ -0,0 +1,114 @@
+# Layout Slots
+
+A project layout registered as `ConfiguratorLayout` builds its UI from its own components and from the pieces of the built-in layout it wants to keep. Those pieces are the members of `LayoutSlots`, from `@salsita-ai/sdk/configurator`. This page lists every member: what it shows, what in the spec or the configurator's state feeds it, what it renders when the spec configures nothing for it, and what it does in read mode. [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) says what a project layout has to mount, and its [Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout) list the hooks for a layout that draws its own UI.
+
+- [How the slots behave](#how-the-slots-behave)
+- [Canvas and services](#canvas-and-services)
+- [Desktop sidebar](#desktop-sidebar)
+- [Header, toolbar and controls](#header-toolbar-and-controls)
+- [Banners and branding](#banners-and-branding)
+- [Page footer](#page-footer)
+- [Phone layout](#phone-layout)
+- [Others](#others)
+
+## How the slots behave
+
+```tsx
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+// Part of a ConfiguratorLayout: the built-in toolbar, placed by the layout in the bottom right corner
+export const Toolbar = () => (
+  <div style={{ position: 'absolute', insetBlockEnd: 24, insetInlineEnd: 24 }}>
+    <LayoutSlots.DesktopToolbar />
+  </div>
+)
+```
+
+- A slot takes no props unless its row names them, and reads what it shows from the spec and the configurator's state. It renders inside the configurator only, under a `ConfiguratorLayout`.
+- A slot brings its own look but not its place: it adds no padding or scrolling around itself, so the layout puts it in a container. Two members differ: `SharedCanvas` fills its nearest positioned ancestor, and `DesktopSidebar` brings the sidebar's spacing and scrolling with it.
+- Read mode means `useAccessService().accessInfo.viewMode` is `true`: a configuration shared for viewing is open, or the host sets the `readonly` property. "No change" in the read-mode column means the slot renders the same for a viewer, so the layout decides whether a viewer sees it.
+- `Desktop*` and `Mobile*` members are twins that differ in size and arrangement; [Phone layout](#phone-layout) lists the phone ones. The container's width, not the window's, decides which one fits: `useActiveViewports()` from `@salsita-ai/sdk/react` returns the breakpoints the container satisfies.
+
+## Canvas and services
+
+| Member                 | Shows                                                                                                                                                                                                                                                                                                                        | Fed by                                                        | With nothing configured | Read mode |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------- | --------- |
+| `SharedCanvas`         | The 3D scene, in a container that is `position: absolute; inset: 0` with the scene's background colour. The scene is hidden for a moment while the preview expands or collapses.                                                                                                                                             | The scene of the spec, through `Canvas`                       | Always renders          | No change |
+| `Canvas`               | The WebGL canvas alone, or `GPUIssuePage` when the browser has no WebGL or no GPU acceleration. It reports the scene-assets loading phase the app loader waits for.                                                                                                                                                          | The scene, the canvas settings and the `CanvasLoader` element | Always renders          | No change |
+| `Services`             | Nothing visible: it mounts `InvariantViolations` and `SideEffects`, which show the messages of `useConfiguratorMessages()` as snackbars                                                                                                                                                                                      | The configurator's state                                      | Always mounted          | No change |
+| `InvariantViolations`  | When a change is rejected, a snackbar for each violation of the rejected state, including notices and warnings already present, as `<entity id>: <message>` (a `notice` as info, a `warning` as warning, `fixable` and `fatal` as error), and "Oops, something went wrong" for an error thrown while the state was validated | The spec's invariants                                         | Nothing                 | No change |
+| `SideEffects`          | An info snackbar for each committed update that carries a hint                                                                                                                                                                                                                                                               | The hints of committed updates                                | Nothing                 | No change |
+| `DesktopSnackbarsRoot` | The element the snackbars are rendered into: a stack anchored to its bottom edge, at most 320 pixels wide                                                                                                                                                                                                                    | Every snackbar the configurator raises                        | An empty element        | No change |
+
+- Mount `SharedCanvas`, not `Canvas`: `Canvas` suspends while it probes the GPU on its first mount, and `SharedCanvas` holds the boundary that catches it. Without either, the app loader stays on screen unless the project sets `appLoader: legacy`.
+- `SharedCanvas` fills its nearest positioned ancestor and paints an opaque background, so the layout positions its own UI after it in the markup.
+- Snackbars are raised by `Services`, and also by the built-in finalize and footer actions when their handler fails and when saving the configuration fails. A layout that shows violations, side-effect hints and validation errors its own way calls `phx.frontend.useConfiguratorMessages(onMessage)` instead of mounting `Services`, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout); the other snackbars still need a root. They render into the snackbar root the layout mounts; with no root mounted they render into the page's `document.body`, outside the configurator. The desktop root is a zero-height element the snackbars stack upwards from, so the layout places it where their bottom edge belongs. The phone root leaves them fixed to the viewport, see `MobileSnackbarsRoot`.
+
+## Desktop sidebar
+
+| Member                        | Shows                                                                                                                                                                                                                                                                                            | Fed by                                                                                                                                                                                                                                                                                                     | With nothing configured                                                                                                                                                                                                                                                                                                          | Read mode                                                                                                                                                                                                  |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DesktopSidebar`              | The whole built-in desktop sidebar: tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Props: `width`, and `side` (`'start'` or `'end'`, typed `DesktopSidebarSide`; `DesktopSidebarProps` types both)                | The members below                                                                                                                                                                                                                                                                                          | As its parts                                                                                                                                                                                                                                                                                                                     | As its parts. In fullscreen it stays in place, transparent and inert                                                                                                                                       |
+| `DesktopSidebarTabs`          | Tabs that switch the navigation state                                                                                                                                                                                                                                                            | The `sidebarTabs` components of the selected entity; the `horizontalTabs` component is not shown here                                                                                                                                                                                                      | Nothing; also nothing while the summary is shown                                                                                                                                                                                                                                                                                 | No change                                                                                                                                                                                                  |
+| `useSidebarTabs()`            | A hook, `{ tabs, activeTab, onChange }`: each tab is `{ label, icon, value, isActive }`, `activeTab` is the active tab's value or `'none'`, and `onChange(value)` switches to that tab's first navigation state                                                                                  | As `DesktopSidebarTabs`                                                                                                                                                                                                                                                                                    | `tabs` is empty                                                                                                                                                                                                                                                                                                                  | No change                                                                                                                                                                                                  |
+| `DesktopSidebarBackButton`    | A "Back" button. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxDesktopSidebarBackButton`; the application config's `sidebarBackIcon` takes precedence over both                                                                                                    | The sidebar's way back: a navigation state to pop, a stacked property page, or a selected entity other than the root, unless the application config sets `showSelectionBackButton` to `false` or sets `ignoreSelectionInSidebar`                                                                           | Nothing while there is no way back                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
+| `DesktopSidebarContent`       | The property pages of the selected entity with its entity header, a stacked page opened from them, or the summary page while the summary is shown. With the application config's `ignoreSelectionInSidebar` set, every `propertyPage` of every entity shows under the root, whatever is selected | `propertyPage`, `entityHeader`, `simpleSummary` and `customSummaryPage` components, and `ignoreSelectionInSidebar`                                                                                                                                                                                         | Nothing                                                                                                                                                                                                                                                                                                                          | **No change: the controls stay editable.** Limit them with `$filter.modes`, or render something else in read mode                                                                                          |
+| `useSidebarContent(options?)` | A hook, `{ content, goBack, hasMiniSidebar, hasSplitSidebar }`: `content` is what `DesktopSidebarContent` shows, `goBack` is the back action or `null`. `options` sets the `HeaderContainer` and `BodyContainer` components the content is wrapped in                                            | As `DesktopSidebarContent`                                                                                                                                                                                                                                                                                 | `content` is empty                                                                                                                                                                                                                                                                                                               | No change                                                                                                                                                                                                  |
+| `EntityHeader`                | An entity's title, subtitle, description and thumbnail, with its primary and secondary buttons, such as delete or replace. Props, typed `EntityHeaderProps`: `entityId` and `headerComponent`                                                                                                    | The texts and thumbnail from the entity's `detail` component (the title falls back to the entity type); the buttons from the `entityHeader` component passed in                                                                                                                                            | —                                                                                                                                                                                                                                                                                                                                | No change                                                                                                                                                                                                  |
+| `DesktopSidebarFooter`        | The price and the actions                                                                                                                                                                                                                                                                        | `basicSidebarFooter`, `universalSidebarFooter`, `readSidebarFooter`, `hiddenSidebarFooter` or `customSidebarFooter`. The basic footer offers a `finalizeButton`, else a button for a `finalizePage`, else a disabled button; the universal footer offers the `finalizeAction` and `otherAction` components | The basic footer: the price and a finalize button. With a `navigationSteps` component of two or more steps, previous and next step buttons and the finalize button only on the last step; with a summary and no steps, a **Summary** button until the summary is shown; in a preset embed, **Save Template** instead of finalize | With nothing configured, the read footer: price only. The basic footer hides its buttons. **The universal footer still shows its finalize and other actions to a viewer**; limit them with `$filter.modes` |
+
+A sidebar footer with `universalSidebarFooter` does not check read mode, although the component's own description says its buttons are hidden then. A viewer of a shared configuration sees its actions. The `custom` footer renders its children unchanged as well.
+
+## Header, toolbar and controls
+
+| Member                | Shows                                                                                                                        | Fed by                                                                                | With nothing configured                                                                                                                                                                                                                                                                                                                                                                         | Read mode                                                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `DesktopHeader`       | The floating, fixed or custom header                                                                                         | The first `floatingHeader`, `fixedHeader`, `hiddenHeader` or `customHeader` component | The floating header. Nothing with `hiddenHeader` or in fullscreen                                                                                                                                                                                                                                                                                                                               | The floating header shows the back button instead of the step navigation; the fixed header hides its horizontal tabs |
+| `DesktopToolbar`      | The toolbar's button groups                                                                                                  | The `toolbar` component's `desktop` list, or else a default set                       | Default buttons: fullscreen and camera reset; language with more than one locale; share unless sharing is disabled; measurements with more than one dimension or with `indicatorSwitch` on (the default), and help in that group when the project registers a `ToolbarHelp` element; undo and redo; the assistant when the spec has an `assistant` section. In fullscreen, only the exit button | The default set drops share and undo/redo; a configured `toolbar` is shown unchanged                                 |
+| `DesktopViewControls` | A toggle between view states                                                                                                 | The root entity's `viewControls` component and the active view state                  | Nothing without the component or without an active view state                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
+| `DesktopToolControls` | A vertical group of tool buttons that switch the tool state                                                                  | The root entity's `toolControls` component                                            | Nothing without the component                                                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
+| `ToolControls`        | The same component as `DesktopToolControls` and `MobileToolControls`                                                         | As `DesktopToolControls`                                                              | Nothing without the component                                                                                                                                                                                                                                                                                                                                                                   | No change                                                                                                            |
+| `DesktopCallToAction` | **The button that leaves a tool mode, not the finalize button.** Clicking it switches to the component's `exitTo` tool state | An `exitToolModeFab` component, usually filtered to the tool states it belongs to     | Nothing. It throws when more than one is active                                                                                                                                                                                                                                                                                                                                                 | Nothing                                                                                                              |
+
+## Banners and branding
+
+| Member                                 | Shows                                                                                                                                                                                                              | Fed by                                                                                                                                                                                                                       | With nothing configured           | Read mode                                                                                                                     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `DesktopReadonlyBanner`                | "You're viewing a read-only configuration" with an **Edit configuration** button that opens `CloneToEditDialog`. Props: the MUI `Alert` props and `icon`, also settable in the theme as `PhxDesktopReadonlyBanner` | `useIsCloningAllowed()`; its icon from the application config's `readonlyBannerIcon`                                                                                                                                         | Nothing unless cloning is allowed | **It does not check read mode.** The layout renders it only in read mode, as the built-in layout does while not in fullscreen |
+| `MobileReadonlyBanner`                 | An **Edit** button that opens `CloneToEditDialog`. Props: the MUI `Button` props and `icon`, also settable in the theme as `PhxMobileReadonlyBanner`                                                               | As `DesktopReadonlyBanner`                                                                                                                                                                                                   | Nothing unless cloning is allowed | As `DesktopReadonlyBanner`                                                                                                    |
+| `CloneToEditDialog`                    | The "Edit configuration" dialog that creates an editable copy of the configuration and opens it. Props, typed `CloneToEditDialogProps`: `open` and `onClose`                                                       | The open configuration                                                                                                                                                                                                       | —                                 | —                                                                                                                             |
+| `useIsCloningAllowed()`                | A hook, `boolean`: `true` when the application config sets `shareCloneToEdit` and the session's role may create configurations                                                                                     | The application config and the session                                                                                                                                                                                       | `false`                           | Does not check read mode                                                                                                      |
+| `DesktopPoweredBy` / `MobilePoweredBy` | The "Powered by Salsita" mark, a link                                                                                                                                                                              | Its props `visible`, `variant` (`'black'` or `'white'`), `href`, `title`, `slots` and `slotProps`. All but `href` and `title` are also settable in the theme as `PhxDesktopBrandingPoweredBy` / `PhxMobileBrandingPoweredBy` | The mark                          | No change                                                                                                                     |
+
+## Page footer
+
+| Member                           | Shows                                                   | Fed by                                                                                  | With nothing configured | Read mode |
+| -------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------- | --------- |
+| `DesktopFooter` / `MobileFooter` | A footer below the whole layout, not the sidebar footer | The project's `LayoutFooter` element, registered with `phx.frontend.createLayoutFooter` | Nothing                 | No change |
+
+## Phone layout
+
+The phone twins read the same spec as their desktop members.
+
+| Member                    | Shows                                                                     | Differences from the desktop member                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MobileHeader`            | The header                                                                | The floating and fixed headers show a back button and the branding; the back button is hidden with steps and in read mode                                                                                                                                                                                                                                                                 |
+| `MobileToolbar`           | The toolbar                                                               | Reads the `toolbar` component's `mobile` list, rendered in reverse order. The default set has undo and redo, camera reset, fullscreen and the assistant, and drops undo and redo in read mode                                                                                                                                                                                             |
+| `MobileHamburgerMenu`     | A menu button that opens the remaining actions in a dialog                | Reads the `toolbar` component's `mobileMenu` list, or else share, measurements, language and help under the same conditions as the desktop toolbar; share is dropped in read mode. Nothing when the list is empty. Props: `icon` and `closeIcon`, also settable in the theme as `PhxMobileHamburgerMenu`; the application config's `hamburgerIcon` and `toolbarCloseIcon` take precedence |
+| `MobileTabs`              | Scrollable tabs that switch the navigation state                          | Reads the selected entity's `sidebarTabs` or the `horizontalTabs` component, and throws when both are active or when more than one of either is active. Nothing without tabs or while the summary is shown. Unlike the desktop fixed header, it keeps horizontal tabs in read mode                                                                                                        |
+| `MobileViewControls`      | A toolbar button with the active view's icon that opens the list of views | Nothing without the component, an active view state or that view's icon                                                                                                                                                                                                                                                                                                                   |
+| `MobileToolControls`      | The tool buttons                                                          | Same component as `DesktopToolControls`                                                                                                                                                                                                                                                                                                                                                   |
+| `MobileCallToAction`      | The button that leaves a tool mode                                        | Same as `DesktopCallToAction`                                                                                                                                                                                                                                                                                                                                                             |
+| `MobileSidebarBackButton` | A "Back" button                                                           | Same as `DesktopSidebarBackButton`, smaller, with `sidebarBackIcon` taking precedence the same way; its theme name is `PhxMobileSidebarBackButton`                                                                                                                                                                                                                                        |
+| `MobileSidebarContent`    | The property pages                                                        | Same content as `DesktopSidebarContent`                                                                                                                                                                                                                                                                                                                                                   |
+| `MobileSidebarFooter`     | The price and the actions                                                 | Same as `DesktopSidebarFooter`; the universal footer adds the step label and progress                                                                                                                                                                                                                                                                                                     |
+| `MobileSnackbarsRoot`     | The element the snackbars are rendered into                               | It does not position the snackbars: they keep notistack's `position: fixed` and sit at the viewport's edge wherever the root is. The built-in phone layout positions them with its own styles; a project layout styles `notistackSnackbarClasses.container` from `@salsita-ai/sdk/ui`                                                                                                     |
+
+## Others
+
+| Member                    | Shows                                                                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `GPUIssuePage`            | `WebGLNotSupported` or `GPUAccelerationDisabled`, chosen by its `issue` prop. `Canvas` renders it; a layout does not need it    |
+| `GPUIssue`                | The two values of that prop, `'no-gpu'` and `'no-acceleration'`, as a constant and a type                                       |
+| `WebGLNotSupported`       | A full-page message that WebGL is not supported, with a **Go To Homepage** button that returns to the configurator's start page |
+| `GPUAccelerationDisabled` | A full-page message that GPU acceleration is disabled, with the same button                                                     |

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -222,7 +222,7 @@ A build pipeline that receives the source archive of a [`phoenix deploy`](#phoen
 - it refuses an archive over 200 MB, one that extracts to more than 1 GB, or one with more than 100,000 files;
 - it refuses links, special files, absolute paths, paths that leave the folder, names with control characters, and entries that repeat or collide with an earlier one;
 - it refuses an archive it cannot read to the end, such as a truncated upload;
-- it extracts only project files, the same set `phoenix deploy` packs, and reports the entries it left out.
+- it extracts only project files and reports the entries it left out, including the optional `conversation.log` that deploy keeps in the private archive for review.
 
 `<folder>` must be new or empty. When the command refuses an archive, it removes the folder, so a partly extracted project is never built.
 
@@ -705,6 +705,10 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
+To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
+
+The Phoenix agent skill explains how to prepare the transcript: prefer a native session export; otherwise mark a reconstruction as incomplete. Preserve available user/assistant messages and tool calls, cap individual tool results at 16 KiB with explicit truncation markers, and reference images rather than embedding them. Include the agent, export time, source and known omissions. Review and redact credentials or unrelated sensitive content before approving upload. The CLI uploads the file as supplied; it does not collect agent history, redact content, check freshness or verify completeness. Remove the file from the project root to deploy without it. The log counts toward the source archive's existing size limits; there is no separate conversation upload or viewer.
+
 ### `phoenix feedback [message]`
 
 Sends feedback about the SDK, the CLI, the documentation or Studio to the Phoenix team. It needs `phoenix login`: the server records the workspace, user and API token of the sign-in, so the message itself needs no introduction.

package/dist/docs/phoenix/project-structure.mdx

@@ -53,7 +53,8 @@ Every file in `components/`, `elements/`, `expressions/`, `actions/`, `invariant
 (and their `admin/` counterparts) is imported by its location, so its default export must be what that folder's `phx`
 factory returns, or an array of those. A file that exports anything else, such as a plain React component in
 `elements/`, stops the application at start with an `Invalid default export in <file>` error that names the expected
-shape. Keep plain components and helpers in a `_*` folder.
+shape. When several files in `handlers/`, `elements/`, `transformers/`, `components/`, `admin/elements/` and
+`admin/components/` are wrong, the error lists all of them, one numbered line per file. Keep plain components and helpers in a `_*` folder.
 
 ### Admin Folders (src/admin/)
 
@@ -182,7 +183,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 | `tsconfig.json`                                        | Yes             | Managed by Phoenix                     |
 | `eslint.config.js`                                     | Yes             | Managed by Phoenix                     |
 | `prettier.config.js`                                   | Yes             | Managed by Phoenix                     |
-| `.prettierignore`                                      | Yes             | Managed by Phoenix                     |
+| `.prettierignore`                                      | No              | Optional and your own; see below       |
 | `.linguirc`                                            | Yes             | Managed by Phoenix                     |
 | `.nvmrc`                                               | Yes             | Managed by Phoenix                     |
 | `.gitignore`                                           | Partially       | Only in a git repository; see Markers  |
@@ -195,10 +196,12 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 Sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. Earlier SDK versions wrote them once; a project that has them keeps them, and they are yours to edit.
 
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), Phoenix does not write a `.prettierignore`, and a fresh clone or CI checkout of a project has none. `phoenix check` and `phoenix fix` do not read one: they skip `.phoenix/`, `dist/`, the compiled catalogs in `src/locales/`, `pnpm-lock.yaml` and `.linguirc` on their own. A project that runs Prettier directly, as `prettier --check .` or from an editor, can add its own `.prettierignore`. To commit it, add a `!.prettierignore` line after the Phoenix block of `.gitignore`, because that block lists the file. The legacy pipeline writes `.prettierignore` on every sync.
+
 ### DO NOT EDIT (Fully Auto-Generated)
 
 - **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
-- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
+- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
 - `.env.generated`

package/dist/docs/phoenix/testing.mdx

@@ -0,0 +1,140 @@
+# Testing
+
+- [Your application in a test](#your-application-in-a-test)
+- [Run the domain on a preset](#run-the-domain-on-a-preset)
+- [Test a transformer](#test-a-transformer)
+- [Mock a domain context](#mock-a-domain-context)
+- [Options](#options)
+
+A project's tests check its own logic, such as an expression on a preset, a transformer that completes an
+edit, a Blender projection or a migration, against the application the project ships. They run with
+Vitest in Node, without a browser or a server.
+
+## Your application in a test
+
+`createTestApplicationConfig` from `@salsita-ai/sdk/domain` is the way a test builds the project's
+application. It takes the generated application the test imports and returns its application config,
+typed with the project's entities, states and data, with no type argument at the call:
+
+```ts
+import { createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+import { configuratorBuilder } from '../../.phoenix/domain.js'
+
+const config = createTestApplicationConfig(configuratorBuilder)
+
+config.domain.presets // the presets of spec/presets
+config.initialPublishedData // the published data the application starts with
+```
+
+`configuratorBuilder` from `.phoenix/domain.js` is the domain of the configurator: the model, expressions,
+invariants, actions, migrations, presets and the components declared in YAML. `configuratorConfig` from
+`.phoenix/configurator-config.js` is the whole configurator as the browser runs it, with every component,
+handler, element and transformer; it reads the frontend environment when it is imported, so a test that
+uses it stubs `phx.frontendEnv` first.
+
+A test passes the generated export to the helper and does not call the export's methods: they are how the
+SDK assembles an application, not an interface for tests, while the helper's call does not depend on that
+assembly.
+
+## Run the domain on a preset
+
+The config goes into `createDomainRuntime`, which runs the same systems as the configurator:
+
+```ts
+import { vi } from 'vitest'
+
+import { NoopAnalyticsSystem, createDomainRuntime, createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+import { configuratorBuilder, createI18n } from '../../.phoenix/domain.js'
+
+const logger = {
+  info: vi.fn(),
+  error: vi.fn(),
+  warn: vi.fn(),
+  debug: vi.fn(),
+  verbose: vi.fn(),
+  appendToGlobalContext: vi.fn(),
+}
+const config = createTestApplicationConfig(configuratorBuilder)
+const runtime = createDomainRuntime({
+  config,
+  services: { analyticsService: new NoopAnalyticsSystem(), i18n: createI18n(), logger },
+})
+
+runtime.actions.domainContext.configurator.setExecutionMode('finalize')
+runtime.actions.domainData.setDomainData({
+  publishedData: config.initialPublishedData,
+  backendData: undefined,
+  frontendData: {},
+})
+runtime.actions.sessionContext.setSessionContext({ role: 'anonymous', data: {} })
+
+const preset = config.domain.presets[0]!
+runtime.actions.loadedData.completeConfiguratorLoad({
+  initialRevisionId: 'test',
+  initialEntities: preset.initialDomainEntities,
+  modelVersion: config.domain.domainFactory.modelVersion,
+  rootEntityType: preset.rootEntityType,
+  schemaIdentity: runtime.selectors.spec.getConfiguratorFactory(),
+})
+runtime.selectors.domainContext.configurator.getDomainContext().initialize()
+```
+
+## Test a transformer
+
+The domain of `configuratorBuilder` has no code-attached components and no transformers. A test adds the
+ones it needs, the way the configurator and the webhooks add them:
+
+```ts
+// Files that read `phx.domain` at module scope are imported after `.phoenix/domain.js`.
+const { customComponentOptics } = await import('../../.phoenix/configurator-domain-code.js')
+const { default: addCookingTop } = await import('../transformers/add-cooking-top.js')
+
+const config = createTestApplicationConfig(configuratorBuilder, {
+  componentModules: customComponentOptics,
+  transformers: {
+    importedTransformers: [{ origin: 'src/transformers/add-cooking-top.ts', exports: addCookingTop }],
+    specTransformers: [{ name: 'addCookingTop', priority: 30 }],
+  },
+})
+```
+
+`specTransformers` are the entries of the `transformers` section of `spec/application.yaml` that the test
+runs, with the priorities the spec gives them.
+
+## Mock a domain context
+
+`createMockState`, `createMockDomain` and `createMockDomainContext` take the same config and check the
+mock data against the project's types:
+
+```ts
+import { createMockDomainContext, createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+const config = createTestApplicationConfig(configuratorBuilder)
+const preset = config.domain.presets[0]!
+const { domainContext, destroy } = createMockDomainContext(config, {
+  entities: preset.initialDomainEntities,
+  rootEntityType: preset.rootEntityType,
+  publishedData: config.initialPublishedData,
+  frontendData: {},
+  sessionData: {},
+  backendData: undefined,
+  mode: 'owner',
+  role: 'anonymous',
+  transformers: [],
+})
+```
+
+## Options
+
+| Option             | What it does                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `componentModules` | Component files added after the components the application already has, each `{ origin, exports }`                 |
+| `transformers`     | Replaces the application's transformers: files (`importedTransformers`) and spec entries (`specTransformers`)      |
+| `tag`              | The tag of the custom element the application mounts as; without it the application's own (`salsita-configurator`) |
+
+## See Also
+
+- [Best Practices](?path=/docs/phoenix-best-practices--docs) - Where custom code lives
+- [Transformers](?path=/docs/other-features-transformers--docs) - Writing transformers