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

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>
       )}
 
@@ -150,7 +164,7 @@ The components it uses live in `src/_shared/`, which Phoenix does not import by
 ## What the layout has to do
 
 - **Position the root and cover the page.** `LayoutSlots.SharedCanvas` is absolutely positioned and fills its nearest positioned ancestor. The root here is `position: absolute; inset: 0`.
-- **Mount the shared canvas.** The app loader stays on screen until the scene has loaded. A layout without `LayoutSlots.SharedCanvas` never gets past the loader unless the project sets `appLoader: legacy`.
+- **Mount the shared canvas.** It renders the scene, and the app loader stays on screen until the scene has loaded. A layout without a canvas is not held by the loader: it leaves once the configuration is up.
 - **Put the UI above the canvas.** The canvas is opaque. Content that is positioned and comes after it in the markup is painted above it; unpositioned content is painted under it and cannot be seen.
 - **Tell the camera where the free area is.** `useSceneSafeArea()` returns two refs. `containerRef` goes on the element that covers the whole canvas, `safeAreaRef` on the region the product should stay visible in, here everything right of the panel, or above the sheet on a phone. The camera then frames the product in that region. The hook measures again whenever either of the two elements resizes; for a change no resize reports, such as a `transform` on an ancestor settling at the end of an animation, it also returns `update` to call. Without the two refs the product is centred in the whole canvas and sits against the panel.
 - **Let the pointer through.** The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'`; otherwise the scene cannot be orbited. The fullscreen button inside it switches pointer events back on.
@@ -319,6 +333,9 @@ 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.                                                                                       |
+| `phx.frontend.useUndoRedo()`                                                 | Not used here: whether there is a change to undo or redo, and `undo` and `redo`, for a layout's own undo and redo buttons; see [Known gaps](#known-gaps).                                   |
 | `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 +541,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 +560,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 +597,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 +620,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 +1032,156 @@ export default phx.frontend.createCustomPhoenixEntityElement('EdgeFinishHotspot'
 
 [Html Hotspots](?path=/docs/controls-scene-html-hotspots--docs) describes the component and its other properties.
 
+The SDK's own controls on the product, such as `sceneEntityAddFab` and `sceneEntitySelectHotspot`, keep the SDK's look in a project layout too. Each is rendered through an entity element of its own name, so a project gives it the brand's look by registering that name, for example with `phx.frontend.createAddEntityFab`; see [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls). `htmlHotspot` is for a control the SDK has none of, like this one.
+
+## 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 +1189,10 @@ navigationStates:
   - checkout
   - requested
 
+viewStates:
+  - overview
+  - edge
+
 components:
   Table:
     detail:
@@ -1077,7 +1245,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 +1260,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: `phx.frontend.useUndoRedo()`, `useMeasurements()`, `useShareLinks()` and `useLocaleSwitch()` serve single actions, pushing the same analytics events as the built-in buttons; see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+- **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 +1330,10 @@ navigationStates:
   - checkout
   - requested
 
+viewStates:
+  - overview
+  - edge
+
 components:
   Table:
     detail:
@@ -1229,6 +1405,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 +1849,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 +2083,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 +2192,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 +2271,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/other-features/error-5xx.mdx

@@ -12,7 +12,7 @@ Error page that is displayed when needed.
 
 ## Code
 
-The `ErrorPage` is provided in the default in the `LoadedConfigurationDetailPage` and `PresetSelectionProvider`.
+In production the configurator renders the layout element `ConfiguratorErrorPage` when an error reaches its error boundary or a configuration cannot be created from the only preset. Its default is a built-in page made with `ErrorPage` from `@salsita-ai/sdk/ui`; this example renders `ErrorPage` directly to show it. A project replaces the page with `phx.frontend.createConfiguratorErrorPage`, see [Configurator Interface → Configurator Error Page](?path=/docs/phoenix-configurator-interface--docs#configurator-error-page), which also lists the cases that still show another page.
 
 ## Example
 

package/dist/docs/other-features/navigation-hotspot.mdx

@@ -96,6 +96,8 @@ Key observations:
 - With `pushToStack: true` and no `canStackOnto`, the new state is always pushed on top
 - With `canStackOnto: [Legs]`, the stack is "rewound" to `Legs` before pushing - any states after `Legs` are removed
 
+The hotspot is the entity element `NavigationHotspot`. A project replaces its look by registering its own with `phx.frontend.createNavigationHotspot`, which receives `navigationState` and `onNavigate`, the navigation with the stack rules above. See [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls).
+
 ## Example
 
 This example demonstrates navigation hotspots with stack behavior. The sidebar shows breadcrumbs displaying the current navigation stack for easier understanding.

package/dist/docs/other-features/not-found-404.mdx

@@ -12,7 +12,7 @@ Error page that is displayed when the configuration is not accesible.
 
 ## Code
 
-The `NotFoundPage` is provided in the default in the `ConfiguratorRoot` and `ConfiguratorApp`.
+The configurator renders the layout element `ConfigurationNotFoundPage`, whose default is the built-in page, `ConfigurationNotFoundPage` from `@salsita-ai/sdk/react`. This example renders that component directly to show it. A project replaces the page with `phx.frontend.createConfigurationNotFoundPage`, see [Configurator Interface → Configuration Not Found Page](?path=/docs/phoenix-configurator-interface--docs#configuration-not-found-page), which also lists when the page is shown.
 
 ## Example
 

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.