@salsita-ai/sdk 0.50.0-develop.2f8d91de91 → 0.50.0-develop.30ea3b5e1a

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

@@ -1,6 +1,6 @@
 # Custom Layout
 
-Make the configurator look like the brand's own product page. A furniture shop wants its table configurator to read like the rest of its site: a floating panel on the left with the product's name, the edge finishes as picture cards, the price in large type and one clear call to action, and the table in the space beside it. The project writes that page as one React component. Phoenix supplies the 3D scene, the product's state and a few hooks; every pixel around the scene is the project's own.
+Make the configurator look like the brand's own product page. A furniture shop wants its table configurator to read like the rest of its site: a floating panel on the left with the product's name, the edge finishes as picture cards, the price in large type and one clear call to action, and the table in the space beside it. On a phone the panel becomes a sheet at the bottom, and a button on the table's edge offers the finishes right where they apply. 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)
@@ -11,6 +11,8 @@ Make the configurator look like the brand's own product page. A furniture shop w
 - [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)
 - [The spec the layout reads](#the-spec-the-layout-reads)
 - [Try the example](#try-the-example)
 - [Test cases](#test-cases)
@@ -32,26 +34,43 @@ Create `src/elements/ConfiguratorLayout.tsx` with a default export made by `phx.
 
 ```tsx
 import { Box } from '@mui/material'
+import { useState } from 'react'
 
 import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+import { useActiveViewports } from '@salsita-ai/sdk/react'
 
 import { phx } from '../../.phoenix/phx.js'
+import { BottomSheet } from '../_shared/BottomSheet.js'
 import { FullscreenToggle } from '../_shared/FullscreenToggle.js'
 import { MessageToast } from '../_shared/MessageToast.js'
 import { ProductPanel } from '../_shared/ProductPanel.js'
 
 const GUTTER = 24
 const PANEL_WIDTH = 380
+const PHONE_GUTTER = 16
+const TOUCH_TARGET = 44
 
 const ConfiguratorLayout = () => {
   const { containerRef, safeAreaRef } = useSceneSafeArea()
   const isFullscreen = phx.frontend.useIsFullscreenActive()
+  // `null` until the container has been measured; the layout shows only the scene until then
+  const viewports = useActiveViewports()
+  const [isSheetOpen, setSheetOpen] = useState(false)
+
+  const isDesktop = viewports?.includes('desktop') ?? false
+  const gutter = isDesktop ? GUTTER : PHONE_GUTTER
 
   return (
-    <Box component="div" ref={containerRef} sx={{ position: 'absolute', inset: 0 }}>
+    <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 />
 
-      {!isFullscreen && (
+      {viewports !== null && isDesktop && !isFullscreen && (
         <Box
           component="aside"
           sx={{
@@ -65,37 +84,60 @@ const ConfiguratorLayout = () => {
             borderRadius: 5,
             bgcolor: 'background.paper',
             boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)',
-            overflow: 'hidden',
+            // 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>
       )}
 
-      <Box
-        component="div"
-        ref={safeAreaRef}
-        sx={{
-          position: 'absolute',
-          insetBlock: 0,
-          insetInlineStart: isFullscreen ? 0 : PANEL_WIDTH + 2 * GUTTER,
-          insetInlineEnd: 0,
-          pointerEvents: 'none',
-        }}
-      >
+      {viewports !== null && (
         <Box
           component="div"
-          sx={{ position: 'absolute', insetBlockStart: GUTTER, insetInlineEnd: GUTTER, pointerEvents: 'auto' }}
-        >
-          <FullscreenToggle />
-        </Box>
-        <Box
-          component="div"
-          sx={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, pointerEvents: 'auto' }}
+          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',
+          }}
         >
-          <MessageToast />
+          <Box
+            component="div"
+            sx={{ position: 'absolute', insetBlockStart: gutter, insetInlineEnd: gutter, pointerEvents: 'auto' }}
+          >
+            <FullscreenToggle compact={!isDesktop} />
+          </Box>
+          <Box
+            component="div"
+            sx={{
+              position: 'absolute',
+              pointerEvents: 'auto',
+              // Desktop: bottom left. Phone: at the top beside the fullscreen button, clear of the sheet's handle.
+              ...(isDesktop
+                ? { insetBlockEnd: GUTTER, insetInlineStart: GUTTER }
+                : { insetBlockStart: gutter, insetInline: `${gutter}px ${2 * gutter + TOUCH_TARGET}px` }),
+            }}
+          >
+            <MessageToast />
+          </Box>
         </Box>
-      </Box>
+      )}
+
+      {viewports !== null && !isDesktop && !isFullscreen && (
+        <BottomSheet open={isSheetOpen} onOpenChange={setSheetOpen} label="Product details">
+          <ProductPanel collapsed={!isSheetOpen} inSheet />
+        </BottomSheet>
+      )}
     </Box>
   )
 }
@@ -110,9 +152,10 @@ The components it uses live in `src/_shared/`, which Phoenix does not import by
 - **Position the root and cover the page.** `LayoutSlots.SharedCanvas` is absolutely positioned and fills its nearest positioned ancestor. The root here is `position: absolute; inset: 0`.
 - **Mount the shared canvas.** The app loader stays on screen until the scene has loaded. A layout without `LayoutSlots.SharedCanvas` never gets past the loader unless the project sets `appLoader: legacy`.
 - **Put the UI above the canvas.** The canvas is opaque. Content that is positioned and comes after it in the markup is painted above it; unpositioned content is painted under it and cannot be seen.
-- **Tell the camera where the free area is.** `useSceneSafeArea()` returns two refs. `containerRef` goes on the element that covers the whole canvas, `safeAreaRef` on the region the product should stay visible in, here everything right of the panel. 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.
+- **Tell the camera where the free area is.** `useSceneSafeArea()` returns two refs. `containerRef` goes on the element that covers the whole canvas, `safeAreaRef` on the region the product should stay visible in, here everything right of the panel, or above the sheet on a phone. The camera then frames the product in that region. The hook measures again whenever either of the two elements resizes; for a change no resize reports, such as a `transform` on an ancestor settling at the end of an animation, it also returns `update` to call. Without the two refs the product is centred in the whole canvas and sits against the panel.
 - **Let the pointer through.** The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'`; otherwise the scene cannot be orbited. The fullscreen button inside it switches pointer events back on.
-- **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 and lets the safe area start at the left edge, so the camera frames the product in the whole canvas.
+- **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 `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, and the layout decides what a viewer sees.
 
 ## Read and change the product
@@ -131,7 +174,14 @@ import { ReviewActions } from './ReviewActions.js'
 
 const BUTTON_SX = { minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 } as const
 
-export const ProductPanel = () => {
+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 = useResolveLocalizable()
   const detail = phx.frontend.useFirstRootComponent(detailComponent)
   const price = phx.frontend.useRootEntityPrice()
@@ -168,29 +218,44 @@ export const ProductPanel = () => {
         <Typography variant="h5" component="h2" fontWeight={700}>
           {resolve(detail?.state.title)}
         </Typography>
-        <Typography variant="body2" color="text.secondary">
-          {resolve(detail?.state.description)}
-        </Typography>
-      </Box>
-
-      <Box component="div" sx={{ display: 'grid', gap: 1.5, paddingInline: 3, paddingBlockEnd: 3, 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} />
+        {!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">
@@ -241,22 +306,23 @@ export const ProductPanel = () => {
 }
 ```
 
-| 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.useAccessService()`                                            | `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                     |
-| `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.useComponents({ componentTypes: [finalizeActionComponent] })`  | The spec's `finalizeAction` components; the panel offers the primary one in its review step. `finalizeActionComponent` comes from `@salsita-ai/sdk/domain`.                 |
-| `phx.frontend.useFinalizeAction(handler)`                                    | Run the finalize action's handler, with its pending state, its error and whether finalizing is possible; see [Request a quote](#request-a-quote).                           |
-| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | Read the fullscreen flag, and set it from the layout's own button.                                                                                                          |
-| `phx.frontend.useConfiguratorMessages(onMessage)`                            | Receive violations, side-effect hints and errors one by one, with their text resolved, for the layout's own toast; see [Show messages](#show-messages).                     |
-| `useResolveLocalizable()` from `@salsita-ai/sdk/react`                       | Turns the localizable texts of the spec into strings in the current language. [Localization](?path=/docs/phoenix-localization--docs) describes it and `LocalizableMessage`. |
-| `PhoenixHandlerBoundary` from `@salsita-ai/sdk/react`                        | Wraps the review step's buttons, so an edited handler takes effect without a reload.                                                                                        |
+| 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.useAccessService()`                                            | `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                     |
+| `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.useComponents({ componentTypes: [finalizeActionComponent] })`  | The spec's `finalizeAction` components; the panel offers the primary one in its review step. `finalizeActionComponent` comes from `@salsita-ai/sdk/domain`.                                 |
+| `phx.frontend.useFinalizeAction(handler)`                                    | Run the finalize action's handler, with its pending state, its error and whether finalizing is possible; see [Request a quote](#request-a-quote).                                           |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | Read the fullscreen flag, and set it from the layout's own button.                                                                                                                          |
+| `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The width classes of the configurator's container, or `null` before it is measured; the layout renders its phone arrangement unless it includes `desktop`, see [Fit a phone](#fit-a-phone). |
+| `phx.frontend.useConfiguratorMessages(onMessage)`                            | Receive violations, side-effect hints and errors one by one, with their text resolved, for the layout's own toast; see [Show messages](#show-messages).                                     |
+| `useResolveLocalizable()` from `@salsita-ai/sdk/react`                       | Turns the localizable texts of the spec into strings in the current language. [Localization](?path=/docs/phoenix-localization--docs) describes it and `LocalizableMessage`.                 |
+| `PhoenixHandlerBoundary` from `@salsita-ai/sdk/react`                        | Wraps the review step's buttons, so an edited handler takes effect without a reload.                                                                                                        |
 
 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`.
 
@@ -406,39 +472,50 @@ The drawings are keyed by the option values of the spec. A spec can carry a pict
 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.
 
 ```tsx
-import { Button } from '@mui/material'
+import { Button, Tooltip } from '@mui/material'
 
 import { phx } from '../../.phoenix/phx.js'
 
 const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
 const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
 
-export const FullscreenToggle = () => {
+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 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>
+  )
 
   return (
-    <Button
-      onClick={() => setFullscreen(!isFullscreen)}
-      startIcon={
-        <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
-          <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
-        </svg>
-      }
-      sx={{
-        minBlockSize: 44,
-        paddingInline: 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)' },
-      }}
-    >
-      {isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
-    </Button>
+    <Tooltip title={compact ? label : ''}>
+      <Button
+        onClick={() => setFullscreen(!isFullscreen)}
+        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>
   )
 }
 ```
@@ -447,7 +524,7 @@ The button stays in the free area in both states, so the way back is always wher
 
 ## Show messages
 
-When a change is rejected because it breaks an invariant, when a committed change carries a hint, or when an error is thrown while a change is validated, the configurator has a message for the customer. `phx.frontend.useConfiguratorMessages(onMessage)` calls `onMessage` once for each, with the text already in the customer's language, and the layout shows it its own way. Here a toast at the bottom of the free area shows a message for six seconds, colored by its severity:
+When a change is rejected because it breaks an invariant, when a committed change carries a hint, or when an error is thrown while a change is validated, the configurator has a message for the customer. `phx.frontend.useConfiguratorMessages(onMessage)` calls `onMessage` once for each, with the text already in the customer's language, and the layout shows it its own way. Here a toast shows a message for six seconds, colored by its severity, at the bottom of the free area on a desktop and at its top on a phone:
 
 ```tsx
 import { Alert } from '@mui/material'
@@ -581,7 +658,9 @@ interface ReviewActionsProps {
 
 // The review step's buttons: one finalize action and the way back. `useFinalizeAction` runs the action's handler,
 // so this component calls it exactly once and is rendered inside a `PhoenixHandlerBoundary` for that handler.
-// Back is disabled while the request is pending, so the confirmation never follows a configuration that changed.
+// Back is disabled while the request is pending, so the customer cannot change the configuration while it is sent.
+// The pending state belongs to this component: when the panel unmounts, as in fullscreen, the request goes on and
+// the remounted buttons are enabled again.
 export const ReviewActions = ({ handler, label, onBack }: ReviewActionsProps) => {
   const { run, isPending, error, disabled, hints } = phx.frontend.useFinalizeAction(handler)
 
@@ -614,7 +693,7 @@ export const ReviewActions = ({ handler, label, onBack }: ReviewActionsProps) =>
 ```
 
 - `run()` records the finalize-button click for analytics and runs the handler; it does nothing while `disabled` or `isPending`.
-- While `isPending` the button shows a spinner and cannot be clicked again, and **Back to the configuration** is disabled: leaving the review step then would let the confirmation arrive for a configuration that has changed since.
+- 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. `isPending` and `error` belong to the mounted component: entering fullscreen unmounts the panel, the request goes on, and the panel shown after fullscreen starts with both buttons enabled. A layout that must rule that out keeps the review step mounted, or hides its fullscreen button while a request runs.
 - `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.
 
@@ -622,7 +701,319 @@ The review step stays: a quote request is a commitment, so the customer sees the
 
 ## Serve read mode
 
-While `accessInfo.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; the finalize action is not offered, since `useFinalizeAction` does not check read mode itself. 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.
+While `accessInfo.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; the finalize action is not offered, since `useFinalizeAction` does not check read mode itself. 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).
+
+## 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.** `useActiveViewports()` from `@salsita-ai/sdk/react` 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`. `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, 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, so the toast has room beside it. 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 { phx } from '../../.phoenix/phx.js'
+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 spec the layout reads
 
@@ -680,6 +1071,8 @@ transformers:
 
 To see read mode, open **Mocks** in the editor rail on the left and apply the **Read User** template.
 
+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.
@@ -691,15 +1084,22 @@ To see read mode, open **Mocks** in the editor rail on the left and apply the **
 - **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.
 - With the **Read User** mock the panel says **View only**, shows the chosen finish and the price, and has no button, so no quote can be requested.
+- 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 with the **Read User** mock, 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, beside the fullscreen button.
+- On the phone, the fullscreen button removes the sheet and the table moves to the centre of the canvas; pressing it again brings the sheet back in the position it had.
 
 ## 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.
 
-- **Phone width.** The panel is written for desktop: on a narrow screen it covers the scene. A phone layout puts the panel in a bottom sheet and moves the safe area above it.
 - **Messages that stay snackbars.** The toast shows violations, side effects and errors, and the finalize button shows its own error. A failure to save the configuration is still raised as a snackbar, which renders into `LayoutSlots.DesktopSnackbarsRoot`; this layout mounts no snackbar root, so it appears outside the configurator. A layout that wants it inside mounts the root.
 - **Toolbar actions.** Undo and redo, camera reset, measurements, sharing and language switching are not offered. A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons.
-- **View controls, tool controls and leaving a tool mode.** A spec can configure view controls and tool controls, and a tool mode has a button that leaves it. The built-in layout places them with `LayoutSlots.DesktopViewControls`, `LayoutSlots.DesktopToolControls` and `LayoutSlots.DesktopCallToAction`; this layout mounts none of them, so they do not appear.
+- **View controls, tool controls and leaving a tool mode.** A spec can configure view controls and tool controls, and a tool mode has a button that leaves it. The built-in layout places them with `LayoutSlots.DesktopViewControls`, `LayoutSlots.DesktopToolControls` and `LayoutSlots.DesktopCallToAction`; this layout mounts none of them, so they do not appear. Nor does this layout build view buttons or a camera reset of its own.
 - **A project's layout dialog.** A dialog the project registers with `phx.frontend.createLayoutDialog` is shown by `LayoutDialog`, which the built-in layout mounts. This layout does not; a layout that needs the dialog mounts `LayoutDialog` from `@salsita-ai/sdk/configurator`.
 - **Selection.** The table has no parts to select. A product with selectable parts reads `phx.frontend.useSelectedDomainEntityId()` and shows the controls of the selected part.
 - **Clone to edit in read mode.** With `shareCloneToEdit` set, the built-in layout's `LayoutSlots.DesktopReadonlyBanner` offers **Edit configuration** to a viewer; this layout's "View only" label offers nothing. A layout mounts the banner, or builds its own action with `LayoutSlots.useIsCloningAllowed()` and `LayoutSlots.CloneToEditDialog`.
@@ -793,9 +1193,18 @@ components:
         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: 1
+        priority: 2
         fov: 35
         near: 100
         far: 10000
@@ -805,6 +1214,21 @@ components:
         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]
     sceneEntityRemoteObject:
       top:
         fileUrl: /models/tables.gltf
@@ -852,6 +1276,170 @@ 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
@@ -990,39 +1578,50 @@ export const EdgeFinishCards = ({ selection }: EdgeFinishCardsProps) => {
 ### ./src/\_shared/FullscreenToggle.tsx
 
 ```tsx
-import { Button } from '@mui/material'
+import { Button, Tooltip } from '@mui/material'
 
 import { phx } from '../../.phoenix/phx.js'
 
 const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
 const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
 
-export const FullscreenToggle = () => {
+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 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>
+  )
 
   return (
-    <Button
-      onClick={() => setFullscreen(!isFullscreen)}
-      startIcon={
-        <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
-          <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
-        </svg>
-      }
-      sx={{
-        minBlockSize: 44,
-        paddingInline: 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)' },
-      }}
-    >
-      {isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
-    </Button>
+    <Tooltip title={compact ? label : ''}>
+      <Button
+        onClick={() => setFullscreen(!isFullscreen)}
+        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>
   )
 }
 ```
@@ -1097,7 +1696,14 @@ import { ReviewActions } from './ReviewActions.js'
 
 const BUTTON_SX = { minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 } as const
 
-export const ProductPanel = () => {
+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 = useResolveLocalizable()
   const detail = phx.frontend.useFirstRootComponent(detailComponent)
   const price = phx.frontend.useRootEntityPrice()
@@ -1134,29 +1740,44 @@ export const ProductPanel = () => {
         <Typography variant="h5" component="h2" fontWeight={700}>
           {resolve(detail?.state.title)}
         </Typography>
-        <Typography variant="body2" color="text.secondary">
-          {resolve(detail?.state.description)}
-        </Typography>
-      </Box>
-
-      <Box component="div" sx={{ display: 'grid', gap: 1.5, paddingInline: 3, paddingBlockEnd: 3, 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} />
+        {!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">
@@ -1224,7 +1845,9 @@ interface ReviewActionsProps {
 
 // The review step's buttons: one finalize action and the way back. `useFinalizeAction` runs the action's handler,
 // so this component calls it exactly once and is rendered inside a `PhoenixHandlerBoundary` for that handler.
-// Back is disabled while the request is pending, so the confirmation never follows a configuration that changed.
+// Back is disabled while the request is pending, so the customer cannot change the configuration while it is sent.
+// The pending state belongs to this component: when the panel unmounts, as in fullscreen, the request goes on and
+// the remounted buttons are enabled again.
 export const ReviewActions = ({ handler, label, onBack }: ReviewActionsProps) => {
   const { run, isPending, error, disabled, hints } = phx.frontend.useFinalizeAction(handler)
 
@@ -1260,26 +1883,43 @@ export const ReviewActions = ({ handler, label, onBack }: ReviewActionsProps) =>
 
 ```tsx
 import { Box } from '@mui/material'
+import { useState } from 'react'
 
 import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+import { useActiveViewports } from '@salsita-ai/sdk/react'
 
 import { phx } from '../../.phoenix/phx.js'
+import { BottomSheet } from '../_shared/BottomSheet.js'
 import { FullscreenToggle } from '../_shared/FullscreenToggle.js'
 import { MessageToast } from '../_shared/MessageToast.js'
 import { ProductPanel } from '../_shared/ProductPanel.js'
 
 const GUTTER = 24
 const PANEL_WIDTH = 380
+const PHONE_GUTTER = 16
+const TOUCH_TARGET = 44
 
 const ConfiguratorLayout = () => {
   const { containerRef, safeAreaRef } = useSceneSafeArea()
   const isFullscreen = phx.frontend.useIsFullscreenActive()
+  // `null` until the container has been measured; the layout shows only the scene until then
+  const viewports = useActiveViewports()
+  const [isSheetOpen, setSheetOpen] = useState(false)
+
+  const isDesktop = viewports?.includes('desktop') ?? false
+  const gutter = isDesktop ? GUTTER : PHONE_GUTTER
 
   return (
-    <Box component="div" ref={containerRef} sx={{ position: 'absolute', inset: 0 }}>
+    <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 />
 
-      {!isFullscreen && (
+      {viewports !== null && isDesktop && !isFullscreen && (
         <Box
           component="aside"
           sx={{
@@ -1293,37 +1933,60 @@ const ConfiguratorLayout = () => {
             borderRadius: 5,
             bgcolor: 'background.paper',
             boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)',
-            overflow: 'hidden',
+            // 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>
       )}
 
-      <Box
-        component="div"
-        ref={safeAreaRef}
-        sx={{
-          position: 'absolute',
-          insetBlock: 0,
-          insetInlineStart: isFullscreen ? 0 : PANEL_WIDTH + 2 * GUTTER,
-          insetInlineEnd: 0,
-          pointerEvents: 'none',
-        }}
-      >
+      {viewports !== null && (
         <Box
           component="div"
-          sx={{ position: 'absolute', insetBlockStart: GUTTER, insetInlineEnd: GUTTER, pointerEvents: 'auto' }}
-        >
-          <FullscreenToggle />
-        </Box>
-        <Box
-          component="div"
-          sx={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, pointerEvents: 'auto' }}
+          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',
+          }}
         >
-          <MessageToast />
+          <Box
+            component="div"
+            sx={{ position: 'absolute', insetBlockStart: gutter, insetInlineEnd: gutter, pointerEvents: 'auto' }}
+          >
+            <FullscreenToggle compact={!isDesktop} />
+          </Box>
+          <Box
+            component="div"
+            sx={{
+              position: 'absolute',
+              pointerEvents: 'auto',
+              // Desktop: bottom left. Phone: at the top beside the fullscreen button, clear of the sheet's handle.
+              ...(isDesktop
+                ? { insetBlockEnd: GUTTER, insetInlineStart: GUTTER }
+                : { insetBlockStart: gutter, insetInline: `${gutter}px ${2 * gutter + TOUCH_TARGET}px` }),
+            }}
+          >
+            <MessageToast />
+          </Box>
         </Box>
-      </Box>
+      )}
+
+      {viewports !== null && !isDesktop && !isFullscreen && (
+        <BottomSheet open={isSheetOpen} onOpenChange={setSheetOpen} label="Product details">
+          <ProductPanel collapsed={!isSheetOpen} inSheet />
+        </BottomSheet>
+      )}
     </Box>
   )
 }
@@ -1331,6 +1994,68 @@ const ConfiguratorLayout = () => {
 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 { phx } from '../../.phoenix/phx.js'
+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