@salsita-ai/sdk 0.50.0-develop.8f6deac646 → 0.50.0-develop.91d65bd507

package/dist/docs/layouts/gallery/nightjar-guitar.mdx

@@ -0,0 +1,3683 @@
+# Nightjar Guitar
+
+Walk a customer through a product one step at a time and end in an order. A custom guitar shop, Northfret, sells its Nightjar electric guitar through a five-step wizard: the body, the neck, the electronics, a signature on the headstock and a summary with **Place order**. A stepper across the top shows where the customer is, each step's choices slide in beside the guitar, the camera moves to what the step changes, and a bar at the bottom keeps the price, **Back** and **Next** in reach. The project writes the wizard as one layout element; the spec holds the steps, which step asks each choice, the cameras, the rules and the order action.
+
+- [Try it](#try-it)
+- [What the example demonstrates](#what-the-example-demonstrates)
+- [Steps from the spec](#steps-from-the-spec)
+- [Each step shows the choices the spec gives it](#each-step-shows-the-choices-the-spec-gives-it)
+- [The camera follows the wizard](#the-camera-follows-the-wizard)
+- [Finish swatches](#finish-swatches)
+- [A signature on the headstock](#a-signature-on-the-headstock)
+- [Summary and conflicts](#summary-and-conflicts)
+- [Place the order](#place-the-order)
+- [Pages that slide in](#pages-that-slide-in)
+- [On a phone](#on-a-phone)
+- [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 [On a phone](#on-a-phone).
+
+## 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 product sold in ordered steps, and it shows the pieces Custom Layout does not use:
+
+| Piece                                                                                                        | Where                                                                                    |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `phx.frontend.useStepNavigation()` for a stepper and **Back** and **Next** from the spec's `navigationSteps` | `StepHeader`, `OrderBar`, [Steps from the spec](#steps-from-the-spec)                    |
+| A step's fields from the components a `$filter` leaves active, read with `phx.frontend.useComponents()`      | `use-active-choices`, [Each step shows…](#each-step-shows-the-choices-the-spec-gives-it) |
+| Cameras filtered by navigation state, so the camera follows the wizard with no camera code                   | the spec, [The camera follows the wizard](#the-camera-follows-the-wizard)                |
+| `phx.frontend.useSwatchSelection()` for a `materialSwatch`                                                   | `FinishField`, [Finish swatches](#finish-swatches)                                       |
+| `phx.frontend.useTextValue()` with a `sceneEntityObjectTextDecal`, and a `fixable` rule on the text          | `SignatureField`, [A signature on the headstock](#a-signature-on-the-headstock)          |
+| A summary read with the control hooks, and warnings from `phx.frontend.useFinalizeViolations()`              | `SummaryPanel`, `SummaryRows`, [Summary and conflicts](#summary-and-conflicts)           |
+| `phx.frontend.useFinalizeActions()` with its pending state and error, and an `ordered` confirmation          | `OrderBar`, `SummaryPanel`, [Place the order](#place-the-order)                          |
+| `phx.frontend.useSceneSafeArea().update()` once a page has slid in                                           | `DesktopPage`, `PhonePage`, [Pages that slide in](#pages-that-slide-in)                  |
+| `phx.frontend.useAnalytics()` with `FrontendAnalyticsFactory.SummaryButtonClicked()`                         | `OrderBar`, [Steps from the spec](#steps-from-the-spec)                                  |
+| `sceneEntityObjectLocalMaterialOverride` with a clearcoat, and a `canvasCustomEnvironment` stage             | the spec, `NightjarStage`, [The stage and the model](#the-stage-and-the-model)           |
+
+## Steps from the spec
+
+The steps are product structure, so they live in the spec. Each navigation state is a page of the wizard; `navigationSteps` groups them into the steps the stepper shows, with their labels and their order. The summary step holds two states: `summary`, and `ordered` for the confirmation after the order.
+
+```yaml
+navigationStates:
+  - body
+  - neck
+  - electronics
+  - details
+  - summary
+  - ordered
+```
+
+```yaml
+components:
+  Guitar:
+    navigationSteps:
+      main:
+        steps:
+          - label: Body
+            navigationStates:
+              - body
+          - label: Neck
+            navigationStates:
+              - neck
+          - label: Electronics
+            navigationStates:
+              - electronics
+          - label: Details
+            navigationStates:
+              - details
+          - label: Summary
+            navigationStates:
+              - summary
+              - ordered
+```
+
+`phx.frontend.useStepNavigation()` reads them and returns every step with its label resolved and its `status`, `'complete'`, `'active'` or `'upcoming'`, with `next()`, `previous()` and `goTo(index)` to move. `StepHeader` draws the stepper from `steps`, and `OrderBar` the buttons from `canGoPrevious`, `isLast` and the label of the step after the active one:
+
+- **A wizard that remembers.** The hook enforces no order: `goTo` enters any step. `StepHeader` lets the customer go back to any step they have reached and never ahead of it, so after changing the body from the summary they return to the summary in one click. The furthest step is the layout's own state.
+- **Analytics come with the moves.** `next()` and `previous()` record the built-in step buttons' events and `goTo()` the header stepper's, so the stepper and the bar need no analytics code. The button that opens the summary is the exception: like the built-in **Summary** button, it records `FrontendAnalyticsFactory.SummaryButtonClicked()` from `@salsita-ai/sdk/configurator` through `phx.frontend.useAnalytics().push()` and enters the state with `phx.frontend.useNavigate()`, because `next()` would record the next-step button's event instead.
+- **Locked once ordered.** The stepper takes no clicks while the order is being placed or after it was placed; **Design another** in the bar returns to the first step.
+
+## Each step shows the choices the spec gives it
+
+The layout does not list which choice belongs to which step. A `$filter` with `navigationStates` makes a spec component active only in those states, so each choice names its step in the spec, plus the summary and the confirmation, which list every choice:
+
+```yaml
+components:
+  Guitar:
+    attributeSelection:
+      bodyShape:
+        value:
+          $bind: bodyShape
+        options:
+          - label: Offset
+            description: Contoured waist, 3.4 kg
+            value: Offset
+          - label: Single-cut
+            description: Thicker body, long sustain
+            value: SingleCut
+        $filter:
+          navigationStates:
+            - body
+            - summary
+            - ordered
+```
+
+`useActiveChoices` reads the `attributeSelection`, `materialSwatch` and `textValue` components active now with `phx.frontend.useComponents()` and orders them by the layout's field list, which also names each choice: the spec's control components carry no label.
+
+```ts
+import { useMemo } from 'react'
+
+import { attributeSelectionComponent, materialSwatchComponent, textValueComponent } from '@salsita-ai/sdk/domain'
+
+import { phx } from '../../.phoenix/phx.js'
+import { byFieldOrder } from './fields.js'
+
+export type ChoiceKind = 'selection' | 'swatch' | 'text'
+
+/** A choice of the spec that is active now. */
+export interface ActiveChoice {
+  readonly instanceName: string
+  readonly kind: ChoiceKind
+}
+
+// The guitar's choices whose spec component is active in the current navigation state, in the layout's order. A
+// `$filter` with `navigationStates` makes a component active only in those states, so on each step this is the step's
+// choices, and on the summary every choice. The control hooks throw for an inactive component; a field mounts only
+// for a choice listed here.
+export const useActiveChoices = (): readonly ActiveChoice[] => {
+  const guitarId = phx.frontend.useRootEntityId()
+  const selections = phx.frontend.useComponents({
+    componentTypes: [attributeSelectionComponent],
+    entityIds: [guitarId],
+  })
+  const swatches = phx.frontend.useComponents({ componentTypes: [materialSwatchComponent], entityIds: [guitarId] })
+  const texts = phx.frontend.useComponents({ componentTypes: [textValueComponent], entityIds: [guitarId] })
+
+  return useMemo(() => {
+    const choices = [
+      ...(selections ?? []).map(
+        ({ componentInstance }): ActiveChoice => ({ instanceName: componentInstance.instanceName, kind: 'selection' })
+      ),
+      ...(swatches ?? []).map(
+        ({ componentInstance }): ActiveChoice => ({ instanceName: componentInstance.instanceName, kind: 'swatch' })
+      ),
+      ...(texts ?? []).map(
+        ({ componentInstance }): ActiveChoice => ({ instanceName: componentInstance.instanceName, kind: 'text' })
+      ),
+    ]
+
+    return choices.sort((a, b) => byFieldOrder(a.instanceName, b.instanceName))
+  }, [selections, swatches, texts])
+}
+```
+
+`StepFields` then mounts one field per active choice, by its kind. Moving a choice to another step is a change of its `$filter` in the spec, and the step follows:
+
+```tsx
+import { Box } from '@mui/material'
+
+import { ChoiceField } from './ChoiceField.js'
+import { FinishField } from './FinishField.js'
+import { SignatureField } from './SignatureField.js'
+import { fieldOf } from './fields.js'
+import { useActiveChoices } from './use-active-choices.js'
+
+interface StepFieldsProps {
+  readonly compact: boolean
+}
+
+// The fields of the active step. The layout does not list which choice belongs to which step: it shows the choices
+// the spec leaves active, so moving a choice to another step is a change of its `$filter` in the spec.
+export const StepFields = ({ compact }: StepFieldsProps) => {
+  const choices = useActiveChoices()
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: compact ? 2.5 : 4 }}>
+      {choices.map(({ instanceName, kind }) => {
+        const { label, warningTypes } = fieldOf(instanceName)
+        const props = { instanceName, label, warningTypes, compact }
+
+        switch (kind) {
+          case 'selection':
+            return <ChoiceField key={instanceName} {...props} />
+          case 'swatch':
+            return <FinishField key={instanceName} {...props} />
+          case 'text':
+            return <SignatureField key={instanceName} {...props} />
+        }
+      })}
+    </Box>
+  )
+}
+```
+
+Mount a field only for a choice that is active. The control hooks, such as `useAttributeSelection`, throw for a component that a `$filter` makes inactive, so a layout that renders its fields some other way checks first with `phx.frontend.useComponent({ entityId, componentType, instanceName })`, which returns `null` for an inactive component.
+
+## The camera follows the wizard
+
+The cameras are spec components too, and the same `$filter` switches them: the whole guitar for the body, the summary and the confirmation, the upper neck and the headstock for the neck, the pickups for the electronics, and the headstock close up for the signature. Entering a step activates its camera and the camera moves there; the layout has no camera code.
+
+```yaml
+components:
+  Guitar:
+    fitRootPerspectiveCamera:
+      overview:
+        fov: 30
+        fitToBox: true
+        $filter:
+          navigationStates:
+            - body
+            - summary
+            - ordered
+    staticPerspectiveCamera:
+      neck:
+        fov: 30
+        lookAtX: 0
+        lookAtY: 625
+        lookAtZ: 0
+        distance: 1350
+        azimuthAngle: 0.55
+        polarAngle: 1.36
+        $filter:
+          navigationStates:
+            - neck
+```
+
+The overview fits the guitar into the safe area the page leaves free. A `staticPerspectiveCamera` looks at a point of the model from a fixed distance, in millimetres, which suits a close-up of one part; the camera padding of the safe area still applies, so the part stays beside the panel. [Cameras / Transitions](?path=/docs/3d-scene-cameras-transitions--docs) describes when the camera moves between cameras.
+
+## Finish swatches
+
+The finish is a `materialSwatch`: the spec lists each swatch with its name and the colour of its chip.
+
+```yaml
+components:
+  Guitar:
+    materialSwatch:
+      finish:
+        selectedSwatchKey:
+          $bind: finish
+        swatches:
+          Seafoam:
+            swatchName: Seafoam green
+            color: '#8fcab6'
+          CandyRed:
+            swatchName: Candy apple red
+            color: '#b0141f'
+          Midnight:
+            swatchName: Midnight blue metallic
+            color: '#1d2b4f'
+          NaturalAsh:
+            swatchName: Natural ash
+            color: '#d8b98a'
+```
+
+`FinishField` reads it with `phx.frontend.useSwatchSelection(guitarId, 'finish', [])`. Each option has `swatchKey`, `swatchName`, `color`, `selected`, `disabled`, `hint` and `onClick()`, which writes the swatch; the third argument lists the `fixable` violation types the options ignore. The field draws the swatches as round chips in the spec's colours with the chosen one's name beside the label. How the finish renders on the guitar is the material override's business, see [The stage and the model](#the-stage-and-the-model).
+
+## A signature on the headstock
+
+The customer can sign the headstock. The signature is a `textValue`, and a `sceneEntityObjectTextDecal` on the `headstock` object prints it in script along the headstock's face:
+
+```yaml
+components:
+  Guitar:
+    textValue:
+      signature:
+        value:
+          $bind: signature
+    sceneEntityObjectTextDecal:
+      headstock:
+        text:
+          $read: signature
+        font: SignPainter-HouseScript
+        preloadFonts:
+          - SignPainter-HouseScript
+        fontSize: auto
+        textColor:
+          $read: $signatureColor
+        positionX: 0.002
+        positionY: 0.76
+        positionZ: 0.004
+        rotationZ: 1.5708
+        sizeX: 0.13
+        sizeY: 0.03
+        sizeZ: 0.02
+```
+
+The decal's instance name is the object's: `headstock` in `sceneEntityRemoteObject`. Its position, rotation and size are in the object's own units, metres for this model, and `fontSize: auto` fits the text into the decal's width. The font must be loaded by the page; `preloadFonts` redraws the decal once it is.
+
+The headstock takes 16 characters. The limit is the expression `$signatureLimit`, declared in the spec so the layout can read it, and a `fixable` rule rejects a longer signature with a message that names it:
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomInvariants({
+  Guitar: {
+    // `fixable`: a change that makes the signature too long is rejected, so the headstock never shows more than fits.
+    // The message names the limit, so it is built here rather than in the spec.
+    signatureLength: s => {
+      if (s.signature.length <= s.$signatureLimit) {
+        return []
+      }
+
+      return [
+        {
+          type: 'signatureTooLong',
+          severity: 'fixable',
+          message: `The headstock fits ${s.$signatureLimit} characters. Shorten the signature.`,
+        },
+      ]
+    },
+    // `warning` in the spec: the change is kept, so a body chosen after the pickups does not undo them, and ordering
+    // waits until the customer resolves it
+    offsetHumbuckers: s => {
+      return s.bodyShape !== 'Offset' || s.pickups !== 'Humbuckers'
+    },
+  },
+})
+```
+
+`SignatureField` writes with `phx.frontend.useTextValue(guitarId, 'signature')`. `update(event, value)` stages each value as the customer types, so the headstock follows every key, and `resolve()` commits it when they leave the field or press Enter. While the staged text breaks the rule, `hasErrors` is set and `hints` holds the rule's message, which the field shows in red with the counter; `resolve()` then rolls back to the committed signature instead, so the guitar never keeps a signature that does not fit.
+
+```tsx
+import { Box, InputBase, Typography } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+import { FieldShell } from './FieldShell.js'
+import { NIGHTJAR } from './tokens.js'
+
+interface SignatureFieldProps {
+  readonly instanceName: string
+  readonly label: string
+  readonly warningTypes: readonly string[]
+  readonly compact: boolean
+}
+
+// The spec's `textValue`, which the spec prints on the headstock with a text decal. Typing stages each value, so the
+// headstock follows every key; leaving the field or pressing Enter commits it. A value the `fixable` length rule
+// rejects shows the rule's message as the hook's `hints`, and leaving the field rolls back to the last value that
+// fitted. The counter reads the limit from the spec's `$signatureLimit` expression, which the rule checks too.
+export const SignatureField = ({ instanceName, label, warningTypes, compact }: SignatureFieldProps) => {
+  const guitarId = phx.frontend.useRootEntityId()
+  const guitar = phx.frontend.useRootEntityState()
+  const signature = phx.frontend.useTextValue(guitarId, instanceName)
+  const limit = guitar.$signatureLimit
+
+  return (
+    <FieldShell
+      id={`nightjar-${instanceName}`}
+      label={label}
+      aside={
+        <Typography
+          aria-live="polite"
+          sx={{
+            fontFamily: NIGHTJAR.font,
+            fontSize: 13,
+            fontVariantNumeric: 'tabular-nums',
+            color: signature.hasErrors ? NIGHTJAR.alert : NIGHTJAR.muted,
+          }}
+        >
+          {signature.value.length} / {limit}
+        </Typography>
+      }
+      hint={
+        compact ? undefined : 'In gold leaf on dark necks, in black on maple. Leave it empty for a plain headstock.'
+      }
+      warningTypes={warningTypes}
+      compact={compact}
+    >
+      <Box
+        component="div"
+        sx={{
+          display: 'grid',
+          gap: 1,
+          paddingInline: 2,
+          paddingBlock: compact ? 1 : 1.5,
+          borderRadius: 1.5,
+          border: `1px solid ${signature.hasErrors ? NIGHTJAR.alert : NIGHTJAR.line}`,
+          bgcolor: NIGHTJAR.raised,
+          '&:focus-within': { borderColor: signature.hasErrors ? NIGHTJAR.alert : NIGHTJAR.amber },
+        }}
+      >
+        <InputBase
+          value={signature.value}
+          placeholder="Your name"
+          onChange={event => signature.update(event, event.target.value)}
+          onBlur={signature.resolve}
+          onKeyDown={event => {
+            if (event.key === 'Enter') {
+              signature.resolve()
+            }
+          }}
+          inputProps={{
+            'aria-labelledby': `nightjar-${instanceName}-label`,
+            'aria-invalid': signature.hasErrors,
+            'aria-describedby': `nightjar-${instanceName}-error`,
+            spellCheck: false,
+          }}
+          sx={{
+            fontFamily: NIGHTJAR.script,
+            fontSize: compact ? 30 : 38,
+            lineHeight: 1.2,
+            color: NIGHTJAR.amber,
+            '& input::placeholder': { color: NIGHTJAR.faint, opacity: 1 },
+          }}
+        />
+      </Box>
+      <Typography
+        id={`nightjar-${instanceName}-error`}
+        role="alert"
+        sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.alert, '&:empty': { display: 'none' } }}
+      >
+        {signature.hasErrors ? signature.hints : ''}
+      </Typography>
+    </FieldShell>
+  )
+}
+```
+
+## Summary and conflicts
+
+The last step reviews the guitar. `SummaryRows` lists every choice active in the `summary` state with the control hook of its kind: the option's `title` from `useAttributeSelection`, the swatch's name and colour from `useSwatchSelection`, the text from `useTextValue`. The summary only reviews; a choice is changed on its step.
+
+One rule spans two steps: the Offset body is routed for single-coil-sized pickups. It is a `warning`, so a change that breaks it is kept, and a body chosen after the pickups does not undo them:
+
+```yaml
+invariants:
+  Guitar:
+    offsetHumbuckers:
+      type: offsetHumbuckers
+      severity: warning
+      message: The Offset body is routed for single-coil-sized pickups. Choose single coils or P-90s, or the Single-cut body for humbuckers.
+```
+
+While it holds, the layout shows it three times, each read from `phx.frontend.useFinalizeViolations().violations`: under the **Pickups** and **Body shape** fields, as a mark on the **Electronics** step, and on the summary with **Go to Electronics**. The layout's `STEP_WARNINGS` names the step that resolves each warning. `phx.frontend.useStateValidity()` holds the same violations, but on `phx.frontend` it is typed as the validity value instead of a hook, so calling it does not type-check; `useWarnings` uses `useFinalizeViolations` instead.
+
+## Place the order
+
+The spec declares the order action, and the handler, `src/handlers/place-order.ts`, stands in for the shop's order service:
+
+```yaml
+components:
+  Guitar:
+    finalizeAction:
+      placeOrder:
+        variant: primary
+        label: Place order
+        title: Send the guitar as configured to the Northfret workshop
+        icon: ShoppingBag
+        handler: placeOrder
+```
+
+```ts
+import { useCallback } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+
+// Stands in for Northfret's order service. Placing an order takes a moment. The service checks stock when the order
+// arrives, which the configurator cannot know beforehand: gold hardware is back-ordered, so it refuses that order with
+// its reason; any other order is accepted and the page shows the confirmation.
+export default phx.frontend.createPhoenixHandler('placeOrder', () => {
+  const navigate = phx.frontend.useNavigate()
+  const guitar = phx.frontend.useRootEntityState()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1600))
+
+      if (guitar.hardware === 'Gold') {
+        throw new Error(
+          'Gold hardware is back-ordered until next month. Choose chrome or black hardware, or order later.'
+        )
+      }
+
+      navigate('ordered')
+    }, [guitar.hardware, navigate]),
+  }
+})
+```
+
+**Place order** sits in the bar on the summary step. It runs `phx.frontend.useFinalizeActions().primary`:
+
+- **Blocked.** While a warning holds, the action is `disabled` and `hints` holds the warnings' text: the bar shows "Settle the choices above first" beside the button, and the summary lists the conflicts. The name and the e-mail are the layout's own state. The button stays clickable; while either blocks the order, a click reveals what is missing from the form instead of ordering.
+- **Pending.** `run()` starts the handler beside the layout; `isPending` turns the button into "Placing order…" with a spinner and locks the stepper, **Back** and the form.
+- **Failed.** The service refuses gold hardware, which the configurator cannot know beforehand. The handler throws, and the action's `error` is shown at the top of the summary; no snackbar is raised. **Place order** stays available to try again.
+- **Placed.** The handler enters `ordered`, where the panel thanks the customer by name with an order number made from the configuration's id, and lists the build.
+
+A viewer of a shared configuration sees no **Place order**: neither hook checks read mode, so the bar hides it while `phx.frontend.useAccessService().accessInfo.viewMode` is set.
+
+## Pages that slide in
+
+`ConfiguratorLayout` keeps the scene mounted and lays the desktop or the phone page over it, by the width of the configurator's container from `phx.frontend.useActiveViewports()`. It also holds the contact form's state, so the form survives the switch between the two and the move to the confirmation.
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+import { NIGHTJAR } from '../_fields/index.js'
+import { DesktopPage } from '../_shared/DesktopPage.js'
+import { PhonePage } from '../_shared/PhonePage.js'
+import { useOrderForm } from '../_shared/order-form.js'
+
+// A wizard over the scene. The canvas stays mounted the whole time; the desktop or the phone page lies over it. The
+// contact form's state lives here, so it survives the switch between the two and the move to the confirmation.
+const ConfiguratorLayout = () => {
+  // `null` until the container has been measured; only the scene shows until then
+  const viewports = phx.frontend.useActiveViewports()
+  const form = useOrderForm()
+  const isDesktop = viewports?.includes('desktop') ?? false
+
+  return (
+    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: NIGHTJAR.ink }}>
+      <LayoutSlots.SharedCanvas />
+      {viewports !== null && (isDesktop ? <DesktopPage form={form} /> : <PhonePage form={form} />)}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+Each page measures its safe area with `phx.frontend.useSceneSafeArea()`. The summary's panel is wider than a step's, so the steps, the summary and the confirmation are three pages, each with its own safe area, and each slides in when it opens. The safe area slides with its page: the measurement taken when the page mounts sees it shifted, and a `transform` that ends is not a resize, so nothing measures again. The page calls `update()` from the same hook when its own slide ends, not when the step content's slide inside it does. Without it the guitar stays shifted sideways by the slide's 48 pixels.
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { AnimationEvent } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { ENTER_FROM_END, HEADING_SX, NIGHTJAR } from '../_fields/index.js'
+import { OrderBar } from './OrderBar.js'
+import { OrderConfirmation } from './OrderConfirmation.js'
+import { StepHeader } from './StepHeader.js'
+import { StepPanel } from './StepPanel.js'
+import { SummaryPanel } from './SummaryPanel.js'
+import type { OrderForm } from './order-form.js'
+
+type Page = 'steps' | 'summary' | 'ordered'
+
+// The summary needs room for the contact form, so its panel is wider
+const PANEL_WIDTHS: Readonly<Record<Page, number>> = { steps: 420, summary: 520, ordered: 420 }
+
+const pageOf = (navigationState: string): Page => {
+  return navigationState === 'ordered' ? 'ordered' : navigationState === 'summary' ? 'summary' : 'steps'
+}
+
+// The brand's mark: a fret of amber over the name of the shop
+const Brand = () => {
+  return (
+    <Box component="div" sx={{ display: 'flex', alignItems: 'center', gap: 1.5, flex: 'none' }}>
+      <Box component="span" aria-hidden sx={{ inlineSize: 4, blockSize: 28, bgcolor: NIGHTJAR.amber }} />
+      <Box component="div" sx={{ display: 'grid' }}>
+        <Typography sx={{ ...HEADING_SX, fontSize: 16, letterSpacing: '0.32em', lineHeight: 1.1 }}>
+          Northfret
+        </Typography>
+        <Typography sx={{ ...HEADING_SX, fontSize: 10, letterSpacing: '0.36em', color: NIGHTJAR.muted }}>
+          Custom shop
+        </Typography>
+      </Box>
+    </Box>
+  )
+}
+
+interface DesktopPageProps {
+  readonly form: OrderForm
+}
+
+// The desktop wizard: the stepper on top, the guitar in the free area on the left, the panel of the step on the
+// right and the bar with the price at the bottom.
+//
+// The summary's panel is wider than a step's, so the steps, the summary and the confirmation are three pages, each
+// with its own safe area, and each slides in when it opens. The safe area slides with its page: the first
+// measurement, taken when the page mounts, sees it shifted, and no resize follows when the slide ends. `update()`
+// from `useSceneSafeArea` measures again once the slide has settled, so the camera frames the guitar in the place the
+// page leaves for it.
+export const DesktopPage = ({ form }: DesktopPageProps) => {
+  const { containerRef, safeAreaRef, update } = phx.frontend.useSceneSafeArea()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const page = pageOf(navigationState)
+
+  // The step's own content slides too; only the page's slide moves the safe area
+  const handleAnimationEnd = (event: AnimationEvent<HTMLDivElement>) => {
+    if (event.target === event.currentTarget) {
+      update()
+    }
+  }
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'grid',
+        gridTemplateRows: 'auto minmax(0, 1fr) auto',
+        fontFamily: NIGHTJAR.font,
+        color: NIGHTJAR.cream,
+        // The free area lies over the canvas; only the bars and the panel take the pointer
+        pointerEvents: 'none',
+      }}
+    >
+      <Box
+        component="header"
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 5,
+          minBlockSize: 72,
+          paddingInline: 4,
+          bgcolor: NIGHTJAR.ink,
+          borderBlockEnd: `1px solid ${NIGHTJAR.line}`,
+          pointerEvents: 'auto',
+        }}
+      >
+        <Brand />
+        <StepHeader compact={false} />
+      </Box>
+
+      <Box
+        component="div"
+        key={page}
+        onAnimationEnd={handleAnimationEnd}
+        sx={{
+          display: 'grid',
+          gridTemplateColumns: `minmax(0, 1fr) ${PANEL_WIDTHS[page]}px`,
+          minBlockSize: 0,
+          animation: `${ENTER_FROM_END} 480ms cubic-bezier(0.2, 0.7, 0.2, 1)`,
+          '@media (prefers-reduced-motion: reduce)': { animation: 'none' },
+        }}
+      >
+        <Box component="div" sx={{ position: 'relative', minInlineSize: 0 }}>
+          {/* The camera fits the guitar into this box, so its inset is the room around the guitar */}
+          <Box component="div" ref={safeAreaRef} sx={{ position: 'absolute', inset: '40px 72px 56px' }} />
+          <Typography
+            sx={{
+              position: 'absolute',
+              insetBlockEnd: 20,
+              insetInline: 0,
+              textAlign: 'center',
+              fontSize: 12,
+              letterSpacing: '0.14em',
+              textTransform: 'uppercase',
+              color: NIGHTJAR.faint,
+            }}
+          >
+            Drag to turn the guitar
+          </Typography>
+        </Box>
+        <Box
+          component="aside"
+          aria-label={page === 'steps' ? 'Step' : page === 'summary' ? 'Summary' : 'Order'}
+          sx={{
+            overflowY: 'auto',
+            paddingInline: 4,
+            paddingBlock: 4,
+            bgcolor: NIGHTJAR.panel,
+            borderInlineStart: `1px solid ${NIGHTJAR.line}`,
+            pointerEvents: 'auto',
+          }}
+        >
+          {page === 'steps' && <StepPanel compact={false} />}
+          {page === 'summary' && <SummaryPanel compact={false} form={form} />}
+          {page === 'ordered' && <OrderConfirmation compact={false} contact={form.contact} />}
+        </Box>
+      </Box>
+
+      <OrderBar compact={false} form={form} />
+    </Box>
+  )
+}
+```
+
+## On a phone
+
+The same layout in a frame 390 pixels wide, as on a phone. A compact "2 / 5 · Neck" line with a thin progress bar replaces the stepper, the choices become chips in a row that scrolls sideways, the guitar keeps the top of the screen and the bar stays fixed at the bottom. Opened on its own from the sidebar, the **Phone** story sets Storybook's viewport to 390 × 844.
+
+## The stage and the model
+
+The spec's `canvasCustomEnvironment` names `NightjarStage`, a layout element rendered inside the scene: a dark room with a warm glow on the wall behind the guitar, a warm key light and a cool rim. drei's `Lightformer` panels exist only in the reflections, where they draw the long highlights on the clearcoat and the hardware, and no image has to be downloaded.
+
+```tsx
+import { Environment, Lightformer } from '@react-three/drei'
+import { useMemo } from 'react'
+import { CanvasTexture, SRGBColorSpace } from 'three'
+
+import { phx } from '../../.phoenix/phx.js'
+import { NIGHTJAR } from '../_fields/index.js'
+
+/** A warm pool of light that fades into the dark, drawn once on a canvas. */
+const createGlow = (): CanvasTexture => {
+  const size = 512
+  const canvas = document.createElement('canvas')
+  canvas.width = size
+  canvas.height = size
+  const context = canvas.getContext('2d')
+
+  if (context) {
+    const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2)
+    gradient.addColorStop(0, 'rgba(242, 163, 58, 0.42)')
+    gradient.addColorStop(0.22, 'rgba(214, 112, 46, 0.2)')
+    gradient.addColorStop(0.5, 'rgba(122, 30, 43, 0.07)')
+    gradient.addColorStop(0.75, 'rgba(14, 15, 18, 0)')
+    context.fillStyle = gradient
+    context.fillRect(0, 0, size, size)
+  }
+
+  const texture = new CanvasTexture(canvas)
+  texture.colorSpace = SRGBColorSpace
+  return texture
+}
+
+// The stage named by the spec's `canvasCustomEnvironment`: a dark room with a warm glow on the wall behind the guitar,
+// a warm key light and a cool rim. The light panels exist only in the reflections, where they draw the long highlights
+// on the clearcoat and the hardware. The scene is in millimetres.
+export default phx.frontend.createCustomPhoenixLayoutElement('NightjarStage', () => {
+  const glow = useMemo(createGlow, [])
+
+  return (
+    <>
+      <color attach="background" args={[NIGHTJAR.ink]} />
+      <ambientLight intensity={0.4} />
+      <directionalLight position={[-900, 1400, 1600]} intensity={2.4} color="#ffe6c7" />
+      <directionalLight position={[1400, 700, -900]} intensity={1.2} color="#a9c1ff" />
+
+      {/* The glow on the wall, behind the guitar and out of the camera's fit */}
+      <mesh position={[-250, 300, -900]}>
+        <planeGeometry args={[3600, 3600]} />
+        <meshBasicMaterial map={glow} transparent depthWrite={false} toneMapped={false} />
+      </mesh>
+
+      <Environment resolution={256} frames={1}>
+        <color attach="background" args={['#15161b']} />
+        {/* Tall strips at both sides for the long highlights, a softbox above, an amber wash behind */}
+        <Lightformer form="rect" intensity={7} position={[-5, 1, 3]} rotation-y={Math.PI / 3} scale={[1.2, 9, 1]} />
+        <Lightformer form="rect" intensity={4} position={[5, 1, 2]} rotation-y={-Math.PI / 3} scale={[1, 9, 1]} />
+        <Lightformer form="rect" intensity={2.5} position={[0, 6, 1]} rotation-x={Math.PI / 2} scale={[8, 3, 1]} />
+        <Lightformer form="rect" intensity={1.2} position={[0, 1, 7]} rotation-y={Math.PI} scale={[8, 4, 1]} />
+        <Lightformer form="rect" color={NIGHTJAR.amber} intensity={0.8} position={[0, -2, -7]} scale={[10, 3, 1]} />
+      </Environment>
+    </>
+  )
+})
+```
+
+The finish is a physical material with a clearcoat, set per body object with `sceneEntityObjectLocalMaterialOverride`: the override names the object, and only that object's `Finish` material changes. Natural ash shows a wood texture through the clearcoat; the paints have none. The materials many parts share, such as `Hardware` on the tuners, the bridges, the knobs and the switches, use `sceneEntityLocalMaterialOverride`, which changes every object of the entity that carries the material. The values come from expressions in `src/expressions/guitar.ts`, which also price the guitar.
+
+```yaml
+components:
+  Guitar:
+    sceneEntityObjectLocalMaterialOverride:
+      bodyOffset:
+        materialsToOverride:
+          - Finish
+        materialType: physical
+        color:
+          $read: $finishColor
+        textureUrl:
+          $read: $finishTexture
+        metalness:
+          $read: $finishMetalness
+        roughness:
+          $read: $finishRoughness
+        clearcoat: 1
+        clearcoatRoughness: 0.04
+```
+
+The guitar is `public/models/gallery/guitar.glb`, generated by `scripts/models/guitar.ts` in the Storybook package from three.js geometry: two bodies extruded from their outlines with a rounded bevel, a pickguard for each, the neck, fretboard, frets, inlays, headstock, tuners and strings, three pickup sets and the bridges, knobs and switches of each body. Each part is a named node the spec loads with `sceneEntityRemoteObject.<name>.objectName`; `sceneEntityObjectProperties` shows the parts of the chosen body and pickups. The script lives in `scripts/models/`, outside the example's `src/`, because every file under `src/` is part of this page.
+
+## Test cases
+
+- The page opens on **Body**: the Offset in Seafoam green with a parchment pickguard, maple neck, rosewood board, single coils and chrome, **$1,650.00**, and **Next: Neck**. The stepper shows step 1 active and the rest upcoming, which cannot be clicked yet.
+- **Candy apple red** turns the body red under a glossy clearcoat at $1,830.00; **Natural ash** shows the wood grain. The finish's name appears beside the label.
+- **Single-cut** swaps the body, its small pickguard, the bar bridge with a tailpiece, four knobs and the toggle switch, and adds $150. **None** removes the pickguard.
+- **Next: Neck** slides the neck's choices in from the right and moves the camera to the upper neck and the headstock. **Roasted maple** and **Ebony** change the neck and the board; on a maple board the dots turn black.
+- **Back** slides the body's choices in from the left and returns the camera to the whole guitar.
+- On **Electronics** the camera moves to the pickups. **Humbuckers** on the Offset shows "The Offset body is routed for single-coil-sized pickups. …" under **Pickups**, and the stepper marks **Electronics**. **P-90s** clears both.
+- **Gold** turns the tuners, the bridge, the knobs and the switch gold.
+- On **Details** the camera shows the headstock. Typing a name prints it on the headstock as you type, in gold on a dark neck and in black on maple; the counter shows the characters used of 16, and the price rises by $45.
+- Typing past 16 characters turns the counter and the field red and shows "The headstock fits 16 characters. Shorten the signature."; leaving the field puts back the signature committed before, and the headstock with it.
+- **Review order** opens the summary: a wider panel lists every choice, with the signature in script. With the humbucker conflict, the summary lists it with **Go to Electronics**, the bar shows "Settle the choices above first", and **Place order** reveals "Enter the name the order is for." and "Enter an e-mail address for the build updates." under the empty fields.
+- **Go to Electronics** opens that step; after **P-90s**, the stepper's **Summary** returns to the summary in one click.
+- With a name and an e-mail, **Place order** shows "Placing order…" with a spinner for under two seconds. With gold hardware it then shows "The order did not go through" and the service's reason at the top of the summary; with chrome or black it opens the confirmation: "Thank you, …", the order number, the e-mail and the build. The stepper no longer takes clicks, and **Design another** returns to **Body**.
+- Each step, the summary and the confirmation leave the guitar centred in the area beside the panel once their slide has settled.
+- With the browser console's Verbose level, **Next** and **Back** log the step buttons' `nextStepButton` and `previousStepButton` events, the stepper the `topNavigation` `step` event, **Review order** the `summaryButton` event and **Place order** the `finalizeButton` event: without a Google Tag Manager id, Storybook's analytics log their events with `console.debug`.
+- In the **Phone** story the guitar keeps the top of the screen, "1 / 5 · Body" and the progress line sit above it, the choices are chips in rows that scroll sideways, and **Next**, **Review order** and **Place order** work as on the desktop.
+- The browser console shows no errors, apart from the "Failed to finalize" line that the refused order with gold hardware logs.
+
+## What this layout leaves out
+
+- **Messages for rejected changes.** The only rule that rejects a change is the signature's, which the field explains itself, so the layout mounts neither `LayoutSlots.Services` nor `phx.frontend.useConfiguratorMessages()`. A project whose other rules reject changes, or that saves the configuration, mounts one of the two so a rejected change or a failed save is not silent; see [Custom Layout → Show messages](?path=/docs/layouts-custom-layout--docs#show-messages).
+- **Read mode.** **Place order** is hidden while `phx.frontend.useAccessService().accessInfo.viewMode` is set, but the fields stay editable and the example ships no read template; [Custom Layout → Serve read mode](?path=/docs/layouts-custom-layout--docs#serve-read-mode) shows one.
+- **An order that outlives the page.** The order number is made from the configuration's id and the contact details are the layout's state, so a configuration reopened in the `ordered` state thanks no one by name. A deployed project sends the details with the order and shows what its service answers.
+- **The built-in arrangement.** Header, sidebar, sidebar footer, tabs, tool and view controls and the toolbar are not mounted; [Layout Slots](?path=/docs/phoenix-layout-slots--docs) lists every slot a project layout can mount.
+
+## Related pages
+
+- [Kestrel Kettle](?path=/docs/layouts-gallery-kestrel-kettle--docs) sells a small product from one page, and [Ardent Compressor](?path=/docs/layouts-gallery-ardent-compressor--docs) is a stepped quote builder without a scene.
+- [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 the hooks used here, steps and tabs included.
+- [Floating Header → Adding step navigation](?path=/docs/layouts-header-floating--docs#adding-step-navigation) shows the built-in stepper over the same `navigationSteps`.
+- [Domain Model → Invariants](?path=/docs/phoenix-domain-model--docs#invariants) describes the rules.
+- [Finalization](?path=/docs/phoenix-finalization--docs) describes the server side of a finalize action.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Guitar
+    aliases:
+      RootEntity:
+        - Guitar
+    commonTypes:
+      BodyShape:
+        enum:
+          - Offset
+          - SingleCut
+      Finish:
+        enum:
+          - Seafoam
+          - CandyRed
+          - Midnight
+          - NaturalAsh
+      Pickguard:
+        enum:
+          - Parchment
+          - Black
+          - Pearloid
+          - None
+      NeckWood:
+        enum:
+          - Maple
+          - RoastedMaple
+          - Mahogany
+      Fretboard:
+        enum:
+          - Maple
+          - Rosewood
+          - Ebony
+      Pickups:
+        enum:
+          - SingleCoils
+          - Humbuckers
+          - P90s
+      Hardware:
+        enum:
+          - Chrome
+          - Gold
+          - Black
+    shapes:
+      Guitar:
+        bodyShape:
+          $ref: '#/model/latest/commonTypes/BodyShape'
+        finish:
+          $ref: '#/model/latest/commonTypes/Finish'
+        pickguard:
+          $ref: '#/model/latest/commonTypes/Pickguard'
+        neckWood:
+          $ref: '#/model/latest/commonTypes/NeckWood'
+        fretboard:
+          $ref: '#/model/latest/commonTypes/Fretboard'
+        pickups:
+          $ref: '#/model/latest/commonTypes/Pickups'
+        hardware:
+          $ref: '#/model/latest/commonTypes/Hardware'
+        signature:
+          type: string
+
+presets:
+  - rootEntityType: Guitar
+    initialDomainEntities:
+      - id: Guitar-1
+        type: Guitar
+        bodyShape: Offset
+        finish: Seafoam
+        pickguard: Parchment
+        neckWood: Maple
+        fretboard: Rosewood
+        pickups: SingleCoils
+        hardware: Chrome
+        signature: ''
+
+# One state per wizard step, and `ordered` for the confirmation after the order
+navigationStates:
+  - body
+  - neck
+  - electronics
+  - details
+  - summary
+  - ordered
+
+# The longest signature the headstock takes; the invariant and the layout's counter both read it
+expressions:
+  Guitar:
+    $signatureLimit:
+      type: number
+
+invariants:
+  Guitar:
+    signatureLength:
+      types:
+        - signatureTooLong
+    offsetHumbuckers:
+      type: offsetHumbuckers
+      severity: warning
+      message: The Offset body is routed for single-coil-sized pickups. Choose single coils or P-90s, or the Single-cut body for humbuckers.
+
+components:
+  Guitar:
+    detail:
+      main:
+        title: Nightjar
+        subtitle: Northfret Custom Shop
+        description: A hand-built electric guitar. Choose the body, the neck, the electronics and the details, then order it from the summary.
+    price:
+      main:
+        price:
+          $read: $price
+    navigationSteps:
+      main:
+        steps:
+          - label: Body
+            navigationStates:
+              - body
+          - label: Neck
+            navigationStates:
+              - neck
+          - label: Electronics
+            navigationStates:
+              - electronics
+          - label: Details
+            navigationStates:
+              - details
+          - label: Summary
+            navigationStates:
+              - summary
+              - ordered
+    finalizeAction:
+      placeOrder:
+        variant: primary
+        label: Place order
+        title: Send the guitar as configured to the Northfret workshop
+        icon: ShoppingBag
+        handler: placeOrder
+
+    # Each choice is active on its own step, and on the summary and the confirmation, which list every choice
+    attributeSelection:
+      bodyShape:
+        value:
+          $bind: bodyShape
+        options:
+          - label: Offset
+            description: Contoured waist, 3.4 kg
+            value: Offset
+          - label: Single-cut
+            description: Thicker body, long sustain
+            value: SingleCut
+        $filter:
+          navigationStates:
+            - body
+            - summary
+            - ordered
+      pickguard:
+        value:
+          $bind: pickguard
+        options:
+          - label: Parchment
+            value: Parchment
+          - label: Black
+            value: Black
+          - label: Pearloid
+            description: Shimmers in the light
+            value: Pearloid
+          - label: None
+            value: None
+        $filter:
+          navigationStates:
+            - body
+            - summary
+            - ordered
+      neckWood:
+        value:
+          $bind: neckWood
+        options:
+          - label: Maple
+            description: Bright and snappy
+            value: Maple
+          - label: Roasted maple
+            description: Baked for stability, caramel colour
+            value: RoastedMaple
+          - label: Mahogany
+            description: Warm and round
+            value: Mahogany
+        $filter:
+          navigationStates:
+            - neck
+            - summary
+            - ordered
+      fretboard:
+        value:
+          $bind: fretboard
+        options:
+          - label: Maple
+            value: Maple
+          - label: Rosewood
+            value: Rosewood
+          - label: Ebony
+            description: Dense and smooth
+            value: Ebony
+        $filter:
+          navigationStates:
+            - neck
+            - summary
+            - ordered
+      pickups:
+        value:
+          $bind: pickups
+        options:
+          - label: Single coils
+            description: Glassy and articulate
+            value: SingleCoils
+          - label: Humbuckers
+            description: Thick and hum-free
+            value: Humbuckers
+          - label: P-90s
+            description: Gritty, with bite
+            value: P90s
+        $filter:
+          navigationStates:
+            - electronics
+            - summary
+            - ordered
+      hardware:
+        value:
+          $bind: hardware
+        options:
+          - label: Chrome
+            value: Chrome
+          - label: Gold
+            value: Gold
+          - label: Black
+            value: Black
+        $filter:
+          navigationStates:
+            - electronics
+            - summary
+            - ordered
+    materialSwatch:
+      finish:
+        selectedSwatchKey:
+          $bind: finish
+        swatches:
+          Seafoam:
+            swatchName: Seafoam green
+            color: '#8fcab6'
+          CandyRed:
+            swatchName: Candy apple red
+            color: '#b0141f'
+          Midnight:
+            swatchName: Midnight blue metallic
+            color: '#1d2b4f'
+          NaturalAsh:
+            swatchName: Natural ash
+            color: '#d8b98a'
+        $filter:
+          navigationStates:
+            - body
+            - summary
+            - ordered
+    textValue:
+      signature:
+        value:
+          $bind: signature
+        $filter:
+          navigationStates:
+            - details
+            - summary
+            - ordered
+
+    canvasConfig:
+      main:
+        highlightingDisabled: true
+    canvasCustomEnvironment:
+      main:
+        name: NightjarStage
+
+    # The camera follows the wizard: the whole guitar for the body and the summary, then a closer view of what each
+    # step changes. Each camera is active only in its step's navigation state; the scene is in millimetres.
+    fitRootPerspectiveCamera:
+      overview:
+        fov: 30
+        near: 10
+        far: 20000
+        minDistance: 600
+        maxDistance: 9000
+        azimuthAngle: 0.28
+        polarAngle: 1.48
+        minPolarAngle: 0.9
+        maxPolarAngle: 2
+        fitToBox: true
+        fitMeshChanges: false
+        $filter:
+          navigationStates:
+            - body
+            - summary
+            - ordered
+    staticPerspectiveCamera:
+      neck:
+        fov: 30
+        near: 10
+        far: 20000
+        lookAtX: 0
+        lookAtY: 625
+        lookAtZ: 0
+        distance: 1350
+        minDistance: 300
+        maxDistance: 3000
+        azimuthAngle: 0.55
+        polarAngle: 1.36
+        $filter:
+          navigationStates:
+            - neck
+      electronics:
+        fov: 30
+        near: 10
+        far: 20000
+        lookAtX: 0
+        lookAtY: 40
+        lookAtZ: 0
+        distance: 1150
+        minDistance: 300
+        maxDistance: 3000
+        azimuthAngle: -0.32
+        polarAngle: 1.22
+        $filter:
+          navigationStates:
+            - electronics
+      details:
+        fov: 30
+        near: 10
+        far: 20000
+        lookAtX: -10
+        lookAtY: 750
+        lookAtZ: 0
+        distance: 520
+        minDistance: 200
+        maxDistance: 3000
+        azimuthAngle: 0.12
+        polarAngle: 1.5
+        $filter:
+          navigationStates:
+            - details
+
+    sceneEntityRemoteObject:
+      bodyOffset:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: BodyOffset
+        dimensionUnit: m
+      bodySingleCut:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: BodySingleCut
+        dimensionUnit: m
+      pickguardOffset:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PickguardOffset
+        dimensionUnit: m
+      pickguardSingleCut:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PickguardSingleCut
+        dimensionUnit: m
+      neck:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Neck
+        dimensionUnit: m
+      headstock:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Headstock
+        dimensionUnit: m
+      fretboard:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Fretboard
+        dimensionUnit: m
+      frets:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Frets
+        dimensionUnit: m
+      inlays:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Inlays
+        dimensionUnit: m
+      nut:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Nut
+        dimensionUnit: m
+      strings:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Strings
+        dimensionUnit: m
+      tuners:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: Tuners
+        dimensionUnit: m
+      pickupsSingleCoil:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PickupsSingleCoil
+        dimensionUnit: m
+      polesSingleCoil:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PolesSingleCoil
+        dimensionUnit: m
+      pickupsHumbucker:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PickupsHumbucker
+        dimensionUnit: m
+      polesHumbucker:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PolesHumbucker
+        dimensionUnit: m
+      pickupsP90:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PickupsP90
+        dimensionUnit: m
+      polesP90:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: PolesP90
+        dimensionUnit: m
+      bridgeTremolo:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: BridgeTremolo
+        dimensionUnit: m
+      bridgeTuneOMatic:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: BridgeTuneOMatic
+        dimensionUnit: m
+      knobsOffset:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: KnobsOffset
+        dimensionUnit: m
+      knobsSingleCut:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: KnobsSingleCut
+        dimensionUnit: m
+      switchOffset:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: SwitchOffset
+        dimensionUnit: m
+      switchSingleCut:
+        fileUrl: /models/gallery/guitar.glb
+        objectName: SwitchSingleCut
+        dimensionUnit: m
+
+    # Each body brings its own pickguard, bridge, knobs and switch; the pickups show the chosen set
+    sceneEntityObjectProperties:
+      bodyOffset:
+        visible:
+          $eval: self.bodyShape === 'Offset'
+      bodySingleCut:
+        visible:
+          $eval: self.bodyShape === 'SingleCut'
+      pickguardOffset:
+        visible:
+          $eval: self.bodyShape === 'Offset' && self.pickguard !== 'None'
+      pickguardSingleCut:
+        visible:
+          $eval: self.bodyShape === 'SingleCut' && self.pickguard !== 'None'
+      bridgeTremolo:
+        visible:
+          $eval: self.bodyShape === 'Offset'
+      bridgeTuneOMatic:
+        visible:
+          $eval: self.bodyShape === 'SingleCut'
+      knobsOffset:
+        visible:
+          $eval: self.bodyShape === 'Offset'
+      knobsSingleCut:
+        visible:
+          $eval: self.bodyShape === 'SingleCut'
+      switchOffset:
+        visible:
+          $eval: self.bodyShape === 'Offset'
+      switchSingleCut:
+        visible:
+          $eval: self.bodyShape === 'SingleCut'
+      pickupsSingleCoil:
+        visible:
+          $eval: self.pickups === 'SingleCoils'
+      polesSingleCoil:
+        visible:
+          $eval: self.pickups === 'SingleCoils'
+      pickupsHumbucker:
+        visible:
+          $eval: self.pickups === 'Humbuckers'
+      polesHumbucker:
+        visible:
+          $eval: self.pickups === 'Humbuckers'
+      pickupsP90:
+        visible:
+          $eval: self.pickups === 'P90s'
+      polesP90:
+        visible:
+          $eval: self.pickups === 'P90s'
+
+    # The nitro finish: a physical material with a clearcoat on each body object; natural ash shows the grain
+    sceneEntityObjectLocalMaterialOverride:
+      bodyOffset:
+        materialsToOverride:
+          - Finish
+        materialType: physical
+        color:
+          $read: $finishColor
+        textureUrl:
+          $read: $finishTexture
+        rotation: 1.5708
+        repeatX: 2.2
+        repeatY: 2.2
+        metalness:
+          $read: $finishMetalness
+        roughness:
+          $read: $finishRoughness
+        clearcoat: 1
+        clearcoatRoughness: 0.04
+      bodySingleCut:
+        materialsToOverride:
+          - Finish
+        materialType: physical
+        color:
+          $read: $finishColor
+        textureUrl:
+          $read: $finishTexture
+        rotation: 1.5708
+        repeatX: 2.2
+        repeatY: 2.2
+        metalness:
+          $read: $finishMetalness
+        roughness:
+          $read: $finishRoughness
+        clearcoat: 1
+        clearcoatRoughness: 0.04
+
+    # The materials many parts share change for every object that carries them
+    sceneEntityLocalMaterialOverride:
+      pickguard:
+        materialsToOverride:
+          - Pickguard
+        materialType: physical
+        color:
+          $read: $pickguardColor
+        roughness:
+          $read: $pickguardRoughness
+        metalness: 0
+        iridescence:
+          $read: $pickguardIridescence
+        iridescenceIor: 1.4
+        clearcoat:
+          $read: $pickguardIridescence
+      neck:
+        materialsToOverride:
+          - Neck
+        materialType: physical
+        color:
+          $read: $neckColor
+        textureUrl:
+          $read: $neckTexture
+        repeatX: 5
+        repeatY: 1
+        offsetX: 0.5
+        metalness: 0
+        roughness: 0.42
+        clearcoat: 0.6
+        clearcoatRoughness: 0.2
+      fretboard:
+        materialsToOverride:
+          - Fretboard
+        color:
+          $read: $fretboardColor
+        textureUrl:
+          $read: $fretboardTexture
+        repeatX: 5
+        repeatY: 1
+        offsetX: 0.5
+        metalness: 0
+        roughness: 0.62
+      inlays:
+        materialsToOverride:
+          - Inlay
+        color:
+          $read: $inlayColor
+        metalness: 0
+        roughness: 0.3
+      hardware:
+        materialsToOverride:
+          - Hardware
+        color:
+          $read: $hardwareColor
+        metalness:
+          $read: $hardwareMetalness
+        roughness:
+          $read: $hardwareRoughness
+      pickupCover:
+        materialsToOverride:
+          - PickupCover
+        color:
+          $read: $pickupCoverColor
+        metalness: 0
+        roughness: 0.45
+
+    # The signature in script on the headstock's face, along its length; the text is the customer's own
+    sceneEntityObjectTextDecal:
+      headstock:
+        text:
+          $read: signature
+        font: SignPainter-HouseScript
+        preloadFonts:
+          - SignPainter-HouseScript
+        fontSize: auto
+        textColor:
+          $read: $signatureColor
+        textCanvasHeight: 256
+        positionX: 0.002
+        positionY: 0.76
+        positionZ: 0.004
+        rotationX: 0
+        rotationY: 0
+        rotationZ: 1.5708
+        sizeX: 0.13
+        sizeY: 0.03
+        sizeZ: 0.02
+        roughness: 0.4
+        metalness: 0.2
+        bumpScale: 0.4
+        invertedBump: true
+```
+
+### ./src/\_fields/ChoiceField.tsx
+
+```tsx
+import { Box, ButtonBase, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { FieldShell } from './FieldShell.js'
+import { NIGHTJAR } from './tokens.js'
+
+// The body outlines of the model, drawn small, with a stub of the neck
+const BODY_PATHS: Readonly<Record<string, string>> = {
+  Offset:
+    'M20 52L23.2 51.8L26.4 51.6L29.6 50.8L32.5 49.5L35.1 47.6L36.9 45L38.1 41.9L38.6 38.8L38.5 35.6L37.8 32.4L36.8 29.4L35.5 26.4L34.6 23.3L34.3 20.1L34.8 17L35 13.7L34.4 10.6L32.8 7.8L30.1 6.2L27.4 7.7L25.5 10.3L22.6 10.7L19.4 10.1L16.4 8.9L15.2 6L14.1 3L11.7 1L8.7 2L7 4.7L6.1 7.8L5.4 10.9L5.3 14.1L5.8 17.3L5.5 20.5L4.8 23.6L3.8 26.7L2.8 29.8L2.2 33L1.8 36.2L1.8 39.4L2.1 42.6L3.1 45.7L4.9 48.3L7.3 50.4L10.4 51.5L13.6 52L16.8 52.1Z',
+  SingleCut:
+    'M20 51L22.9 50.9L25.7 50.7L28.5 50.2L31.2 49.1L33.6 47.5L35.4 45.3L36.5 42.7L37.1 39.9L37.3 37L36.9 34.2L36 31.5L34.5 29L33.2 26.5L32.2 23.8L32.2 21L31.9 18.1L31 15.4L29.6 12.9L27.7 10.8L25.1 11.6L23.9 14.2L23 12.2L23.1 9.3L21.6 7.1L18.9 6.2L16 6L13.2 6.5L10.6 7.7L8.5 9.6L7.3 12.2L7 15L7.6 17.8L7.3 20.7L6.5 23.4L5.6 26.2L4.6 28.8L3.8 31.6L3.3 34.4L3.1 37.3L3.2 40.1L3.7 43L4.7 45.6L6.4 47.9L8.8 49.5L11.4 50.6L14.3 51L17.1 51.1Z',
+}
+
+// Two pickups as seen from the front: thin single coils, double humbuckers, wide P-90s
+const PICKUP_SHAPES: Readonly<Record<string, readonly { x: number; y: number; width: number; height: number }[]>> = {
+  SingleCoils: [
+    { x: 8, y: 13, width: 24, height: 5 },
+    { x: 8, y: 30, width: 24, height: 5 },
+  ],
+  Humbuckers: [
+    { x: 9, y: 9, width: 22, height: 5 },
+    { x: 9, y: 15, width: 22, height: 5 },
+    { x: 9, y: 28, width: 22, height: 5 },
+    { x: 9, y: 34, width: 22, height: 5 },
+  ],
+  P90s: [
+    { x: 6, y: 10, width: 28, height: 10 },
+    { x: 6, y: 28, width: 28, height: 10 },
+  ],
+}
+
+// Swatches as CSS backgrounds: wood with a hint of grain, metal with a highlight, the pearloid's shimmer
+const WOOD_GRAIN = 'repeating-linear-gradient(100deg, rgba(0, 0, 0, 0.08) 0 2px, transparent 2px 6px)'
+
+const SWATCHES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  pickguard: {
+    Parchment: '#ece2cb',
+    Black: 'radial-gradient(circle at 30% 30%, #3a3a40, #0c0c0e 70%)',
+    Pearloid: 'conic-gradient(from 40deg, #f6f1ea, #e6eef6, #f4e6f0, #eef6ea, #f6f1ea)',
+    None: 'transparent',
+  },
+  neckWood: {
+    Maple: `${WOOD_GRAIN}, #ecd3a3`,
+    RoastedMaple: `${WOOD_GRAIN}, #b9804a`,
+    Mahogany: `${WOOD_GRAIN}, #7b3f28`,
+  },
+  fretboard: {
+    Maple: `${WOOD_GRAIN}, #ecd3a3`,
+    Rosewood: `${WOOD_GRAIN}, #4a2a1c`,
+    Ebony: `${WOOD_GRAIN}, #1d1916`,
+  },
+  hardware: {
+    Chrome: 'linear-gradient(135deg, #ffffff, #9aa1a8 55%, #e4e7ea)',
+    Gold: 'linear-gradient(135deg, #fff1c4, #b8862e 55%, #f3d38a)',
+    Black: 'linear-gradient(135deg, #6a6a70, #121214 55%, #3a3a40)',
+  },
+}
+
+interface OptionArtProps {
+  readonly instanceName: string
+  readonly value: string
+  readonly size: number
+}
+
+// The small picture beside an option: a silhouette for the body, the pickup layout, or a swatch of the material
+const OptionArt = ({ instanceName, value, size }: OptionArtProps) => {
+  const bodyPath = instanceName === 'bodyShape' ? BODY_PATHS[value] : undefined
+  const pickups = instanceName === 'pickups' ? PICKUP_SHAPES[value] : undefined
+  const swatch = SWATCHES[instanceName]?.[value]
+
+  if (bodyPath) {
+    return (
+      <Box component="svg" viewBox="0 0 40 54" aria-hidden sx={{ inlineSize: size, blockSize: size, flex: 'none' }}>
+        <rect x={17.8} y={0} width={4.4} height={12} rx={1} fill={NIGHTJAR.faint} />
+        <path d={bodyPath} fill={NIGHTJAR.cream} />
+      </Box>
+    )
+  }
+
+  if (pickups) {
+    return (
+      <Box component="svg" viewBox="0 0 40 48" aria-hidden sx={{ inlineSize: size, blockSize: size, flex: 'none' }}>
+        {pickups.map(shape => (
+          <rect key={`${shape.x}-${shape.y}`} {...shape} rx={2.5} fill={NIGHTJAR.cream} />
+        ))}
+      </Box>
+    )
+  }
+
+  if (swatch === undefined) {
+    return null
+  }
+
+  return (
+    <Box
+      component="span"
+      aria-hidden
+      sx={{
+        inlineSize: size,
+        blockSize: size,
+        flex: 'none',
+        borderRadius: '50%',
+        background: swatch,
+        boxShadow: `inset 0 0 0 1px ${NIGHTJAR.line}`,
+        // "None" is an empty, dashed ring
+        ...(value === 'None' && {
+          border: `1.5px dashed ${NIGHTJAR.faint}`,
+          boxShadow: 'none',
+        }),
+      }}
+    />
+  )
+}
+
+// Arrow keys move the selection between the options, as in a native radio group
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface ChoiceFieldProps {
+  readonly instanceName: string
+  readonly label: string
+  readonly warningTypes: readonly string[]
+  /** Chips in one scrolling row, for a phone; cards in a grid otherwise */
+  readonly compact: boolean
+}
+
+// One `attributeSelection` of the spec: cards with a picture, a title and a description, or chips on a phone. An
+// option a `fixable` invariant rules out is faded with the reason below; it stays clickable, so the change is tried
+// and rejected.
+export const ChoiceField = ({ instanceName, label, warningTypes, compact }: ChoiceFieldProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const guitarId = phx.frontend.useRootEntityId()
+  const { value, options } = phx.frontend.useAttributeSelection(guitarId, instanceName)
+  const selected = options.find(option => option.value === value)
+  const ruledOut = 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()
+    const next = (index + step + options.length) % options.length
+    options[next]?.onSelect()
+    event.currentTarget.parentElement?.querySelectorAll<HTMLElement>('[role="radio"]')[next]?.focus()
+  }
+
+  return (
+    <FieldShell
+      id={`nightjar-${instanceName}`}
+      label={label}
+      aside={
+        compact && selected ? (
+          <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.cream }}>
+            {resolve(selected.title)}
+          </Typography>
+        ) : undefined
+      }
+      hint={ruledOut}
+      warningTypes={warningTypes}
+      compact={compact}
+    >
+      <Box
+        component="div"
+        role="radiogroup"
+        aria-labelledby={`nightjar-${instanceName}-label`}
+        sx={
+          compact
+            ? {
+                display: 'flex',
+                gap: 1,
+                marginInline: -2,
+                paddingInline: 2,
+                paddingBlockEnd: 0.5,
+                overflowX: 'auto',
+                scrollbarWidth: 'none',
+              }
+            : { display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(150px, 1fr))', gap: 1 }
+        }
+      >
+        {options.map((option, index) => {
+          const isSelected = option.value === value
+          const description = resolve(option.description)
+
+          return (
+            <ButtonBase
+              key={String(option.value)}
+              role="radio"
+              aria-checked={isSelected}
+              aria-disabled={option.disabled}
+              tabIndex={isSelected ? 0 : -1}
+              onClick={option.onSelect}
+              onKeyDown={event => handleKeyDown(event, index)}
+              sx={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'flex-start',
+                gap: compact ? 1 : 1.5,
+                flex: compact ? 'none' : undefined,
+                minBlockSize: compact ? 44 : 64,
+                paddingInline: compact ? 1.5 : 1.5,
+                paddingBlock: compact ? 0.75 : 1.25,
+                textAlign: 'start',
+                borderRadius: compact ? 999 : 1.5,
+                border: `1px solid ${isSelected ? NIGHTJAR.amber : NIGHTJAR.line}`,
+                bgcolor: isSelected ? NIGHTJAR.amberTint : NIGHTJAR.raised,
+                color: NIGHTJAR.cream,
+                opacity: option.disabled ? 0.45 : 1,
+                transition: 'border-color 160ms, background-color 160ms',
+                '&:hover': { bgcolor: isSelected ? NIGHTJAR.amberTint : NIGHTJAR.raisedHover },
+                '&.Mui-focusVisible': { outline: `2px solid ${NIGHTJAR.amber}`, outlineOffset: 2 },
+              }}
+            >
+              <OptionArt instanceName={instanceName} value={String(option.value)} size={compact ? 22 : 36} />
+              <Box component="span" sx={{ display: 'grid', gap: 0.25 }}>
+                <Typography
+                  component="span"
+                  sx={{
+                    fontFamily: NIGHTJAR.font,
+                    fontSize: compact ? 14 : 15,
+                    fontWeight: 500,
+                    whiteSpace: 'nowrap',
+                    color: NIGHTJAR.cream,
+                  }}
+                >
+                  {resolve(option.title)}
+                </Typography>
+                {!compact && description && (
+                  <Typography
+                    component="span"
+                    sx={{ fontFamily: NIGHTJAR.font, fontSize: 13, lineHeight: 1.3, color: NIGHTJAR.muted }}
+                  >
+                    {description}
+                  </Typography>
+                )}
+              </Box>
+            </ButtonBase>
+          )
+        })}
+      </Box>
+    </FieldShell>
+  )
+}
+```
+
+### ./src/\_fields/FieldShell.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+
+import { LABEL_SX, NIGHTJAR } from './tokens.js'
+import { useWarnings } from './use-warnings.js'
+
+interface FieldShellProps {
+  readonly id: string
+  readonly label: string
+  /** Beside the label: the chosen option's name, or a counter */
+  readonly aside?: ReactNode
+  /** Below the field: why an option is ruled out, or what the customer should know */
+  readonly hint?: string | undefined
+  readonly warningTypes: readonly string[]
+  readonly compact: boolean
+  readonly children: ReactNode
+}
+
+// A labelled field. A `warning` violation the field explains is shown below it while it holds; it is the same text
+// the summary lists, and the stepper marks the step until it is resolved.
+export const FieldShell = ({ id, label, aside, hint, warningTypes, compact, children }: FieldShellProps) => {
+  const warning = useWarnings().find(candidate => warningTypes.includes(candidate.type))
+
+  return (
+    <Box component="section" aria-labelledby={`${id}-label`} sx={{ display: 'grid', gap: compact ? 1 : 1.5 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 2 }}>
+        <Typography component="h3" id={`${id}-label`} sx={LABEL_SX}>
+          {label}
+        </Typography>
+        {aside}
+      </Box>
+      {children}
+      {hint && <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 13, color: NIGHTJAR.muted }}>{hint}</Typography>}
+      {warning && (
+        <Typography
+          role="status"
+          sx={{
+            paddingInline: 1.5,
+            paddingBlock: 1,
+            borderInlineStart: `3px solid ${NIGHTJAR.amber}`,
+            bgcolor: NIGHTJAR.amberTint,
+            fontFamily: NIGHTJAR.font,
+            fontSize: 14,
+            lineHeight: 1.4,
+            color: NIGHTJAR.cream,
+          }}
+        >
+          {warning.text}
+        </Typography>
+      )}
+    </Box>
+  )
+}
+```
+
+### ./src/\_fields/FinishField.tsx
+
+```tsx
+import { Box, ButtonBase, Tooltip, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { FieldShell } from './FieldShell.js'
+import { NIGHTJAR } from './tokens.js'
+
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+// A highlight over each swatch, so the paint reads as a glossy finish
+const GLOSS = 'radial-gradient(circle at 32% 28%, rgba(255, 255, 255, 0.55), rgba(255, 255, 255, 0) 42%)'
+
+interface FinishFieldProps {
+  readonly instanceName: string
+  readonly label: string
+  readonly warningTypes: readonly string[]
+  readonly compact: boolean
+}
+
+// The spec's `materialSwatch`: round swatches in the colours the spec gives each finish, the chosen one's name
+// beside the label. `useSwatchSelection` takes the `fixable` violation types to ignore as its third argument.
+export const FinishField = ({ instanceName, label, warningTypes, compact }: FinishFieldProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const guitarId = phx.frontend.useRootEntityId()
+  const { options } = phx.frontend.useSwatchSelection(guitarId, instanceName, [])
+  const selected = options.find(option => option.selected)
+  const ruledOut = options.find(option => option.disabled && option.hint)?.hint
+  const size = compact ? 40 : 48
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>, index: number) => {
+    const step = ARROW_STEPS[event.key]
+
+    if (step === undefined) {
+      return
+    }
+
+    event.preventDefault()
+    const next = (index + step + options.length) % options.length
+    options[next]?.onClick()
+    event.currentTarget.parentElement?.querySelectorAll<HTMLElement>('[role="radio"]')[next]?.focus()
+  }
+
+  return (
+    <FieldShell
+      id={`nightjar-${instanceName}`}
+      label={label}
+      aside={
+        selected && (
+          <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.cream }}>
+            {resolve(selected.swatchName)}
+          </Typography>
+        )
+      }
+      hint={ruledOut ?? undefined}
+      warningTypes={warningTypes}
+      compact={compact}
+    >
+      <Box
+        component="div"
+        role="radiogroup"
+        aria-labelledby={`nightjar-${instanceName}-label`}
+        sx={{ display: 'flex', flexWrap: 'wrap', gap: compact ? 1.5 : 2 }}
+      >
+        {options.map((option, index) => {
+          const name = resolve(option.swatchName)
+
+          return (
+            <Tooltip key={option.swatchKey} title={name}>
+              <ButtonBase
+                role="radio"
+                aria-label={name}
+                aria-checked={option.selected}
+                aria-disabled={option.disabled}
+                tabIndex={option.selected ? 0 : -1}
+                onClick={option.onClick}
+                onKeyDown={event => handleKeyDown(event, index)}
+                sx={{
+                  inlineSize: size,
+                  blockSize: size,
+                  borderRadius: '50%',
+                  background: `${GLOSS}, ${option.color}`,
+                  // The ring sits outside the swatch, in the panel's colour, so the swatch keeps its full size
+                  boxShadow: option.selected
+                    ? `0 0 0 3px ${NIGHTJAR.ink}, 0 0 0 5px ${NIGHTJAR.amber}`
+                    : `inset 0 0 0 1px ${NIGHTJAR.line}`,
+                  opacity: option.disabled ? 0.4 : 1,
+                  transition: 'box-shadow 160ms, transform 160ms',
+                  '&:hover': { transform: 'scale(1.06)' },
+                  '&.Mui-focusVisible': { outline: `2px solid ${NIGHTJAR.cream}`, outlineOffset: 6 },
+                }}
+              />
+            </Tooltip>
+          )
+        })}
+      </Box>
+    </FieldShell>
+  )
+}
+```
+
+### ./src/\_fields/SignatureField.tsx
+
+```tsx
+import { Box, InputBase, Typography } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+import { FieldShell } from './FieldShell.js'
+import { NIGHTJAR } from './tokens.js'
+
+interface SignatureFieldProps {
+  readonly instanceName: string
+  readonly label: string
+  readonly warningTypes: readonly string[]
+  readonly compact: boolean
+}
+
+// The spec's `textValue`, which the spec prints on the headstock with a text decal. Typing stages each value, so the
+// headstock follows every key; leaving the field or pressing Enter commits it. A value the `fixable` length rule
+// rejects shows the rule's message as the hook's `hints`, and leaving the field rolls back to the last value that
+// fitted. The counter reads the limit from the spec's `$signatureLimit` expression, which the rule checks too.
+export const SignatureField = ({ instanceName, label, warningTypes, compact }: SignatureFieldProps) => {
+  const guitarId = phx.frontend.useRootEntityId()
+  const guitar = phx.frontend.useRootEntityState()
+  const signature = phx.frontend.useTextValue(guitarId, instanceName)
+  const limit = guitar.$signatureLimit
+
+  return (
+    <FieldShell
+      id={`nightjar-${instanceName}`}
+      label={label}
+      aside={
+        <Typography
+          aria-live="polite"
+          sx={{
+            fontFamily: NIGHTJAR.font,
+            fontSize: 13,
+            fontVariantNumeric: 'tabular-nums',
+            color: signature.hasErrors ? NIGHTJAR.alert : NIGHTJAR.muted,
+          }}
+        >
+          {signature.value.length} / {limit}
+        </Typography>
+      }
+      hint={
+        compact ? undefined : 'In gold leaf on dark necks, in black on maple. Leave it empty for a plain headstock.'
+      }
+      warningTypes={warningTypes}
+      compact={compact}
+    >
+      <Box
+        component="div"
+        sx={{
+          display: 'grid',
+          gap: 1,
+          paddingInline: 2,
+          paddingBlock: compact ? 1 : 1.5,
+          borderRadius: 1.5,
+          border: `1px solid ${signature.hasErrors ? NIGHTJAR.alert : NIGHTJAR.line}`,
+          bgcolor: NIGHTJAR.raised,
+          '&:focus-within': { borderColor: signature.hasErrors ? NIGHTJAR.alert : NIGHTJAR.amber },
+        }}
+      >
+        <InputBase
+          value={signature.value}
+          placeholder="Your name"
+          onChange={event => signature.update(event, event.target.value)}
+          onBlur={signature.resolve}
+          onKeyDown={event => {
+            if (event.key === 'Enter') {
+              signature.resolve()
+            }
+          }}
+          inputProps={{
+            'aria-labelledby': `nightjar-${instanceName}-label`,
+            'aria-invalid': signature.hasErrors,
+            'aria-describedby': `nightjar-${instanceName}-error`,
+            spellCheck: false,
+          }}
+          sx={{
+            fontFamily: NIGHTJAR.script,
+            fontSize: compact ? 30 : 38,
+            lineHeight: 1.2,
+            color: NIGHTJAR.amber,
+            '& input::placeholder': { color: NIGHTJAR.faint, opacity: 1 },
+          }}
+        />
+      </Box>
+      <Typography
+        id={`nightjar-${instanceName}-error`}
+        role="alert"
+        sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.alert, '&:empty': { display: 'none' } }}
+      >
+        {signature.hasErrors ? signature.hints : ''}
+      </Typography>
+    </FieldShell>
+  )
+}
+```
+
+### ./src/\_fields/StepFields.tsx
+
+```tsx
+import { Box } from '@mui/material'
+
+import { ChoiceField } from './ChoiceField.js'
+import { FinishField } from './FinishField.js'
+import { SignatureField } from './SignatureField.js'
+import { fieldOf } from './fields.js'
+import { useActiveChoices } from './use-active-choices.js'
+
+interface StepFieldsProps {
+  readonly compact: boolean
+}
+
+// The fields of the active step. The layout does not list which choice belongs to which step: it shows the choices
+// the spec leaves active, so moving a choice to another step is a change of its `$filter` in the spec.
+export const StepFields = ({ compact }: StepFieldsProps) => {
+  const choices = useActiveChoices()
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: compact ? 2.5 : 4 }}>
+      {choices.map(({ instanceName, kind }) => {
+        const { label, warningTypes } = fieldOf(instanceName)
+        const props = { instanceName, label, warningTypes, compact }
+
+        switch (kind) {
+          case 'selection':
+            return <ChoiceField key={instanceName} {...props} />
+          case 'swatch':
+            return <FinishField key={instanceName} {...props} />
+          case 'text':
+            return <SignatureField key={instanceName} {...props} />
+        }
+      })}
+    </Box>
+  )
+}
+```
+
+### ./src/\_fields/SummaryRows.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { fieldOf } from './fields.js'
+import { NIGHTJAR } from './tokens.js'
+import type { ActiveChoice } from './use-active-choices.js'
+import { useActiveChoices } from './use-active-choices.js'
+
+interface RowProps {
+  readonly label: string
+  readonly children: ReactNode
+}
+
+const Row = ({ label, children }: RowProps) => {
+  return (
+    <Box
+      component="div"
+      sx={{
+        display: 'flex',
+        alignItems: 'baseline',
+        justifyContent: 'space-between',
+        gap: 2,
+        paddingBlock: 1.1,
+        borderBlockEnd: `1px solid ${NIGHTJAR.line}`,
+      }}
+    >
+      <Typography component="dt" sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.muted }}>
+        {label}
+      </Typography>
+      <Typography
+        component="dd"
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 1,
+          margin: 0,
+          fontFamily: NIGHTJAR.font,
+          fontSize: 15,
+          fontWeight: 500,
+          textAlign: 'end',
+          color: NIGHTJAR.cream,
+        }}
+      >
+        {children}
+      </Typography>
+    </Box>
+  )
+}
+
+interface ChoiceRowProps {
+  readonly instanceName: string
+  readonly label: string
+}
+
+// Each row reads its choice with the same control hook the step uses: the option's title, the swatch's name and
+// colour, the text as written
+const SelectionRow = ({ instanceName, label }: ChoiceRowProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const guitarId = phx.frontend.useRootEntityId()
+  const { value, options } = phx.frontend.useAttributeSelection(guitarId, instanceName)
+  const selected = options.find(option => option.value === value)
+
+  return <Row label={label}>{selected ? resolve(selected.title) : '—'}</Row>
+}
+
+const SwatchRow = ({ instanceName, label }: ChoiceRowProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const guitarId = phx.frontend.useRootEntityId()
+  const { options } = phx.frontend.useSwatchSelection(guitarId, instanceName, [])
+  const selected = options.find(option => option.selected)
+
+  return (
+    <Row label={label}>
+      {selected && (
+        <Box
+          component="span"
+          aria-hidden
+          sx={{ inlineSize: 12, blockSize: 12, borderRadius: '50%', bgcolor: selected.color }}
+        />
+      )}
+      {selected ? resolve(selected.swatchName) : '—'}
+    </Row>
+  )
+}
+
+const TextRow = ({ instanceName, label }: ChoiceRowProps) => {
+  const guitarId = phx.frontend.useRootEntityId()
+  const { value } = phx.frontend.useTextValue(guitarId, instanceName)
+
+  return (
+    <Row label={label}>
+      {value.trim() === '' ? (
+        'None'
+      ) : (
+        <Box component="span" sx={{ fontFamily: NIGHTJAR.script, fontSize: 24, lineHeight: 1, color: NIGHTJAR.amber }}>
+          {value}
+        </Box>
+      )}
+    </Row>
+  )
+}
+
+const ChoiceRow = ({ instanceName, kind }: ActiveChoice) => {
+  const { label } = fieldOf(instanceName)
+
+  switch (kind) {
+    case 'selection':
+      return <SelectionRow instanceName={instanceName} label={label} />
+    case 'swatch':
+      return <SwatchRow instanceName={instanceName} label={label} />
+    case 'text':
+      return <TextRow instanceName={instanceName} label={label} />
+  }
+}
+
+// Every choice, read-only: the summary and the confirmation list the choices the spec leaves active in their states
+export const SummaryRows = () => {
+  const choices = useActiveChoices()
+
+  return (
+    <Box component="dl" sx={{ margin: 0 }}>
+      {choices.map(choice => (
+        <ChoiceRow key={choice.instanceName} {...choice} />
+      ))}
+    </Box>
+  )
+}
+```
+
+### ./src/\_fields/fields.ts
+
+```ts
+/** A choice of the spec as the layout presents it. */
+export interface Field {
+  /** The spec component's instance name */
+  readonly instanceName: string
+  /** The spec's `attributeSelection`, `materialSwatch` and `textValue` carry no label; the layout names the choice */
+  readonly label: string
+  /** The `warning` violations the field explains when they hold */
+  readonly warningTypes: readonly string[]
+}
+
+// Every choice the layout knows, in the order it lists them. Which ones a step shows is the spec's business: a step
+// lists the choices whose `$filter` leaves them active in its navigation state.
+export const FIELDS: readonly Field[] = [
+  { instanceName: 'bodyShape', label: 'Body shape', warningTypes: ['offsetHumbuckers'] },
+  { instanceName: 'finish', label: 'Finish', warningTypes: [] },
+  { instanceName: 'pickguard', label: 'Pickguard', warningTypes: [] },
+  { instanceName: 'neckWood', label: 'Neck wood', warningTypes: [] },
+  { instanceName: 'fretboard', label: 'Fretboard', warningTypes: [] },
+  { instanceName: 'pickups', label: 'Pickups', warningTypes: ['offsetHumbuckers'] },
+  { instanceName: 'hardware', label: 'Hardware', warningTypes: [] },
+  { instanceName: 'signature', label: 'Headstock signature', warningTypes: [] },
+]
+
+/** The layout's field for an instance name, or a plain one for a choice the layout does not know. */
+export const fieldOf = (instanceName: string): Field => {
+  return (
+    FIELDS.find(field => field.instanceName === instanceName) ?? { instanceName, label: instanceName, warningTypes: [] }
+  )
+}
+
+/** Orders instance names as the layout lists them; unknown ones go last. */
+export const byFieldOrder = (a: string, b: string): number => {
+  const rank = (instanceName: string) => {
+    const index = FIELDS.findIndex(field => field.instanceName === instanceName)
+
+    return index === -1 ? FIELDS.length : index
+  }
+
+  return rank(a) - rank(b)
+}
+```
+
+### ./src/\_fields/tokens.ts
+
+```ts
+import { keyframes } from '@mui/material'
+
+// Backstage at night: ink panels, amber light and cream type. Barlow is the brand's typeface, loaded by the page;
+// SignPainter only previews the headstock signature. The stacks fall back to system fonts where they are not loaded.
+export const NIGHTJAR = {
+  ink: '#0e0f12',
+  panel: 'rgba(14, 15, 18, 0.9)',
+  raised: '#181a20',
+  raisedHover: '#20232a',
+  line: 'rgba(237, 230, 214, 0.14)',
+  amber: '#f2a33a',
+  amberHover: '#ffb54f',
+  amberTint: 'rgba(242, 163, 58, 0.12)',
+  cream: '#ede6d6',
+  muted: 'rgba(237, 230, 214, 0.64)',
+  faint: 'rgba(237, 230, 214, 0.38)',
+  oxblood: '#7a1e2b',
+  alert: '#f07a84',
+  alertTint: 'rgba(122, 30, 43, 0.32)',
+  font: "'Barlow', 'Helvetica Neue', Arial, sans-serif",
+  script: "'SignPainter-HouseScript', 'Brush Script MT', cursive",
+} as const
+
+// Bold capitals with wide tracking, for headings and the stepper
+export const HEADING_SX = {
+  fontFamily: NIGHTJAR.font,
+  fontWeight: 700,
+  letterSpacing: '0.16em',
+  textTransform: 'uppercase',
+  color: NIGHTJAR.cream,
+} as const
+
+// Small capitals, for field labels and overlines
+export const LABEL_SX = {
+  fontFamily: NIGHTJAR.font,
+  fontSize: 12,
+  fontWeight: 500,
+  letterSpacing: '0.2em',
+  textTransform: 'uppercase',
+  color: NIGHTJAR.muted,
+} as const
+
+// A page or a step's content enters from the side it comes from, or a phone's sheet from below, fading in
+export const ENTER_FROM_END = keyframes`
+  from { opacity: 0; transform: translateX(48px); }
+  to { opacity: 1; transform: none; }
+`
+
+export const ENTER_FROM_START = keyframes`
+  from { opacity: 0; transform: translateX(-48px); }
+  to { opacity: 1; transform: none; }
+`
+
+export const ENTER_FROM_BELOW = keyframes`
+  from { opacity: 0; transform: translateY(56px); }
+  to { opacity: 1; transform: none; }
+`
+```
+
+### ./src/\_fields/use-active-choices.ts
+
+```ts
+import { useMemo } from 'react'
+
+import { attributeSelectionComponent, materialSwatchComponent, textValueComponent } from '@salsita-ai/sdk/domain'
+
+import { phx } from '../../.phoenix/phx.js'
+import { byFieldOrder } from './fields.js'
+
+export type ChoiceKind = 'selection' | 'swatch' | 'text'
+
+/** A choice of the spec that is active now. */
+export interface ActiveChoice {
+  readonly instanceName: string
+  readonly kind: ChoiceKind
+}
+
+// The guitar's choices whose spec component is active in the current navigation state, in the layout's order. A
+// `$filter` with `navigationStates` makes a component active only in those states, so on each step this is the step's
+// choices, and on the summary every choice. The control hooks throw for an inactive component; a field mounts only
+// for a choice listed here.
+export const useActiveChoices = (): readonly ActiveChoice[] => {
+  const guitarId = phx.frontend.useRootEntityId()
+  const selections = phx.frontend.useComponents({
+    componentTypes: [attributeSelectionComponent],
+    entityIds: [guitarId],
+  })
+  const swatches = phx.frontend.useComponents({ componentTypes: [materialSwatchComponent], entityIds: [guitarId] })
+  const texts = phx.frontend.useComponents({ componentTypes: [textValueComponent], entityIds: [guitarId] })
+
+  return useMemo(() => {
+    const choices = [
+      ...(selections ?? []).map(
+        ({ componentInstance }): ActiveChoice => ({ instanceName: componentInstance.instanceName, kind: 'selection' })
+      ),
+      ...(swatches ?? []).map(
+        ({ componentInstance }): ActiveChoice => ({ instanceName: componentInstance.instanceName, kind: 'swatch' })
+      ),
+      ...(texts ?? []).map(
+        ({ componentInstance }): ActiveChoice => ({ instanceName: componentInstance.instanceName, kind: 'text' })
+      ),
+    ]
+
+    return choices.sort((a, b) => byFieldOrder(a.instanceName, b.instanceName))
+  }, [selections, swatches, texts])
+}
+```
+
+### ./src/\_fields/use-warnings.ts
+
+```ts
+import { useMemo } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+
+export interface Warning {
+  readonly type: string
+  readonly text: string
+}
+
+// The warnings of the committed configuration, with their text resolved. A `warning` invariant keeps the change, so
+// its violation stays until the customer resolves it, and ordering waits for that. `useFinalizeViolations` lists them;
+// `useStateValidity` holds the same list, but on `phx.frontend` it is typed as the validity value instead of a hook,
+// so calling it does not type-check.
+export const useWarnings = (): readonly Warning[] => {
+  const { violations } = phx.frontend.useFinalizeViolations()
+  const resolve = phx.frontend.useResolveLocalizable()
+
+  return useMemo(() => {
+    return (violations ?? [])
+      .filter(({ violation }) => violation.severity === 'warning')
+      .map(({ violation }) => ({ type: violation.type, text: resolve(violation.message) ?? violation.type }))
+  }, [violations, resolve])
+}
+```
+
+### ./src/\_shared/DesktopPage.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { AnimationEvent } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { ENTER_FROM_END, HEADING_SX, NIGHTJAR } from '../_fields/index.js'
+import { OrderBar } from './OrderBar.js'
+import { OrderConfirmation } from './OrderConfirmation.js'
+import { StepHeader } from './StepHeader.js'
+import { StepPanel } from './StepPanel.js'
+import { SummaryPanel } from './SummaryPanel.js'
+import type { OrderForm } from './order-form.js'
+
+type Page = 'steps' | 'summary' | 'ordered'
+
+// The summary needs room for the contact form, so its panel is wider
+const PANEL_WIDTHS: Readonly<Record<Page, number>> = { steps: 420, summary: 520, ordered: 420 }
+
+const pageOf = (navigationState: string): Page => {
+  return navigationState === 'ordered' ? 'ordered' : navigationState === 'summary' ? 'summary' : 'steps'
+}
+
+// The brand's mark: a fret of amber over the name of the shop
+const Brand = () => {
+  return (
+    <Box component="div" sx={{ display: 'flex', alignItems: 'center', gap: 1.5, flex: 'none' }}>
+      <Box component="span" aria-hidden sx={{ inlineSize: 4, blockSize: 28, bgcolor: NIGHTJAR.amber }} />
+      <Box component="div" sx={{ display: 'grid' }}>
+        <Typography sx={{ ...HEADING_SX, fontSize: 16, letterSpacing: '0.32em', lineHeight: 1.1 }}>
+          Northfret
+        </Typography>
+        <Typography sx={{ ...HEADING_SX, fontSize: 10, letterSpacing: '0.36em', color: NIGHTJAR.muted }}>
+          Custom shop
+        </Typography>
+      </Box>
+    </Box>
+  )
+}
+
+interface DesktopPageProps {
+  readonly form: OrderForm
+}
+
+// The desktop wizard: the stepper on top, the guitar in the free area on the left, the panel of the step on the
+// right and the bar with the price at the bottom.
+//
+// The summary's panel is wider than a step's, so the steps, the summary and the confirmation are three pages, each
+// with its own safe area, and each slides in when it opens. The safe area slides with its page: the first
+// measurement, taken when the page mounts, sees it shifted, and no resize follows when the slide ends. `update()`
+// from `useSceneSafeArea` measures again once the slide has settled, so the camera frames the guitar in the place the
+// page leaves for it.
+export const DesktopPage = ({ form }: DesktopPageProps) => {
+  const { containerRef, safeAreaRef, update } = phx.frontend.useSceneSafeArea()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const page = pageOf(navigationState)
+
+  // The step's own content slides too; only the page's slide moves the safe area
+  const handleAnimationEnd = (event: AnimationEvent<HTMLDivElement>) => {
+    if (event.target === event.currentTarget) {
+      update()
+    }
+  }
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'grid',
+        gridTemplateRows: 'auto minmax(0, 1fr) auto',
+        fontFamily: NIGHTJAR.font,
+        color: NIGHTJAR.cream,
+        // The free area lies over the canvas; only the bars and the panel take the pointer
+        pointerEvents: 'none',
+      }}
+    >
+      <Box
+        component="header"
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 5,
+          minBlockSize: 72,
+          paddingInline: 4,
+          bgcolor: NIGHTJAR.ink,
+          borderBlockEnd: `1px solid ${NIGHTJAR.line}`,
+          pointerEvents: 'auto',
+        }}
+      >
+        <Brand />
+        <StepHeader compact={false} />
+      </Box>
+
+      <Box
+        component="div"
+        key={page}
+        onAnimationEnd={handleAnimationEnd}
+        sx={{
+          display: 'grid',
+          gridTemplateColumns: `minmax(0, 1fr) ${PANEL_WIDTHS[page]}px`,
+          minBlockSize: 0,
+          animation: `${ENTER_FROM_END} 480ms cubic-bezier(0.2, 0.7, 0.2, 1)`,
+          '@media (prefers-reduced-motion: reduce)': { animation: 'none' },
+        }}
+      >
+        <Box component="div" sx={{ position: 'relative', minInlineSize: 0 }}>
+          {/* The camera fits the guitar into this box, so its inset is the room around the guitar */}
+          <Box component="div" ref={safeAreaRef} sx={{ position: 'absolute', inset: '40px 72px 56px' }} />
+          <Typography
+            sx={{
+              position: 'absolute',
+              insetBlockEnd: 20,
+              insetInline: 0,
+              textAlign: 'center',
+              fontSize: 12,
+              letterSpacing: '0.14em',
+              textTransform: 'uppercase',
+              color: NIGHTJAR.faint,
+            }}
+          >
+            Drag to turn the guitar
+          </Typography>
+        </Box>
+        <Box
+          component="aside"
+          aria-label={page === 'steps' ? 'Step' : page === 'summary' ? 'Summary' : 'Order'}
+          sx={{
+            overflowY: 'auto',
+            paddingInline: 4,
+            paddingBlock: 4,
+            bgcolor: NIGHTJAR.panel,
+            borderInlineStart: `1px solid ${NIGHTJAR.line}`,
+            pointerEvents: 'auto',
+          }}
+        >
+          {page === 'steps' && <StepPanel compact={false} />}
+          {page === 'summary' && <SummaryPanel compact={false} form={form} />}
+          {page === 'ordered' && <OrderConfirmation compact={false} contact={form.contact} />}
+        </Box>
+      </Box>
+
+      <OrderBar compact={false} form={form} />
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/OrderBar.tsx
+
+```tsx
+import { Box, Button, CircularProgress, IconButton, Tooltip, Typography } from '@mui/material'
+
+import { FrontendAnalyticsFactory } from '@salsita-ai/sdk/configurator'
+import { detailComponent } from '@salsita-ai/sdk/domain'
+
+import { phx } from '../../.phoenix/phx.js'
+import { HEADING_SX, LABEL_SX, NIGHTJAR } from '../_fields/index.js'
+import type { OrderForm } from './order-form.js'
+
+const BACK_ICON = 'M15 5l-7 7 7 7'
+
+interface OrderBarProps {
+  /** The phone's bar: price and two buttons */
+  readonly compact: boolean
+  readonly form: OrderForm
+}
+
+// The bar at the bottom: the guitar's name and price, Back, and the step's main action. On a step that is Next, on
+// the step before the summary **Review order**, on the summary **Place order**, and after the order **Design another**.
+export const OrderBar = ({ compact, form }: OrderBarProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const price = phx.frontend.useRootEntityPrice()
+  const { steps, activeIndex, canGoPrevious, isLast, next, previous } = phx.frontend.useStepNavigation()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const navigate = phx.frontend.useNavigate()
+  const analytics = phx.frontend.useAnalytics()
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const { accessInfo } = phx.frontend.useAccessService()
+
+  const isOrdered = navigationState === 'ordered'
+  const isPending = primary?.isPending ?? false
+  const nextStep = steps[activeIndex + 1]
+  const firstStep = steps[0]
+
+  // The step before the last one leads to the summary. Like the built-in summary button, it records
+  // `SummaryButtonClicked`, which `next()` would not: it records the next-step button's event.
+  const enterSummary = () => {
+    if (nextStep === undefined) {
+      return
+    }
+
+    analytics.push(FrontendAnalyticsFactory.SummaryButtonClicked())
+    navigate(nextStep.state)
+  }
+
+  // A conflict or a missing detail blocks the order; the button stays clickable and shows what is missing instead
+  const placeOrder = () => {
+    if (primary === null) {
+      return
+    }
+
+    if (primary.disabled || !form.isComplete) {
+      form.revealErrors()
+      return
+    }
+
+    void primary.run()
+  }
+
+  const designAnother = () => {
+    if (firstStep) {
+      navigate(firstStep.state)
+    }
+  }
+
+  const action = isOrdered
+    ? { label: 'Design another', onClick: designAnother, blocked: false }
+    : isLast
+      ? { label: primary?.label ?? 'Place order', onClick: placeOrder, blocked: primary?.disabled ?? true }
+      : nextStep?.index === steps.length - 1
+        ? { label: 'Review order', onClick: enterSummary, blocked: false }
+        : { label: compact ? 'Next' : `Next: ${nextStep?.label ?? ''}`, onClick: next, blocked: false }
+  const showAction = !(isLast && !isOrdered && (primary === null || accessInfo.viewMode))
+  const blockedNote = isLast && !isOrdered && primary?.disabled && hints ? 'Settle the choices above first' : null
+
+  return (
+    <Box
+      component="footer"
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: compact ? 1.5 : 3,
+        minBlockSize: compact ? 72 : 84,
+        paddingInline: compact ? 2 : 4,
+        paddingBlock: 1.5,
+        bgcolor: NIGHTJAR.ink,
+        borderBlockStart: `1px solid ${NIGHTJAR.line}`,
+        pointerEvents: 'auto',
+      }}
+    >
+      {!compact && (
+        <Box component="div" sx={{ display: 'grid', gap: 0.25, minInlineSize: 0 }}>
+          <Typography sx={{ ...HEADING_SX, fontSize: 18, letterSpacing: '0.24em' }}>
+            {detail ? resolve(detail.state.title) : 'Nightjar'}
+          </Typography>
+          <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 13, color: NIGHTJAR.muted, whiteSpace: 'nowrap' }}>
+            {detail ? resolve(detail.state.subtitle) : ''}
+          </Typography>
+        </Box>
+      )}
+
+      <Box component="div" sx={{ display: 'grid', marginInlineStart: compact ? 0 : 'auto', minInlineSize: 0 }}>
+        <Typography sx={{ ...LABEL_SX, fontSize: 11 }}>{isOrdered ? 'Ordered' : 'Your price'}</Typography>
+        <Typography
+          aria-live="polite"
+          sx={{
+            fontFamily: NIGHTJAR.font,
+            fontSize: compact ? 22 : 28,
+            fontWeight: 700,
+            lineHeight: 1.1,
+            fontVariantNumeric: 'tabular-nums',
+            color: NIGHTJAR.cream,
+          }}
+        >
+          {price}
+        </Typography>
+      </Box>
+
+      <Box
+        component="div"
+        sx={{ display: 'flex', alignItems: 'center', gap: 1.5, marginInlineStart: compact ? 'auto' : 2 }}
+      >
+        {blockedNote && !compact && (
+          <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.amber }}>{blockedNote}</Typography>
+        )}
+        {canGoPrevious && !isOrdered && (
+          <Tooltip title="Back">
+            <span>
+              <IconButton
+                aria-label="Back"
+                onClick={previous}
+                disabled={isPending}
+                sx={{
+                  inlineSize: 48,
+                  blockSize: 48,
+                  border: `1px solid ${NIGHTJAR.line}`,
+                  color: NIGHTJAR.cream,
+                  '&:hover': { bgcolor: NIGHTJAR.raisedHover },
+                  '&.Mui-disabled': { color: NIGHTJAR.faint },
+                }}
+              >
+                <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+                  <path d={BACK_ICON} strokeLinecap="round" strokeLinejoin="round" />
+                </svg>
+              </IconButton>
+            </span>
+          </Tooltip>
+        )}
+        {showAction && (
+          <Button
+            onClick={action.onClick}
+            disabled={isPending}
+            aria-disabled={action.blocked || undefined}
+            title={isLast && !isOrdered ? (hints ?? primary?.title) : undefined}
+            startIcon={isPending ? <CircularProgress size={16} sx={{ color: NIGHTJAR.ink }} /> : undefined}
+            sx={{
+              ...HEADING_SX,
+              minBlockSize: 48,
+              paddingInline: compact ? 2.5 : 3.5,
+              borderRadius: 1,
+              fontSize: 14,
+              whiteSpace: 'nowrap',
+              color: NIGHTJAR.ink,
+              bgcolor: action.blocked ? NIGHTJAR.muted : NIGHTJAR.amber,
+              '&:hover': { bgcolor: action.blocked ? NIGHTJAR.muted : NIGHTJAR.amberHover },
+              '&.Mui-disabled': { color: NIGHTJAR.ink, bgcolor: NIGHTJAR.amber, opacity: 0.75 },
+              '&.Mui-focusVisible': { outline: `2px solid ${NIGHTJAR.cream}`, outlineOffset: 2 },
+            }}
+          >
+            {isPending ? 'Placing order…' : action.label}
+          </Button>
+        )}
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/OrderConfirmation.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+import { HEADING_SX, LABEL_SX, NIGHTJAR, SummaryRows } from '../_fields/index.js'
+import type { Contact } from './order-form.js'
+
+const CHECK_ICON = 'M5 12.5 10 17.5 19 7'
+
+interface OrderConfirmationProps {
+  readonly compact: boolean
+  readonly contact: Contact
+}
+
+// The `ordered` navigation state, which the order handler enters once the order is accepted. The order number is
+// made from the configuration's id, so it stays the same when the confirmation is shown again.
+export const OrderConfirmation = ({ compact, contact }: OrderConfirmationProps) => {
+  const configurationId = phx.frontend.useConfigurationId()
+  const price = phx.frontend.useRootEntityPrice()
+  const orderNumber = `NJ-${String(configurationId)
+    .replace(/[^a-z0-9]/gi, '')
+    .slice(-6)
+    .toUpperCase()}`
+  const name = contact.name.trim()
+
+  return (
+    <Box component="div" role="status" sx={{ display: 'grid', gap: compact ? 2.5 : 3 }}>
+      <Box component="header" sx={{ display: 'grid', gap: 1.5, justifyItems: 'start' }}>
+        <Box
+          component="svg"
+          viewBox="0 0 24 24"
+          aria-hidden
+          sx={{ inlineSize: 44, blockSize: 44, padding: 1.25, borderRadius: '50%', bgcolor: NIGHTJAR.amber }}
+        >
+          <path d={CHECK_ICON} fill="none" stroke={NIGHTJAR.ink} strokeWidth={2.6} strokeLinecap="round" />
+        </Box>
+        <Typography sx={LABEL_SX}>Order {orderNumber}</Typography>
+        <Typography component="h2" sx={{ ...HEADING_SX, fontSize: compact ? 24 : 30, lineHeight: 1.05 }}>
+          {name ? `Thank you, ${name}` : 'Thank you'}
+        </Typography>
+        <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 15, lineHeight: 1.5, color: NIGHTJAR.muted }}>
+          Your Nightjar goes into the build queue at {price}. We will write to {contact.email.trim() || 'you'} when the
+          shop confirms it; a build takes about eight weeks.
+        </Typography>
+      </Box>
+      <Box component="section" sx={{ display: 'grid', gap: 1.5 }}>
+        <Typography component="h3" sx={LABEL_SX}>
+          What we are building
+        </Typography>
+        <SummaryRows />
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/PhonePage.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { AnimationEvent } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { ENTER_FROM_BELOW, HEADING_SX, NIGHTJAR } from '../_fields/index.js'
+import { OrderBar } from './OrderBar.js'
+import { OrderConfirmation } from './OrderConfirmation.js'
+import { StepHeader } from './StepHeader.js'
+import { StepPanel } from './StepPanel.js'
+import { SummaryPanel } from './SummaryPanel.js'
+import type { OrderForm } from './order-form.js'
+
+type Page = 'steps' | 'summary' | 'ordered'
+
+// How much of the screen below the header the guitar keeps: the summary's form needs more of it
+const SCENE_SHARES: Readonly<Record<Page, string>> = { steps: '46%', summary: '30%', ordered: '40%' }
+
+const pageOf = (navigationState: string): Page => {
+  return navigationState === 'ordered' ? 'ordered' : navigationState === 'summary' ? 'summary' : 'steps'
+}
+
+interface PhonePageProps {
+  readonly form: OrderForm
+}
+
+// The phone wizard: a compact progress line, the guitar at the top, the step's choices in a sheet below it and the
+// bar fixed at the bottom. Like the desktop pages, each page rises in with its own safe area and measures it again
+// with `update()` once the slide has settled.
+export const PhonePage = ({ form }: PhonePageProps) => {
+  const { containerRef, safeAreaRef, update } = phx.frontend.useSceneSafeArea()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const page = pageOf(navigationState)
+
+  const handleAnimationEnd = (event: AnimationEvent<HTMLDivElement>) => {
+    if (event.target === event.currentTarget) {
+      update()
+    }
+  }
+
+  return (
+    <Box
+      component="div"
+      ref={containerRef}
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        fontFamily: NIGHTJAR.font,
+        color: NIGHTJAR.cream,
+        pointerEvents: 'none',
+      }}
+    >
+      <Box
+        component="header"
+        sx={{
+          display: 'grid',
+          gap: 1.25,
+          paddingInline: 2,
+          paddingBlock: 1.5,
+          bgcolor: NIGHTJAR.ink,
+          borderBlockEnd: `1px solid ${NIGHTJAR.line}`,
+          pointerEvents: 'auto',
+        }}
+      >
+        <Box component="div" sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+          <Box component="span" aria-hidden sx={{ inlineSize: 3, blockSize: 16, bgcolor: NIGHTJAR.amber }} />
+          <Typography sx={{ ...HEADING_SX, fontSize: 13, letterSpacing: '0.32em' }}>Northfret</Typography>
+        </Box>
+        <StepHeader compact />
+      </Box>
+
+      <Box
+        component="div"
+        key={page}
+        onAnimationEnd={handleAnimationEnd}
+        sx={{
+          display: 'flex',
+          flexDirection: 'column',
+          flex: '1 1 0',
+          minBlockSize: 0,
+          animation: `${ENTER_FROM_BELOW} 460ms cubic-bezier(0.2, 0.7, 0.2, 1)`,
+          '@media (prefers-reduced-motion: reduce)': { animation: 'none' },
+        }}
+      >
+        <Box component="div" sx={{ position: 'relative', flex: `0 0 ${SCENE_SHARES[page]}`, minBlockSize: 0 }}>
+          <Box component="div" ref={safeAreaRef} sx={{ position: 'absolute', inset: '12px 16px 8px' }} />
+        </Box>
+        <Box
+          component="main"
+          sx={{
+            flex: '1 1 0',
+            minBlockSize: 0,
+            overflowY: 'auto',
+            overscrollBehavior: 'contain',
+            paddingInline: 2,
+            paddingBlock: 2.5,
+            bgcolor: NIGHTJAR.panel,
+            borderBlockStart: `1px solid ${NIGHTJAR.line}`,
+            borderStartStartRadius: 16,
+            borderStartEndRadius: 16,
+            pointerEvents: 'auto',
+          }}
+        >
+          {page === 'steps' && <StepPanel compact />}
+          {page === 'summary' && <SummaryPanel compact form={form} />}
+          {page === 'ordered' && <OrderConfirmation compact contact={form.contact} />}
+        </Box>
+      </Box>
+
+      <OrderBar compact form={form} />
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/StepHeader.tsx
+
+```tsx
+import { Box, ButtonBase, Typography } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+import { HEADING_SX, NIGHTJAR, useWarnings } from '../_fields/index.js'
+import { STEP_WARNINGS } from './step-warnings.js'
+import { useReachedStep } from './use-reached-step.js'
+
+const CHECK_ICON = 'M5 12.5 10 17.5 19 7'
+
+interface StepHeaderProps {
+  /** One line with a progress bar, for a phone; the full stepper otherwise */
+  readonly compact: boolean
+}
+
+// The spec's `navigationSteps` as a stepper. Labels and order come from the spec; `useStepNavigation` gives each step
+// its status, and `goTo` enters a step and records the stepper's analytics event. The customer can go back to any step
+// they have reached, never ahead of it, and nowhere while the order is being placed or after it was placed.
+export const StepHeader = ({ compact }: StepHeaderProps) => {
+  const { steps, activeIndex, activeStep, goTo } = phx.frontend.useStepNavigation()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const { primary } = phx.frontend.useFinalizeActions()
+  const warnings = useWarnings()
+  const reached = useReachedStep(activeIndex)
+  const isLocked = navigationState === 'ordered' || (primary?.isPending ?? false)
+
+  const hasWarning = (state: string) => {
+    return warnings.some(warning => STEP_WARNINGS[state]?.includes(warning.type))
+  }
+
+  if (compact) {
+    const progress = steps.length === 0 ? 0 : (activeIndex + 1) / steps.length
+
+    return (
+      <Box component="nav" aria-label="Build steps" sx={{ display: 'grid', gap: 1 }}>
+        <Typography
+          sx={{ ...HEADING_SX, fontSize: 13, letterSpacing: '0.14em', display: 'flex', alignItems: 'center', gap: 1 }}
+        >
+          <Box component="span" sx={{ color: NIGHTJAR.amber, fontVariantNumeric: 'tabular-nums' }}>
+            {activeIndex + 1} / {steps.length}
+          </Box>
+          <Box component="span" aria-hidden sx={{ color: NIGHTJAR.faint }}>
+            ·
+          </Box>
+          <Box component="span" aria-current="step">
+            {activeStep?.label}
+          </Box>
+        </Typography>
+        <Box
+          component="div"
+          role="progressbar"
+          aria-label="Build progress"
+          aria-valuemin={0}
+          aria-valuemax={steps.length}
+          aria-valuenow={activeIndex + 1}
+          sx={{ blockSize: 2, borderRadius: 1, bgcolor: NIGHTJAR.line, overflow: 'hidden' }}
+        >
+          <Box
+            component="div"
+            sx={{
+              blockSize: '100%',
+              inlineSize: `${progress * 100}%`,
+              bgcolor: NIGHTJAR.amber,
+              transition: 'inline-size 400ms ease-out',
+            }}
+          />
+        </Box>
+      </Box>
+    )
+  }
+
+  return (
+    <Box component="nav" aria-label="Build steps">
+      <Box
+        component="ol"
+        sx={{ display: 'flex', alignItems: 'center', gap: 1, margin: 0, padding: 0, listStyle: 'none' }}
+      >
+        {steps.map(step => {
+          const isActive = step.status === 'active'
+          const isComplete = step.status === 'complete'
+          const canEnter = !isLocked && !isActive && step.index <= reached
+          const warn = hasWarning(step.state)
+
+          return (
+            <Box component="li" key={step.state} sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+              {step.index > 0 && (
+                <Box
+                  component="span"
+                  aria-hidden
+                  sx={{
+                    inlineSize: 28,
+                    blockSize: '1px',
+                    bgcolor: step.index <= reached ? NIGHTJAR.muted : NIGHTJAR.line,
+                  }}
+                />
+              )}
+              <ButtonBase
+                aria-label={warn ? `${step.label}, needs attention` : step.label}
+                aria-current={isActive ? 'step' : undefined}
+                disabled={!canEnter}
+                onClick={() => goTo(step.index)}
+                sx={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 1,
+                  paddingInline: 1,
+                  paddingBlock: 0.75,
+                  borderRadius: 1,
+                  color: isActive ? NIGHTJAR.cream : step.index <= reached ? NIGHTJAR.muted : NIGHTJAR.faint,
+                  '&:hover': { color: NIGHTJAR.cream },
+                  '&.Mui-focusVisible': { outline: `2px solid ${NIGHTJAR.amber}` },
+                }}
+              >
+                <Box
+                  component="span"
+                  sx={{
+                    display: 'grid',
+                    placeItems: 'center',
+                    inlineSize: 24,
+                    blockSize: 24,
+                    borderRadius: '50%',
+                    fontFamily: NIGHTJAR.font,
+                    fontSize: 12,
+                    fontWeight: 700,
+                    color: isActive ? NIGHTJAR.ink : 'inherit',
+                    bgcolor: isActive ? NIGHTJAR.amber : 'transparent',
+                    border: isActive ? 'none' : `1px solid ${isComplete ? NIGHTJAR.muted : NIGHTJAR.line}`,
+                  }}
+                >
+                  {isComplete ? (
+                    <Box component="svg" viewBox="0 0 24 24" aria-hidden sx={{ inlineSize: 14, blockSize: 14 }}>
+                      <path d={CHECK_ICON} fill="none" stroke="currentColor" strokeWidth={2.6} strokeLinecap="round" />
+                    </Box>
+                  ) : (
+                    step.index + 1
+                  )}
+                </Box>
+                {/* In a narrow window only the active step keeps its label; the others keep their number */}
+                <Typography
+                  component="span"
+                  sx={{
+                    ...HEADING_SX,
+                    display: { xs: isActive ? 'inline' : 'none', lg: 'inline' },
+                    fontSize: 13,
+                    color: 'inherit',
+                  }}
+                >
+                  {step.label}
+                </Typography>
+                {warn && (
+                  <Box
+                    component="span"
+                    aria-hidden
+                    sx={{ inlineSize: 7, blockSize: 7, borderRadius: '50%', bgcolor: NIGHTJAR.amber }}
+                  />
+                )}
+              </ButtonBase>
+            </Box>
+          )
+        })}
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/StepPanel.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import { useState } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { ENTER_FROM_END, ENTER_FROM_START, HEADING_SX, LABEL_SX, NIGHTJAR, StepFields } from '../_fields/index.js'
+
+// A line under each step's title; the layout's copy, keyed by the step's navigation state
+const STEP_INTROS: Readonly<Record<string, string>> = {
+  body: 'The shape sets the feel, the finish and the pickguard the look.',
+  neck: 'What your hand holds: the neck and the board under the strings.',
+  electronics: 'The sound: two pickups, and the metal parts around them.',
+  details: 'Sign the headstock. The shop paints it on by hand.',
+}
+
+/** 1 when the active step moved forward, -1 when it moved back; the step's content slides in from that side. */
+const useStepDirection = (activeIndex: number): 1 | -1 => {
+  const [shown, setShown] = useState<{ readonly index: number; readonly direction: 1 | -1 }>({
+    index: activeIndex,
+    direction: 1,
+  })
+
+  if (activeIndex !== shown.index) {
+    setShown({ index: activeIndex, direction: activeIndex > shown.index ? 1 : -1 })
+  }
+
+  return shown.direction
+}
+
+interface StepPanelProps {
+  readonly compact: boolean
+}
+
+// The active step: its number, its label from the spec, and its fields. The content is keyed by the step, so each
+// step slides in from the side the customer moves towards.
+export const StepPanel = ({ compact }: StepPanelProps) => {
+  const { steps, activeStep, activeIndex } = phx.frontend.useStepNavigation()
+  const direction = useStepDirection(activeIndex)
+
+  if (activeStep === null) {
+    return null
+  }
+
+  return (
+    <Box
+      component="div"
+      key={activeStep.state}
+      sx={{
+        display: 'grid',
+        gap: compact ? 2.5 : 3.5,
+        animation: `${direction === 1 ? ENTER_FROM_END : ENTER_FROM_START} 420ms cubic-bezier(0.2, 0.7, 0.2, 1)`,
+        '@media (prefers-reduced-motion: reduce)': { animation: 'none' },
+      }}
+    >
+      {!compact && (
+        <Box component="header" sx={{ display: 'grid', gap: 1 }}>
+          <Typography sx={LABEL_SX}>
+            Step {activeIndex + 1} of {steps.length}
+          </Typography>
+          <Typography component="h2" sx={{ ...HEADING_SX, fontSize: 30, lineHeight: 1.05 }}>
+            {activeStep.label}
+          </Typography>
+          {STEP_INTROS[activeStep.state] && (
+            <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 15, lineHeight: 1.45, color: NIGHTJAR.muted }}>
+              {STEP_INTROS[activeStep.state]}
+            </Typography>
+          )}
+        </Box>
+      )}
+      <StepFields compact={compact} />
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/SummaryPanel.tsx
+
+```tsx
+import { Box, Button, InputBase, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+import { useEffect, useRef } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { HEADING_SX, LABEL_SX, NIGHTJAR, SummaryRows, useWarnings } from '../_fields/index.js'
+import type { OrderForm } from './order-form.js'
+import { STEP_WARNINGS } from './step-warnings.js'
+
+const SECTION_SX = { display: 'grid', gap: 1.5 } as const
+
+interface ContactInputProps {
+  readonly id: string
+  readonly label: string
+  readonly value: string
+  readonly onChange: (value: string) => void
+  readonly error: string | undefined
+  readonly type: 'text' | 'email'
+  readonly autoComplete: string
+  readonly disabled: boolean
+}
+
+const ContactInput = ({ id, label, value, onChange, error, type, autoComplete, disabled }: ContactInputProps) => {
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 0.75 }}>
+      <Typography
+        component="label"
+        htmlFor={id}
+        sx={{ fontFamily: NIGHTJAR.font, fontSize: 14, color: NIGHTJAR.muted }}
+      >
+        {label}
+      </Typography>
+      <InputBase
+        id={id}
+        type={type}
+        value={value}
+        disabled={disabled}
+        autoComplete={autoComplete}
+        onChange={event => onChange(event.target.value)}
+        inputProps={{ 'aria-invalid': error !== undefined, 'aria-describedby': error ? `${id}-error` : undefined }}
+        sx={{
+          paddingInline: 1.5,
+          paddingBlock: 0.75,
+          borderRadius: 1.5,
+          border: `1px solid ${error ? NIGHTJAR.alert : NIGHTJAR.line}`,
+          bgcolor: NIGHTJAR.raised,
+          fontFamily: NIGHTJAR.font,
+          fontSize: 16,
+          color: NIGHTJAR.cream,
+          '&.Mui-focused': { borderColor: error ? NIGHTJAR.alert : NIGHTJAR.amber },
+        }}
+      />
+      {error && (
+        <Typography id={`${id}-error`} sx={{ fontFamily: NIGHTJAR.font, fontSize: 13, color: NIGHTJAR.alert }}>
+          {error}
+        </Typography>
+      )}
+    </Box>
+  )
+}
+
+const Card = ({ children, tone }: { readonly children: ReactNode; readonly tone: 'plain' | 'warning' | 'alert' }) => {
+  const borders = { plain: NIGHTJAR.line, warning: NIGHTJAR.amber, alert: NIGHTJAR.alert }
+  const backgrounds = { plain: NIGHTJAR.raised, warning: NIGHTJAR.amberTint, alert: NIGHTJAR.alertTint }
+
+  return (
+    <Box
+      component="section"
+      sx={{
+        display: 'grid',
+        gap: 1.5,
+        padding: 2,
+        borderRadius: 2,
+        border: `1px solid ${borders[tone]}`,
+        bgcolor: backgrounds[tone],
+      }}
+    >
+      {children}
+    </Box>
+  )
+}
+
+// The warnings left between choices, each with the way to the step that resolves it. Ordering waits until none is
+// left: `useFinalizeActions` reports the action `disabled` with the same texts as `hints`.
+const Conflicts = () => {
+  const warnings = useWarnings()
+  const { steps, goTo } = phx.frontend.useStepNavigation()
+  const conflicts = warnings.flatMap(warning => {
+    const step = steps.find(candidate => STEP_WARNINGS[candidate.state]?.includes(warning.type))
+
+    return step ? [{ ...warning, step }] : []
+  })
+
+  if (conflicts.length === 0) {
+    return null
+  }
+
+  return (
+    <Card tone="warning">
+      <Typography component="h3" sx={{ ...LABEL_SX, color: NIGHTJAR.amber }}>
+        {conflicts.length === 1 ? 'One choice to settle before ordering' : `${conflicts.length} choices to settle`}
+      </Typography>
+      {conflicts.map(conflict => (
+        <Box component="div" key={conflict.type} sx={{ display: 'grid', gap: 1, justifyItems: 'start' }}>
+          <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 15, lineHeight: 1.45, color: NIGHTJAR.cream }}>
+            {conflict.text}
+          </Typography>
+          <Button
+            onClick={() => goTo(conflict.step.index)}
+            sx={{
+              ...LABEL_SX,
+              minBlockSize: 36,
+              paddingInline: 1.5,
+              color: NIGHTJAR.ink,
+              bgcolor: NIGHTJAR.amber,
+              '&:hover': { bgcolor: NIGHTJAR.amberHover },
+            }}
+          >
+            Go to {conflict.step.label}
+          </Button>
+        </Box>
+      ))}
+    </Card>
+  )
+}
+
+interface SummaryPanelProps {
+  readonly compact: boolean
+  readonly form: OrderForm
+}
+
+// The last step: every choice as the spec's control hooks read it, the conflicts left, the contact form and the
+// order's error. The summary only reviews; a choice is changed on its step, which the stepper and the conflicts link
+// to. **Place order** is in the bar at the bottom.
+export const SummaryPanel = ({ compact, form }: SummaryPanelProps) => {
+  const { primary } = phx.frontend.useFinalizeActions()
+  const { contact, setContact, errors, showErrors, blockedAttempts, isComplete } = form
+  const isPending = primary?.isPending ?? false
+  const topRef = useRef<HTMLDivElement>(null)
+  const detailsRef = useRef<HTMLElement>(null)
+  // The attempts already handled; the summary opens again after a blocked attempt without scrolling
+  const scrolledFor = useRef(blockedAttempts)
+
+  // After each blocked attempt to order, bring what blocks it into view: the missing details, or the conflicts on top.
+  // Typing into the form changes `isComplete` but is no new attempt, so it does not scroll.
+  useEffect(() => {
+    if (blockedAttempts === scrolledFor.current) {
+      return
+    }
+
+    scrolledFor.current = blockedAttempts
+    const target = isComplete ? topRef.current : detailsRef.current
+    target?.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+  }, [blockedAttempts, isComplete])
+
+  return (
+    <Box component="div" ref={topRef} sx={{ display: 'grid', gap: compact ? 2.5 : 3, scrollMarginBlockStart: 32 }}>
+      {!compact && (
+        <Box component="header" sx={{ display: 'grid', gap: 1 }}>
+          <Typography sx={LABEL_SX}>Last step</Typography>
+          <Typography component="h2" sx={{ ...HEADING_SX, fontSize: 30, lineHeight: 1.05 }}>
+            Your Nightjar
+          </Typography>
+          <Typography sx={{ fontFamily: NIGHTJAR.font, fontSize: 15, lineHeight: 1.45, color: NIGHTJAR.muted }}>
+            Check the build, tell us who it is for, and place the order. Nothing is charged until the shop confirms.
+          </Typography>
+        </Box>
+      )}
+
+      {primary?.error && (
+        <Card tone="alert">
+          <Typography component="h3" sx={{ ...LABEL_SX, color: NIGHTJAR.alert }}>
+            The order did not go through
+          </Typography>
+          <Typography
+            role="alert"
+            sx={{ fontFamily: NIGHTJAR.font, fontSize: 15, lineHeight: 1.45, color: NIGHTJAR.cream }}
+          >
+            {primary.error.message}
+          </Typography>
+        </Card>
+      )}
+
+      <Conflicts />
+
+      <Box component="section" sx={SECTION_SX}>
+        <Typography component="h3" sx={LABEL_SX}>
+          The build
+        </Typography>
+        <SummaryRows />
+      </Box>
+
+      <Box component="section" ref={detailsRef} sx={{ ...SECTION_SX, scrollMarginBlockEnd: 32 }}>
+        <Typography component="h3" sx={LABEL_SX}>
+          Your details
+        </Typography>
+        <Box component="div" sx={{ display: 'grid', gridTemplateColumns: compact ? '1fr' : '1fr 1fr', gap: 1.5 }}>
+          <ContactInput
+            id="nightjar-name"
+            label="Name"
+            type="text"
+            autoComplete="name"
+            value={contact.name}
+            onChange={name => setContact({ ...contact, name })}
+            error={showErrors ? errors.name : undefined}
+            disabled={isPending}
+          />
+          <ContactInput
+            id="nightjar-email"
+            label="E-mail"
+            type="email"
+            autoComplete="email"
+            value={contact.email}
+            onChange={email => setContact({ ...contact, email })}
+            error={showErrors ? errors.email : undefined}
+            disabled={isPending}
+          />
+        </Box>
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/order-form.ts
+
+```ts
+import { useState } from 'react'
+
+/** The customer's name and e-mail, which the summary asks for. */
+export interface Contact {
+  readonly name: string
+  readonly email: string
+}
+
+/** What is missing from the contact details, per field. */
+export interface ContactErrors {
+  readonly name?: string
+  readonly email?: string
+}
+
+/**
+ * The summary's contact form. It is the layout's own state, not the configuration's: the details are needed only to
+ * place the order, and the confirmation thanks the customer by name.
+ */
+export interface OrderForm {
+  readonly contact: Contact
+  readonly setContact: (contact: Contact) => void
+  readonly errors: ContactErrors
+  readonly isComplete: boolean
+  /** Whether the form shows what is missing: from the first attempt to order on */
+  readonly showErrors: boolean
+  /** How many attempts to order were blocked; the summary scrolls to what blocks the order after each */
+  readonly blockedAttempts: number
+  readonly revealErrors: () => void
+}
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/
+
+export const useOrderForm = (): OrderForm => {
+  const [contact, setContact] = useState<Contact>({ name: '', email: '' })
+  const [blockedAttempts, setBlockedAttempts] = useState(0)
+  const errors: ContactErrors = {
+    ...(contact.name.trim() === '' && { name: 'Enter the name the order is for.' }),
+    ...(!EMAIL.test(contact.email.trim()) && { email: 'Enter an e-mail address for the build updates.' }),
+  }
+
+  return {
+    contact,
+    setContact,
+    errors,
+    isComplete: errors.name === undefined && errors.email === undefined,
+    showErrors: blockedAttempts > 0,
+    blockedAttempts,
+    revealErrors: () => setBlockedAttempts(attempts => attempts + 1),
+  }
+}
+```
+
+### ./src/\_shared/step-warnings.ts
+
+```ts
+// Which step resolves each warning: the stepper marks the step while the warning holds, and the summary sends the
+// customer there. A warning can involve several steps; this names the one the layout sends the customer to.
+export const STEP_WARNINGS: Readonly<Record<string, readonly string[]>> = {
+  electronics: ['offsetHumbuckers'],
+}
+```
+
+### ./src/\_shared/use-reached-step.ts
+
+```ts
+import { useState } from 'react'
+
+// The furthest step the customer has reached. The stepper offers every step up to it, so after changing an earlier
+// step the customer returns to where they were without stepping through the ones between.
+export const useReachedStep = (activeIndex: number): number => {
+  const [reached, setReached] = useState(activeIndex)
+
+  if (activeIndex > reached) {
+    setReached(activeIndex)
+  }
+
+  return Math.max(reached, activeIndex)
+}
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+import { NIGHTJAR } from '../_fields/index.js'
+import { DesktopPage } from '../_shared/DesktopPage.js'
+import { PhonePage } from '../_shared/PhonePage.js'
+import { useOrderForm } from '../_shared/order-form.js'
+
+// A wizard over the scene. The canvas stays mounted the whole time; the desktop or the phone page lies over it. The
+// contact form's state lives here, so it survives the switch between the two and the move to the confirmation.
+const ConfiguratorLayout = () => {
+  // `null` until the container has been measured; only the scene shows until then
+  const viewports = phx.frontend.useActiveViewports()
+  const form = useOrderForm()
+  const isDesktop = viewports?.includes('desktop') ?? false
+
+  return (
+    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: NIGHTJAR.ink }}>
+      <LayoutSlots.SharedCanvas />
+      {viewports !== null && (isDesktop ? <DesktopPage form={form} /> : <PhonePage form={form} />)}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/elements/NightjarStage.tsx
+
+```tsx
+import { Environment, Lightformer } from '@react-three/drei'
+import { useMemo } from 'react'
+import { CanvasTexture, SRGBColorSpace } from 'three'
+
+import { phx } from '../../.phoenix/phx.js'
+import { NIGHTJAR } from '../_fields/index.js'
+
+/** A warm pool of light that fades into the dark, drawn once on a canvas. */
+const createGlow = (): CanvasTexture => {
+  const size = 512
+  const canvas = document.createElement('canvas')
+  canvas.width = size
+  canvas.height = size
+  const context = canvas.getContext('2d')
+
+  if (context) {
+    const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2)
+    gradient.addColorStop(0, 'rgba(242, 163, 58, 0.42)')
+    gradient.addColorStop(0.22, 'rgba(214, 112, 46, 0.2)')
+    gradient.addColorStop(0.5, 'rgba(122, 30, 43, 0.07)')
+    gradient.addColorStop(0.75, 'rgba(14, 15, 18, 0)')
+    context.fillStyle = gradient
+    context.fillRect(0, 0, size, size)
+  }
+
+  const texture = new CanvasTexture(canvas)
+  texture.colorSpace = SRGBColorSpace
+  return texture
+}
+
+// The stage named by the spec's `canvasCustomEnvironment`: a dark room with a warm glow on the wall behind the guitar,
+// a warm key light and a cool rim. The light panels exist only in the reflections, where they draw the long highlights
+// on the clearcoat and the hardware. The scene is in millimetres.
+export default phx.frontend.createCustomPhoenixLayoutElement('NightjarStage', () => {
+  const glow = useMemo(createGlow, [])
+
+  return (
+    <>
+      <color attach="background" args={[NIGHTJAR.ink]} />
+      <ambientLight intensity={0.4} />
+      <directionalLight position={[-900, 1400, 1600]} intensity={2.4} color="#ffe6c7" />
+      <directionalLight position={[1400, 700, -900]} intensity={1.2} color="#a9c1ff" />
+
+      {/* The glow on the wall, behind the guitar and out of the camera's fit */}
+      <mesh position={[-250, 300, -900]}>
+        <planeGeometry args={[3600, 3600]} />
+        <meshBasicMaterial map={glow} transparent depthWrite={false} toneMapped={false} />
+      </mesh>
+
+      <Environment resolution={256} frames={1}>
+        <color attach="background" args={['#15161b']} />
+        {/* Tall strips at both sides for the long highlights, a softbox above, an amber wash behind */}
+        <Lightformer form="rect" intensity={7} position={[-5, 1, 3]} rotation-y={Math.PI / 3} scale={[1.2, 9, 1]} />
+        <Lightformer form="rect" intensity={4} position={[5, 1, 2]} rotation-y={-Math.PI / 3} scale={[1, 9, 1]} />
+        <Lightformer form="rect" intensity={2.5} position={[0, 6, 1]} rotation-x={Math.PI / 2} scale={[8, 3, 1]} />
+        <Lightformer form="rect" intensity={1.2} position={[0, 1, 7]} rotation-y={Math.PI} scale={[8, 4, 1]} />
+        <Lightformer form="rect" color={NIGHTJAR.amber} intensity={0.8} position={[0, -2, -7]} scale={[10, 3, 1]} />
+      </Environment>
+    </>
+  )
+})
+```
+
+### ./src/expressions/guitar.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+const BASE_PRICE = 1650
+const SIGNATURE_PRICE = 45
+const SIGNATURE_LIMIT = 16
+
+const SURCHARGES = {
+  bodyShape: { Offset: 0, SingleCut: 150 },
+  finish: { Seafoam: 0, CandyRed: 180, Midnight: 120, NaturalAsh: 90 },
+  pickguard: { Parchment: 0, Black: 0, Pearloid: 40, None: 0 },
+  neckWood: { Maple: 0, RoastedMaple: 110, Mahogany: 80 },
+  fretboard: { Maple: 0, Rosewood: 0, Ebony: 140 },
+  pickups: { SingleCoils: 0, Humbuckers: 120, P90s: 90 },
+  hardware: { Chrome: 0, Gold: 160, Black: 60 },
+}
+
+// The wood textures ship with Storybook; a texture is multiplied by the material's colour
+const LIGHT_WOOD = '/textures/Material_Lightwood.png'
+const DARK_WOOD = '/textures/Material_Darkwood.png'
+const ASH = '/textures/oak_varnished_BaseColor.png'
+
+// How each finish renders under the clearcoat: the paints are solid, natural ash shows the grain through a tint
+const FINISHES = {
+  Seafoam: { color: '#9fd8c4', metalness: 0, roughness: 0.38, texture: null },
+  CandyRed: { color: '#a3101c', metalness: 0.35, roughness: 0.3, texture: null },
+  Midnight: { color: '#1b2a52', metalness: 0.55, roughness: 0.34, texture: null },
+  NaturalAsh: { color: '#f4e2c4', metalness: 0, roughness: 0.5, texture: ASH },
+}
+
+const PICKGUARDS = {
+  Parchment: { color: '#ece2cb', roughness: 0.5, iridescence: 0 },
+  Black: { color: '#121214', roughness: 0.3, iridescence: 0 },
+  Pearloid: { color: '#f2ede6', roughness: 0.22, iridescence: 1 },
+  None: { color: '#ece2cb', roughness: 0.5, iridescence: 0 },
+}
+
+const NECKS = {
+  Maple: { color: '#f6dcae', texture: LIGHT_WOOD },
+  RoastedMaple: { color: '#c58a4e', texture: LIGHT_WOOD },
+  Mahogany: { color: '#c47a5a', texture: DARK_WOOD },
+}
+
+const FRETBOARDS = {
+  Maple: { color: '#f6dcae', texture: LIGHT_WOOD, inlay: '#1b1714' },
+  Rosewood: { color: '#ffffff', texture: DARK_WOOD, inlay: '#efe9df' },
+  Ebony: { color: '#3a3330', texture: DARK_WOOD, inlay: '#efe9df' },
+}
+
+const HARDWARE = {
+  Chrome: { color: '#eceef0', metalness: 1, roughness: 0.12 },
+  Gold: { color: '#e6b964', metalness: 1, roughness: 0.2 },
+  Black: { color: '#26262a', metalness: 0.7, roughness: 0.32 },
+}
+
+export default phx.domain.implementCustomExpressions({
+  Guitar: {
+    $price: s => {
+      return (
+        BASE_PRICE +
+        SURCHARGES.bodyShape[s.bodyShape] +
+        SURCHARGES.finish[s.finish] +
+        SURCHARGES.pickguard[s.pickguard] +
+        SURCHARGES.neckWood[s.neckWood] +
+        SURCHARGES.fretboard[s.fretboard] +
+        SURCHARGES.pickups[s.pickups] +
+        SURCHARGES.hardware[s.hardware] +
+        (s.signature.trim() === '' ? 0 : SIGNATURE_PRICE)
+      )
+    },
+    $signatureLimit: () => {
+      return SIGNATURE_LIMIT
+    },
+    $finishColor: s => {
+      return FINISHES[s.finish].color
+    },
+    $finishMetalness: s => {
+      return FINISHES[s.finish].metalness
+    },
+    $finishRoughness: s => {
+      return FINISHES[s.finish].roughness
+    },
+    $finishTexture: s => {
+      return FINISHES[s.finish].texture
+    },
+    $pickguardColor: s => {
+      return PICKGUARDS[s.pickguard].color
+    },
+    $pickguardRoughness: s => {
+      return PICKGUARDS[s.pickguard].roughness
+    },
+    $pickguardIridescence: s => {
+      return PICKGUARDS[s.pickguard].iridescence
+    },
+    $neckColor: s => {
+      return NECKS[s.neckWood].color
+    },
+    $neckTexture: s => {
+      return NECKS[s.neckWood].texture
+    },
+    $fretboardColor: s => {
+      return FRETBOARDS[s.fretboard].color
+    },
+    $fretboardTexture: s => {
+      return FRETBOARDS[s.fretboard].texture
+    },
+    $inlayColor: s => {
+      return FRETBOARDS[s.fretboard].inlay
+    },
+    $hardwareColor: s => {
+      return HARDWARE[s.hardware].color
+    },
+    $hardwareMetalness: s => {
+      return HARDWARE[s.hardware].metalness
+    },
+    $hardwareRoughness: s => {
+      return HARDWARE[s.hardware].roughness
+    },
+    // Single coils match a black pickguard and are cream otherwise; humbuckers and P-90s are black
+    $pickupCoverColor: s => {
+      return s.pickups === 'SingleCoils' && s.pickguard !== 'Black' ? '#efe7d4' : '#141416'
+    },
+    // Gold leaf on the dark woods, black ink on maple
+    $signatureColor: s => {
+      return s.neckWood === 'Maple' ? '#1c1714' : '#e8c27a'
+    },
+  },
+})
+```
+
+### ./src/handlers/place-order.ts
+
+```ts
+import { useCallback } from 'react'
+
+import { phx } from '../../.phoenix/phx.js'
+
+// Stands in for Northfret's order service. Placing an order takes a moment. The service checks stock when the order
+// arrives, which the configurator cannot know beforehand: gold hardware is back-ordered, so it refuses that order with
+// its reason; any other order is accepted and the page shows the confirmation.
+export default phx.frontend.createPhoenixHandler('placeOrder', () => {
+  const navigate = phx.frontend.useNavigate()
+  const guitar = phx.frontend.useRootEntityState()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1600))
+
+      if (guitar.hardware === 'Gold') {
+        throw new Error(
+          'Gold hardware is back-ordered until next month. Choose chrome or black hardware, or order later.'
+        )
+      }
+
+      navigate('ordered')
+    }, [guitar.hardware, navigate]),
+  }
+})
+```
+
+### ./src/invariants/guitar.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomInvariants({
+  Guitar: {
+    // `fixable`: a change that makes the signature too long is rejected, so the headstock never shows more than fits.
+    // The message names the limit, so it is built here rather than in the spec.
+    signatureLength: s => {
+      if (s.signature.length <= s.$signatureLimit) {
+        return []
+      }
+
+      return [
+        {
+          type: 'signatureTooLong',
+          severity: 'fixable',
+          message: `The headstock fits ${s.$signatureLimit} characters. Shorten the signature.`,
+        },
+      ]
+    },
+    // `warning` in the spec: the change is kept, so a body chosen after the pickups does not undo them, and ordering
+    // waits until the customer resolves it
+    offsetHumbuckers: s => {
+      return s.bodyShape !== 'Offset' || s.pickups !== 'Humbuckers'
+    },
+  },
+})
+```
+
+</details>