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

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

@@ -0,0 +1,2557 @@
+# 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, 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)
+- [What the layout has to do](#what-the-layout-has-to-do)
+- [Read and change the product](#read-and-change-the-product)
+- [Draw the choices](#draw-the-choices)
+- [Offer fullscreen](#offer-fullscreen)
+- [Undo and redo](#undo-and-redo)
+- [Show messages](#show-messages)
+- [Request a quote](#request-a-quote)
+- [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)
+- [Known gaps](#known-gaps)
+- [Related pages](#related-pages)
+- [Complete Implementation](#complete-implementation)
+
+## Choose this approach
+
+Write your own layout when the configurator has to follow a design the built-in layout cannot take on: the brand's typography, controls and spacing, a panel on the left, a top bar with the price, an area the built-in layout has no place for.
+
+Stay with the built-in layout when its structure fits and only its parts change. [Universal](?path=/docs/layouts-universal--docs) demonstrates that layout, and the pages of its parts describe what the spec configures: [Header](?path=/docs/layouts-header-floating--docs), [Sidebar](?path=/docs/layouts-sidebar-general--docs), [Sidebar Footer](?path=/docs/layouts-sidebar-footer-basic--docs), [Toolbar](?path=/docs/layouts-toolbar--docs) and [View Controls](?path=/docs/layouts-view-controls--docs).
+
+A project layout replaces all of that. None of the built-in sidebar, footer, toolbar or property pages is rendered for it, so the layout builds every control the user needs. This example uses no SDK component that draws UI: only the scene and the `phx.frontend` hooks that measure the free area, read and change the product's state and record analytics. A layout may also mount the SDK's own pieces where it wants them, see [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui).
+
+## Register the layout
+
+Create `src/elements/ConfiguratorLayout.tsx` with a default export made by `phx.frontend.createCustomPhoenixLayoutElement`. The name `ConfiguratorLayout` is what makes it the layout: Phoenix renders the element registered under that name for every loaded configuration, in owner and in read mode, whatever `layout` the spec sets. Nothing in the YAML refers to it.
+
+```tsx
+import { Box } from '@mui/material'
+import { useState } from 'react'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+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'
+import { UndoRedo } from '../_shared/UndoRedo.js'
+
+const GUTTER = 24
+const PANEL_WIDTH = 380
+const PHONE_GUTTER = 16
+const TOUCH_TARGET = 44
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  // `null` until the container has been measured; the layout shows only the scene until then
+  const viewports = phx.frontend.useActiveViewports()
+  const [isSheetOpen, setSheetOpen] = useState(false)
+
+  const isDesktop = viewports?.includes('desktop') ?? false
+  const gutter = isDesktop ? GUTTER : PHONE_GUTTER
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      // `clip`, not `hidden`: what overflows, such as the sheet's fill below its edge, can never be scrolled into view,
+      // not even by the browser when the focus moves
+      sx={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', overflow: 'clip' }}
+    >
+      <LayoutSlots.SharedCanvas />
+
+      {viewports !== null && isDesktop && !isFullscreen && (
+        <Box
+          component="aside"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: PANEL_WIDTH,
+            maxBlockSize: `calc(100% - ${2 * GUTTER}px)`,
+            display: 'flex',
+            flexDirection: 'column',
+            borderRadius: 5,
+            bgcolor: 'background.paper',
+            boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)',
+            // A very short container, such as a phone held sideways, scrolls the panel instead of clipping its footer
+            overflowX: 'hidden',
+            overflowY: 'auto',
+            overscrollBehavior: 'contain',
+          }}
+        >
+          <ProductPanel />
+        </Box>
+      )}
+
+      {viewports !== null && (
+        <Box
+          component="div"
+          ref={safeAreaRef}
+          sx={{
+            // Desktop: right of the panel. Phone: above the sheet, whose height the column gives the rest.
+            ...(isDesktop
+              ? {
+                  position: 'absolute',
+                  insetBlock: 0,
+                  insetInlineStart: isFullscreen ? 0 : PANEL_WIDTH + 2 * GUTTER,
+                  insetInlineEnd: 0,
+                }
+              : { position: 'relative', flex: '1 1 0', minBlockSize: 0 }),
+            pointerEvents: 'none',
+          }}
+        >
+          <Box
+            component="div"
+            sx={{
+              position: 'absolute',
+              insetBlockStart: gutter,
+              insetInlineEnd: gutter,
+              display: 'flex',
+              gap: 1,
+              pointerEvents: 'auto',
+            }}
+          >
+            {!isFullscreen && <UndoRedo />}
+            <FullscreenToggle compact={!isDesktop} />
+          </Box>
+          <Box
+            component="div"
+            sx={{
+              position: 'absolute',
+              pointerEvents: 'auto',
+              // Desktop: bottom left, above the row of view controls. Phone: at the top below the row of undo, redo and
+              // fullscreen, clear of the sheet's handle and the view controls.
+              ...(isDesktop
+                ? { insetBlockEnd: 2 * GUTTER + TOUCH_TARGET, insetInlineStart: GUTTER }
+                : { insetBlockStart: gutter + TOUCH_TARGET + gutter / 2, insetInline: gutter }),
+            }}
+          >
+            <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>
+      )}
+
+      {viewports !== null && !isDesktop && !isFullscreen && (
+        <BottomSheet open={isSheetOpen} onOpenChange={setSheetOpen} label="Product details">
+          <ProductPanel collapsed={!isSheetOpen} inSheet />
+        </BottomSheet>
+      )}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+The components it uses live in `src/_shared/`, which Phoenix does not import by convention, so the layout imports them itself. Application projects receive `phx` as a global. Storybook examples cannot rely on that project environment, so the example's files import it from `../../.phoenix/phx.js`; leave that import out in a project.
+
+## 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.** 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.** `phx.frontend.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.
+- **Honour fullscreen.** Fullscreen is a flag in the product's state, not a browser feature. The layout reads it with `phx.frontend.useIsFullscreenActive()`, removes the panel or the sheet and lets the safe area cover the canvas, so the camera frames the product in the whole canvas.
+- **Fit the width it is given.** The configurator can be embedded in a narrow column or opened on a phone. The layout reads the container's width class with `phx.frontend.useActiveViewports()` and renders a desktop or a phone arrangement, see [Fit a phone](#fit-a-phone).
+- **Serve read mode.** The same element renders a configuration shared for viewing, or one the host page opens read-only, and the layout decides what a viewer sees; see [Serve read mode](#serve-read-mode).
+
+## Read and change the product
+
+The panel reads everything it shows from hooks and writes the customer's choice back through one of them. The table lists the hooks the whole layout uses:
+
+```tsx
+import { Box, Button, Typography } from '@mui/material'
+
+import { detailComponent } from '@salsita-ai/sdk/domain'
+
+import { EdgeFinishCards } from './EdgeFinishCards.js'
+import { ReviewActions } from './ReviewActions.js'
+
+const BUTTON_SX = { minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 } as const
+
+interface ProductPanelProps {
+  // Only the name, the price and the action, for a collapsed bottom sheet
+  readonly collapsed?: boolean
+  // In a bottom sheet the cards region keeps the top of the cards in view, and the sheet scrolls when that does not fit
+  readonly inSheet?: boolean
+}
+
+export const ProductPanel = ({ collapsed = false, inSheet = false }: ProductPanelProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const price = phx.frontend.useRootEntityPrice()
+  const tableId = phx.frontend.useRootEntityId()
+  const edgeFinish = phx.frontend.useAttributeSelection(tableId, 'edgeFinish')
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const pushNavigate = phx.frontend.usePushNavigate()
+  const popNavigate = phx.frontend.usePopNavigate()
+  const navigate = phx.frontend.useNavigate()
+
+  const isReadMode = accessInfo.viewMode
+  const isReview = isReadMode || navigationState !== 'configure'
+  const chosenEdge = edgeFinish.options.find(option => option.value === edgeFinish.value)
+
+  return (
+    <>
+      <Box component="header" sx={{ display: 'grid', gap: 1, padding: 3, paddingBlockEnd: 2 }}>
+        {isReadMode ? (
+          <Typography
+            variant="overline"
+            sx={{ justifySelf: 'start', paddingInline: 1.5, borderRadius: 999, bgcolor: 'action.selected' }}
+          >
+            View only
+          </Typography>
+        ) : (
+          <Typography variant="overline" color="text.secondary">
+            {resolve(detail?.state.subtitle)}
+          </Typography>
+        )}
+        <Typography variant="h5" component="h2" fontWeight={700}>
+          {resolve(detail?.state.title)}
+        </Typography>
+        {!collapsed && (
+          <Typography variant="body2" color="text.secondary">
+            {resolve(detail?.state.description)}
+          </Typography>
+        )}
+      </Box>
+
+      {!collapsed && (
+        <Box
+          component="div"
+          sx={{
+            display: 'grid',
+            gap: 1.5,
+            paddingInline: 3,
+            paddingBlockEnd: 3,
+            // In a short container the region shrinks and scrolls; a scroll past its end moves its container on
+            minBlockSize: inSheet ? 120 : 0,
+            overflowY: 'auto',
+          }}
+        >
+          <Typography variant="subtitle2" component="h3">
+            Edge finish
+          </Typography>
+          {isReview ? (
+            <Box component="div" sx={{ padding: 2, borderRadius: 3, bgcolor: 'action.hover' }}>
+              <Typography variant="body2" fontWeight={600}>
+                {resolve(chosenEdge?.title)}
+              </Typography>
+              <Typography variant="caption" color="text.secondary">
+                {resolve(chosenEdge?.description)}
+              </Typography>
+            </Box>
+          ) : (
+            <EdgeFinishCards selection={edgeFinish} />
+          )}
+        </Box>
+      )}
+
+      <Box component="footer" sx={{ display: 'grid', gap: 2, padding: 3, borderTop: 1, borderColor: 'divider' }}>
+        <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
+          <Typography variant="body2" color="text.secondary">
+            Total price
+          </Typography>
+          <Typography variant="h5" component="p" fontWeight={700}>
+            {price}
+          </Typography>
+        </Box>
+        {!isReadMode && navigationState === 'configure' && (
+          <Button size="large" variant="contained" onClick={() => pushNavigate('checkout')} sx={BUTTON_SX}>
+            Review and request a quote
+          </Button>
+        )}
+        {!isReadMode && navigationState === 'checkout' && (
+          <>
+            <Typography variant="body2" color="text.secondary">
+              Your table is ready for a quote. A real shop collects the contact details here.
+            </Typography>
+            <ReviewActions onBack={popNavigate} />
+          </>
+        )}
+        {!isReadMode && navigationState === 'requested' && (
+          <>
+            <Typography variant="body2" role="status">
+              Thank you. Your quote request is on its way, and the shop replies within two working days.
+            </Typography>
+            <Button size="large" variant="outlined" onClick={() => navigate('configure')} sx={BUTTON_SX}>
+              Back to the configuration
+            </Button>
+          </>
+        )}
+      </Box>
+    </>
+  )
+}
+```
+
+| Hook                                                                         | What the layout uses it for                                                                                                                                                                                                           |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useFirstRootComponent(detailComponent)`                        | The `detail` component of the root entity: name, subtitle and description. `detailComponent` comes from `@salsita-ai/sdk/domain`; the hook returns `null` without one.                                                                |
+| `phx.frontend.useRootEntityId()`                                             | The id of the table, which the control hooks take.                                                                                                                                                                                    |
+| `phx.frontend.useAttributeSelection(entityId, instanceName)`                 | The `attributeSelection` component named `edgeFinish`: the current `value` and the `options`, each with `title`, `description`, `value`, `disabled` and `onSelect`.                                                                   |
+| `phx.frontend.useRootEntityPrice()`                                          | The root entity's `price` component, formatted for the current locale and currency, or `null` without one.                                                                                                                            |
+| `phx.frontend.useResolveLocalizable()`                                       | Turns the localizable texts of the spec into strings in the current language. [Localization](?path=/docs/phoenix-localization--docs) describes it, `phx.frontend.useLocalizable(text)` and `LocalizableMessage`.                      |
+| `phx.frontend.useAccessService()`                                            | `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property; see [Serve read mode](#serve-read-mode).                                                      |
+| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state; the panel shows its review step while it is `checkout`.                                                                                                                                                  |
+| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | Enter the review step and leave it again.                                                                                                                                                                                             |
+| `phx.frontend.useNavigate()`                                                 | Return from the confirmation to the configuration, forgetting the review step.                                                                                                                                                        |
+| `phx.frontend.useFinalizeActions()`                                          | The spec's `finalizeAction` components with what a button needs; the review step offers the `primary` one and runs it, with its pending state, its error and whether finalizing is possible; see [Request a quote](#request-a-quote). |
+| `phx.frontend.useUndoRedo()`                                                 | Whether there is a change to undo or redo, and `undo` and `redo`, for the layout's own buttons; see [Undo and redo](#undo-and-redo).                                                                                                  |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | Read the fullscreen flag, and set it from the layout's own button.                                                                                                                                                                    |
+| `phx.frontend.useAnalytics()`                                                | Record the fullscreen button's click as the built-in button does; see [Offer fullscreen](#offer-fullscreen).                                                                                                                          |
+| `phx.frontend.useSceneSafeArea()`                                            | The two refs that tell the camera which part of the canvas the panel or the sheet leaves free; see [What the layout has to do](#what-the-layout-has-to-do).                                                                           |
+| `phx.frontend.useActiveViewports()`                                          | 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.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.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).                                                                               |
+
+Calling an option's `onSelect` is the whole write: it changes `edgeFinish` on the table, the scene morphs the edge and the price expression recalculates. The option fields are named for display: the spec's `label` arrives as `title`, its `img` as `imageSrc`.
+
+The review step is the layout's own: the button pushes the `checkout` navigation state, and the panel shows a summary instead of the cards. There **Request a quote** runs the spec's finalize action, whose handler moves the panel on to the `requested` state and its confirmation; see [Request a quote](#request-a-quote). A real shop collects the contact details in the review step before it sends the request.
+
+## Draw the choices
+
+The edge finish is a visual choice, so the panel shows it as cards with a drawing of each profile, as [Choosing a Control](?path=/docs/ux-guidelines-choosing-a-control--docs) recommends for shapes. The selected card has a border in the theme's primary colour, a tinted background and a check mark, so the state does not depend on colour alone. The cards form a radio group: the group has `role="radiogroup"` and a label, each card `role="radio"` and `aria-checked`, only the selected card is in the tab order, and the arrow keys move the selection, skipping disabled options, as in a native radio group. Each card is at least 44 pixels high and shows a focus ring for keyboard users.
+
+```tsx
+import { Box, ButtonBase, type SxProps, type Theme, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import type { UseAttributeSelection } from '@salsita-ai/sdk/react'
+
+// Cross-sections of the tabletop's edge, keyed by the option values of the spec.
+const EDGE_PROFILES: Readonly<Record<string, string>> = {
+  None: 'M0 4H32V20H0Z',
+  Facet: 'M0 4H26L32 10V14L26 20H0Z',
+  Round: 'M0 4H24A8 8 0 0 1 24 20H0Z',
+  TreeTrunk: 'M0 4H27C33 5 28 9 34 11C29 13 34 17 27 20H0Z',
+}
+
+const CHECK_BADGE: SxProps<Theme> = {
+  position: 'absolute',
+  insetBlockStart: 10,
+  insetInlineEnd: 10,
+  display: 'grid',
+  placeItems: 'center',
+  inlineSize: 22,
+  blockSize: 22,
+  borderRadius: '50%',
+  bgcolor: 'primary.main',
+  color: 'primary.contrastText',
+  fontSize: 13,
+}
+
+// Arrow keys move the selection between the cards, as in a native radio group.
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface EdgeFinishCardsProps {
+  readonly selection: ReturnType<UseAttributeSelection>
+}
+
+export const EdgeFinishCards = ({ selection }: EdgeFinishCardsProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const { options } = selection
+  // The card in the tab order: the selected one, or the first enabled one. Disabled cards are never in it.
+  const selectedIndex = options.findIndex(option => option.value === selection.value && !option.disabled)
+  const focusIndex = selectedIndex >= 0 ? selectedIndex : options.findIndex(option => !option.disabled)
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>, index: number) => {
+    const step = ARROW_STEPS[event.key]
+
+    if (step === undefined) {
+      return
+    }
+
+    event.preventDefault()
+    // The next enabled option in the arrow's direction, wrapping around; disabled options are skipped.
+    const count = options.length
+    const next = Array.from(
+      { length: count - 1 },
+      (_, offset) => (((index + step * (offset + 1)) % count) + count) % count
+    ).find(candidate => !options[candidate]?.disabled)
+
+    if (next === undefined) {
+      return
+    }
+
+    options[next]?.onSelect()
+    event.currentTarget.parentElement?.querySelectorAll<HTMLElement>('[role="radio"]')[next]?.focus()
+  }
+
+  return (
+    <Box
+      component="div"
+      role="radiogroup"
+      aria-label="Edge finish"
+      sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 1.5 }}
+    >
+      {options.map((option, index) => {
+        const isSelected = option.value === selection.value
+
+        return (
+          <ButtonBase
+            key={String(option.value)}
+            role="radio"
+            aria-checked={isSelected}
+            tabIndex={index === focusIndex ? 0 : -1}
+            disabled={option.disabled}
+            onClick={option.onSelect}
+            onKeyDown={event => handleKeyDown(event, index)}
+            sx={{
+              position: 'relative',
+              display: 'grid',
+              justifyItems: 'start',
+              gap: 0.5,
+              padding: 2,
+              borderRadius: 3,
+              border: 2,
+              borderColor: isSelected ? 'primary.main' : 'divider',
+              bgcolor: isSelected ? 'action.hover' : 'transparent',
+              textAlign: 'start',
+              transition: 'border-color 150ms, background-color 150ms',
+              '&:hover': { borderColor: isSelected ? 'primary.main' : 'text.disabled' },
+              '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+              '&.Mui-disabled': { opacity: 0.4 },
+            }}
+          >
+            {isSelected && (
+              <Box component="span" aria-hidden sx={CHECK_BADGE}>
+                ✓
+              </Box>
+            )}
+            <Box
+              component="svg"
+              viewBox="0 0 36 24"
+              aria-hidden
+              sx={{ inlineSize: 60, blockSize: 40, color: '#b98b5e' }}
+            >
+              <path d={EDGE_PROFILES[String(option.value)]} fill="currentColor" />
+            </Box>
+            <Typography variant="body2" fontWeight={600}>
+              {resolve(option.title)}
+            </Typography>
+            <Typography variant="caption" color="text.secondary">
+              {resolve(option.description)}
+            </Typography>
+          </ButtonBase>
+        )
+      })}
+    </Box>
+  )
+}
+```
+
+The drawings are keyed by the option values of the spec. A spec can carry a picture per option instead, as `img`, which the hook returns as `imageSrc`; [CardSelect](?path=/docs/controls-select-attribute-cardselect--docs) shows the SDK's own card control.
+
+## Offer fullscreen
+
+Fullscreen is a flag in the configurator's state, not the browser's fullscreen mode. `phx.frontend.useIsFullscreenActive()` reads it and `phx.frontend.useSetFullscreen()` returns a function that sets it: `setFullscreen(true)` turns it on, `setFullscreen(false)` off. The layout's own button flips it, and the layout decides what to hide. Before it flips the flag, the button records the click with `phx.frontend.useAnalytics().push(FrontendAnalyticsFactory.FullScreenModeToggled())`, the event the built-in fullscreen button records, so the shop's analytics count fullscreen the same way with either layout. `FrontendAnalyticsFactory` comes from `@salsita-ai/sdk/configurator`.
+
+```tsx
+import { Button, Tooltip } from '@mui/material'
+
+import { FrontendAnalyticsFactory } from '@salsita-ai/sdk/configurator'
+
+const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
+const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
+
+interface FullscreenToggleProps {
+  // Only the icon, with the label as its accessible name and tooltip, where a label would cover the product
+  readonly compact?: boolean
+}
+
+export const FullscreenToggle = ({ compact = false }: FullscreenToggleProps) => {
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const setFullscreen = phx.frontend.useSetFullscreen()
+  const analytics = phx.frontend.useAnalytics()
+  const label = isFullscreen ? 'Exit fullscreen' : 'Fullscreen'
+  const icon = (
+    <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+      <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
+    </svg>
+  )
+
+  // The same event the built-in fullscreen button records, for entering and for leaving
+  const toggle = () => {
+    analytics.push(FrontendAnalyticsFactory.FullScreenModeToggled())
+    setFullscreen(!isFullscreen)
+  }
+
+  return (
+    <Tooltip title={compact ? label : ''}>
+      <Button
+        onClick={toggle}
+        aria-label={compact ? label : undefined}
+        startIcon={compact ? undefined : icon}
+        sx={{
+          minBlockSize: 44,
+          minInlineSize: 44,
+          paddingInline: compact ? 0 : 2.5,
+          borderRadius: 999,
+          bgcolor: 'background.paper',
+          color: 'text.primary',
+          boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+          textTransform: 'none',
+          fontWeight: 600,
+          '&:hover': { bgcolor: 'background.paper', boxShadow: '0 6px 20px rgba(0, 0, 0, 0.18)' },
+        }}
+      >
+        {compact ? icon : label}
+      </Button>
+    </Tooltip>
+  )
+}
+```
+
+The button stays in the free area in both states, so the way back is always where the user left it. [Interaction Modes](?path=/docs/ux-guidelines-interaction-modes--docs#full-screen-preview) describes what fullscreen hides.
+
+## Undo and redo
+
+The customer tries the four finishes against each other, so the layout offers **Undo** and **Redo** at the top right of the free area, beside the fullscreen button. `phx.frontend.useUndoRedo()` returns `canUndo` and `canRedo`, whether the history has a change to undo or to redo, and `undo` and `redo`, which change the configuration back or forward as the built-in toolbar's buttons do and push the same analytics events:
+
+```tsx
+import { Box, IconButton, Tooltip } from '@mui/material'
+
+const UNDO_ICON = 'M9 14 4 9l5-5M4 9h10.5a5.5 5.5 0 0 1 0 11H11'
+const REDO_ICON = 'M15 14l5-5-5-5M20 9H9.5a5.5 5.5 0 0 0 0 11H13'
+
+interface HistoryButtonProps {
+  readonly label: string
+  readonly icon: string
+  readonly enabled: boolean
+  readonly onClick: () => void
+}
+
+const HistoryButton = ({ label, icon, enabled, onClick }: HistoryButtonProps) => (
+  <Tooltip title={label}>
+    {/* A disabled button fires no pointer events, so the span keeps the tooltip working */}
+    <span>
+      <IconButton
+        aria-label={label}
+        disabled={!enabled}
+        onClick={onClick}
+        sx={{ inlineSize: 44, blockSize: 44, color: 'text.primary' }}
+      >
+        <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+          <path d={icon} />
+        </svg>
+      </IconButton>
+    </span>
+  </Tooltip>
+)
+
+// Undo and redo for the customer's choices. They change the configuration, so they are offered only where the cards
+// are: not to a viewer, and not in the review step, where the summary and a running request must not change under the
+// customer. `useUndoRedo` pushes the same analytics events as the built-in toolbar's buttons.
+export const UndoRedo = () => {
+  const { canUndo, canRedo, undo, redo } = phx.frontend.useUndoRedo()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+
+  if (accessInfo.viewMode || navigationState !== 'configure') {
+    return null
+  }
+
+  return (
+    <Box
+      component="div"
+      role="group"
+      aria-label="History"
+      sx={{
+        display: 'flex',
+        borderRadius: 999,
+        bgcolor: 'background.paper',
+        boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+      }}
+    >
+      <HistoryButton label="Undo" icon={UNDO_ICON} enabled={canUndo} onClick={undo} />
+      <HistoryButton label="Redo" icon={REDO_ICON} enabled={canRedo} onClick={redo} />
+    </Box>
+  )
+}
+```
+
+- Each choice of a finish is one step of the history, whether it is made on the cards or on the button on the table's edge; undoing it moves the check mark back, changes the edge back and restores the price.
+- Each button is disabled while there is nothing to undo or redo, and keeps its tooltip and accessible name. A disabled MUI button receives no pointer events, so a `span` around it carries the tooltip.
+- The hook does not look at read mode or at the navigation state. The buttons change the configuration, so the component renders them only while the cards are shown: not to a viewer, not in the review step, where the summary and a running request must not change under the customer, and not in the confirmation. The layout also leaves them out in fullscreen, which gives the canvas to the product and keeps only the controls placed on it or for looking at it. The button on the table's edge stays there and still changes the finish; the history keeps that change, so **Undo** undoes it after fullscreen is left.
+
+## Show messages
+
+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, below the row of buttons, on a phone:
+
+```tsx
+import { Alert } from '@mui/material'
+import { useEffect, useState } from 'react'
+
+import type { ConfiguratorMessage } from '@salsita-ai/sdk/react'
+
+const VIOLATION_SEVERITY = { fatal: 'error', fixable: 'error', warning: 'warning', notice: 'info' } as const
+const RANK = { info: 0, warning: 1, error: 2 } as const
+const VISIBLE_MS = 6000
+
+const severityOf = (message: ConfiguratorMessage) => {
+  if (message.kind === 'violation') {
+    return VIOLATION_SEVERITY[message.violation.severity]
+  }
+
+  return message.kind === 'error' || message.kind === 'saveError' ? 'error' : 'info'
+}
+
+export const MessageToast = () => {
+  const [message, setMessage] = useState<ConfiguratorMessage | null>(null)
+
+  // A rejected change also reports the notices already present; keep the worst message while it is shown
+  phx.frontend.useConfiguratorMessages(next => {
+    setMessage(shown => (shown !== null && RANK[severityOf(next)] < RANK[severityOf(shown)] ? shown : next))
+  })
+
+  useEffect(() => {
+    if (message === null) {
+      return
+    }
+
+    const timeout = setTimeout(() => setMessage(null), VISIBLE_MS)
+
+    return () => clearTimeout(timeout)
+  }, [message])
+
+  if (message === null) {
+    return null
+  }
+
+  return (
+    <Alert
+      severity={severityOf(message)}
+      onClose={() => setMessage(null)}
+      sx={{ maxInlineSize: 420, borderRadius: 3, boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)' }}
+    >
+      {message.text}
+    </Alert>
+  )
+}
+```
+
+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:
+
+```ts
+import { msg } from '@lingui/core/macro'
+
+// A tree-trunk edge is cut by hand; choosing it carries a hint, which reaches the layout as a side-effect message
+export default phx.frontend.transformerBuilder.when
+  .entity(['Table'])
+  .modified({ atFields: ['edgeFinish'] })
+  .then.overrideMatchingUpdate(({ update }) => {
+    if (update.stateDelta.edgeFinish !== 'TreeTrunk') {
+      return [update]
+    }
+
+    return [{ ...update, hint: msg`Tree trunk edges are cut by hand, so delivery takes three weeks longer.` }]
+  })
+  .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: 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
+
+The spec declares what finalizing means for this product as a `finalizeAction` component, and the project registers the handler it names:
+
+```yaml
+components:
+  Table:
+    finalizeAction:
+      quote:
+        variant: primary
+        label: Request a quote
+        title: Send the configuration to the shop for a quote
+        icon: PaperPlaneTilt
+        handler: requestQuote
+```
+
+```ts
+import { useCallback } from 'react'
+
+// Stands in for the shop's quote service: the request takes a moment, then the panel shows the confirmation
+export default phx.frontend.createPhoenixHandler('requestQuote', () => {
+  const navigate = phx.frontend.useNavigate()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1500))
+      navigate('requested')
+    }, [navigate]),
+  }
+})
+```
+
+The handler stands in for the shop's quote service: it waits a moment, as a request would, and then enters the `requested` navigation state, in which the panel thanks the customer. A handler is a hook factory, so it can use any hook, here `phx.frontend.useNavigate()`.
+
+The review step offers the spec's primary finalize action, or the first one when none is primary, with `phx.frontend.useFinalizeActions()`. The hook lists the active `finalizeAction` components with what a button needs, the label and the title resolved to the customer's language, and runs their handlers itself, beside the layout, so the buttons need no handler boundary and the component may be called anywhere and as often as the layout likes. **Back to the configuration** lives in the same component, so it can be disabled while the request is pending.
+
+```tsx
+import { Alert, Box, Button, CircularProgress, Typography } from '@mui/material'
+
+const BUTTON_SX = { minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 } as const
+
+interface ReviewActionsProps {
+  readonly onBack: () => void
+}
+
+// The review step's buttons: the spec's primary finalize action and the way back. `useFinalizeActions` runs the
+// action's handler beside the layout, so its pending state and error outlive this component: when the panel unmounts,
+// as in fullscreen, the request goes on and the remounted buttons still show it. Back is disabled while the request
+// is pending, so the customer cannot change the configuration while it is sent.
+export const ReviewActions = ({ onBack }: ReviewActionsProps) => {
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const isPending = primary?.isPending ?? false
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 2 }}>
+      {primary && (
+        <Box component="div" sx={{ display: 'grid', gap: 1 }}>
+          <Button
+            size="large"
+            variant="contained"
+            disabled={primary.disabled || isPending}
+            onClick={() => void primary.run()}
+            title={primary.title}
+            startIcon={isPending ? <CircularProgress size={18} color="inherit" /> : undefined}
+            sx={BUTTON_SX}
+          >
+            {isPending ? 'Sending the request…' : primary.label}
+          </Button>
+          {primary.disabled && hints && (
+            <Typography variant="caption" color="text.secondary">
+              {hints}
+            </Typography>
+          )}
+          {primary.error && <Alert severity="error">The request could not be sent: {primary.error.message}</Alert>}
+        </Box>
+      )}
+      <Button size="large" variant="outlined" disabled={isPending} onClick={onBack} sx={BUTTON_SX}>
+        Back to the configuration
+      </Button>
+    </Box>
+  )
+}
+```
+
+- `primary` is the first `'primary'` action, or else the first action, or `null` when the spec has none; the component then shows only **Back to the configuration**. `secondary` holds the others, which this product does not have.
+- `run()` records the finalize-button click for analytics and runs the handler; it does nothing while `disabled` or `isPending`, and returns a promise that never rejects.
+- While `isPending` the button shows a spinner and cannot be clicked again, and **Back to the configuration** is disabled, so the customer cannot change the configuration while it is sent. The configurator keeps `isPending` and `error` while the layout's components unmount: entering fullscreen during the request removes the panel, and the panel shown after fullscreen still shows the spinner until the handler settles.
+- `error` is what the handler rejected with. The layout shows it under the button; no snackbar is raised. It is cleared when the customer tries again.
+- `disabled` and `hints` come from the configuration's violations: while a `warning` or worse holds, or the configuration failed to save, finalizing is not possible and `hints` says why.
+
+The review step stays: a quote request is a commitment, so the customer sees the summary first, and a real shop collects the contact details there. A product that finalizes without a review offers the button in place of **Review and request a quote**. [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout) describes the hook, and `phx.frontend.useFinalizeAction(handler)`, which runs one known action inside the layout instead, and [Finalization](?path=/docs/phoenix-finalization--docs) what a real flow does on the server.
+
+## Serve read mode
+
+A configuration is in read mode by one of two routes, and the layout does not need to know which:
+
+- **A configuration shared for viewing.** The configuration is opened with `read-revision` access, as a viewer of a shared link opens it. The `read` mock template sets that access, and the **Read Mode** story below opens it.
+- **The host page sets `readonly`.** The page that embeds the configurator sets the web component's `readonly` property, here on a configuration the user owns. The mock template `mocks/readonly-host.yaml`, **Host sets readonly** in the editor's **Mocks** panel, keeps `access: owner` and sets the property with `webComponentProperties: { readonly: true }`.
+
+Both routes set `accessInfo.viewMode` to `true`, and both switch the spec's filter mode to read, so a component filtered with `$filter.modes: [owner]` is left out either way. While `viewMode` is `true` the panel marks the view as view only, replaces the cards with the chosen finish and shows the price without an action; neither the finalize action nor undo and redo are offered, since `useFinalizeActions` and `useUndoRedo` do not check read mode themselves. The hooks do not hide or disable anything in read mode: what a viewer can change is decided by what the layout renders. Rotating and zooming the scene, and fullscreen, stay available, as [Interaction Modes](?path=/docs/ux-guidelines-interaction-modes--docs#view-only-mode) recommends. The button on the table's edge is hidden for viewers by the spec, see [Put a control on the product](#put-a-control-on-the-product).
+
+A viewer of a shared configuration has no way here to edit a copy of it; see **Clone to edit in read mode** in [Known gaps](#known-gaps).
+
+## Fit a phone
+
+A panel 380 pixels wide beside the scene leaves nothing of the table on a phone. Below a desktop width the layout puts the panel into a sheet at the bottom and lets the camera frame the table in the area above it. The layout above shows both arrangements.
+
+**The switch.** `phx.frontend.useActiveViewports()` returns the width classes the configurator's container satisfies. The container decides, not the window, so a configurator embedded in a narrow column of a wide page gets the phone arrangement too. The built-in layout switches on `desktop` as well.
+
+| Value       | When it is active                                                                  |
+| ----------- | ---------------------------------------------------------------------------------- |
+| `phone`     | The container is narrower than 480 pixels.                                         |
+| `mobile`    | The container is at most 768 pixels wide.                                          |
+| `tablet`    | The container is wider than 480 and narrower than 1024 pixels.                     |
+| `desktop`   | The container is wider than 768 pixels; `mobile` and `desktop` exclude each other. |
+| `landscape` | The browser window, not the container, is wider than it is high.                   |
+| `portrait`  | The browser window, not the container, is higher than it is wide.                  |
+
+The hook returns `null` until the container has been measured, and the layout renders only the scene until then, so a phone never shows the desktop panel for a frame.
+
+**The sheet.** On a phone the layout is a column: the safe-area element takes the height the sheet leaves, and the sheet sits below it. The sheet has two positions. Collapsed, it shows the name, the price and the action; open, it shows the description and the cards too. The `collapsed` prop of the panel hides the description and the cards, and nothing else, and `inSheet` keeps the top of the cards in view. The sheet scrolls what does not fit, so the price, the review step, **Request a quote** and the thank-you message are reachable in both positions.
+
+```tsx
+import { Box, ButtonBase } from '@mui/material'
+import { type MouseEvent, type PointerEvent, type ReactNode, useRef } from 'react'
+
+// A drag shorter than this is a tap, and the handle's click toggles the sheet
+const TAP_DISTANCE = 6
+// A drag that ends this far from where it started snaps to the other position
+const SNAP_DISTANCE = 48
+// A drag faster than this, in pixels per millisecond, snaps in its direction even when it is short
+const SNAP_VELOCITY = 0.5
+// How far the sheet follows the finger towards the position it is already in
+const OVERDRAG = 0.25
+
+interface BottomSheetProps {
+  readonly open: boolean
+  readonly onOpenChange: (open: boolean) => void
+  readonly label: string
+  readonly children: ReactNode
+}
+
+interface Drag {
+  readonly startY: number
+  readonly startTime: number
+  delta: number
+}
+
+// A persistent sheet at the bottom of the layout with two positions, open and collapsed. It is not a modal: the scene
+// above it stays interactive. Its height comes from its content, so the layout's safe area ends where the sheet
+// starts and changes only when the sheet snaps. While the handle is dragged the sheet follows the finger with a
+// transform, which the safe area does not see, so the camera refits once per snap and not on every move.
+export const BottomSheet = ({ open, onOpenChange, label, children }: BottomSheetProps) => {
+  const sheetRef = useRef<HTMLElement>(null)
+  const dragRef = useRef<Drag | null>(null)
+  const draggedRef = useRef(false)
+
+  const moveSheet = (offset: number, animate: boolean) => {
+    if (sheetRef.current) {
+      sheetRef.current.style.transition = animate ? 'transform 200ms ease-out' : 'none'
+      sheetRef.current.style.transform = offset === 0 ? '' : `translateY(${offset}px)`
+    }
+  }
+
+  const handlePointerDown = (event: PointerEvent<HTMLButtonElement>) => {
+    event.currentTarget.setPointerCapture(event.pointerId)
+    dragRef.current = { startY: event.clientY, startTime: event.timeStamp, delta: 0 }
+    draggedRef.current = false
+  }
+
+  const handlePointerMove = (event: PointerEvent<HTMLButtonElement>) => {
+    const drag = dragRef.current
+
+    if (drag === null) {
+      return
+    }
+
+    drag.delta = event.clientY - drag.startY
+    // Down closes an open sheet and up opens a collapsed one; the other direction only gives a little
+    const towardsOther = open ? drag.delta > 0 : drag.delta < 0
+    moveSheet(towardsOther ? drag.delta : drag.delta * OVERDRAG, false)
+  }
+
+  const handlePointerEnd = (event: PointerEvent<HTMLButtonElement>) => {
+    const drag = dragRef.current
+    dragRef.current = null
+
+    if (drag === null) {
+      return
+    }
+
+    moveSheet(0, true)
+
+    if (Math.abs(drag.delta) < TAP_DISTANCE) {
+      return
+    }
+
+    draggedRef.current = true
+    const velocity = drag.delta / Math.max(event.timeStamp - drag.startTime, 1)
+    const flicked = Math.abs(drag.delta) >= SNAP_DISTANCE || Math.abs(velocity) >= SNAP_VELOCITY
+
+    if (flicked && (open ? drag.delta > 0 : drag.delta < 0)) {
+      onOpenChange(!open)
+    }
+  }
+
+  // A tap, Enter or Space toggles the sheet. The pointer click that ends a drag has already been handled; a keyboard
+  // click (`detail` 0) always toggles, also after a touch drag that was followed by no click.
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    const dragged = draggedRef.current
+    draggedRef.current = false
+
+    if (dragged && event.detail !== 0) {
+      return
+    }
+
+    onOpenChange(!open)
+  }
+
+  return (
+    <Box
+      component="section"
+      ref={sheetRef}
+      aria-label={label}
+      sx={{
+        position: 'relative',
+        flexShrink: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        maxBlockSize: '55%',
+        paddingBlockEnd: 'env(safe-area-inset-bottom)',
+        borderStartStartRadius: 20,
+        borderStartEndRadius: 20,
+        bgcolor: 'background.paper',
+        boxShadow: '0 -8px 32px rgba(0, 0, 0, 0.12)',
+        // Fills the gap below the sheet while it is dragged up
+        '&::after': {
+          content: '""',
+          position: 'absolute',
+          insetInline: 0,
+          insetBlockStart: '100%',
+          blockSize: '100vh',
+          bgcolor: 'background.paper',
+        },
+      }}
+    >
+      <ButtonBase
+        aria-expanded={open}
+        disableRipple
+        aria-label={open ? `Collapse ${label.toLowerCase()}` : `Expand ${label.toLowerCase()}`}
+        onClick={handleClick}
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerEnd}
+        onPointerCancel={handlePointerEnd}
+        sx={{
+          flexShrink: 0,
+          blockSize: 36,
+          touchAction: 'none',
+          '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: -4, borderRadius: 3 },
+        }}
+      >
+        <Box component="span" sx={{ inlineSize: 40, blockSize: 4, borderRadius: 2, bgcolor: 'text.disabled' }} />
+      </ButtonBase>
+      {/* A column, so the panel's cards region shrinks first and the price and action stay in view; below the cards
+          region's minimum height the content scrolls as a whole, as the review step does on a short phone */}
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          flexDirection: 'column',
+          flex: '1 1 auto',
+          minBlockSize: 0,
+          overflowY: 'auto',
+          overscrollBehavior: 'contain',
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  )
+}
+```
+
+- The handle is a real button with `aria-expanded`. A tap, Enter or Space toggles the sheet, and dragging it up or down snaps the sheet to the other position when the drag is long or fast enough. `touchAction: 'none'` is set on the handle only, so the cards still scroll by touch.
+- The sheet's height comes from its content and is at most 55% of the configurator; when the content does not fit, the cards region shrinks until only the top of the cards shows and scrolls, and below that the sheet's content scrolls as a whole. On a phone with room for the header, the top of the cards and the footer, the price and the action stay in view with the sheet open; on a shorter one the customer scrolls the sheet to them, and the review step's buttons are reached the same way in both positions. A scroll on the cards that reaches their end moves the sheet on. Because the safe-area element is its neighbour in the column, the free area ends where the sheet starts without anything being measured by the layout.
+- While the handle is dragged the sheet follows the finger with a `transform`. `phx.frontend.useSceneSafeArea()` does not see a transform, so the free area changes once, when the sheet snaps, and the camera refits once. A safe area that followed the finger would refit the camera on every move and reset an orbit the customer made.
+- The sheet is not a modal: no backdrop covers the scene, so the table can be orbited with one finger and zoomed with two while the sheet is open. MUI's temporary `Drawer` and `SwipeableDrawer` are modals and would block the scene; their persistent and permanent variants have no backdrop, but no drag handle with two positions either.
+
+**What else moves.** The toast sits at the top of the free area, below the row of undo, redo and fullscreen buttons, so it does not cover the sheet's handle, and the fullscreen button shows only its icon, with its label as tooltip and accessible name. Fullscreen removes the sheet as it removes the panel on a desktop. The sheet keeps its position while fullscreen is on.
+
+**A camera for the phone.** The desktop camera is close enough to fill a wide free area, and on a narrow one it cuts off the ends of the table. So each camera has a filter on the viewport: the desktop camera `main` applies while `desktop` is active, and a second camera, `phone`, with a larger distance frames the whole table while `mobile` is. The filters exclude each other once the container is measured. Before that, for example when an image of the configuration is rendered, no viewport is known and a viewport filter matches, so both cameras apply and the higher priority of `main` decides:
+
+```yaml
+components:
+  Table:
+    fitRootPerspectiveCamera:
+      main:
+        priority: 2
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 9000
+        distance: 5000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        fitMeshChanges: true
+        $filter:
+          viewports: [desktop]
+      phone:
+        priority: 1
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 12000
+        distance: 8000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        fitMeshChanges: true
+        $filter:
+          viewports: [mobile]
+```
+
+## Put a control on the product
+
+The edge finish is a detail of the tabletop, so the layout also offers it on the table itself: a round button on the middle of the long edge opens the four finishes next to the edge. On a phone it is a way to change the edge without opening the sheet.
+
+A control in the scene is a spec component that names an element of the project. `htmlHotspot` places an HTML element at an offset from the entity's origin, in the model's units, here millimetres: half the table's depth towards the camera and just below the top's surface. Its `$filter` shows it only to the owner and only while the `configure` navigation state is active, so a viewer and the review step do not get it, and the element does not check either itself:
+
+```yaml
+components:
+  Table:
+    htmlHotspot:
+      edgeFinish:
+        name: EdgeFinishHotspot
+        offsetX: 500
+        offsetY: 800
+        offsetZ: 0
+        $filter:
+          modes: [owner]
+          navigationStates: [configure]
+```
+
+The element is registered with `phx.frontend.createCustomPhoenixEntityElement` under the name the spec gives. It receives the id of the entity the hotspot belongs to, and reads the same `attributeSelection` the panel reads:
+
+```tsx
+import { Box, ButtonBase, Popover, Tooltip } from '@mui/material'
+import { useState } from 'react'
+
+import { EdgeFinishCards } from '../_shared/EdgeFinishCards.js'
+
+// The edge profile the button shows, the square edge of the cards' drawings
+const EDGE_ICON = 'M3 7H17L21 11V13L17 17H3Z'
+
+// Rendered by the spec's `htmlHotspot` on the table's edge: a button on the product that opens the edge finishes
+// next to the edge, with the same cards as the panel. The spec's `$filter` decides when it is shown.
+export default phx.frontend.createCustomPhoenixEntityElement('EdgeFinishHotspot', ({ entityId }) => {
+  const edgeFinish = phx.frontend.useAttributeSelection(entityId, 'edgeFinish')
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null)
+
+  return (
+    <>
+      <Tooltip title="Edge finish">
+        <ButtonBase
+          aria-label="Edge finish"
+          aria-haspopup="dialog"
+          aria-expanded={anchor !== null}
+          onClick={event => setAnchor(event.currentTarget)}
+          sx={{
+            display: 'grid',
+            placeItems: 'center',
+            inlineSize: 44,
+            blockSize: 44,
+            borderRadius: '50%',
+            bgcolor: 'background.paper',
+            color: 'primary.main',
+            boxShadow: '0 4px 16px rgba(0, 0, 0, 0.2)',
+            '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+          }}
+        >
+          <svg viewBox="0 0 24 24" width={22} height={22} aria-hidden>
+            <path d={EDGE_ICON} fill="currentColor" />
+          </svg>
+        </ButtonBase>
+      </Tooltip>
+      <Popover
+        open={anchor !== null}
+        anchorEl={anchor}
+        onClose={() => setAnchor(null)}
+        anchorOrigin={{ vertical: 'top', horizontal: 'center' }}
+        transformOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+        slotProps={{
+          paper: { role: 'dialog', 'aria-label': 'Edge finish', sx: { borderRadius: 4, marginBlockStart: -1 } },
+        }}
+      >
+        <Box component="div" sx={{ inlineSize: 340, maxInlineSize: 'calc(100vw - 32px)', padding: 2 }}>
+          <EdgeFinishCards selection={edgeFinish} />
+        </Box>
+      </Popover>
+    </>
+  )
+})
+```
+
+- The hotspot is rendered inside the scene, but it has the theme and every `phx.frontend` hook, like the layout. MUI's `Popover` and `Tooltip` render into the configurator's own modal root, so they are styled and work inside its shadow root.
+- The cards in the popover are the panel's `EdgeFinishCards`, used a second time. A choice changes the edge, the price and the panel's cards at once, and the popover stays open so the customer can compare the finishes on the table.
+- Keyboard: the button is in the tab order, Enter and Space open the popover and move the focus into it, the arrow keys change the finish, and Escape closes it and returns the focus to the button.
+- `controlHotspot: true` would hide the hotspot while a change is being applied, which would also unmount the open popover on every choice, so this hotspot does not set it.
+- The scene's HTML is painted inside the canvas's stacking context, under the layout's panel and sheet. A hotspot that a panel covers cannot be clicked there.
+
+[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'
+
+// 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 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:
+  - configure
+  - checkout
+  - requested
+
+viewStates:
+  - overview
+  - edge
+
+components:
+  Table:
+    detail:
+      main:
+        title: Linden dining table
+        subtitle: Solid oak, seats six
+        description: A solid oak top on slender steel legs, finished with the edge profile of your choice.
+    price:
+      main:
+        price:
+          $read: $price
+    attributeSelection:
+      edgeFinish:
+        value:
+          $bind: edgeFinish
+        options:
+          - label: Square
+            description: Crisp and modern
+            value: None
+          - label: Facet
+            description: A light bevel
+            value: Facet
+          - label: Round
+            description: Soft to the touch
+            value: Round
+          - label: Tree trunk
+            description: The natural edge
+            value: TreeTrunk
+    finalizeAction:
+      quote:
+        variant: primary
+        label: Request a quote
+        title: Send the configuration to the shop for a quote
+        icon: PaperPlaneTilt
+        handler: requestQuote
+
+transformers:
+  - name: tree-trunk-delivery
+```
+
+`$price` is a custom expression in `src/expressions/table.ts` that adds a surcharge per finish, and `tree-trunk-delivery` is the transformer in `src/transformers/tree-trunk-delivery.ts` that adds the hint shown in [Show messages](#show-messages), and `requestQuote` is the handler in `src/handlers/request-quote.ts`. The example sets no `applicationConfig` and no layout components: `layout`, the header, the sidebar footer, the toolbar, `viewControls` and property pages configure the built-in layout and have no effect on this one. The `finalizeAction` is not one of them: it describes the product's own finalizing, which this layout offers itself.
+
+## Try the example
+
+Each story names the mock template it opens with `args: { mockTemplate }`: **Example** and **Phone** open `default-user`, and **Read Mode** opens `read`. A template applied from the **Mocks** panel lasts until the story is opened again.
+
+The same layout in a frame 390 pixels wide, as on a phone. Opened on its own from the sidebar, the **Phone** story sets Storybook's viewport to 390 × 844.
+
+## Test cases
+
+- 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 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.
+- **Request a quote** shows a spinner and "Sending the request…" for about a second and a half, with **Back to the configuration** disabled, then "Thank you. Your quote request is on its way, and the shop replies within two working days."; **Back to the configuration** then returns to the cards.
+- **Fullscreen** removes the panel and the table moves to the centre of the canvas; **Exit fullscreen** brings both back.
+- In the **Read Mode** story the panel says **View only**, shows the chosen finish and the price, and has no button, so no quote can be requested; **Undo**, **Redo** and the button on the table's edge are not shown, and **Fullscreen**, the view buttons and **Reset view** work.
+- Applying **Host sets readonly** from the **Mocks** panel in the **Example** story shows the same read mode: **View only**, the chosen finish, no button in the panel, no **Undo**, **Redo** or button on the table's edge. Applying **Default User** brings the cards back.
+- **Undo** and **Redo** are disabled when the story opens. After choosing **Tree trunk**, **Undo** restores **Square** and $1,290.00 and enables **Redo**; **Redo** chooses **Tree trunk** again at $1,630.00.
+- **Undo** and **Redo** are not shown in the review step, in the confirmation or in fullscreen.
+- Clicking **Fullscreen** and **Exit fullscreen** each pushes the `fullscreenButton` user-action event, as an `AnalyticsService.push` line in the browser console shows: without a Google Tag Manager id, Storybook's analytics only log their events with `console.debug`, which the console shows only with its Verbose level enabled.
+- Entering fullscreen while **Request a quote** is pending and leaving it again shows the panel with the spinner still running, until the thank-you message appears.
+- A round button sits on the middle of the table's long edge. Clicking it opens the four finishes next to it; choosing **Round** there moves the check mark in the popover and in the panel, rounds the edge and raises the price to $1,410.00. Escape closes the popover.
+- Tab reaches the button on the edge, and Enter or Space opens the popover.
+- The button on the edge is gone in the review step, in the confirmation and in both read routes, and stays in fullscreen.
+- In the **Phone** story the panel is a sheet at the bottom showing the name, the price and **Review and request a quote**, and the whole table is visible above it.
+- Tapping the sheet's handle, or dragging it up, opens the sheet with the cards; the table moves up once the sheet has snapped and stays fully visible. Dragging the handle down, or tapping it again, collapses the sheet.
+- 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, below the undo, redo and fullscreen buttons.
+- 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, 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.** Measurements, sharing and language switching are not offered; undo and redo are the layout's own buttons, see [Undo and redo](#undo-and-redo). A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons: `phx.frontend.useToolbarActions()` returns the spec's toolbar as runnable entries, and `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 `phx.frontend.useIsCloningAllowed()` and `LayoutSlots.CloneToEditDialog`. The example leaves it out because Storybook cannot show the result: the dialog creates and opens the copy, but the mock template keeps its `read-revision` access on every configuration it opens, so the copy opens in read mode again.
+- **Back and close.** The built-in header's back button returns to the product choice, runs the host's close action or leaves the expanded view, whichever applies. This layout has none of them. `phx.frontend.useCloseAction()` returns the host's close action, or `null` when there is none, as in this Storybook example; the hook that chooses among the three is not exported.
+- **Analytics.** The finalize button records `FinalizeButtonClicked` through `useFinalizeActions`, the cards record the attribute choice through `useAttributeSelection`, undo and redo record their events through `useUndoRedo`, and the fullscreen button records `FullScreenModeToggled` itself. The review step's navigation buttons, the view buttons, **Reset view**, the sheet's handle and the button on the table's edge record nothing. A layout that wants more events pushes them from `FrontendAnalyticsFactory`, from `@salsita-ai/sdk/configurator`, with `phx.frontend.useAnalytics().push(...)`, as [Offer fullscreen](#offer-fullscreen) does.
+- **Preview start screen.** The built-in layout shows a preview while `phx.frontend.usePreview().isPreview` is set, which `preview: auto` does on phones without the project opting in. This layout ignores it and always renders the interface.
+- **Assistant panel.** A project layout gets it only with `LayoutSlots.DesktopSidebar`, the built-in sidebar as one piece, see [Sidebar in a Custom Layout](?path=/docs/layouts-sidebar-in-a-custom-layout--docs); this layout does not use it.
+- **"Powered by Salsita" mark.** The built-in layout shows it; a project layout decides whether to mount `LayoutSlots.DesktopPoweredBy`, and this one does not.
+
+## Related pages
+
+- [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) is the reference for the element name, the minimal layout, the SDK pieces a layout can mount and the hooks it reads.
+- [Universal](?path=/docs/layouts-universal--docs) is the built-in layout this one replaces.
+- [Header / Custom](?path=/docs/layouts-header-custom--docs) replaces only the header, with the price from `useRootEntityPrice()`.
+- [Canvas Padding](?path=/docs/layouts-canvas-padding--docs) scales the gaps `phx.frontend.useSceneSafeArea()` measures.
+- [Presets / Custom](?path=/docs/layouts-presets-custom--docs) replaces the preset screen the same way.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Table
+    aliases:
+      RootEntity:
+        - Table
+    commonTypes:
+      EdgeFinish:
+        enum:
+          - None
+          - Facet
+          - Round
+          - TreeTrunk
+    shapes:
+      Table:
+        edgeFinish:
+          $ref: '#/model/latest/commonTypes/EdgeFinish'
+
+presets:
+  - rootEntityType: Table
+    initialDomainEntities:
+      - id: Table-1
+        type: Table
+        edgeFinish: None
+
+navigationStates:
+  - configure
+  - checkout
+  - requested
+
+viewStates:
+  - overview
+  - edge
+
+components:
+  Table:
+    detail:
+      main:
+        title: Linden dining table
+        subtitle: Solid oak, seats six
+        description: A solid oak top on slender steel legs, finished with the edge profile of your choice.
+    price:
+      main:
+        price:
+          $read: $price
+    attributeSelection:
+      edgeFinish:
+        value:
+          $bind: edgeFinish
+        options:
+          - label: Square
+            description: Crisp and modern
+            value: None
+          - label: Facet
+            description: A light bevel
+            value: Facet
+          - label: Round
+            description: Soft to the touch
+            value: Round
+          - label: Tree trunk
+            description: The natural edge
+            value: TreeTrunk
+    finalizeAction:
+      quote:
+        variant: primary
+        label: Request a quote
+        title: Send the configuration to the shop for a quote
+        icon: PaperPlaneTilt
+        handler: requestQuote
+    htmlHotspot:
+      edgeFinish:
+        name: EdgeFinishHotspot
+        offsetX: 500
+        offsetY: 800
+        offsetZ: 0
+        $filter:
+          modes: [owner]
+          navigationStates: [configure]
+    fitRootPerspectiveCamera:
+      main:
+        priority: 2
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 9000
+        distance: 5000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        fitMeshChanges: true
+        $filter:
+          viewports: [desktop]
+      phone:
+        priority: 1
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 12000
+        distance: 8000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        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
+        objectName: RECHTHOEK_RECTANGLE
+        dimensionUnit: m
+      leg:
+        fileUrl: /models/tables.gltf
+        objectName: AXL_LEG
+        dimensionUnit: m
+    sceneEntityObjectProperties:
+      top:
+        offsetY: 820
+        morphTargetInfluences:
+          Facet:
+            value:
+              $read: $edgeFinishFacet
+            scaleOne: 1
+            scaleZero: 0
+          Bol:
+            value:
+              $read: $edgeFinishRound
+            scaleOne: 1
+            scaleZero: 0
+          Boomstamrand:
+            value:
+              $read: $edgeFinishTreeTrunk
+            scaleOne: 1
+            scaleZero: 0
+      leg:
+        morphTargetInfluences:
+          Length:
+            value: 1000
+            scaleOne: 3000
+            scaleZero: 1400
+          Width:
+            value: 700
+            scaleOne: 1300
+            scaleZero: 600
+          Height:
+            value: 780
+            scaleOne: 780
+            scaleZero: 740
+
+transformers:
+  - name: tree-trunk-delivery
+```
+
+### ./src/\_shared/BottomSheet.tsx
+
+```tsx
+import { Box, ButtonBase } from '@mui/material'
+import { type MouseEvent, type PointerEvent, type ReactNode, useRef } from 'react'
+
+// A drag shorter than this is a tap, and the handle's click toggles the sheet
+const TAP_DISTANCE = 6
+// A drag that ends this far from where it started snaps to the other position
+const SNAP_DISTANCE = 48
+// A drag faster than this, in pixels per millisecond, snaps in its direction even when it is short
+const SNAP_VELOCITY = 0.5
+// How far the sheet follows the finger towards the position it is already in
+const OVERDRAG = 0.25
+
+interface BottomSheetProps {
+  readonly open: boolean
+  readonly onOpenChange: (open: boolean) => void
+  readonly label: string
+  readonly children: ReactNode
+}
+
+interface Drag {
+  readonly startY: number
+  readonly startTime: number
+  delta: number
+}
+
+// A persistent sheet at the bottom of the layout with two positions, open and collapsed. It is not a modal: the scene
+// above it stays interactive. Its height comes from its content, so the layout's safe area ends where the sheet
+// starts and changes only when the sheet snaps. While the handle is dragged the sheet follows the finger with a
+// transform, which the safe area does not see, so the camera refits once per snap and not on every move.
+export const BottomSheet = ({ open, onOpenChange, label, children }: BottomSheetProps) => {
+  const sheetRef = useRef<HTMLElement>(null)
+  const dragRef = useRef<Drag | null>(null)
+  const draggedRef = useRef(false)
+
+  const moveSheet = (offset: number, animate: boolean) => {
+    if (sheetRef.current) {
+      sheetRef.current.style.transition = animate ? 'transform 200ms ease-out' : 'none'
+      sheetRef.current.style.transform = offset === 0 ? '' : `translateY(${offset}px)`
+    }
+  }
+
+  const handlePointerDown = (event: PointerEvent<HTMLButtonElement>) => {
+    event.currentTarget.setPointerCapture(event.pointerId)
+    dragRef.current = { startY: event.clientY, startTime: event.timeStamp, delta: 0 }
+    draggedRef.current = false
+  }
+
+  const handlePointerMove = (event: PointerEvent<HTMLButtonElement>) => {
+    const drag = dragRef.current
+
+    if (drag === null) {
+      return
+    }
+
+    drag.delta = event.clientY - drag.startY
+    // Down closes an open sheet and up opens a collapsed one; the other direction only gives a little
+    const towardsOther = open ? drag.delta > 0 : drag.delta < 0
+    moveSheet(towardsOther ? drag.delta : drag.delta * OVERDRAG, false)
+  }
+
+  const handlePointerEnd = (event: PointerEvent<HTMLButtonElement>) => {
+    const drag = dragRef.current
+    dragRef.current = null
+
+    if (drag === null) {
+      return
+    }
+
+    moveSheet(0, true)
+
+    if (Math.abs(drag.delta) < TAP_DISTANCE) {
+      return
+    }
+
+    draggedRef.current = true
+    const velocity = drag.delta / Math.max(event.timeStamp - drag.startTime, 1)
+    const flicked = Math.abs(drag.delta) >= SNAP_DISTANCE || Math.abs(velocity) >= SNAP_VELOCITY
+
+    if (flicked && (open ? drag.delta > 0 : drag.delta < 0)) {
+      onOpenChange(!open)
+    }
+  }
+
+  // A tap, Enter or Space toggles the sheet. The pointer click that ends a drag has already been handled; a keyboard
+  // click (`detail` 0) always toggles, also after a touch drag that was followed by no click.
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    const dragged = draggedRef.current
+    draggedRef.current = false
+
+    if (dragged && event.detail !== 0) {
+      return
+    }
+
+    onOpenChange(!open)
+  }
+
+  return (
+    <Box
+      component="section"
+      ref={sheetRef}
+      aria-label={label}
+      sx={{
+        position: 'relative',
+        flexShrink: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        maxBlockSize: '55%',
+        paddingBlockEnd: 'env(safe-area-inset-bottom)',
+        borderStartStartRadius: 20,
+        borderStartEndRadius: 20,
+        bgcolor: 'background.paper',
+        boxShadow: '0 -8px 32px rgba(0, 0, 0, 0.12)',
+        // Fills the gap below the sheet while it is dragged up
+        '&::after': {
+          content: '""',
+          position: 'absolute',
+          insetInline: 0,
+          insetBlockStart: '100%',
+          blockSize: '100vh',
+          bgcolor: 'background.paper',
+        },
+      }}
+    >
+      <ButtonBase
+        aria-expanded={open}
+        disableRipple
+        aria-label={open ? `Collapse ${label.toLowerCase()}` : `Expand ${label.toLowerCase()}`}
+        onClick={handleClick}
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerEnd}
+        onPointerCancel={handlePointerEnd}
+        sx={{
+          flexShrink: 0,
+          blockSize: 36,
+          touchAction: 'none',
+          '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: -4, borderRadius: 3 },
+        }}
+      >
+        <Box component="span" sx={{ inlineSize: 40, blockSize: 4, borderRadius: 2, bgcolor: 'text.disabled' }} />
+      </ButtonBase>
+      {/* A column, so the panel's cards region shrinks first and the price and action stay in view; below the cards
+          region's minimum height the content scrolls as a whole, as the review step does on a short phone */}
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          flexDirection: 'column',
+          flex: '1 1 auto',
+          minBlockSize: 0,
+          overflowY: 'auto',
+          overscrollBehavior: 'contain',
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/EdgeFinishCards.tsx
+
+```tsx
+import { Box, ButtonBase, type SxProps, type Theme, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import type { UseAttributeSelection } from '@salsita-ai/sdk/react'
+
+// Cross-sections of the tabletop's edge, keyed by the option values of the spec.
+const EDGE_PROFILES: Readonly<Record<string, string>> = {
+  None: 'M0 4H32V20H0Z',
+  Facet: 'M0 4H26L32 10V14L26 20H0Z',
+  Round: 'M0 4H24A8 8 0 0 1 24 20H0Z',
+  TreeTrunk: 'M0 4H27C33 5 28 9 34 11C29 13 34 17 27 20H0Z',
+}
+
+const CHECK_BADGE: SxProps<Theme> = {
+  position: 'absolute',
+  insetBlockStart: 10,
+  insetInlineEnd: 10,
+  display: 'grid',
+  placeItems: 'center',
+  inlineSize: 22,
+  blockSize: 22,
+  borderRadius: '50%',
+  bgcolor: 'primary.main',
+  color: 'primary.contrastText',
+  fontSize: 13,
+}
+
+// Arrow keys move the selection between the cards, as in a native radio group.
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface EdgeFinishCardsProps {
+  readonly selection: ReturnType<UseAttributeSelection>
+}
+
+export const EdgeFinishCards = ({ selection }: EdgeFinishCardsProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const { options } = selection
+  // The card in the tab order: the selected one, or the first enabled one. Disabled cards are never in it.
+  const selectedIndex = options.findIndex(option => option.value === selection.value && !option.disabled)
+  const focusIndex = selectedIndex >= 0 ? selectedIndex : options.findIndex(option => !option.disabled)
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>, index: number) => {
+    const step = ARROW_STEPS[event.key]
+
+    if (step === undefined) {
+      return
+    }
+
+    event.preventDefault()
+    // The next enabled option in the arrow's direction, wrapping around; disabled options are skipped.
+    const count = options.length
+    const next = Array.from(
+      { length: count - 1 },
+      (_, offset) => (((index + step * (offset + 1)) % count) + count) % count
+    ).find(candidate => !options[candidate]?.disabled)
+
+    if (next === undefined) {
+      return
+    }
+
+    options[next]?.onSelect()
+    event.currentTarget.parentElement?.querySelectorAll<HTMLElement>('[role="radio"]')[next]?.focus()
+  }
+
+  return (
+    <Box
+      component="div"
+      role="radiogroup"
+      aria-label="Edge finish"
+      sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 1.5 }}
+    >
+      {options.map((option, index) => {
+        const isSelected = option.value === selection.value
+
+        return (
+          <ButtonBase
+            key={String(option.value)}
+            role="radio"
+            aria-checked={isSelected}
+            tabIndex={index === focusIndex ? 0 : -1}
+            disabled={option.disabled}
+            onClick={option.onSelect}
+            onKeyDown={event => handleKeyDown(event, index)}
+            sx={{
+              position: 'relative',
+              display: 'grid',
+              justifyItems: 'start',
+              gap: 0.5,
+              padding: 2,
+              borderRadius: 3,
+              border: 2,
+              borderColor: isSelected ? 'primary.main' : 'divider',
+              bgcolor: isSelected ? 'action.hover' : 'transparent',
+              textAlign: 'start',
+              transition: 'border-color 150ms, background-color 150ms',
+              '&:hover': { borderColor: isSelected ? 'primary.main' : 'text.disabled' },
+              '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+              '&.Mui-disabled': { opacity: 0.4 },
+            }}
+          >
+            {isSelected && (
+              <Box component="span" aria-hidden sx={CHECK_BADGE}>
+                ✓
+              </Box>
+            )}
+            <Box
+              component="svg"
+              viewBox="0 0 36 24"
+              aria-hidden
+              sx={{ inlineSize: 60, blockSize: 40, color: '#b98b5e' }}
+            >
+              <path d={EDGE_PROFILES[String(option.value)]} fill="currentColor" />
+            </Box>
+            <Typography variant="body2" fontWeight={600}>
+              {resolve(option.title)}
+            </Typography>
+            <Typography variant="caption" color="text.secondary">
+              {resolve(option.description)}
+            </Typography>
+          </ButtonBase>
+        )
+      })}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/FullscreenToggle.tsx
+
+```tsx
+import { Button, Tooltip } from '@mui/material'
+
+import { FrontendAnalyticsFactory } from '@salsita-ai/sdk/configurator'
+
+const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
+const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
+
+interface FullscreenToggleProps {
+  // Only the icon, with the label as its accessible name and tooltip, where a label would cover the product
+  readonly compact?: boolean
+}
+
+export const FullscreenToggle = ({ compact = false }: FullscreenToggleProps) => {
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const setFullscreen = phx.frontend.useSetFullscreen()
+  const analytics = phx.frontend.useAnalytics()
+  const label = isFullscreen ? 'Exit fullscreen' : 'Fullscreen'
+  const icon = (
+    <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+      <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
+    </svg>
+  )
+
+  // The same event the built-in fullscreen button records, for entering and for leaving
+  const toggle = () => {
+    analytics.push(FrontendAnalyticsFactory.FullScreenModeToggled())
+    setFullscreen(!isFullscreen)
+  }
+
+  return (
+    <Tooltip title={compact ? label : ''}>
+      <Button
+        onClick={toggle}
+        aria-label={compact ? label : undefined}
+        startIcon={compact ? undefined : icon}
+        sx={{
+          minBlockSize: 44,
+          minInlineSize: 44,
+          paddingInline: compact ? 0 : 2.5,
+          borderRadius: 999,
+          bgcolor: 'background.paper',
+          color: 'text.primary',
+          boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+          textTransform: 'none',
+          fontWeight: 600,
+          '&:hover': { bgcolor: 'background.paper', boxShadow: '0 6px 20px rgba(0, 0, 0, 0.18)' },
+        }}
+      >
+        {compact ? icon : label}
+      </Button>
+    </Tooltip>
+  )
+}
+```
+
+### ./src/\_shared/MessageToast.tsx
+
+```tsx
+import { Alert } from '@mui/material'
+import { useEffect, useState } from 'react'
+
+import type { ConfiguratorMessage } from '@salsita-ai/sdk/react'
+
+const VIOLATION_SEVERITY = { fatal: 'error', fixable: 'error', warning: 'warning', notice: 'info' } as const
+const RANK = { info: 0, warning: 1, error: 2 } as const
+const VISIBLE_MS = 6000
+
+const severityOf = (message: ConfiguratorMessage) => {
+  if (message.kind === 'violation') {
+    return VIOLATION_SEVERITY[message.violation.severity]
+  }
+
+  return message.kind === 'error' || message.kind === 'saveError' ? 'error' : 'info'
+}
+
+export const MessageToast = () => {
+  const [message, setMessage] = useState<ConfiguratorMessage | null>(null)
+
+  // A rejected change also reports the notices already present; keep the worst message while it is shown
+  phx.frontend.useConfiguratorMessages(next => {
+    setMessage(shown => (shown !== null && RANK[severityOf(next)] < RANK[severityOf(shown)] ? shown : next))
+  })
+
+  useEffect(() => {
+    if (message === null) {
+      return
+    }
+
+    const timeout = setTimeout(() => setMessage(null), VISIBLE_MS)
+
+    return () => clearTimeout(timeout)
+  }, [message])
+
+  if (message === null) {
+    return null
+  }
+
+  return (
+    <Alert
+      severity={severityOf(message)}
+      onClose={() => setMessage(null)}
+      sx={{ maxInlineSize: 420, borderRadius: 3, boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)' }}
+    >
+      {message.text}
+    </Alert>
+  )
+}
+```
+
+### ./src/\_shared/ProductPanel.tsx
+
+```tsx
+import { Box, Button, Typography } from '@mui/material'
+
+import { detailComponent } from '@salsita-ai/sdk/domain'
+
+import { EdgeFinishCards } from './EdgeFinishCards.js'
+import { ReviewActions } from './ReviewActions.js'
+
+const BUTTON_SX = { minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 } as const
+
+interface ProductPanelProps {
+  // Only the name, the price and the action, for a collapsed bottom sheet
+  readonly collapsed?: boolean
+  // In a bottom sheet the cards region keeps the top of the cards in view, and the sheet scrolls when that does not fit
+  readonly inSheet?: boolean
+}
+
+export const ProductPanel = ({ collapsed = false, inSheet = false }: ProductPanelProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const price = phx.frontend.useRootEntityPrice()
+  const tableId = phx.frontend.useRootEntityId()
+  const edgeFinish = phx.frontend.useAttributeSelection(tableId, 'edgeFinish')
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const pushNavigate = phx.frontend.usePushNavigate()
+  const popNavigate = phx.frontend.usePopNavigate()
+  const navigate = phx.frontend.useNavigate()
+
+  const isReadMode = accessInfo.viewMode
+  const isReview = isReadMode || navigationState !== 'configure'
+  const chosenEdge = edgeFinish.options.find(option => option.value === edgeFinish.value)
+
+  return (
+    <>
+      <Box component="header" sx={{ display: 'grid', gap: 1, padding: 3, paddingBlockEnd: 2 }}>
+        {isReadMode ? (
+          <Typography
+            variant="overline"
+            sx={{ justifySelf: 'start', paddingInline: 1.5, borderRadius: 999, bgcolor: 'action.selected' }}
+          >
+            View only
+          </Typography>
+        ) : (
+          <Typography variant="overline" color="text.secondary">
+            {resolve(detail?.state.subtitle)}
+          </Typography>
+        )}
+        <Typography variant="h5" component="h2" fontWeight={700}>
+          {resolve(detail?.state.title)}
+        </Typography>
+        {!collapsed && (
+          <Typography variant="body2" color="text.secondary">
+            {resolve(detail?.state.description)}
+          </Typography>
+        )}
+      </Box>
+
+      {!collapsed && (
+        <Box
+          component="div"
+          sx={{
+            display: 'grid',
+            gap: 1.5,
+            paddingInline: 3,
+            paddingBlockEnd: 3,
+            // In a short container the region shrinks and scrolls; a scroll past its end moves its container on
+            minBlockSize: inSheet ? 120 : 0,
+            overflowY: 'auto',
+          }}
+        >
+          <Typography variant="subtitle2" component="h3">
+            Edge finish
+          </Typography>
+          {isReview ? (
+            <Box component="div" sx={{ padding: 2, borderRadius: 3, bgcolor: 'action.hover' }}>
+              <Typography variant="body2" fontWeight={600}>
+                {resolve(chosenEdge?.title)}
+              </Typography>
+              <Typography variant="caption" color="text.secondary">
+                {resolve(chosenEdge?.description)}
+              </Typography>
+            </Box>
+          ) : (
+            <EdgeFinishCards selection={edgeFinish} />
+          )}
+        </Box>
+      )}
+
+      <Box component="footer" sx={{ display: 'grid', gap: 2, padding: 3, borderTop: 1, borderColor: 'divider' }}>
+        <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
+          <Typography variant="body2" color="text.secondary">
+            Total price
+          </Typography>
+          <Typography variant="h5" component="p" fontWeight={700}>
+            {price}
+          </Typography>
+        </Box>
+        {!isReadMode && navigationState === 'configure' && (
+          <Button size="large" variant="contained" onClick={() => pushNavigate('checkout')} sx={BUTTON_SX}>
+            Review and request a quote
+          </Button>
+        )}
+        {!isReadMode && navigationState === 'checkout' && (
+          <>
+            <Typography variant="body2" color="text.secondary">
+              Your table is ready for a quote. A real shop collects the contact details here.
+            </Typography>
+            <ReviewActions onBack={popNavigate} />
+          </>
+        )}
+        {!isReadMode && navigationState === 'requested' && (
+          <>
+            <Typography variant="body2" role="status">
+              Thank you. Your quote request is on its way, and the shop replies within two working days.
+            </Typography>
+            <Button size="large" variant="outlined" onClick={() => navigate('configure')} sx={BUTTON_SX}>
+              Back to the configuration
+            </Button>
+          </>
+        )}
+      </Box>
+    </>
+  )
+}
+```
+
+### ./src/\_shared/ReviewActions.tsx
+
+```tsx
+import { Alert, Box, Button, CircularProgress, Typography } from '@mui/material'
+
+const BUTTON_SX = { minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 } as const
+
+interface ReviewActionsProps {
+  readonly onBack: () => void
+}
+
+// The review step's buttons: the spec's primary finalize action and the way back. `useFinalizeActions` runs the
+// action's handler beside the layout, so its pending state and error outlive this component: when the panel unmounts,
+// as in fullscreen, the request goes on and the remounted buttons still show it. Back is disabled while the request
+// is pending, so the customer cannot change the configuration while it is sent.
+export const ReviewActions = ({ onBack }: ReviewActionsProps) => {
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const isPending = primary?.isPending ?? false
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 2 }}>
+      {primary && (
+        <Box component="div" sx={{ display: 'grid', gap: 1 }}>
+          <Button
+            size="large"
+            variant="contained"
+            disabled={primary.disabled || isPending}
+            onClick={() => void primary.run()}
+            title={primary.title}
+            startIcon={isPending ? <CircularProgress size={18} color="inherit" /> : undefined}
+            sx={BUTTON_SX}
+          >
+            {isPending ? 'Sending the request…' : primary.label}
+          </Button>
+          {primary.disabled && hints && (
+            <Typography variant="caption" color="text.secondary">
+              {hints}
+            </Typography>
+          )}
+          {primary.error && <Alert severity="error">The request could not be sent: {primary.error.message}</Alert>}
+        </Box>
+      )}
+      <Button size="large" variant="outlined" disabled={isPending} onClick={onBack} sx={BUTTON_SX}>
+        Back to the configuration
+      </Button>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/SceneControls.tsx
+
+```tsx
+import { Box, Button, Tooltip } from '@mui/material'
+
+// 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/\_shared/UndoRedo.tsx
+
+```tsx
+import { Box, IconButton, Tooltip } from '@mui/material'
+
+const UNDO_ICON = 'M9 14 4 9l5-5M4 9h10.5a5.5 5.5 0 0 1 0 11H11'
+const REDO_ICON = 'M15 14l5-5-5-5M20 9H9.5a5.5 5.5 0 0 0 0 11H13'
+
+interface HistoryButtonProps {
+  readonly label: string
+  readonly icon: string
+  readonly enabled: boolean
+  readonly onClick: () => void
+}
+
+const HistoryButton = ({ label, icon, enabled, onClick }: HistoryButtonProps) => (
+  <Tooltip title={label}>
+    {/* A disabled button fires no pointer events, so the span keeps the tooltip working */}
+    <span>
+      <IconButton
+        aria-label={label}
+        disabled={!enabled}
+        onClick={onClick}
+        sx={{ inlineSize: 44, blockSize: 44, color: 'text.primary' }}
+      >
+        <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+          <path d={icon} />
+        </svg>
+      </IconButton>
+    </span>
+  </Tooltip>
+)
+
+// Undo and redo for the customer's choices. They change the configuration, so they are offered only where the cards
+// are: not to a viewer, and not in the review step, where the summary and a running request must not change under the
+// customer. `useUndoRedo` pushes the same analytics events as the built-in toolbar's buttons.
+export const UndoRedo = () => {
+  const { canUndo, canRedo, undo, redo } = phx.frontend.useUndoRedo()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+
+  if (accessInfo.viewMode || navigationState !== 'configure') {
+    return null
+  }
+
+  return (
+    <Box
+      component="div"
+      role="group"
+      aria-label="History"
+      sx={{
+        display: 'flex',
+        borderRadius: 999,
+        bgcolor: 'background.paper',
+        boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+      }}
+    >
+      <HistoryButton label="Undo" icon={UNDO_ICON} enabled={canUndo} onClick={undo} />
+      <HistoryButton label="Redo" icon={REDO_ICON} enabled={canRedo} onClick={redo} />
+    </Box>
+  )
+}
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { Box } from '@mui/material'
+import { useState } from 'react'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+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'
+import { UndoRedo } from '../_shared/UndoRedo.js'
+
+const GUTTER = 24
+const PANEL_WIDTH = 380
+const PHONE_GUTTER = 16
+const TOUCH_TARGET = 44
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  // `null` until the container has been measured; the layout shows only the scene until then
+  const viewports = phx.frontend.useActiveViewports()
+  const [isSheetOpen, setSheetOpen] = useState(false)
+
+  const isDesktop = viewports?.includes('desktop') ?? false
+  const gutter = isDesktop ? GUTTER : PHONE_GUTTER
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      // `clip`, not `hidden`: what overflows, such as the sheet's fill below its edge, can never be scrolled into view,
+      // not even by the browser when the focus moves
+      sx={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', overflow: 'clip' }}
+    >
+      <LayoutSlots.SharedCanvas />
+
+      {viewports !== null && isDesktop && !isFullscreen && (
+        <Box
+          component="aside"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: PANEL_WIDTH,
+            maxBlockSize: `calc(100% - ${2 * GUTTER}px)`,
+            display: 'flex',
+            flexDirection: 'column',
+            borderRadius: 5,
+            bgcolor: 'background.paper',
+            boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)',
+            // A very short container, such as a phone held sideways, scrolls the panel instead of clipping its footer
+            overflowX: 'hidden',
+            overflowY: 'auto',
+            overscrollBehavior: 'contain',
+          }}
+        >
+          <ProductPanel />
+        </Box>
+      )}
+
+      {viewports !== null && (
+        <Box
+          component="div"
+          ref={safeAreaRef}
+          sx={{
+            // Desktop: right of the panel. Phone: above the sheet, whose height the column gives the rest.
+            ...(isDesktop
+              ? {
+                  position: 'absolute',
+                  insetBlock: 0,
+                  insetInlineStart: isFullscreen ? 0 : PANEL_WIDTH + 2 * GUTTER,
+                  insetInlineEnd: 0,
+                }
+              : { position: 'relative', flex: '1 1 0', minBlockSize: 0 }),
+            pointerEvents: 'none',
+          }}
+        >
+          <Box
+            component="div"
+            sx={{
+              position: 'absolute',
+              insetBlockStart: gutter,
+              insetInlineEnd: gutter,
+              display: 'flex',
+              gap: 1,
+              pointerEvents: 'auto',
+            }}
+          >
+            {!isFullscreen && <UndoRedo />}
+            <FullscreenToggle compact={!isDesktop} />
+          </Box>
+          <Box
+            component="div"
+            sx={{
+              position: 'absolute',
+              pointerEvents: 'auto',
+              // Desktop: bottom left, above the row of view controls. Phone: at the top below the row of undo, redo and
+              // fullscreen, clear of the sheet's handle and the view controls.
+              ...(isDesktop
+                ? { insetBlockEnd: 2 * GUTTER + TOUCH_TARGET, insetInlineStart: GUTTER }
+                : { insetBlockStart: gutter + TOUCH_TARGET + gutter / 2, insetInline: gutter }),
+            }}
+          >
+            <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>
+      )}
+
+      {viewports !== null && !isDesktop && !isFullscreen && (
+        <BottomSheet open={isSheetOpen} onOpenChange={setSheetOpen} label="Product details">
+          <ProductPanel collapsed={!isSheetOpen} inSheet />
+        </BottomSheet>
+      )}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/elements/EdgeFinishHotspot.tsx
+
+```tsx
+import { Box, ButtonBase, Popover, Tooltip } from '@mui/material'
+import { useState } from 'react'
+
+import { EdgeFinishCards } from '../_shared/EdgeFinishCards.js'
+
+// The edge profile the button shows, the square edge of the cards' drawings
+const EDGE_ICON = 'M3 7H17L21 11V13L17 17H3Z'
+
+// Rendered by the spec's `htmlHotspot` on the table's edge: a button on the product that opens the edge finishes
+// next to the edge, with the same cards as the panel. The spec's `$filter` decides when it is shown.
+export default phx.frontend.createCustomPhoenixEntityElement('EdgeFinishHotspot', ({ entityId }) => {
+  const edgeFinish = phx.frontend.useAttributeSelection(entityId, 'edgeFinish')
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null)
+
+  return (
+    <>
+      <Tooltip title="Edge finish">
+        <ButtonBase
+          aria-label="Edge finish"
+          aria-haspopup="dialog"
+          aria-expanded={anchor !== null}
+          onClick={event => setAnchor(event.currentTarget)}
+          sx={{
+            display: 'grid',
+            placeItems: 'center',
+            inlineSize: 44,
+            blockSize: 44,
+            borderRadius: '50%',
+            bgcolor: 'background.paper',
+            color: 'primary.main',
+            boxShadow: '0 4px 16px rgba(0, 0, 0, 0.2)',
+            '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+          }}
+        >
+          <svg viewBox="0 0 24 24" width={22} height={22} aria-hidden>
+            <path d={EDGE_ICON} fill="currentColor" />
+          </svg>
+        </ButtonBase>
+      </Tooltip>
+      <Popover
+        open={anchor !== null}
+        anchorEl={anchor}
+        onClose={() => setAnchor(null)}
+        anchorOrigin={{ vertical: 'top', horizontal: 'center' }}
+        transformOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+        slotProps={{
+          paper: { role: 'dialog', 'aria-label': 'Edge finish', sx: { borderRadius: 4, marginBlockStart: -1 } },
+        }}
+      >
+        <Box component="div" sx={{ inlineSize: 340, maxInlineSize: 'calc(100vw - 32px)', padding: 2 }}>
+          <EdgeFinishCards selection={edgeFinish} />
+        </Box>
+      </Popover>
+    </>
+  )
+})
+```
+
+### ./src/expressions/table.ts
+
+```ts
+const EDGE_FINISH_SURCHARGE = { None: 0, Facet: 90, Round: 120, TreeTrunk: 340 }
+
+export default phx.domain.implementCustomExpressions({
+  Table: {
+    $price: s => {
+      return 1290 + EDGE_FINISH_SURCHARGE[s.edgeFinish]
+    },
+    $edgeFinishFacet: s => {
+      return s.edgeFinish === 'Facet' ? 1 : 0
+    },
+    $edgeFinishRound: s => {
+      return s.edgeFinish === 'Round' ? 1 : 0
+    },
+    $edgeFinishTreeTrunk: s => {
+      return s.edgeFinish === 'TreeTrunk' ? 1 : 0
+    },
+  },
+})
+```
+
+### ./src/handlers/request-quote.ts
+
+```ts
+import { useCallback } from 'react'
+
+// Stands in for the shop's quote service: the request takes a moment, then the panel shows the confirmation
+export default phx.frontend.createPhoenixHandler('requestQuote', () => {
+  const navigate = phx.frontend.useNavigate()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1500))
+      navigate('requested')
+    }, [navigate]),
+  }
+})
+```
+
+### ./src/transformers/tree-trunk-delivery.ts
+
+```ts
+import { msg } from '@lingui/core/macro'
+
+// A tree-trunk edge is cut by hand; choosing it carries a hint, which reaches the layout as a side-effect message
+export default phx.frontend.transformerBuilder.when
+  .entity(['Table'])
+  .modified({ atFields: ['edgeFinish'] })
+  .then.overrideMatchingUpdate(({ update }) => {
+    if (update.stateDelta.edgeFinish !== 'TreeTrunk') {
+      return [update]
+    }
+
+    return [{ ...update, hint: msg`Tree trunk edges are cut by hand, so delivery takes three weeks longer.` }]
+  })
+  .build('tree-trunk-delivery')
+```
+
+</details>