@salsita-ai/sdk 0.50.0-develop.c28cfb7ded → 0.50.0-develop.d0eaeed131

package/dist/docs/layouts/custom-layout.mdx

@@ -1,6 +1,6 @@
 # Custom Layout
 
-Make the configurator look like the brand's own product page. A furniture shop wants its table configurator to read like the rest of its site: a floating panel on the left with the product's name, the edge finishes as picture cards, the price in large type and one clear call to action, and the table in the space beside it. On a phone the panel becomes a sheet at the bottom, and a button on the table's edge offers the finishes right where they apply. The project writes that page as one React component. Phoenix supplies the 3D scene, the product's state and a few hooks; every pixel around the scene is the project's own.
+Make the configurator look like the brand's own product page. A furniture shop wants its table configurator to read like the rest of its site: a floating panel on the left with the product's name, the edge finishes as picture cards, the price in large type and one clear call to action, and the table in the space beside it. On a phone the panel becomes a sheet at the bottom, and a button on the table's edge offers the finishes right where they apply, and the layout's own buttons switch between the whole table and a close-up of its edge. The project writes that page as one React component. Phoenix supplies the 3D scene, the product's state and a few hooks; every pixel around the scene is the project's own.
 
 - [Choose this approach](#choose-this-approach)
 - [Register the layout](#register-the-layout)
@@ -13,6 +13,7 @@ Make the configurator look like the brand's own product page. A furniture shop w
 - [Serve read mode](#serve-read-mode)
 - [Fit a phone](#fit-a-phone)
 - [Put a control on the product](#put-a-control-on-the-product)
+- [Control the scene](#control-the-scene)
 - [The spec the layout reads](#the-spec-the-layout-reads)
 - [Try the example](#try-the-example)
 - [Test cases](#test-cases)
@@ -44,6 +45,7 @@ import { BottomSheet } from '../_shared/BottomSheet.js'
 import { FullscreenToggle } from '../_shared/FullscreenToggle.js'
 import { MessageToast } from '../_shared/MessageToast.js'
 import { ProductPanel } from '../_shared/ProductPanel.js'
+import { SceneControls } from '../_shared/SceneControls.js'
 
 const GUTTER = 24
 const PANEL_WIDTH = 380
@@ -122,14 +124,26 @@ const ConfiguratorLayout = () => {
             sx={{
               position: 'absolute',
               pointerEvents: 'auto',
-              // Desktop: bottom left. Phone: at the top beside the fullscreen button, clear of the sheet's handle.
+              // Desktop: bottom left, above the row of view controls. Phone: at the top beside the fullscreen button,
+              // clear of the sheet's handle and the view controls.
               ...(isDesktop
-                ? { insetBlockEnd: GUTTER, insetInlineStart: GUTTER }
+                ? { insetBlockEnd: 2 * GUTTER + TOUCH_TARGET, insetInlineStart: GUTTER }
                 : { insetBlockStart: gutter, insetInline: `${gutter}px ${2 * gutter + TOUCH_TARGET}px` }),
             }}
           >
             <MessageToast />
           </Box>
+          {/* A phone in fullscreen keeps only the reset, as the built-in layout does. Below 1024 pixels (`tablet`) the
+              free area beside the panel is narrow, so the reset shows only its icon there too. */}
+          <Box
+            component="div"
+            sx={{ position: 'absolute', insetBlockEnd: gutter, insetInlineEnd: gutter, pointerEvents: 'auto' }}
+          >
+            <SceneControls
+              compact={!isDesktop || (viewports?.includes('tablet') ?? false)}
+              resetOnly={!isDesktop && isFullscreen}
+            />
+          </Box>
         </Box>
       )}
 
@@ -319,6 +333,8 @@ export const ProductPanel = ({ collapsed = false, inSheet = false }: ProductPane
 | `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`  | The spec's `finalizeAction` components; the panel offers the primary one in its review step. `finalizeActionComponent` comes from `@salsita-ai/sdk/domain`.                                 |
 | `phx.frontend.useFinalizeAction(handler)`                                    | Run the finalize action's handler, with its pending state, its error and whether finalizing is possible; see [Request a quote](#request-a-quote).                                           |
 | `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | Read the fullscreen flag, and set it from the layout's own button.                                                                                                                          |
+| `phx.frontend.useActiveViewState()` and `phx.frontend.useSetViewState()`     | Read the active view state, one of the spec's `viewStates`, to mark the active view button, and make another one active; see [Control the scene](#control-the-scene).                       |
+| `phx.frontend.useResetCamera()`                                              | Move the camera back to the framing of the active camera, undoing the customer's orbit, pan and zoom.                                                                                       |
 | `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The width classes of the configurator's container, or `null` before it is measured; the layout renders its phone arrangement unless it includes `desktop`, see [Fit a phone](#fit-a-phone). |
 | `phx.frontend.useConfiguratorMessages(onMessage)`                            | Receive violations, side-effect hints and errors one by one, with their text resolved, for the layout's own toast; see [Show messages](#show-messages).                                     |
 | `useResolveLocalizable()` from `@salsita-ai/sdk/react`                       | Turns the localizable texts of the spec into strings in the current language. [Localization](?path=/docs/phoenix-localization--docs) describes it and `LocalizableMessage`.                 |
@@ -524,7 +540,7 @@ The button stays in the free area in both states, so the way back is always wher
 
 ## Show messages
 
-When a change is rejected because it breaks an invariant, when a committed change carries a hint, or when an error is thrown while a change is validated, the configurator has a message for the customer. `phx.frontend.useConfiguratorMessages(onMessage)` calls `onMessage` once for each, with the text already in the customer's language, and the layout shows it its own way. Here a toast shows a message for six seconds, colored by its severity, at the bottom of the free area on a desktop and at its top on a phone:
+When a change is rejected because it breaks an invariant, when a committed change carries a hint, when an error is thrown while a change is validated, or when saving the configuration fails and later succeeds again, the configurator has a message for the customer. `phx.frontend.useConfiguratorMessages(onMessage)` calls `onMessage` once for each, with the text already in the customer's language, and the layout shows it its own way. Here a toast shows a message for six seconds, colored by its severity, at the bottom left of the free area above the view controls on a desktop, and at its top on a phone:
 
 ```tsx
 import { Alert } from '@mui/material'
@@ -543,7 +559,7 @@ const severityOf = (message: ConfiguratorMessage) => {
     return VIOLATION_SEVERITY[message.violation.severity]
   }
 
-  return message.kind === 'error' ? 'error' : 'info'
+  return message.kind === 'error' || message.kind === 'saveError' ? 'error' : 'info'
 }
 
 export const MessageToast = () => {
@@ -580,7 +596,7 @@ export const MessageToast = () => {
 }
 ```
 
-The hook takes a new function on every render without missing a message, so passing the state setter, or an inline function, is fine. `message.kind` is `'violation'`, `'sideEffect'` or `'error'`; a violation also carries `entityId` and the `violation` itself, with its `severity`. A rejected change brings one message for each violation of the rejected state, including notices and warnings that were already present, so the toast keeps the most severe message while it is shown instead of letting a later notice replace the reason for the rejection. The layout mounts the toast in the safe-area element, which sets `pointerEvents: 'none'`, so the toast's wrapper switches pointer events back on for the close button.
+The hook takes a new function on every render without missing a message, so passing the state setter, or an inline function, is fine. `message.kind` is `'violation'`, `'sideEffect'`, `'error'`, `'saveError'` or `'saveRecovery'`; the toast shows an error and a failed save as errors, a hint and the save that succeeded again as information. A violation also carries `entityId` and the `violation` itself, with its `severity`. A rejected change brings one message for each violation of the rejected state, including notices and warnings that were already present, so the toast keeps the most severe message while it is shown instead of letting a later notice replace the reason for the rejection. The layout mounts the toast in the safe-area element, which sets `pointerEvents: 'none'`, so the toast's wrapper switches pointer events back on for the close button.
 
 To give the toast something to show, the spec registers one transformer. Choosing **Tree trunk** keeps the change and adds a hint to it, which arrives as a `sideEffect` message:
 
@@ -603,7 +619,7 @@ export default phx.frontend.transformerBuilder.when
   .build('tree-trunk-delivery')
 ```
 
-[Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) lists the messages the hook does not deliver: a failure to save, errors of the built-in finalize and other actions, and preset errors stay snackbars.
+[Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) lists the messages the hook does not deliver: errors of the built-in finalize and other actions stay snackbars, and a failure to start from a preset is raised on the preset screen.
 
 ## Request a quote
 
@@ -1015,9 +1031,154 @@ export default phx.frontend.createCustomPhoenixEntityElement('EdgeFinishHotspot'
 
 [Html Hotspots](?path=/docs/controls-scene-html-hotspots--docs) describes the component and its other properties.
 
+## Control the scene
+
+The four finishes differ by a few millimetres on a table two metres long, so from the default distance the difference is hard to judge. The layout offers two views, **Whole table** and **Edge close-up**, a close and low look at a corner of the top, and a **Reset view** button that brings back the framing after the customer has orbited, panned or zoomed.
+
+**Views are view states.** The spec lists them, and each camera says by its `$filter` in which view states and at which widths it applies. The two close-up cameras have the highest priorities and apply only in the `edge` view state, the desktop one with `desktop` and the phone one with `mobile`, a little farther away. In the `overview` view state, the first in the list and so the initial one, only the two whole-table cameras of [Fit a phone](#fit-a-phone) apply. A camera always looks at the middle of the table, so the close-up shows the near corner, where the edge profile is seen on both sides:
+
+```yaml
+viewStates:
+  - overview
+  - edge
+
+components:
+  Table:
+    fitRootPerspectiveCamera:
+      edge:
+        priority: 4
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 800
+        maxDistance: 9000
+        distance: 2000
+        azimuthAngle: 0.5
+        polarAngle: 1.15
+        fitMeshChanges: true
+        $filter:
+          viewports: [desktop]
+          viewStates: [edge]
+      edgePhone:
+        priority: 3
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 800
+        maxDistance: 12000
+        distance: 3000
+        azimuthAngle: 0.5
+        polarAngle: 1.15
+        fitMeshChanges: true
+        $filter:
+          viewports: [mobile]
+          viewStates: [edge]
+```
+
+**The buttons.** `phx.frontend.useActiveViewState()` returns the active view state and `phx.frontend.useSetViewState()` a function that makes another one active; the camera then moves to the camera of that view state. `phx.frontend.useResetCamera()` returns a function that moves the camera back to the framing of the active camera, the whole table or the close-up:
+
+```tsx
+import { Box, Button, Tooltip } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+
+// The spec's view states, each with the label of the button that shows it
+const VIEWS = [
+  { state: 'overview', label: 'Whole table' },
+  { state: 'edge', label: 'Edge close-up' },
+] as const
+
+const RESET_ICON = 'M4 12a8 8 0 1 0 2.4-5.7M4 4v4h4'
+
+const SURFACE_SX = {
+  borderRadius: 999,
+  bgcolor: 'background.paper',
+  boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+} as const
+
+const BUTTON_SX = {
+  minBlockSize: 44,
+  minInlineSize: 44,
+  borderRadius: 999,
+  textTransform: 'none',
+  fontWeight: 600,
+  whiteSpace: 'nowrap',
+} as const
+
+interface SceneControlsProps {
+  // The reset button shows only its icon, with its label as tooltip and accessible name
+  readonly compact?: boolean
+  // Only the reset button, without the view buttons
+  readonly resetOnly?: boolean
+}
+
+// The layout's own camera controls: one button per view state of the spec, and a reset that undoes an orbit
+export const SceneControls = ({ compact = false, resetOnly = false }: SceneControlsProps) => {
+  const activeView = phx.frontend.useActiveViewState()
+  const setViewState = phx.frontend.useSetViewState()
+  const resetCamera = phx.frontend.useResetCamera()
+  const resetIcon = (
+    <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+      <path d={RESET_ICON} />
+    </svg>
+  )
+
+  return (
+    <Box component="div" sx={{ display: 'flex', gap: 1 }}>
+      {!resetOnly && (
+        <Box component="div" role="group" aria-label="View" sx={{ ...SURFACE_SX, display: 'flex' }}>
+          {VIEWS.map(view => {
+            const isActive = activeView === view.state
+
+            return (
+              <Button
+                key={view.state}
+                aria-pressed={isActive}
+                onClick={() => setViewState(view.state)}
+                sx={{
+                  ...BUTTON_SX,
+                  paddingInline: 2,
+                  bgcolor: isActive ? 'text.primary' : 'transparent',
+                  color: isActive ? 'background.paper' : 'text.primary',
+                  '&:hover': { bgcolor: isActive ? 'text.primary' : 'action.hover' },
+                }}
+              >
+                {view.label}
+              </Button>
+            )
+          })}
+        </Box>
+      )}
+      <Tooltip title={compact ? 'Reset view' : ''}>
+        <Button
+          onClick={resetCamera}
+          aria-label={compact ? 'Reset view' : undefined}
+          startIcon={compact ? undefined : resetIcon}
+          sx={{
+            ...SURFACE_SX,
+            ...BUTTON_SX,
+            paddingInline: compact ? 0 : 2,
+            color: 'text.primary',
+            '&:hover': { bgcolor: 'background.paper', boxShadow: '0 6px 20px rgba(0, 0, 0, 0.18)' },
+          }}
+        >
+          {compact ? resetIcon : 'Reset view'}
+        </Button>
+      </Tooltip>
+    </Box>
+  )
+}
+```
+
+- The view buttons are a group with `aria-pressed`, so a screen reader announces which view is active, and the active one is drawn dark, not only in another colour.
+- On a desktop the controls sit at the bottom right of the free area and the toast above its bottom left; on a phone they sit at the bottom of the free area, just above the sheet. On a phone, and on a desktop arrangement below 1024 pixels, where `tablet` is also active and the free area beside the panel is narrow, **Reset view** shows only its icon, with its label as tooltip and accessible name.
+- In fullscreen the controls stay on a desktop. On a phone the view buttons are hidden and **Reset view** stays, as [Interaction Modes](?path=/docs/ux-guidelines-interaction-modes--docs#full-screen-preview) describes for the built-in layout: on a phone the canvas is small and the product comes first, and the way back to the framed product is still needed after an orbit.
+- The controls stay in the review step and in read mode: changing the view changes nothing in the configuration, and a viewer may look at the product as closely as the customer.
+- The hooks need no `viewControls` component. That component configures the built-in layout's view controls and has no effect here.
+
 ## The spec the layout reads
 
-The layout reads four components of the root entity and its navigation states; the scene components are in the complete implementation below.
+The layout reads four components of the root entity and its navigation and view states; the scene components are in the complete implementation below. `SceneControls` names the view states `overview` and `edge` in its code, so they must match the spec's `viewStates`.
 
 ```yaml
 navigationStates:
@@ -1025,6 +1186,10 @@ navigationStates:
   - checkout
   - requested
 
+viewStates:
+  - overview
+  - edge
+
 components:
   Table:
     detail:
@@ -1077,7 +1242,7 @@ The same layout in a frame 390 pixels wide, as on a phone. Opened on its own fro
 
 - The panel is on the left and the table is centred in the area to the right of it, not in the whole canvas.
 - Choosing **Tree trunk** moves the check mark to that card, changes the edge of the tabletop and raises the price from $1,290.00 to $1,630.00.
-- Choosing **Tree trunk** also shows "Tree trunk edges are cut by hand, so delivery takes three weeks longer." at the bottom of the free area, until its close button is clicked or six seconds pass. Choosing another finish shows nothing.
+- Choosing **Tree trunk** also shows "Tree trunk edges are cut by hand, so delivery takes three weeks longer." at the bottom left of the free area, above the view controls, until its close button is clicked or six seconds pass. Choosing another finish shows nothing.
 - Tab reaches the selected card, and the arrow keys move the selection to the next or previous card.
 - Dragging in the area to the right of the panel orbits the camera.
 - **Review and request a quote** replaces the cards with the chosen finish and offers **Request a quote**; **Back to the configuration** brings the cards back.
@@ -1092,14 +1257,18 @@ The same layout in a frame 390 pixels wide, as on a phone. Opened on its own fro
 - On the phone, the review step, **Request a quote** and the thank-you message work with the sheet collapsed and open.
 - On the phone, choosing **Tree trunk** shows the hint at the top of the free area, beside the fullscreen button.
 - On the phone, the fullscreen button removes the sheet and the table moves to the centre of the canvas; pressing it again brings the sheet back in the position it had.
+- **Edge close-up** moves the camera close to the near corner of the top, where the edge profile shows; the button is drawn dark and the other light. **Whole table** returns to the whole table.
+- After dragging in the free area to orbit the table, **Reset view** returns to the framing of the active view, the whole table or the close-up.
+- The view buttons and **Reset view** sit at the bottom right of the free area on a desktop and just above the sheet on a phone, and overlap neither the panel, the sheet, the button on the edge nor the toast.
+- In fullscreen the view controls stay on a desktop. On a phone the view buttons are hidden and **Reset view** stays; after an orbit it restores the framing.
 
 ## Known gaps
 
 A project layout has only what it renders. This one leaves out the following, each of which a product may need. [Layout Slots](?path=/docs/phoenix-layout-slots--docs) describes every `LayoutSlots` member named here.
 
-- **Messages that stay snackbars.** The toast shows violations, side effects and errors, and the finalize button shows its own error. A failure to save the configuration is still raised as a snackbar, which renders into `LayoutSlots.DesktopSnackbarsRoot`; this layout mounts no snackbar root, so it appears outside the configurator. A layout that wants it inside mounts the root.
-- **Toolbar actions.** Undo and redo, camera reset, measurements, sharing and language switching are not offered. A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons.
-- **View controls, tool controls and leaving a tool mode.** A spec can configure view controls and tool controls, and a tool mode has a button that leaves it. The built-in layout places them with `LayoutSlots.DesktopViewControls`, `LayoutSlots.DesktopToolControls` and `LayoutSlots.DesktopCallToAction`; this layout mounts none of them, so they do not appear. Nor does this layout build view buttons or a camera reset of its own.
+- **Messages that stay snackbars.** The toast shows violations, side effects, errors and failed saves, and the finalize button shows its own error. Two kinds of message stay snackbars. An error of a built-in action, such as one from `LayoutSlots.DesktopToolbar`, renders into `LayoutSlots.DesktopSnackbarsRoot`; this layout mounts neither, and a layout that mounts such an action mounts the root too, or the snackbar appears outside the configurator. A failure to start from a preset appears on the preset screen, before this layout mounts; a project replaces that screen with `phx.frontend.createPresetUi`, see [Configurator Interface → Preset UI](?path=/docs/phoenix-configurator-interface--docs#preset-ui).
+- **Toolbar actions.** Undo and redo, measurements, sharing and language switching are not offered. A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons.
+- **The spec's view controls, tool controls and leaving a tool mode.** A spec can configure view controls and tool controls, and a tool mode has a button that leaves it. The built-in layout places them with `LayoutSlots.DesktopViewControls`, `LayoutSlots.DesktopToolControls` and `LayoutSlots.DesktopCallToAction`; this layout mounts none of them, so the spec's `viewControls` and `toolControls` do not appear. Its views come from its own buttons instead, see [Control the scene](#control-the-scene), and it has no tool modes.
 - **A project's layout dialog.** A dialog the project registers with `phx.frontend.createLayoutDialog` is shown by `LayoutDialog`, which the built-in layout mounts. This layout does not; a layout that needs the dialog mounts `LayoutDialog` from `@salsita-ai/sdk/configurator`.
 - **Selection.** The table has no parts to select. A product with selectable parts reads `phx.frontend.useSelectedDomainEntityId()` and shows the controls of the selected part.
 - **Clone to edit in read mode.** With `shareCloneToEdit` set, the built-in layout's `LayoutSlots.DesktopReadonlyBanner` offers **Edit configuration** to a viewer; this layout's "View only" label offers nothing. A layout mounts the banner, or builds its own action with `LayoutSlots.useIsCloningAllowed()` and `LayoutSlots.CloneToEditDialog`.
@@ -1158,6 +1327,10 @@ navigationStates:
   - checkout
   - requested
 
+viewStates:
+  - overview
+  - edge
+
 components:
   Table:
     detail:
@@ -1229,6 +1402,34 @@ components:
         fitMeshChanges: true
         $filter:
           viewports: [mobile]
+      edge:
+        priority: 4
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 800
+        maxDistance: 9000
+        distance: 2000
+        azimuthAngle: 0.5
+        polarAngle: 1.15
+        fitMeshChanges: true
+        $filter:
+          viewports: [desktop]
+          viewStates: [edge]
+      edgePhone:
+        priority: 3
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 800
+        maxDistance: 12000
+        distance: 3000
+        azimuthAngle: 0.5
+        polarAngle: 1.15
+        fitMeshChanges: true
+        $filter:
+          viewports: [mobile]
+          viewStates: [edge]
     sceneEntityRemoteObject:
       top:
         fileUrl: /models/tables.gltf
@@ -1645,7 +1846,7 @@ const severityOf = (message: ConfiguratorMessage) => {
     return VIOLATION_SEVERITY[message.violation.severity]
   }
 
-  return message.kind === 'error' ? 'error' : 'info'
+  return message.kind === 'error' || message.kind === 'saveError' ? 'error' : 'info'
 }
 
 export const MessageToast = () => {
@@ -1879,6 +2080,101 @@ export const ReviewActions = ({ handler, label, onBack }: ReviewActionsProps) =>
 }
 ```
 
+### ./src/\_shared/SceneControls.tsx
+
+```tsx
+import { Box, Button, Tooltip } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+
+// The spec's view states, each with the label of the button that shows it
+const VIEWS = [
+  { state: 'overview', label: 'Whole table' },
+  { state: 'edge', label: 'Edge close-up' },
+] as const
+
+const RESET_ICON = 'M4 12a8 8 0 1 0 2.4-5.7M4 4v4h4'
+
+const SURFACE_SX = {
+  borderRadius: 999,
+  bgcolor: 'background.paper',
+  boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+} as const
+
+const BUTTON_SX = {
+  minBlockSize: 44,
+  minInlineSize: 44,
+  borderRadius: 999,
+  textTransform: 'none',
+  fontWeight: 600,
+  whiteSpace: 'nowrap',
+} as const
+
+interface SceneControlsProps {
+  // The reset button shows only its icon, with its label as tooltip and accessible name
+  readonly compact?: boolean
+  // Only the reset button, without the view buttons
+  readonly resetOnly?: boolean
+}
+
+// The layout's own camera controls: one button per view state of the spec, and a reset that undoes an orbit
+export const SceneControls = ({ compact = false, resetOnly = false }: SceneControlsProps) => {
+  const activeView = phx.frontend.useActiveViewState()
+  const setViewState = phx.frontend.useSetViewState()
+  const resetCamera = phx.frontend.useResetCamera()
+  const resetIcon = (
+    <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+      <path d={RESET_ICON} />
+    </svg>
+  )
+
+  return (
+    <Box component="div" sx={{ display: 'flex', gap: 1 }}>
+      {!resetOnly && (
+        <Box component="div" role="group" aria-label="View" sx={{ ...SURFACE_SX, display: 'flex' }}>
+          {VIEWS.map(view => {
+            const isActive = activeView === view.state
+
+            return (
+              <Button
+                key={view.state}
+                aria-pressed={isActive}
+                onClick={() => setViewState(view.state)}
+                sx={{
+                  ...BUTTON_SX,
+                  paddingInline: 2,
+                  bgcolor: isActive ? 'text.primary' : 'transparent',
+                  color: isActive ? 'background.paper' : 'text.primary',
+                  '&:hover': { bgcolor: isActive ? 'text.primary' : 'action.hover' },
+                }}
+              >
+                {view.label}
+              </Button>
+            )
+          })}
+        </Box>
+      )}
+      <Tooltip title={compact ? 'Reset view' : ''}>
+        <Button
+          onClick={resetCamera}
+          aria-label={compact ? 'Reset view' : undefined}
+          startIcon={compact ? undefined : resetIcon}
+          sx={{
+            ...SURFACE_SX,
+            ...BUTTON_SX,
+            paddingInline: compact ? 0 : 2,
+            color: 'text.primary',
+            '&:hover': { bgcolor: 'background.paper', boxShadow: '0 6px 20px rgba(0, 0, 0, 0.18)' },
+          }}
+        >
+          {compact ? resetIcon : 'Reset view'}
+        </Button>
+      </Tooltip>
+    </Box>
+  )
+}
+```
+
 ### ./src/elements/ConfiguratorLayout.tsx
 
 ```tsx
@@ -1893,6 +2189,7 @@ import { BottomSheet } from '../_shared/BottomSheet.js'
 import { FullscreenToggle } from '../_shared/FullscreenToggle.js'
 import { MessageToast } from '../_shared/MessageToast.js'
 import { ProductPanel } from '../_shared/ProductPanel.js'
+import { SceneControls } from '../_shared/SceneControls.js'
 
 const GUTTER = 24
 const PANEL_WIDTH = 380
@@ -1971,14 +2268,26 @@ const ConfiguratorLayout = () => {
             sx={{
               position: 'absolute',
               pointerEvents: 'auto',
-              // Desktop: bottom left. Phone: at the top beside the fullscreen button, clear of the sheet's handle.
+              // Desktop: bottom left, above the row of view controls. Phone: at the top beside the fullscreen button,
+              // clear of the sheet's handle and the view controls.
               ...(isDesktop
-                ? { insetBlockEnd: GUTTER, insetInlineStart: GUTTER }
+                ? { insetBlockEnd: 2 * GUTTER + TOUCH_TARGET, insetInlineStart: GUTTER }
                 : { insetBlockStart: gutter, insetInline: `${gutter}px ${2 * gutter + TOUCH_TARGET}px` }),
             }}
           >
             <MessageToast />
           </Box>
+          {/* A phone in fullscreen keeps only the reset, as the built-in layout does. Below 1024 pixels (`tablet`) the
+              free area beside the panel is narrow, so the reset shows only its icon there too. */}
+          <Box
+            component="div"
+            sx={{ position: 'absolute', insetBlockEnd: gutter, insetInlineEnd: gutter, pointerEvents: 'auto' }}
+          >
+            <SceneControls
+              compact={!isDesktop || (viewports?.includes('tablet') ?? false)}
+              resetOnly={!isDesktop && isFullscreen}
+            />
+          </Box>
         </Box>
       )}
 

package/dist/docs/phoenix/clerk-sign-in.mdx

@@ -14,7 +14,7 @@ useAuthHook: true
 useClerk: true
 ```
 
-`phoenix sync` then adds `@clerk/clerk-react` as a direct application dependency and generates typed Clerk environment readers. `phoenix deployment:prepare-local` writes the deployment's public `CLERK_PUBLISHABLE_KEY` to `.env.generated`; application source should read it from `phx.frontendEnv`, not hardcode a key.
+`@clerk/clerk-react` then becomes a dependency the project declares: run `phoenix deps` through your package manager (for example `pnpm phoenix deps`) and install to add it, because `phoenix sync`, `dev` and `build` stop while it is missing. `phoenix sync` generates typed Clerk environment readers. In a project on the legacy pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), `phoenix sync` adds the dependency itself. `phoenix deployment:prepare-local` writes the deployment's public `CLERK_PUBLISHABLE_KEY` to `.env.generated`; application source should read it from `phx.frontendEnv`, not hardcode a key.
 
 ## Configure the auth webhook
 

package/dist/docs/phoenix/components.mdx

@@ -273,6 +273,12 @@ components:
 
 `$bind` is essential for form controls that need to show current state and accept changes, any UI element that both displays and modifies data, and interactive controls like attribute selectors, toggles, sliders, and input fields.
 
+### Types of bound values
+
+The build checks that the field a `$read` or `$bind` reads fits the prop it is read into, the filter criterion, or, for `$filter: { $read: field }`, the whole filter. A `string` field read into a number prop, a nullable field read into a text, or an array read into a boolean is reported as `COMPONENT_BINDING_TYPE_MISMATCH` at the prop. A field whose schema gives its type only as `tsType` is not checked here. Expressions are checked where their type is settled.
+
+A prop or filter criterion that takes an entity id, such as the `value` of `childEntitySelection` or `selectedEntityIds`, cannot hold an id written in YAML: an entity id is a branded type that only comes from the domain state. Bind it to a field or expression that holds the id; a written id is reported as `COMPONENT_STATIC_ENTITY_ID`.
+
 ### `$eval` - Inline Expressions
 
 `$eval` allows simple dynamic calculations directly in YAML without defining separate `$expression` implementations in TypeScript. It can appear wherever `$read` is allowed — including in component filter `active` properties — and is mutually exclusive with `$read` on the same property, but both can coexist on the same component instance across different properties.

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

@@ -222,7 +222,7 @@ const controlViolations = phx.frontend.useControlViolations([])
 // Finalize violations
 const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
-// Messages for the user: violations of a rejected change, side-effect hints and errors, one call each
+// Messages for the user: violations of a rejected change, side-effect hints, errors and failed saves, one call each
 phx.frontend.useConfiguratorMessages(message => showToast(message.text))
 
 // Map violations to hints
@@ -433,10 +433,10 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - `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. A finalize action the layout runs with `phx.frontend.useFinalizeAction` reports its error as that hook's `error` instead, neither as a message nor as a snackbar.
+- 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. `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. A finalize action the layout runs with `phx.frontend.useFinalizeAction` reports its error as that hook's `error` instead, neither as a message nor as a snackbar.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
-`defaultConfiguratorElements`, exported from `@salsita-ai/sdk/configurator`, holds the built-in UI as a `ConfiguratorLayout` registration that renders the layout the spec selects. Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default.
+`defaultConfiguratorElements`, exported from `@salsita-ai/sdk/configurator`, holds the built-in UI as a `ConfiguratorLayout` registration that renders the layout the spec selects. Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default. 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.
 
 #### Hooks for a Project Layout
 
@@ -481,14 +481,14 @@ Texts from the spec, such as option titles and the `detail` fields, are `Localiz
 
 **Violations**
 
-| Hook                                              | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `phx.frontend.useStateValidity()`                 | The validity of the last committed state: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'notice' \| 'warning', entityViolations }`. A change that leaves a `fixable` or `fatal` violation is rejected and never committed, and neither is a change during which an error was thrown, so neither is seen here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `phx.frontend.useFinalizeViolations()`            | `{ disabled, hints, violations }`. `disabled` is `true` while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save; `hints` is the violations' text, or `undefined`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `phx.frontend.useConfiguratorMessages(onMessage)` | Nothing. It calls `onMessage(message)` once per message: `{ kind: 'violation', entityId, violation, text }` for each violation of the rejected state, including notices and warnings already present, so `violation.severity` tells the reason for the rejection (`fixable` or `fatal`) from them, `{ kind: 'sideEffect', text }` for each hint of a committed update, and `{ kind: 'error', error, text }` when an error is thrown while a change is validated, with `text` the generic "Oops, something went wrong". `text` is resolved to the current language; a violation's is its `message`, or its `type` without one, and the built-in snackbar prefixes it with `entityId`. Hints committed before the layout mounted are not delivered; when the most recent change was rejected or threw, its messages are delivered again when the hook mounts. `onMessage` may be a new function on every render. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types; from `@salsita-ai/sdk/react` the type is `ConfiguratorMessage`. |
-| `phx.frontend.useFinalizeAction(handler)`         | `{ run, isPending, error, disabled, hints }` for the `finalizeAction` whose `handler` it is given; see the Finalize paragraph below for how to call it. `run()` records the finalize-button click for analytics and runs the project's handler, and does nothing while `disabled` or `isPending`; `error` is what the handler's last run rejected with, or `null`; `disabled` and `hints` are those of `useFinalizeViolations()`. The type of the result is `UseFinalizeActionResult` from `@salsita-ai/sdk/configurator`, which also exports the hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| 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, `{ 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.useFinalizeAction(handler)`         | `{ run, isPending, error, disabled, hints }` for the `finalizeAction` whose `handler` it is given; see the Finalize paragraph below for how to call it. `run()` records the finalize-button click for analytics and runs the project's handler, and does nothing while `disabled` or `isPending`; `error` is what the handler's last run rejected with, or `null`; `disabled` and `hints` are those of `useFinalizeViolations()`. The type of the result is `UseFinalizeActionResult` from `@salsita-ai/sdk/configurator`, which also exports the hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
-`LayoutSlots.Services` shows the messages of `useConfiguratorMessages` as snackbars; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
+`LayoutSlots.Services` shows every message of `useConfiguratorMessages` as a snackbar, `saveError` and `saveRecovery` included; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
 
 **Finalize**
 

package/dist/docs/phoenix/deployments.mdx

@@ -281,9 +281,7 @@ Phoenix provides two helper functions for reading environment variables with val
 **`createEnvReader`** - General purpose environment reader used in frontend and deployment contexts:
 
 ```typescript
-import { bool, str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { bool, createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 // Create a reader function
 const readEnv = createEnvReader({
@@ -301,9 +299,7 @@ console.log(env.SERVER_URL) // Typed and validated
 
 ```typescript
 // webhooks/webhooks.config.ts
-import { str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 export const readRuntimeConfig = createEnvReader({
   AWS_S3_PUBLIC_RESOURCES_BUCKET: str(),

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

@@ -329,6 +329,8 @@ components:
 
 The code generator will automatically create an expression with the same name and infer the return type based on usage context.
 
+The type of an expression must share values with the type every component expects where it is read, and with its declared type. An expression declared as a number and read into a `title`, or one read both into a `title` and into `offsetX`, has no value its implementation could return, so the build reports `EXPRESSION_READ_TYPE_CONFLICT` at the expression and names each place it is read. A type given only as `tsType` is not checked here.
+
 ## Constants
 
 Constants are pre-generated expressions that return fixed values. Under the hood, they are implemented as expressions but are automatically generated by the Phoenix system, so you don't need to write TypeScript implementation code for them.