@salsita-ai/sdk 0.50.0-develop.a49722158a → 0.50.0-develop.a8cf9ffd01

package/dist/docs/layouts/gallery/kestrel-kettle.mdx

@@ -0,0 +1,1829 @@
+# Kestrel Kettle
+
+Sell a small product from one calm page that looks like the shop's own. A specialty-coffee shop, Aldermoor Coffee, sells its Kestrel pour-over kettle in three finishes, two handle woods and with or without a thermometer lid. The page reads like an editorial product page: the kettle on the left, a quiet column on the right with the name, the story, three rows of choices, the price and **Add to cart**, and the shop's promises in a thin strip at the bottom. On a phone the page opens on the shop's own start screen, "Make it yours", and then shows the kettle above one scrolling column. The project writes the page as one layout element; the spec holds the product, its prices, the rule between finish and wood, and the cart action.
+
+- [Try it](#try-it)
+- [What the example demonstrates](#what-the-example-demonstrates)
+- [One page over the scene](#one-page-over-the-scene)
+- [Choices from the spec](#choices-from-the-spec)
+- [A rule between two choices](#a-rule-between-two-choices)
+- [Add to cart](#add-to-cart)
+- [The phone's start screen](#the-phones-start-screen)
+- [The shop's footer and the Powered by mark](#the-shops-footer-and-the-powered-by-mark)
+- [Texts from the spec](#texts-from-the-spec)
+- [The stage and the model](#the-stage-and-the-model)
+- [Test cases](#test-cases)
+- [What this layout leaves out](#what-this-layout-leaves-out)
+- [Related pages](#related-pages)
+- [Complete Implementation](#complete-implementation)
+
+## Try it
+
+The phone version is under [The phone's start screen](#the-phones-start-screen).
+
+## What the example demonstrates
+
+[Custom Layout](?path=/docs/layouts-custom-layout--docs) explains how a project layout works: the element name, the scene, the safe area and the hooks. This page is a finished design built the same way, for a single-page product with no steps or tabs, and it shows the pieces Custom Layout does not use:
+
+| Piece                                                                                                  | Where                                                                            |
+| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `phx.frontend.useAttributeSwitch()` for an on/off choice                                               | `ThermometerRow`, [Choices from the spec](#choices-from-the-spec)                |
+| `LayoutSlots.Services` with the built-in snackbars in `DesktopSnackbarsRoot` and `MobileSnackbarsRoot` | [A rule between two choices](#a-rule-between-two-choices)                        |
+| `phx.frontend.useFinalizeActions()` for the spec's `addToCart` action                                  | `CartBlock`, [Add to cart](#add-to-cart)                                         |
+| `phx.frontend.usePreview()` with the layout's own start screen, and `phx.frontend.useCloseAction()`    | `PhonePoster`, `PhonePage`, [The phone's start screen](#the-phones-start-screen) |
+| `phx.frontend.createLayoutFooter` with `LayoutSlots.DesktopFooter` and `MobileFooter`                  | [The shop's footer](#the-shops-footer-and-the-powered-by-mark)                   |
+| `LayoutSlots.DesktopPoweredBy` and `MobilePoweredBy`                                                   | the footer strip and the end of the phone's column                               |
+| `phx.frontend.useLocalizable()` and `LocalizableMessage`                                               | `ProductHeading`, [Texts from the spec](#texts-from-the-spec)                    |
+| A `canvasCustomEnvironment` stage with procedural light and a contact shadow                           | `KettleStudio`, [The stage and the model](#the-stage-and-the-model)              |
+
+## One page over the scene
+
+`src/elements/ConfiguratorLayout.tsx` keeps the scene and the services mounted for as long as the configuration is open and chooses what lies over the scene: the start screen on a phone while `phx.frontend.usePreview().isPreview` is set, the phone page, or the desktop page. `phx.frontend.useActiveViewports()` tells desktop from phone by the width of the configurator's container, not the window.
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { DesktopPage } from '../_shared/DesktopPage.js'
+import { PhonePage } from '../_shared/PhonePage.js'
+import { PhonePoster } from '../_shared/PhonePoster.js'
+import { KESTREL } from '../_shared/tokens.js'
+
+// One page, no steps or tabs. The canvas and the services stay mounted the whole time; what lies over the canvas is
+// the phone's start screen, the phone page or the desktop page. Each calls `useSceneSafeArea` itself, so only the one
+// on screen tells the camera where the kettle goes.
+const ConfiguratorLayout = () => {
+  // `null` until the container has been measured; only the scene shows until then
+  const viewports = phx.frontend.useActiveViewports()
+  const { isPreview } = phx.frontend.usePreview()
+  const isDesktop = viewports?.includes('desktop') ?? false
+
+  return (
+    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: KESTREL.oat }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+      {viewports !== null && (isPreview ? <PhonePoster /> : isDesktop ? <DesktopPage /> : <PhonePage />)}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+- **Each arrangement measures its own safe area.** `DesktopPage`, `PhonePage` and `PhonePoster` each call `phx.frontend.useSceneSafeArea()` and attach `safeAreaRef` to a box inside the free area, inset from its edges. The camera fits the kettle into that box, so the inset is the breathing room around the product. Only the arrangement on screen is mounted, so only one of them steers the camera.
+- **The camera fits the product, it does not use a fixed distance.** Both `fitRootPerspectiveCamera` instances leave `distance` out and set `fitToBox: true`. A `distance` overrides the fit, and the kettle is then as large on a 390-pixel phone as on a desktop.
+- **Fullscreen** removes the column and the footer, so the free area, and the kettle with it, takes the whole canvas. The button sets the flag with `phx.frontend.useSetFullscreen()`; the layout reads it with `phx.frontend.useIsFullscreenActive()`. Like the built-in fullscreen button, it records `FrontendAnalyticsFactory.FullScreenModeToggled()` from `@salsita-ai/sdk/configurator` through `phx.frontend.useAnalytics().push()`, on entering and on leaving.
+
+## Choices from the spec
+
+The three choices are plain spec components on the root entity. The layout decides how they look: round swatches for the finish and the wood, a switch for the thermometer lid.
+
+```yaml
+components:
+  Kettle:
+    attributeSelection:
+      bodyFinish:
+        value:
+          $bind: bodyFinish
+        options:
+          - label: Brushed steel
+            description: Satin stainless that hides fingerprints
+            value: BrushedSteel
+          - label: Matte black
+            description: A soft powder coat
+            value: MatteBlack
+          - label: Copper
+            description: Lacquered copper, warm in the light
+            value: Copper
+      handleWood:
+        value:
+          $bind: handleWood
+        options:
+          - label: Walnut
+            description: Dark and oiled
+            value: Walnut
+          - label: Oak
+            description: Pale and matte
+            value: Oak
+    attributeSwitch:
+      thermometer:
+        value:
+          $bind: thermometer
+```
+
+`SwatchRow` draws one `attributeSelection` with `phx.frontend.useAttributeSelection(kettleId, instanceName)`: a `radiogroup` of round buttons, the chosen option's `title` beside the label and its `description` below. The colours of the swatches are the layout's, keyed by the option `value`; the spec's `attributeSelection` carries no label either, so "Body finish" and "Handle" are the layout's text too. The arrow keys move the selection within a row.
+
+An `attributeSwitch` is a boolean. `phx.frontend.useAttributeSwitch(kettleId, 'thermometer')` returns `state.value` and `onChange()`, which writes the opposite value, so it fits a switch directly:
+
+```tsx
+import { Box, Switch, Typography } from '@mui/material'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+interface ThermometerRowProps {
+  readonly readOnly: boolean
+}
+
+// The spec's `attributeSwitch` as a labelled switch: on, the lid carries a dial thermometer; off, a plain wooden knob
+export const ThermometerRow = ({ readOnly }: ThermometerRowProps) => {
+  const kettleId = phx.frontend.useRootEntityId()
+  const thermometer = phx.frontend.useAttributeSwitch(kettleId, 'thermometer')
+  const isOn = thermometer.state.value
+
+  return (
+    <Box component="section" sx={{ display: 'grid', gap: 0.5, paddingBlock: 2 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 2 }}>
+        <Typography component="h3" id="kestrel-thermometer-label" sx={LABEL_SX}>
+          Thermometer lid
+        </Typography>
+        <Switch
+          checked={isOn}
+          disabled={readOnly || thermometer.disabled}
+          onChange={thermometer.onChange}
+          inputProps={{ 'aria-labelledby': 'kestrel-thermometer-label' }}
+          sx={{
+            '& .MuiSwitch-switchBase.Mui-checked': { color: KESTREL.oat },
+            '& .MuiSwitch-switchBase.Mui-checked + .MuiSwitch-track': { bgcolor: KESTREL.copper, opacity: 1 },
+            '& .MuiSwitch-track': { bgcolor: KESTREL.hairline, opacity: 1 },
+          }}
+        />
+      </Box>
+      <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>
+        {isOn ? 'A dial in the lid shows when the water is ready to pour.' : 'A plain lid with a wooden knob.'}
+      </Typography>
+    </Box>
+  )
+}
+```
+
+The choices change the scene through the spec, not through the layout. A material override recolours the `Body` material from expressions in `src/expressions/kettle.ts`, which also add each choice's surcharge to `$price`, and the switch shows the dial or the knob:
+
+```yaml
+components:
+  Kettle:
+    sceneEntityObjectProperties:
+      knob:
+        visible:
+          $read: $plainKnob
+      thermometerDial:
+        visible:
+          $read: thermometer
+    sceneEntityLocalMaterialOverride:
+      body:
+        materialsToOverride: [Body]
+        materialType: physical
+        color:
+          $read: $bodyColor
+        metalness:
+          $read: $bodyMetalness
+        roughness:
+          $read: $bodyRoughness
+        clearcoat:
+          $read: $bodyClearcoat
+        clearcoatRoughness: 0.15
+```
+
+## A rule between two choices
+
+The copper body is sold only with the walnut handle. The rule is an invariant: its message and severity are in the spec, its condition in `src/invariants/kettle.ts`.
+
+```yaml
+invariants:
+  Kettle:
+    copperNeedsWalnut:
+      type: copperNeedsWalnut
+      severity: fixable
+      message: The copper body comes only with the walnut handle.
+```
+
+```ts
+// The copper body is sold only with the walnut handle. The spec marks the violation `fixable`, so a change that breaks
+// it is rejected and the built-in snackbar shows the spec's message.
+export default phx.domain.implementCustomInvariants({
+  Kettle: {
+    copperNeedsWalnut: s => {
+      return s.bodyFinish !== 'Copper' || s.handleWood === 'Walnut'
+    },
+  },
+})
+```
+
+The customer sees the rule twice:
+
+- **Before choosing.** While the handle is oak, the control hook marks the copper option `disabled` with `hint` set to the invariant's message. `SwatchRow` fades the swatch, sets `aria-disabled` and shows the hint below the row; while the body is copper, the oak swatch is faded the same way.
+- **After choosing anyway.** The faded swatch stays clickable and calls the option's `onSelect()`. A `fixable` violation rejects the change, the kettle keeps its finish, and `LayoutSlots.Services` raises the built-in snackbar "Kettle-1: The copper body comes only with the walnut handle." The built-in snackbar puts the entity id before the message.
+
+The snackbars render where the layout mounts a root. On a desktop `LayoutSlots.DesktopSnackbarsRoot` is a zero-height element at the bottom left of the free area, and the snackbars stack upwards from it. On a phone `LayoutSlots.MobileSnackbarsRoot` leaves them fixed to the viewport; `PhonePage` places them below its top bar by styling `notistackSnackbarClasses.container` from `@salsita-ai/sdk/ui`. Mount the snackbars or `phx.frontend.useConfiguratorMessages()`, not both, see [Custom Layout → Show messages](?path=/docs/layouts-custom-layout--docs#show-messages) for the other way.
+
+Passing the violation type to the hook's third argument, `fixableViolations`, does not enable the option: it only drops the violation from `hint`. A layout that wants the option clickable calls `onSelect()` on the disabled option, as `SwatchRow` does.
+
+## Add to cart
+
+The spec declares one finalize action. Its handler, `src/handlers/add-to-cart.ts`, stands in for the shop's cart: it waits, then enters the `added` navigation state.
+
+```yaml
+navigationStates:
+  - configure
+  - added
+```
+
+```yaml
+components:
+  Kettle:
+    finalizeAction:
+      addToCart:
+        variant: primary
+        label: Add to cart
+        title: Add the kettle as configured to the cart
+        icon: ShoppingBag
+        handler: addToCart
+```
+
+```ts
+import { useCallback } from 'react'
+
+// Stands in for the shop's cart: adding takes a moment, then the page shows the confirmation
+export default phx.frontend.createPhoenixHandler('addToCart', () => {
+  const navigate = phx.frontend.useNavigate()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1200))
+      navigate('added')
+    }, [navigate]),
+  }
+})
+```
+
+`CartBlock` shows the price from `phx.frontend.useRootEntityPrice()` and runs the action from `phx.frontend.useFinalizeActions().primary`. The hook runs the handler beside the layout, so the pending state survives the block unmounting, for example in fullscreen. In the `added` state the block confirms the purchase and **Make another** returns to `configure`; `KettleOptions` keeps the choices as they were added until then. A viewer of a shared configuration sees the price and no button, because neither hook checks read mode. `DesktopPage` keeps the block at the bottom of the column with `position: sticky`, so the button stays in view when a short window makes the column scroll.
+
+```tsx
+import { Alert, Box, Button, CircularProgress, Typography } from '@mui/material'
+
+import { KESTREL } from './tokens.js'
+
+const CHECK_ICON = 'M5 12.5 10 17.5 19 7'
+
+// The price and the spec's `addToCart` finalize action. `useFinalizeActions` runs the action's handler beside the
+// layout, so its pending state survives this block unmounting, as it does in fullscreen. The handler moves to the
+// `added` navigation state, where the block confirms the purchase instead. A viewer sees the price only.
+export const CartBlock = () => {
+  const price = phx.frontend.useRootEntityPrice()
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const navigate = phx.frontend.useNavigate()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const isPending = primary?.isPending ?? false
+
+  if (navigationState === 'added') {
+    return (
+      <Box component="div" role="status" sx={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+        <Box
+          component="svg"
+          viewBox="0 0 24 24"
+          aria-hidden
+          sx={{ inlineSize: 40, blockSize: 40, flex: 'none', padding: 1, borderRadius: '50%', bgcolor: KESTREL.sage }}
+        >
+          <path d={CHECK_ICON} fill="none" stroke={KESTREL.oat} strokeWidth={2.4} strokeLinecap="round" />
+        </Box>
+        <Box component="div" sx={{ display: 'grid', flex: 1 }}>
+          <Typography sx={{ fontFamily: KESTREL.display, fontSize: 20, color: KESTREL.charcoal }}>
+            In your cart
+          </Typography>
+          <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>Kestrel, {price}</Typography>
+        </Box>
+        <Button
+          onClick={() => navigate('configure')}
+          sx={{ textTransform: 'none', color: KESTREL.charcoal, textDecoration: 'underline', fontSize: 14 }}
+        >
+          Make another
+        </Button>
+      </Box>
+    )
+  }
+
+  const showButton = primary !== null && !accessInfo.viewMode
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.5 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 2 }}>
+        <Box component="div" sx={{ display: 'grid' }}>
+          <Typography sx={{ fontFamily: KESTREL.display, fontSize: 30, lineHeight: 1.1, color: KESTREL.charcoal }}>
+            {price}
+          </Typography>
+          <Typography sx={{ fontSize: 12, color: KESTREL.muted, whiteSpace: 'nowrap' }}>Ships in two days</Typography>
+        </Box>
+        {showButton && (
+          <Button
+            variant="contained"
+            disableElevation
+            disabled={primary.disabled || isPending}
+            onClick={() => void primary.run()}
+            title={primary.title}
+            startIcon={isPending ? <CircularProgress size={16} color="inherit" /> : undefined}
+            sx={{
+              minBlockSize: 52,
+              paddingInline: 4.5,
+              borderRadius: 999,
+              bgcolor: KESTREL.charcoal,
+              color: KESTREL.oat,
+              fontFamily: KESTREL.body,
+              fontSize: 15,
+              letterSpacing: '0.02em',
+              textTransform: 'none',
+              '&:hover': { bgcolor: '#000000' },
+              '&.Mui-disabled': { bgcolor: KESTREL.charcoal, color: KESTREL.oat, opacity: 0.55 },
+            }}
+          >
+            {isPending ? 'Adding…' : primary.label}
+          </Button>
+        )}
+      </Box>
+      {showButton && primary.disabled && hints && (
+        <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>{hints}</Typography>
+      )}
+      {primary?.error && <Alert severity="error">The kettle could not be added: {primary.error.message}</Alert>}
+    </Box>
+  )
+}
+```
+
+## The phone's start screen
+
+`preview: auto` at the top of the spec asks for a start screen when the configurator's container is phone-sized. The built-in layout shows `MobilePreview`; a project layout shows its own while `phx.frontend.usePreview().isPreview` is set, and calls `enter()` to open the page. The poster frames the kettle in the area above its text with its own `useSceneSafeArea()`.
+
+```yaml
+preview: auto
+```
+
+The same layout in a frame 390 pixels wide, as on a phone. It opens on the start screen; **Start designing** opens the page, and the close button at the top left returns to the start screen. Opened on its own from the sidebar, the **Phone** story sets Storybook's viewport to 390 × 844.
+
+```tsx
+import { Box, Button, Typography } from '@mui/material'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+// The layout's own start screen, shown on a phone while `usePreview().isPreview` is set (the spec's `preview: auto`).
+// It frames the kettle in the area above the text with its own safe area; `enter()` opens the page.
+export const PhonePoster = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const { enter } = phx.frontend.usePreview()
+  const price = phx.frontend.useRootEntityPrice()
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        fontFamily: KESTREL.body,
+        pointerEvents: 'none',
+      }}
+    >
+      <Typography
+        sx={{
+          paddingBlockStart: 3,
+          textAlign: 'center',
+          fontFamily: KESTREL.display,
+          fontSize: 20,
+          color: KESTREL.charcoal,
+        }}
+      >
+        Aldermoor
+      </Typography>
+      <Box component="div" ref={safeAreaRef} sx={{ flex: '1 1 0', minBlockSize: 0, marginInline: 3 }} />
+      <Box component="div" sx={{ display: 'grid', gap: 2, padding: 3, paddingBlockEnd: 4, pointerEvents: 'auto' }}>
+        <Typography sx={{ ...LABEL_SX, color: KESTREL.copper }}>The Kestrel pour-over kettle</Typography>
+        <Typography
+          component="h1"
+          sx={{
+            fontFamily: KESTREL.display,
+            fontSize: 48,
+            lineHeight: 1,
+            letterSpacing: '-0.01em',
+            color: KESTREL.charcoal,
+          }}
+        >
+          Make it yours
+        </Typography>
+        <Typography sx={{ fontSize: 15, lineHeight: 1.6, color: KESTREL.muted }}>
+          Three finishes, two woods and a thermometer lid if you want one. As shown, {price}.
+        </Typography>
+        <Button
+          variant="contained"
+          disableElevation
+          onClick={enter}
+          sx={{
+            marginBlockStart: 1,
+            minBlockSize: 52,
+            borderRadius: 999,
+            bgcolor: KESTREL.charcoal,
+            color: KESTREL.oat,
+            fontFamily: KESTREL.body,
+            fontSize: 15,
+            textTransform: 'none',
+            '&:hover': { bgcolor: '#000000' },
+          }}
+        >
+          Start designing
+        </Button>
+      </Box>
+    </Box>
+  )
+}
+```
+
+On a phone, `enter()` also expands the configurator, which `usePreview().isExpanded` reports. `PhonePage` offers one close button at the top left: the host's close action from `phx.frontend.useCloseAction()` when the integration provides one, otherwise `usePreview().leave()`, which returns to the start screen. Storybook provides no close action, so here the button returns to the start screen; with neither, the button is not shown.
+
+## The shop's footer and the Powered by mark
+
+`LayoutSlots.DesktopFooter` and `LayoutSlots.MobileFooter` render the project's `LayoutFooter` element, registered with `phx.frontend.createLayoutFooter`, and nothing when there is none. The desktop page mounts it in the footer strip, with `LayoutSlots.DesktopPoweredBy` at the strip's right end; the phone page mounts `MobileFooter` and `MobilePoweredBy` at the end of its column.
+
+```tsx
+import { Box } from '@mui/material'
+
+import { KESTREL } from '../_shared/tokens.js'
+
+const PROMISES = ['Free delivery over $75', 'Two-year warranty', '30-day returns']
+
+// The shop's promises. `createLayoutFooter` registers it as the `LayoutFooter` element, which the layout shows where it
+// mounts `LayoutSlots.DesktopFooter` or `LayoutSlots.MobileFooter`.
+const LayoutFooter = () => {
+  return (
+    <Box
+      component="ul"
+      sx={{
+        display: 'flex',
+        flexWrap: 'wrap',
+        columnGap: 3,
+        rowGap: 0.5,
+        margin: 0,
+        padding: 0,
+        listStyle: 'none',
+        fontSize: 12,
+        letterSpacing: '0.04em',
+        color: KESTREL.muted,
+      }}
+    >
+      {PROMISES.map(promise => (
+        <Box
+          component="li"
+          key={promise}
+          sx={{ display: 'flex', alignItems: 'center', gap: 1, '&::before': { content: '"·"', color: KESTREL.sage } }}
+        >
+          {promise}
+        </Box>
+      ))}
+    </Box>
+  )
+}
+
+export default phx.frontend.createLayoutFooter(LayoutFooter)
+```
+
+## Texts from the spec
+
+The `detail` component holds the name, the subtitle and the story. Its fields are `Localizable`, not `string`. `ProductHeading` resolves the title and subtitle with `phx.frontend.useLocalizable()` and renders the description in place with `LocalizableMessage` from `@salsita-ai/sdk/react`; `SwatchRow` resolves a list of option titles with `phx.frontend.useResolveLocalizable()`. See [Localization](?path=/docs/phoenix-localization--docs).
+
+```yaml
+components:
+  Kettle:
+    detail:
+      main:
+        title: Kestrel
+        subtitle: Pour-over kettle, 0.9 litres
+```
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { detailComponent } from '@salsita-ai/sdk/domain'
+import { LocalizableMessage } from '@salsita-ai/sdk/react'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+interface ProductHeadingProps {
+  readonly size: 'large' | 'small'
+}
+
+// The overline, the name and the story from the spec's `detail` component. Its texts are `Localizable`:
+// `useLocalizable` resolves one into a string and `LocalizableMessage` renders one in place.
+export const ProductHeading = ({ size }: ProductHeadingProps) => {
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const title = phx.frontend.useLocalizable(detail?.state.title)
+  const subtitle = phx.frontend.useLocalizable(detail?.state.subtitle)
+
+  return (
+    <Box component="header" sx={{ display: 'grid', gap: size === 'large' ? 2 : 1.5 }}>
+      <Typography sx={{ ...LABEL_SX, color: KESTREL.copper }}>Aldermoor Coffee</Typography>
+      <Box component="div" sx={{ display: 'grid', gap: 0.75 }}>
+        <Typography
+          component="h1"
+          sx={{
+            fontFamily: KESTREL.display,
+            fontSize: size === 'large' ? 60 : 40,
+            lineHeight: 1,
+            letterSpacing: '-0.01em',
+            color: KESTREL.charcoal,
+          }}
+        >
+          {title}
+        </Typography>
+        <Typography sx={{ fontFamily: KESTREL.body, fontSize: 15, color: KESTREL.muted }}>{subtitle}</Typography>
+      </Box>
+      <Typography sx={{ fontFamily: KESTREL.body, fontSize: 15, lineHeight: 1.65, color: KESTREL.charcoal }}>
+        <LocalizableMessage>{detail?.state.description}</LocalizableMessage>
+      </Typography>
+    </Box>
+  )
+}
+```
+
+## The stage and the model
+
+The spec's `canvasCustomEnvironment` names `KettleStudio`, a layout element rendered inside the scene. It paints the page's oat colour as the scene's background, so the scene and the column read as one surface, lights the kettle with drei's `Lightformer` panels, which show only in the reflections and need no image download, and grounds it with a `ContactShadows` plane just below its base. The scene is in millimetres.
+
+```tsx
+import { ContactShadows, Environment, Lightformer } from '@react-three/drei'
+
+import { KESTREL } from '../_shared/tokens.js'
+
+// The stage named by the spec's `canvasCustomEnvironment`: a backdrop, a soft shadow under the kettle and a studio of
+// light panels. The panels exist only in the reflections, so the metal finishes have something to mirror and no image
+// has to be downloaded. The scene is in millimetres.
+export default phx.frontend.createCustomPhoenixLayoutElement('KettleStudio', () => {
+  return (
+    <>
+      {/* The page's oat background, so the scene and the layout read as one surface */}
+      <color attach="background" args={[KESTREL.oat]} />
+      <ambientLight intensity={0.35} />
+      <directionalLight position={[400, 900, 600]} intensity={1.1} />
+
+      <Environment resolution={256} frames={1}>
+        <color attach="background" args={['#77706a']} />
+        {/* A softbox above, tall strips at the sides for the long highlights, a warm fill behind, a dim one in front */}
+        <Lightformer form="rect" intensity={2.4} position={[0, 6, 0]} rotation-x={Math.PI / 2} scale={[10, 6, 1]} />
+        <Lightformer form="rect" intensity={3} position={[-6, 1, 2]} rotation-y={Math.PI / 2} scale={[1.2, 8, 1]} />
+        <Lightformer form="rect" intensity={1.6} position={[6, 1, 3]} rotation-y={-Math.PI / 2} scale={[1.2, 8, 1]} />
+        <Lightformer form="rect" color="#f3d9c2" intensity={1} position={[0, 1, -8]} scale={[12, 4, 1]} />
+        <Lightformer form="rect" intensity={0.8} position={[0, 0, 8]} rotation-y={Math.PI} scale={[10, 3, 1]} />
+      </Environment>
+
+      <ContactShadows position={[0, -1, 0]} scale={520} far={60} blur={2.2} opacity={0.7} resolution={512} />
+    </>
+  )
+})
+```
+
+The kettle is `public/models/gallery/kettle.glb`, generated by `scripts/models/kettle.ts` in the Storybook package from three.js geometry: lathed body, lid, base ring and knob, a gooseneck spout and a flat handle swept along curves, and a dial with ticks and a needle. Each part is a named node the spec loads with `sceneEntityRemoteObject.<name>.objectName`; the parts that change with a choice carry the `Body` and `Handle` materials the overrides target. The script and its helper live in `scripts/models/`, outside the example's `src/`, because every file under `src/` is part of this page.
+
+## Test cases
+
+- The kettle stands on the left of the page, centred in the free area beside the column, with a soft shadow below it. The column shows "Aldermoor Coffee", **Kestrel**, the subtitle, the story, the three choices, **$175.00** and **Add to cart**; the footer strip shows the three promises and the Powered by mark.
+- **Matte black** turns the body, lid and spout black and the price to $185.00; **Copper** turns them copper at $220.00. The chosen swatch has a ring and its name and description change.
+- **Oak** turns the handle and, without the thermometer, the knob pale. The price drops by $10.
+- With **Oak** chosen, the **Copper** swatch is faded and "The copper body comes only with the walnut handle." is shown below the finishes. Clicking it keeps the finish and shows the snackbar "Kettle-1: The copper body comes only with the walnut handle." at the bottom left of the free area.
+- With **Copper** chosen, the **Oak** swatch is faded and the same sentence is shown below the handles.
+- Turning **Thermometer lid** off replaces the dial with a wooden knob and lowers the price by $20; turning it on brings the dial back.
+- Tab reaches the chosen swatch of each row, and the arrow keys move the selection, skipping a faded swatch.
+- **Add to cart** shows a spinner and "Adding…" for about a second, then "In your cart" with the price; the choices cannot be changed until **Make another**, which brings the button back.
+- **Fullscreen** removes the column and the footer, and the kettle moves to the centre of the canvas; **Exit fullscreen** brings both back.
+- Clicking **Fullscreen** and **Exit fullscreen** each pushes the `fullscreenButton` user-action event, as an `AnalyticsService.push` line in the browser console shows with its Verbose level enabled: without a Google Tag Manager id, Storybook's analytics log their events with `console.debug`.
+- In a window too short for the column, the column scrolls and the price with **Add to cart** stays at its bottom edge.
+- Dragging in the free area turns the kettle.
+- In the **Phone** story the start screen shows the kettle above "Make it yours" and **Start designing**. **Start designing** opens the page: the kettle at the top, the column below it and the price with **Add to cart** in a bar at the bottom of the screen.
+- On the phone, the column scrolls under the kettle and ends with the promises and the Powered by mark; the bar with the price stays.
+- On the phone, the snackbar of the copper rule appears below the top bar.
+- On the phone, the close button at the top left returns to the start screen.
+- The browser console shows no errors.
+
+## What this layout leaves out
+
+- **Undo and redo, sharing, measurements and the language switch.** The page has none of the toolbar's actions. A layout adds undo and redo with `phx.frontend.useUndoRedo()`, see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+- **Read mode.** The layout hides **Add to cart** and makes the choices inert while `phx.frontend.useAccessService().accessInfo.viewMode` is set, but the example ships no read template; [Custom Layout → Serve read mode](?path=/docs/layouts-custom-layout--docs#serve-read-mode) shows one.
+- **Messages in the layout's own UI.** The rejected change is a built-in snackbar; a layout that wants its own toast uses `phx.frontend.useConfiguratorMessages()` instead.
+- **The built-in arrangement.** Header, sidebar, sidebar footer, tabs, tool controls, view controls and the built-in `DesktopPreview` and `MobilePreview` are not mounted; this page draws its own. [Layout Slots](?path=/docs/phoenix-layout-slots--docs) lists every slot a project layout can mount.
+
+## Related pages
+
+- [Custom Layout](?path=/docs/layouts-custom-layout--docs) explains a project layout step by step.
+- [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout) lists every hook used here.
+- [Layout Slots](?path=/docs/phoenix-layout-slots--docs) describes `Services`, the snackbar roots, the footers and the Powered by mark.
+- [Preview / Auto](?path=/docs/layouts-preview-auto--docs) shows the built-in start screen that `preview: auto` opens.
+
+## 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
+preview: auto
+
+model:
+  latest:
+    entityTypes:
+      - Kettle
+    aliases:
+      RootEntity:
+        - Kettle
+    commonTypes:
+      BodyFinish:
+        enum:
+          - BrushedSteel
+          - MatteBlack
+          - Copper
+      HandleWood:
+        enum:
+          - Walnut
+          - Oak
+    shapes:
+      Kettle:
+        bodyFinish:
+          $ref: '#/model/latest/commonTypes/BodyFinish'
+        handleWood:
+          $ref: '#/model/latest/commonTypes/HandleWood'
+        thermometer:
+          type: boolean
+
+presets:
+  - rootEntityType: Kettle
+    initialDomainEntities:
+      - id: Kettle-1
+        type: Kettle
+        bodyFinish: BrushedSteel
+        handleWood: Walnut
+        thermometer: true
+
+navigationStates:
+  - configure
+  - added
+
+invariants:
+  Kettle:
+    copperNeedsWalnut:
+      type: copperNeedsWalnut
+      severity: fixable
+      message: The copper body comes only with the walnut handle.
+
+components:
+  Kettle:
+    detail:
+      main:
+        title: Kestrel
+        subtitle: Pour-over kettle, 0.9 litres
+        description: A gooseneck kettle for slow, even pours. The spout narrows to a steady thread of water, and the dial in the lid tells you when it has cooled to brewing temperature.
+    price:
+      main:
+        price:
+          $read: $price
+    attributeSelection:
+      bodyFinish:
+        value:
+          $bind: bodyFinish
+        options:
+          - label: Brushed steel
+            description: Satin stainless that hides fingerprints
+            value: BrushedSteel
+          - label: Matte black
+            description: A soft powder coat
+            value: MatteBlack
+          - label: Copper
+            description: Lacquered copper, warm in the light
+            value: Copper
+      handleWood:
+        value:
+          $bind: handleWood
+        options:
+          - label: Walnut
+            description: Dark and oiled
+            value: Walnut
+          - label: Oak
+            description: Pale and matte
+            value: Oak
+    attributeSwitch:
+      thermometer:
+        value:
+          $bind: thermometer
+    finalizeAction:
+      addToCart:
+        variant: primary
+        label: Add to cart
+        title: Add the kettle as configured to the cart
+        icon: ShoppingBag
+        handler: addToCart
+
+    canvasConfig:
+      main:
+        highlightingDisabled: true
+    canvasCustomEnvironment:
+      main:
+        name: KettleStudio
+    fitRootPerspectiveCamera:
+      desktop:
+        priority: 2
+        fov: 30
+        near: 10
+        far: 5000
+        minDistance: 350
+        maxDistance: 1400
+        azimuthAngle: 0.35
+        polarAngle: 1.2
+        minPolarAngle: 0.5
+        maxPolarAngle: 1.5
+        fitToBox: true
+        fitMeshChanges: false
+        $filter:
+          viewports: [desktop]
+      phone:
+        priority: 1
+        fov: 30
+        near: 10
+        far: 5000
+        minDistance: 350
+        maxDistance: 1600
+        azimuthAngle: 0.35
+        polarAngle: 1.2
+        minPolarAngle: 0.5
+        maxPolarAngle: 1.5
+        fitToBox: true
+        fitMeshChanges: false
+        $filter:
+          viewports: [mobile]
+
+    sceneEntityRemoteObject:
+      body:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: Body
+        dimensionUnit: m
+      lid:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: Lid
+        dimensionUnit: m
+      spout:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: Spout
+        dimensionUnit: m
+      baseRing:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: BaseRing
+        dimensionUnit: m
+      handle:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: Handle
+        dimensionUnit: m
+      handleCollars:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: HandleCollars
+        dimensionUnit: m
+      knob:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: Knob
+        dimensionUnit: m
+      thermometerDial:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: ThermometerDial
+        dimensionUnit: m
+      dialFace:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: DialFace
+        dimensionUnit: m
+      dialGlass:
+        fileUrl: /models/gallery/kettle.glb
+        objectName: DialGlass
+        dimensionUnit: m
+    sceneEntityObjectProperties:
+      knob:
+        visible:
+          $read: $plainKnob
+      thermometerDial:
+        visible:
+          $read: thermometer
+      dialFace:
+        visible:
+          $read: thermometer
+      dialGlass:
+        visible:
+          $read: thermometer
+    sceneEntityLocalMaterialOverride:
+      body:
+        materialsToOverride: [Body]
+        materialType: physical
+        color:
+          $read: $bodyColor
+        metalness:
+          $read: $bodyMetalness
+        roughness:
+          $read: $bodyRoughness
+        clearcoat:
+          $read: $bodyClearcoat
+        clearcoatRoughness: 0.15
+      handle:
+        materialsToOverride: [Handle]
+        color:
+          $read: $handleColor
+        metalness: 0
+        roughness: 0.58
+      glass:
+        materialsToOverride: [DialGlass]
+        materialType: physical
+        color: '#ffffff'
+        metalness: 0
+        roughness: 0.05
+        transparent: true
+        opacity: 0.18
+```
+
+### ./src/\_shared/CartBlock.tsx
+
+```tsx
+import { Alert, Box, Button, CircularProgress, Typography } from '@mui/material'
+
+import { KESTREL } from './tokens.js'
+
+const CHECK_ICON = 'M5 12.5 10 17.5 19 7'
+
+// The price and the spec's `addToCart` finalize action. `useFinalizeActions` runs the action's handler beside the
+// layout, so its pending state survives this block unmounting, as it does in fullscreen. The handler moves to the
+// `added` navigation state, where the block confirms the purchase instead. A viewer sees the price only.
+export const CartBlock = () => {
+  const price = phx.frontend.useRootEntityPrice()
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const navigate = phx.frontend.useNavigate()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const isPending = primary?.isPending ?? false
+
+  if (navigationState === 'added') {
+    return (
+      <Box component="div" role="status" sx={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+        <Box
+          component="svg"
+          viewBox="0 0 24 24"
+          aria-hidden
+          sx={{ inlineSize: 40, blockSize: 40, flex: 'none', padding: 1, borderRadius: '50%', bgcolor: KESTREL.sage }}
+        >
+          <path d={CHECK_ICON} fill="none" stroke={KESTREL.oat} strokeWidth={2.4} strokeLinecap="round" />
+        </Box>
+        <Box component="div" sx={{ display: 'grid', flex: 1 }}>
+          <Typography sx={{ fontFamily: KESTREL.display, fontSize: 20, color: KESTREL.charcoal }}>
+            In your cart
+          </Typography>
+          <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>Kestrel, {price}</Typography>
+        </Box>
+        <Button
+          onClick={() => navigate('configure')}
+          sx={{ textTransform: 'none', color: KESTREL.charcoal, textDecoration: 'underline', fontSize: 14 }}
+        >
+          Make another
+        </Button>
+      </Box>
+    )
+  }
+
+  const showButton = primary !== null && !accessInfo.viewMode
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.5 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 2 }}>
+        <Box component="div" sx={{ display: 'grid' }}>
+          <Typography sx={{ fontFamily: KESTREL.display, fontSize: 30, lineHeight: 1.1, color: KESTREL.charcoal }}>
+            {price}
+          </Typography>
+          <Typography sx={{ fontSize: 12, color: KESTREL.muted, whiteSpace: 'nowrap' }}>Ships in two days</Typography>
+        </Box>
+        {showButton && (
+          <Button
+            variant="contained"
+            disableElevation
+            disabled={primary.disabled || isPending}
+            onClick={() => void primary.run()}
+            title={primary.title}
+            startIcon={isPending ? <CircularProgress size={16} color="inherit" /> : undefined}
+            sx={{
+              minBlockSize: 52,
+              paddingInline: 4.5,
+              borderRadius: 999,
+              bgcolor: KESTREL.charcoal,
+              color: KESTREL.oat,
+              fontFamily: KESTREL.body,
+              fontSize: 15,
+              letterSpacing: '0.02em',
+              textTransform: 'none',
+              '&:hover': { bgcolor: '#000000' },
+              '&.Mui-disabled': { bgcolor: KESTREL.charcoal, color: KESTREL.oat, opacity: 0.55 },
+            }}
+          >
+            {isPending ? 'Adding…' : primary.label}
+          </Button>
+        )}
+      </Box>
+      {showButton && primary.disabled && hints && (
+        <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>{hints}</Typography>
+      )}
+      {primary?.error && <Alert severity="error">The kettle could not be added: {primary.error.message}</Alert>}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/DesktopPage.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { CartBlock } from './CartBlock.js'
+import { FullscreenButton } from './FullscreenButton.js'
+import { KettleOptions } from './KettleOptions.js'
+import { ProductHeading } from './ProductHeading.js'
+import { KESTREL } from './tokens.js'
+
+const COLUMN_WIDTH = 'clamp(380px, 38%, 520px)'
+const FOOTER_HEIGHT = 52
+const GUTTER = 32
+
+// The desktop page: the kettle in the free area on the left, the product column on the right and the shop's footer
+// strip below both. In fullscreen only the free area stays, so the camera frames the kettle in the whole canvas.
+export const DesktopPage = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const { accessInfo } = phx.frontend.useAccessService()
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'grid',
+        gridTemplateColumns: isFullscreen ? 'minmax(0, 1fr)' : `minmax(0, 1fr) ${COLUMN_WIDTH}`,
+        gridTemplateRows: isFullscreen ? 'minmax(0, 1fr)' : `minmax(0, 1fr) ${FOOTER_HEIGHT}px`,
+        fontFamily: KESTREL.body,
+        // The free area lies over the canvas; only the controls in it take the pointer
+        pointerEvents: 'none',
+      }}
+    >
+      <Box component="div" sx={{ position: 'relative', minInlineSize: 0 }}>
+        {/* The camera fits the kettle into this box, so its inset is the breathing room around the kettle */}
+        <Box component="div" ref={safeAreaRef} sx={{ position: 'absolute', inset: '112px 72px 96px' }} />
+        <Box
+          component="div"
+          sx={{ position: 'absolute', insetBlockStart: GUTTER, insetInlineStart: GUTTER, display: 'grid' }}
+        >
+          <Typography sx={{ fontFamily: KESTREL.display, fontSize: 22, lineHeight: 1, color: KESTREL.charcoal }}>
+            Aldermoor
+          </Typography>
+        </Box>
+        <Box
+          component="div"
+          sx={{ position: 'absolute', insetBlockStart: GUTTER - 8, insetInlineEnd: GUTTER, pointerEvents: 'auto' }}
+        >
+          <FullscreenButton />
+        </Box>
+        <Typography
+          sx={{
+            position: 'absolute',
+            insetBlockEnd: GUTTER,
+            insetInline: 0,
+            textAlign: 'center',
+            fontSize: 12,
+            letterSpacing: '0.08em',
+            color: KESTREL.muted,
+          }}
+        >
+          Drag to turn the kettle
+        </Typography>
+        {/* The built-in snackbars stack upwards from this zero-height root, so it sits where their bottom edge goes */}
+        <Box
+          component="div"
+          sx={{
+            position: 'absolute',
+            insetBlockEnd: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: 340,
+            pointerEvents: 'auto',
+          }}
+        >
+          <LayoutSlots.DesktopSnackbarsRoot />
+        </Box>
+      </Box>
+
+      {!isFullscreen && (
+        <>
+          <Box
+            component="aside"
+            aria-label="Kestrel kettle"
+            sx={{
+              display: 'flex',
+              flexDirection: 'column',
+              overflowY: 'auto',
+              bgcolor: KESTREL.oat,
+              borderInlineStart: `1px solid ${KESTREL.hairline}`,
+              pointerEvents: 'auto',
+            }}
+          >
+            {/* Centred while it fits, scrolling from the top once it does not */}
+            <Box
+              component="div"
+              sx={{ display: 'grid', gap: 3.5, marginBlock: 'auto', paddingInline: 7, paddingBlockStart: 5 }}
+            >
+              <ProductHeading size="large" />
+              <KettleOptions readOnly={accessInfo.viewMode} />
+              {/* Below the choices while the column fits; at the column's bottom edge while it scrolls */}
+              <Box
+                component="div"
+                sx={{
+                  position: 'sticky',
+                  insetBlockEnd: 0,
+                  marginBlockStart: -3.5,
+                  paddingBlock: 3,
+                  bgcolor: KESTREL.oat,
+                  borderBlockStart: `1px solid ${KESTREL.hairline}`,
+                }}
+              >
+                <CartBlock />
+              </Box>
+            </Box>
+          </Box>
+
+          <Box
+            component="footer"
+            sx={{
+              gridColumn: '1 / -1',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              gap: 3,
+              paddingInline: `${GUTTER}px`,
+              bgcolor: KESTREL.oat,
+              borderBlockStart: `1px solid ${KESTREL.hairline}`,
+              pointerEvents: 'auto',
+            }}
+          >
+            <LayoutSlots.DesktopFooter />
+            <LayoutSlots.DesktopPoweredBy />
+          </Box>
+        </>
+      )}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/FullscreenButton.tsx
+
+```tsx
+import { IconButton, Tooltip } from '@mui/material'
+
+import { FrontendAnalyticsFactory } from '@salsita-ai/sdk/configurator'
+
+import { KESTREL } from './tokens.js'
+
+const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
+const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
+
+// Shows the kettle alone: the layout reads the flag and leaves out everything but the scene while it is set
+export const FullscreenButton = () => {
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const setFullscreen = phx.frontend.useSetFullscreen()
+  const analytics = phx.frontend.useAnalytics()
+  const label = isFullscreen ? 'Exit fullscreen' : 'Fullscreen'
+
+  // 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={label}>
+      <IconButton
+        aria-label={label}
+        onClick={toggle}
+        sx={{
+          inlineSize: 44,
+          blockSize: 44,
+          color: KESTREL.charcoal,
+          border: `1px solid ${KESTREL.hairline}`,
+          bgcolor: 'rgba(244, 239, 232, 0.8)',
+          '&:hover': { bgcolor: KESTREL.oat },
+        }}
+      >
+        <svg viewBox="0 0 24 24" width={18} height={18} fill="none" stroke="currentColor" strokeWidth={1.6}>
+          <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
+        </svg>
+      </IconButton>
+    </Tooltip>
+  )
+}
+```
+
+### ./src/\_shared/KettleOptions.tsx
+
+```tsx
+import { Box, Divider } from '@mui/material'
+
+import { SwatchRow } from './SwatchRow.js'
+import { ThermometerRow } from './ThermometerRow.js'
+import { KESTREL } from './tokens.js'
+
+// The swatches' look, keyed by the option values of the spec
+const FINISH_FILLS = {
+  BrushedSteel: 'linear-gradient(135deg, #f1f2f4 0%, #a9aeb4 55%, #dcdfe2 100%)',
+  MatteBlack: 'linear-gradient(135deg, #4a4744 0%, #1f1d1b 100%)',
+  Copper: 'linear-gradient(135deg, #f0b48a 0%, #b8693d 55%, #8a4a28 100%)',
+}
+
+const WOOD_FILLS = {
+  Walnut: 'linear-gradient(135deg, #7a5238 0%, #4a2f1f 100%)',
+  Oak: 'linear-gradient(135deg, #ead2ad 0%, #c49a6c 100%)',
+}
+
+interface KettleOptionsProps {
+  readonly readOnly: boolean
+}
+
+// The three choices, in the order a buyer makes them. The spec's `attributeSelection` has no label, so the labels
+// are the layout's own. Once the kettle is in the cart the choices stay as they were added, until "Make another".
+export const KettleOptions = ({ readOnly }: KettleOptionsProps) => {
+  const isAdded = phx.frontend.useActiveNavigationState() === 'added'
+  const locked = readOnly || isAdded
+
+  return (
+    <Box component="div" sx={{ display: 'grid' }}>
+      <Divider sx={{ borderColor: KESTREL.hairline }} />
+      <SwatchRow label="Body finish" instanceName="bodyFinish" fills={FINISH_FILLS} readOnly={locked} />
+      <Divider sx={{ borderColor: KESTREL.hairline }} />
+      <SwatchRow label="Handle" instanceName="handleWood" fills={WOOD_FILLS} readOnly={locked} />
+      <Divider sx={{ borderColor: KESTREL.hairline }} />
+      <ThermometerRow readOnly={locked} />
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/PhonePage.tsx
+
+```tsx
+import { Box, IconButton, Tooltip, Typography } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+import { notistackSnackbarClasses } from '@salsita-ai/sdk/ui'
+
+import { CartBlock } from './CartBlock.js'
+import { FullscreenButton } from './FullscreenButton.js'
+import { KettleOptions } from './KettleOptions.js'
+import { ProductHeading } from './ProductHeading.js'
+import { KESTREL } from './tokens.js'
+
+const CLOSE_ICON = 'M6 6l12 12M18 6 6 18'
+const GUTTER = 16
+const SCENE_HEIGHT = '44%'
+
+// The phone page: the kettle at the top, then one column that scrolls below it, with the price and the button in a
+// bar that stays at the bottom. In fullscreen only the kettle stays.
+export const PhonePage = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const closeAction = phx.frontend.useCloseAction()
+  const { isExpanded, leave } = phx.frontend.usePreview()
+  // The host's close action when it offers one; otherwise, once the start screen expanded the page, the way back to it
+  const close = closeAction ? () => void closeAction() : isExpanded ? leave : null
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        fontFamily: KESTREL.body,
+        pointerEvents: 'none',
+      }}
+    >
+      <Box
+        component="div"
+        sx={{ position: 'relative', flex: isFullscreen ? '1 1 0' : `0 0 ${SCENE_HEIGHT}`, minBlockSize: 0 }}
+      >
+        {/* The camera fits the kettle into this box: below the top bar, clear of the screen's edges */}
+        <Box
+          component="div"
+          ref={safeAreaRef}
+          sx={{ position: 'absolute', inset: `${GUTTER + 52}px ${GUTTER}px ${GUTTER}px` }}
+        />
+        <Box
+          component="div"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: GUTTER,
+            insetInline: GUTTER,
+            display: 'grid',
+            gridTemplateColumns: '44px 1fr 44px',
+            alignItems: 'center',
+          }}
+        >
+          {close ? (
+            <Tooltip title="Close">
+              <IconButton aria-label="Close" onClick={close} sx={{ color: KESTREL.charcoal, pointerEvents: 'auto' }}>
+                <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={1.6}>
+                  <path d={CLOSE_ICON} />
+                </svg>
+              </IconButton>
+            </Tooltip>
+          ) : (
+            <span />
+          )}
+          <Typography sx={{ fontFamily: KESTREL.display, fontSize: 20, textAlign: 'center', color: KESTREL.charcoal }}>
+            Aldermoor
+          </Typography>
+          <Box component="div" sx={{ pointerEvents: 'auto' }}>
+            <FullscreenButton />
+          </Box>
+        </Box>
+        {/* The phone root leaves the snackbars fixed to the viewport; here they drop in below the top bar instead */}
+        <Box
+          component="div"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: GUTTER + 56,
+            insetInline: GUTTER,
+            pointerEvents: 'auto',
+            [`& .${notistackSnackbarClasses.container}`]: {
+              position: 'absolute',
+              inset: '0 0 auto 0',
+              inlineSize: 'auto',
+              transform: 'none',
+            },
+          }}
+        >
+          <LayoutSlots.MobileSnackbarsRoot />
+        </Box>
+      </Box>
+
+      {!isFullscreen && (
+        <Box
+          component="main"
+          sx={{
+            flex: '1 1 0',
+            minBlockSize: 0,
+            overflowY: 'auto',
+            overscrollBehavior: 'contain',
+            bgcolor: KESTREL.oat,
+            borderBlockStart: `1px solid ${KESTREL.hairline}`,
+            pointerEvents: 'auto',
+          }}
+        >
+          <Box component="div" sx={{ display: 'grid', gap: 3, padding: 3, paddingBlockEnd: 4 }}>
+            <ProductHeading size="small" />
+            <KettleOptions readOnly={accessInfo.viewMode} />
+            <Box
+              component="div"
+              sx={{
+                display: 'grid',
+                justifyItems: 'start',
+                gap: 2,
+                paddingBlockStart: 3,
+                borderBlockStart: `1px solid ${KESTREL.hairline}`,
+              }}
+            >
+              <LayoutSlots.MobileFooter />
+              <LayoutSlots.MobilePoweredBy />
+            </Box>
+          </Box>
+          <Box
+            component="div"
+            sx={{
+              position: 'sticky',
+              insetBlockEnd: 0,
+              paddingInline: 3,
+              paddingBlock: 2,
+              bgcolor: KESTREL.oat,
+              borderBlockStart: `1px solid ${KESTREL.hairline}`,
+            }}
+          >
+            <CartBlock />
+          </Box>
+        </Box>
+      )}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/PhonePoster.tsx
+
+```tsx
+import { Box, Button, Typography } from '@mui/material'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+// The layout's own start screen, shown on a phone while `usePreview().isPreview` is set (the spec's `preview: auto`).
+// It frames the kettle in the area above the text with its own safe area; `enter()` opens the page.
+export const PhonePoster = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const { enter } = phx.frontend.usePreview()
+  const price = phx.frontend.useRootEntityPrice()
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        fontFamily: KESTREL.body,
+        pointerEvents: 'none',
+      }}
+    >
+      <Typography
+        sx={{
+          paddingBlockStart: 3,
+          textAlign: 'center',
+          fontFamily: KESTREL.display,
+          fontSize: 20,
+          color: KESTREL.charcoal,
+        }}
+      >
+        Aldermoor
+      </Typography>
+      <Box component="div" ref={safeAreaRef} sx={{ flex: '1 1 0', minBlockSize: 0, marginInline: 3 }} />
+      <Box component="div" sx={{ display: 'grid', gap: 2, padding: 3, paddingBlockEnd: 4, pointerEvents: 'auto' }}>
+        <Typography sx={{ ...LABEL_SX, color: KESTREL.copper }}>The Kestrel pour-over kettle</Typography>
+        <Typography
+          component="h1"
+          sx={{
+            fontFamily: KESTREL.display,
+            fontSize: 48,
+            lineHeight: 1,
+            letterSpacing: '-0.01em',
+            color: KESTREL.charcoal,
+          }}
+        >
+          Make it yours
+        </Typography>
+        <Typography sx={{ fontSize: 15, lineHeight: 1.6, color: KESTREL.muted }}>
+          Three finishes, two woods and a thermometer lid if you want one. As shown, {price}.
+        </Typography>
+        <Button
+          variant="contained"
+          disableElevation
+          onClick={enter}
+          sx={{
+            marginBlockStart: 1,
+            minBlockSize: 52,
+            borderRadius: 999,
+            bgcolor: KESTREL.charcoal,
+            color: KESTREL.oat,
+            fontFamily: KESTREL.body,
+            fontSize: 15,
+            textTransform: 'none',
+            '&:hover': { bgcolor: '#000000' },
+          }}
+        >
+          Start designing
+        </Button>
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/ProductHeading.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { detailComponent } from '@salsita-ai/sdk/domain'
+import { LocalizableMessage } from '@salsita-ai/sdk/react'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+interface ProductHeadingProps {
+  readonly size: 'large' | 'small'
+}
+
+// The overline, the name and the story from the spec's `detail` component. Its texts are `Localizable`:
+// `useLocalizable` resolves one into a string and `LocalizableMessage` renders one in place.
+export const ProductHeading = ({ size }: ProductHeadingProps) => {
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const title = phx.frontend.useLocalizable(detail?.state.title)
+  const subtitle = phx.frontend.useLocalizable(detail?.state.subtitle)
+
+  return (
+    <Box component="header" sx={{ display: 'grid', gap: size === 'large' ? 2 : 1.5 }}>
+      <Typography sx={{ ...LABEL_SX, color: KESTREL.copper }}>Aldermoor Coffee</Typography>
+      <Box component="div" sx={{ display: 'grid', gap: 0.75 }}>
+        <Typography
+          component="h1"
+          sx={{
+            fontFamily: KESTREL.display,
+            fontSize: size === 'large' ? 60 : 40,
+            lineHeight: 1,
+            letterSpacing: '-0.01em',
+            color: KESTREL.charcoal,
+          }}
+        >
+          {title}
+        </Typography>
+        <Typography sx={{ fontFamily: KESTREL.body, fontSize: 15, color: KESTREL.muted }}>{subtitle}</Typography>
+      </Box>
+      <Typography sx={{ fontFamily: KESTREL.body, fontSize: 15, lineHeight: 1.65, color: KESTREL.charcoal }}>
+        <LocalizableMessage>{detail?.state.description}</LocalizableMessage>
+      </Typography>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/SwatchRow.tsx
+
+```tsx
+import { Box, ButtonBase, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+// Arrow keys move the selection between the swatches, as in a native radio group
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface SwatchRowProps {
+  readonly label: string
+  readonly instanceName: string
+  // How each option looks, keyed by the spec's option values: a CSS background
+  readonly fills: Readonly<Record<string, string>>
+  readonly readOnly: boolean
+}
+
+// One `attributeSelection` of the spec as a row of round swatches, with the chosen option's name and description.
+// An option the spec's invariants rule out is `disabled`: it is drawn faded and its hint says why, but it can still be
+// clicked. Its `onSelect` then makes the change, which the invariant rejects, and the built-in snackbar repeats the
+// reason. The arrow keys skip it.
+export const SwatchRow = ({ label, instanceName, fills, readOnly }: SwatchRowProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const kettleId = phx.frontend.useRootEntityId()
+  const { value, options } = phx.frontend.useAttributeSelection(kettleId, instanceName)
+  const selected = options.find(option => option.value === value)
+  const hint = options.find(option => option.disabled && option.hint)?.hint
+
+  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
+    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="section" sx={{ display: 'grid', gap: 1.5, paddingBlock: 2 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 2 }}>
+        <Typography component="h3" sx={LABEL_SX}>
+          {label}
+        </Typography>
+        <Typography sx={{ fontFamily: KESTREL.display, fontSize: 18, color: KESTREL.charcoal }}>
+          {resolve(selected?.title)}
+        </Typography>
+      </Box>
+
+      <Box component="div" role="radiogroup" aria-label={label} sx={{ display: 'flex', gap: 1.5 }}>
+        {options.map((option, index) => {
+          const isSelected = option.value === value
+          const title = resolve(option.title)
+
+          return (
+            <ButtonBase
+              key={String(option.value)}
+              role="radio"
+              aria-checked={isSelected}
+              aria-label={title}
+              title={option.hint ?? title}
+              aria-disabled={option.disabled}
+              tabIndex={isSelected ? 0 : -1}
+              disabled={readOnly}
+              onClick={option.onSelect}
+              onKeyDown={event => handleKeyDown(event, index)}
+              sx={{
+                inlineSize: 40,
+                blockSize: 40,
+                borderRadius: '50%',
+                background: fills[String(option.value)],
+                // A ring of the page's colour between the swatch and the outline of the chosen one
+                boxShadow: isSelected
+                  ? `0 0 0 3px ${KESTREL.oat}, 0 0 0 4px ${KESTREL.charcoal}`
+                  : `inset 0 0 0 1px ${KESTREL.hairline}`,
+                transition: 'box-shadow 160ms, transform 160ms',
+                opacity: option.disabled ? 0.3 : 1,
+                '&:hover': { transform: isSelected || option.disabled ? 'none' : 'scale(1.06)' },
+                '&.Mui-focusVisible': { outline: `2px solid ${KESTREL.copper}`, outlineOffset: 6 },
+                // A viewer sees the chosen swatch only as chosen; the others fade
+                '&.Mui-disabled': { opacity: isSelected ? 1 : 0.3 },
+              }}
+            />
+          )
+        })}
+      </Box>
+
+      <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>
+        {hint && !readOnly ? hint : resolve(selected?.description)}
+      </Typography>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/ThermometerRow.tsx
+
+```tsx
+import { Box, Switch, Typography } from '@mui/material'
+
+import { KESTREL, LABEL_SX } from './tokens.js'
+
+interface ThermometerRowProps {
+  readonly readOnly: boolean
+}
+
+// The spec's `attributeSwitch` as a labelled switch: on, the lid carries a dial thermometer; off, a plain wooden knob
+export const ThermometerRow = ({ readOnly }: ThermometerRowProps) => {
+  const kettleId = phx.frontend.useRootEntityId()
+  const thermometer = phx.frontend.useAttributeSwitch(kettleId, 'thermometer')
+  const isOn = thermometer.state.value
+
+  return (
+    <Box component="section" sx={{ display: 'grid', gap: 0.5, paddingBlock: 2 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 2 }}>
+        <Typography component="h3" id="kestrel-thermometer-label" sx={LABEL_SX}>
+          Thermometer lid
+        </Typography>
+        <Switch
+          checked={isOn}
+          disabled={readOnly || thermometer.disabled}
+          onChange={thermometer.onChange}
+          inputProps={{ 'aria-labelledby': 'kestrel-thermometer-label' }}
+          sx={{
+            '& .MuiSwitch-switchBase.Mui-checked': { color: KESTREL.oat },
+            '& .MuiSwitch-switchBase.Mui-checked + .MuiSwitch-track': { bgcolor: KESTREL.copper, opacity: 1 },
+            '& .MuiSwitch-track': { bgcolor: KESTREL.hairline, opacity: 1 },
+          }}
+        />
+      </Box>
+      <Typography sx={{ fontSize: 13, color: KESTREL.muted }}>
+        {isOn ? 'A dial in the lid shows when the water is ready to pour.' : 'A plain lid with a wooden knob.'}
+      </Typography>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/tokens.ts
+
+```ts
+// The brand's palette and type. Playfair Display and Circular Std are the fonts the brand ships; the stacks fall back
+// to system fonts where they are not loaded.
+export const KESTREL = {
+  oat: '#f4efe8',
+  charcoal: '#1f1d1b',
+  copper: '#b8693d',
+  sage: '#9daa94',
+  muted: 'rgba(31, 29, 27, 0.62)',
+  hairline: 'rgba(31, 29, 27, 0.12)',
+  display: "'PlayfairDisplay-Regular', 'Playfair Display', Georgia, serif",
+  body: "'Circular-Std-Book', 'Helvetica Neue', Arial, sans-serif",
+} as const
+
+// Small capitals with wide tracking, for the overline and the option labels
+export const LABEL_SX = {
+  fontFamily: KESTREL.body,
+  fontSize: 11,
+  letterSpacing: '0.18em',
+  textTransform: 'uppercase',
+  color: KESTREL.muted,
+} as const
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { DesktopPage } from '../_shared/DesktopPage.js'
+import { PhonePage } from '../_shared/PhonePage.js'
+import { PhonePoster } from '../_shared/PhonePoster.js'
+import { KESTREL } from '../_shared/tokens.js'
+
+// One page, no steps or tabs. The canvas and the services stay mounted the whole time; what lies over the canvas is
+// the phone's start screen, the phone page or the desktop page. Each calls `useSceneSafeArea` itself, so only the one
+// on screen tells the camera where the kettle goes.
+const ConfiguratorLayout = () => {
+  // `null` until the container has been measured; only the scene shows until then
+  const viewports = phx.frontend.useActiveViewports()
+  const { isPreview } = phx.frontend.usePreview()
+  const isDesktop = viewports?.includes('desktop') ?? false
+
+  return (
+    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: KESTREL.oat }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+      {viewports !== null && (isPreview ? <PhonePoster /> : isDesktop ? <DesktopPage /> : <PhonePage />)}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/elements/KettleStudio.tsx
+
+```tsx
+import { ContactShadows, Environment, Lightformer } from '@react-three/drei'
+
+import { KESTREL } from '../_shared/tokens.js'
+
+// The stage named by the spec's `canvasCustomEnvironment`: a backdrop, a soft shadow under the kettle and a studio of
+// light panels. The panels exist only in the reflections, so the metal finishes have something to mirror and no image
+// has to be downloaded. The scene is in millimetres.
+export default phx.frontend.createCustomPhoenixLayoutElement('KettleStudio', () => {
+  return (
+    <>
+      {/* The page's oat background, so the scene and the layout read as one surface */}
+      <color attach="background" args={[KESTREL.oat]} />
+      <ambientLight intensity={0.35} />
+      <directionalLight position={[400, 900, 600]} intensity={1.1} />
+
+      <Environment resolution={256} frames={1}>
+        <color attach="background" args={['#77706a']} />
+        {/* A softbox above, tall strips at the sides for the long highlights, a warm fill behind, a dim one in front */}
+        <Lightformer form="rect" intensity={2.4} position={[0, 6, 0]} rotation-x={Math.PI / 2} scale={[10, 6, 1]} />
+        <Lightformer form="rect" intensity={3} position={[-6, 1, 2]} rotation-y={Math.PI / 2} scale={[1.2, 8, 1]} />
+        <Lightformer form="rect" intensity={1.6} position={[6, 1, 3]} rotation-y={-Math.PI / 2} scale={[1.2, 8, 1]} />
+        <Lightformer form="rect" color="#f3d9c2" intensity={1} position={[0, 1, -8]} scale={[12, 4, 1]} />
+        <Lightformer form="rect" intensity={0.8} position={[0, 0, 8]} rotation-y={Math.PI} scale={[10, 3, 1]} />
+      </Environment>
+
+      <ContactShadows position={[0, -1, 0]} scale={520} far={60} blur={2.2} opacity={0.7} resolution={512} />
+    </>
+  )
+})
+```
+
+### ./src/elements/LayoutFooter.tsx
+
+```tsx
+import { Box } from '@mui/material'
+
+import { KESTREL } from '../_shared/tokens.js'
+
+const PROMISES = ['Free delivery over $75', 'Two-year warranty', '30-day returns']
+
+// The shop's promises. `createLayoutFooter` registers it as the `LayoutFooter` element, which the layout shows where it
+// mounts `LayoutSlots.DesktopFooter` or `LayoutSlots.MobileFooter`.
+const LayoutFooter = () => {
+  return (
+    <Box
+      component="ul"
+      sx={{
+        display: 'flex',
+        flexWrap: 'wrap',
+        columnGap: 3,
+        rowGap: 0.5,
+        margin: 0,
+        padding: 0,
+        listStyle: 'none',
+        fontSize: 12,
+        letterSpacing: '0.04em',
+        color: KESTREL.muted,
+      }}
+    >
+      {PROMISES.map(promise => (
+        <Box
+          component="li"
+          key={promise}
+          sx={{ display: 'flex', alignItems: 'center', gap: 1, '&::before': { content: '"·"', color: KESTREL.sage } }}
+        >
+          {promise}
+        </Box>
+      ))}
+    </Box>
+  )
+}
+
+export default phx.frontend.createLayoutFooter(LayoutFooter)
+```
+
+### ./src/expressions/kettle.ts
+
+```ts
+const BASE_PRICE = 145
+const FINISH_SURCHARGE = { BrushedSteel: 0, MatteBlack: 10, Copper: 45 }
+const WOOD_SURCHARGE = { Walnut: 10, Oak: 0 }
+const THERMOMETER_SURCHARGE = 20
+
+// How each finish renders: the spec's material override of the `Body` material reads these
+const FINISHES = {
+  BrushedSteel: { color: '#c9ccd0', metalness: 1, roughness: 0.3, clearcoat: 0 },
+  MatteBlack: { color: '#2b2927', metalness: 0.1, roughness: 0.55, clearcoat: 0 },
+  Copper: { color: '#d08a5c', metalness: 1, roughness: 0.2, clearcoat: 0.6 },
+}
+
+const WOODS = { Walnut: '#4a2f1f', Oak: '#c49a6c' }
+
+export default phx.domain.implementCustomExpressions({
+  Kettle: {
+    $price: s => {
+      return (
+        BASE_PRICE +
+        FINISH_SURCHARGE[s.bodyFinish] +
+        WOOD_SURCHARGE[s.handleWood] +
+        (s.thermometer ? THERMOMETER_SURCHARGE : 0)
+      )
+    },
+    $plainKnob: s => {
+      return !s.thermometer
+    },
+    $bodyColor: s => {
+      return FINISHES[s.bodyFinish].color
+    },
+    $bodyMetalness: s => {
+      return FINISHES[s.bodyFinish].metalness
+    },
+    $bodyRoughness: s => {
+      return FINISHES[s.bodyFinish].roughness
+    },
+    $bodyClearcoat: s => {
+      return FINISHES[s.bodyFinish].clearcoat
+    },
+    $handleColor: s => {
+      return WOODS[s.handleWood]
+    },
+  },
+})
+```
+
+### ./src/handlers/add-to-cart.ts
+
+```ts
+import { useCallback } from 'react'
+
+// Stands in for the shop's cart: adding takes a moment, then the page shows the confirmation
+export default phx.frontend.createPhoenixHandler('addToCart', () => {
+  const navigate = phx.frontend.useNavigate()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1200))
+      navigate('added')
+    }, [navigate]),
+  }
+})
+```
+
+### ./src/invariants/kettle.ts
+
+```ts
+// The copper body is sold only with the walnut handle. The spec marks the violation `fixable`, so a change that breaks
+// it is rejected and the built-in snackbar shows the spec's message.
+export default phx.domain.implementCustomInvariants({
+  Kettle: {
+    copperNeedsWalnut: s => {
+      return s.bodyFinish !== 'Copper' || s.handleWood === 'Walnut'
+    },
+  },
+})
+```
+
+</details>