@salsita-ai/sdk 0.50.0-develop.ae9a830ef0 → 0.50.0-develop.afbc5157e1

package/dist/docs/layouts/gallery/sunfold-solar.mdx

@@ -0,0 +1,2657 @@
+# Sunfold Solar
+
+Help a household decide on a system by showing what it would do for them. A solar installer, Sunfold, lets a homeowner plan panels and a battery for their roof: the roof's area and direction, the number of panels, the battery, the tariff and the home's yearly use. The page answers with a dashboard: four figures, the solar year month by month, the year the system pays for itself, and how much of the power the home uses. Every figure is an expression of the spec, so the dashboard changes the moment an input does, and **Book a home survey** is a finalize action. There is no 3D model; the tiles and charts are React and hand-written SVG.
+
+- [Try it](#try-it)
+- [What the example demonstrates](#what-the-example-demonstrates)
+- [A dashboard instead of a scene](#a-dashboard-instead-of-a-scene)
+- [Every figure is an expression](#every-figure-is-an-expression)
+- [Figures on tiles](#figures-on-tiles)
+- [Charts in SVG](#charts-in-svg)
+- [A warning and a notice](#a-warning-and-a-notice)
+- [Book a home survey](#book-a-home-survey)
+- [On a phone](#on-a-phone)
+- [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
+
+| Piece                                                                                           | Where                                                                                   |
+| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| A `ConfiguratorLayout` that mounts no `LayoutSlots.SharedCanvas`                                | [A dashboard instead of a scene](#a-dashboard-instead-of-a-scene)                       |
+| Numbers and series declared in `expressions:` and read with `phx.frontend.useRootEntityState()` | [Every figure is an expression](#every-figure-is-an-expression)                         |
+| KPI tiles                                                                                       | `KpiTiles`, [Figures on tiles](#figures-on-tiles)                                       |
+| A stacked column chart with a line, a payback curve and a split bar, with tooltips              | `MonthlyEnergyChart`, `PaybackChart`, `EnergySplitBar`, [Charts in SVG](#charts-in-svg) |
+| A `warning` that blocks finalizing beside a `notice` that does not                              | `PlannerInputs`, [A warning and a notice](#a-warning-and-a-notice)                      |
+| `phx.frontend.useFinalizeActions()` for the spec's `survey` action                              | `SurveyPanel`, [Book a home survey](#book-a-home-survey)                                |
+
+## A dashboard instead of a scene
+
+`src/elements/ConfiguratorLayout.tsx` mounts the services and a page, never `LayoutSlots.SharedCanvas`, so no scene loads and the app loader does not wait for one. On a desktop the inputs are a sidebar with the cost and the booking at its foot, and the dashboard fills the rest; on a phone everything is one scrolling column with the cost in a bar at the bottom.
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { DesktopPage } from '../_shared/DesktopPage.js'
+import { PhonePage } from '../_shared/PhonePage.js'
+import { SUNFOLD } from '../_shared/tokens.js'
+
+// A planning dashboard with no scene: the layout never mounts `LayoutSlots.SharedCanvas`, and every tile and chart is
+// React and SVG drawn from the spec's expressions
+const ConfiguratorLayout = () => {
+  // `null` until the container has been measured
+  const viewports = phx.frontend.useActiveViewports()
+  const isDesktop = viewports?.includes('desktop') ?? false
+
+  return (
+    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: SUNFOLD.linen }}>
+      <LayoutSlots.Services />
+      {viewports !== null && (isDesktop ? <DesktopPage /> : <PhonePage />)}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+## Every figure is an expression
+
+The dashboard computes nothing itself. The system's size, its production month by month, how the production splits between the home and the grid, the yearly saving, the cost and the money returned year by year are expressions of the root entity. Declaring them in `expressions:` gives them their types, so the layout reads `$monthly` as an array of months and `$cumulativeSavings` as an array of numbers with `phx.frontend.useRootEntityState()`.
+
+```yaml
+expressions:
+  SolarPlan:
+    $systemKwp:
+      type: number
+    $roofPanelLimit:
+      type: number
+    $panelAreaM2:
+      type: number
+    $annualProductionKwh:
+      type: number
+    $monthly:
+      type: array
+      items:
+        type: object
+        properties:
+          month:
+            type: string
+          productionKwh:
+            type: number
+          consumptionKwh:
+            type: number
+          selfUseKwh:
+            type: number
+          exportKwh:
+            type: number
+        required:
+          - month
+          - productionKwh
+          - consumptionKwh
+          - selfUseKwh
+          - exportKwh
+        additionalProperties: false
+    $selfConsumption:
+      type: number
+    $selfSufficiency:
+      type: number
+    $annualSavings:
+      type: number
+    $systemCost:
+      type: number
+    $cumulativeSavings:
+      type: array
+      items:
+        type: number
+    $paybackYears:
+      type: number
+    $co2Tonnes:
+      type: number
+```
+
+The model in `src/expressions/solar.ts` is deliberately simple: a south-facing kWp yields 1,000 kWh a year, spread over the months by a typical central European sun curve. Without a battery the home uses solar power only while the sun shines; a battery carries the day's surplus into the evening. The saving counts the power the home no longer buys and the power it sells, and the running total grows with prices rising 2 % a year while the panels lose half a percent.
+
+```ts
+const PANEL_KWP = 0.43
+const PANEL_AREA_M2 = 1.95
+// Vents, chimneys and the edge clearance leave about 85 % of a roof for panels
+const USABLE_ROOF = 0.85
+// A south-facing kWp in central Europe yields about 1,000 kWh a year
+const YIELD_KWH_PER_KWP = 1000
+const ORIENTATION_FACTOR = { South: 1, SouthEastWest: 0.95, EastWest: 0.82, North: 0.6 }
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+// The share of the year's sun and of the household's use that falls in each month
+const SUN_SHARE = [0.04, 0.045, 0.08, 0.105, 0.125, 0.13, 0.13, 0.115, 0.09, 0.065, 0.04, 0.035]
+const USE_SHARE = [0.1, 0.09, 0.088, 0.08, 0.075, 0.07, 0.07, 0.072, 0.076, 0.085, 0.094, 0.1]
+const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+const BATTERY_KWH = { None: 0, Kwh5: 5, Kwh10: 10, Kwh15: 15 }
+const BATTERY_PRICE = { None: 0, Kwh5: 3600, Kwh10: 6400, Kwh15: 8900 }
+const TARIFF = {
+  Flat: { buy: 0.32, sell: 0.08, shiftBonus: 0 },
+  TimeOfUse: { buy: 0.29, sell: 0.1, shiftBonus: 0.09 },
+  ExportPlus: { buy: 0.32, sell: 0.15, shiftBonus: 0 },
+}
+// Panels lose half a percent a year; electricity gets 2 % dearer a year
+const DEGRADATION = 0.995
+const PRICE_GROWTH = 1.02
+const YEARS = 25
+
+export default phx.domain.implementCustomExpressions({
+  SolarPlan: {
+    $systemKwp: s => {
+      return s.panels * PANEL_KWP
+    },
+    $roofPanelLimit: s => {
+      return Math.floor((s.roofArea * USABLE_ROOF) / PANEL_AREA_M2)
+    },
+    // The roof the panels cover, rounded up to whole square metres, as the tiles and the roof warning quote it
+    $panelAreaM2: s => {
+      return Math.ceil(s.panels * PANEL_AREA_M2)
+    },
+    $annualProductionKwh: s => {
+      return s.$systemKwp * YIELD_KWH_PER_KWP * ORIENTATION_FACTOR[s.orientation]
+    },
+    // Each month's production and use, and how the production splits between the home and the grid. Without a
+    // battery the home uses solar power only while the sun shines; a battery carries the surplus into the evening,
+    // one charge a day, and covers the evening but not the early morning.
+    $monthly: s => {
+      const batteryKwh = BATTERY_KWH[s.battery] * 0.9
+
+      return MONTHS.map((month, index) => {
+        const productionKwh = s.$annualProductionKwh * (SUN_SHARE[index] ?? 0)
+        const consumptionKwh = s.annualUse * (USE_SHARE[index] ?? 0)
+        const direct = Math.min(productionKwh * 0.55, consumptionKwh * 0.45)
+        const stored = Math.min(
+          productionKwh - direct,
+          batteryKwh * (DAYS[index] ?? 30),
+          (consumptionKwh - direct) * 0.6
+        )
+        const selfUseKwh = direct + stored
+
+        return { month, productionKwh, consumptionKwh, selfUseKwh, exportKwh: productionKwh - selfUseKwh }
+      })
+    },
+    $selfConsumption: s => {
+      const selfUse = s.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+
+      return s.$annualProductionKwh > 0 ? selfUse / s.$annualProductionKwh : 0
+    },
+    $selfSufficiency: s => {
+      const selfUse = s.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+
+      return selfUse / s.annualUse
+    },
+    // A year's saving: power the home no longer buys, power sold to the grid, and on a time-of-use tariff the
+    // evening power a battery shifts away from the dear hours
+    $annualSavings: s => {
+      const tariff = TARIFF[s.tariff]
+      const selfUse = s.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+      const exported = s.$monthly.reduce((sum, month) => sum + month.exportKwh, 0)
+      const shifted = s.battery === 'None' ? 0 : selfUse * 0.4
+
+      return selfUse * tariff.buy + exported * tariff.sell + shifted * tariff.shiftBonus
+    },
+    $systemCost: s => {
+      return Math.round(1500 + s.$systemKwp * 1050 + BATTERY_PRICE[s.battery])
+    },
+    // The money the system has returned at the end of each year, starting at minus its cost in year 0
+    $cumulativeSavings: s => {
+      return Array.from({ length: YEARS + 1 }, (_, year) => {
+        const earned = Array.from(
+          { length: year },
+          (__, past) => s.$annualSavings * (PRICE_GROWTH * DEGRADATION) ** past
+        ).reduce((sum, value) => sum + value, 0)
+
+        return earned - s.$systemCost
+      })
+    },
+    // The year the running total crosses zero, between whole years; beyond the panels' 25 years it is `Infinity`
+    $paybackYears: s => {
+      const totals = s.$cumulativeSavings
+      const year = totals.findIndex(total => total >= 0)
+
+      if (year <= 0) {
+        return year === 0 ? 0 : Infinity
+      }
+
+      const before = totals[year - 1] ?? 0
+      const after = totals[year] ?? 0
+
+      return year - 1 + -before / (after - before)
+    },
+    $co2Tonnes: s => {
+      return (s.$annualProductionKwh * 0.35) / 1000
+    },
+  },
+})
+```
+
+The cost is the `price` component's value, so `phx.frontend.useRootEntityPrice()` formats it in euros:
+
+```yaml
+components:
+  SolarPlan:
+    price:
+      main:
+        price:
+          $read: $systemCost
+        currency: EUR
+```
+
+## Figures on tiles
+
+`KpiTiles` shows the four figures a household asks first, each with the context that makes it mean something: the panels and roof behind the system size, the CO₂ behind the production, what the self-consumption share means, and the first year's saving behind the payback.
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { CARD_SX, SUNFOLD } from './tokens.js'
+
+const euro = (value: number) => {
+  return value.toLocaleString('en-IE', { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 })
+}
+
+interface KpiTilesProps {
+  readonly columns: number
+}
+
+// The four figures a household asks first, each with the context that makes it mean something. Every value is an
+// expression of the spec, read from the root entity.
+export const KpiTiles = ({ columns }: KpiTilesProps) => {
+  const plan = phx.frontend.useRootEntityState()
+  const payback = plan.$paybackYears
+  const tiles = [
+    {
+      label: 'System size',
+      value: `${plan.$systemKwp.toFixed(1)} kWp`,
+      context: `${plan.panels} panels, ${plan.$panelAreaM2} m² of roof`,
+    },
+    {
+      label: 'Annual production',
+      value: `${Math.round(plan.$annualProductionKwh).toLocaleString('en')} kWh`,
+      context: `About ${plan.$co2Tonnes.toFixed(1)} t of CO₂ avoided a year`,
+    },
+    {
+      label: 'Self-consumption',
+      value: `${Math.round(plan.$selfConsumption * 100)} %`,
+      context: 'of the solar power is used at home',
+    },
+    {
+      label: 'Payback',
+      value: Number.isFinite(payback) ? `${payback.toFixed(1)} years` : 'Over 25 years',
+      context: `${euro(plan.$annualSavings)} saved in the first year`,
+    },
+  ]
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gap: 2 }}>
+      {tiles.map(tile => (
+        <Box
+          component="section"
+          key={tile.label}
+          aria-label={tile.label}
+          sx={{ ...CARD_SX, display: 'grid', gap: 0.5, padding: 2 }}
+        >
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 13, color: SUNFOLD.muted }}>{tile.label}</Typography>
+          <Typography
+            sx={{
+              fontFamily: SUNFOLD.font,
+              fontSize: columns > 2 ? 30 : 24,
+              fontWeight: 600,
+              lineHeight: 1.15,
+              color: SUNFOLD.ink,
+            }}
+          >
+            {tile.value}
+          </Typography>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>{tile.context}</Typography>
+        </Box>
+      ))}
+    </Box>
+  )
+}
+```
+
+## Charts in SVG
+
+The charts are hand-written SVG; the example adds no chart library. Each chart measures its width with a `ResizeObserver` and draws its text at its real size.
+
+- **Your solar year.** `MonthlyEnergyChart` draws each month's production as a column split into what the home uses and what goes to the grid, with a 2-pixel gap between the parts and a rounded top, and the home's use as a line across it. A legend names the three series, hovering a month shows its figures, and **Show figures** swaps the chart for a table of the same numbers.
+- **When it pays back.** `PaybackChart` draws `$cumulativeSavings`, which starts at minus the system's cost, marks the year it crosses zero, and reads off any year under the pointer.
+- **Where the power goes.** `EnergySplitBar` splits a year of production between the home and the grid, and says how much of the home's use solar covers.
+
+The series colours are a fixed set checked together for colour-vision deficiencies; two are lighter than 3:1 against white, which is why every chart also has a legend, a tooltip or the figures written out.
+
+```tsx
+import { Box, ButtonBase, Typography } from '@mui/material'
+import { useState } from 'react'
+
+import { CHART, SERIES } from './chart-style.js'
+import { niceScale } from './nice-scale.js'
+import { useWidth } from './use-width.js'
+
+const MARGIN = { top: 12, right: 8, bottom: 26, left: 48 }
+const GAP = 2
+const RADIUS = 4
+
+const kwh = (value: number) => {
+  return `${Math.round(value).toLocaleString('en')} kWh`
+}
+
+// A column segment whose top corners are rounded, so the stack ends in a 4px data-end and stays square at the
+// baseline
+const roundedTop = (x: number, y: number, width: number, height: number) => {
+  const r = Math.min(RADIUS, height, width / 2)
+
+  return `M${x},${y + height} V${y + r} Q${x},${y} ${x + r},${y} H${x + width - r} Q${x + width},${y} ${x + width},${y + r} V${y + height} Z`
+}
+
+const LEGEND = [
+  { key: 'selfUse', label: 'Solar used at home', color: SERIES.selfUse, line: false },
+  { key: 'exported', label: 'Solar sent to the grid', color: SERIES.exported, line: false },
+  { key: 'consumption', label: 'Home use', color: SERIES.consumption, line: true },
+]
+
+interface MonthlyEnergyChartProps {
+  readonly height: number
+}
+
+// Each month's solar production as a column split into what the home uses and what goes to the grid, with the
+// home's use as a line across it. All figures come from the spec's `$monthly` expression. Hovering a month shows its
+// figures; "Show figures" swaps the chart for a table of the same numbers.
+export const MonthlyEnergyChart = ({ height }: MonthlyEnergyChartProps) => {
+  const plan = phx.frontend.useRootEntityState()
+  const { ref, width } = useWidth()
+  const [hovered, setHovered] = useState<number | null>(null)
+  const [asTable, setAsTable] = useState(false)
+  const months = plan.$monthly
+  const peak = Math.max(...months.map(month => Math.max(month.productionKwh, month.consumptionKwh)))
+  const { high, ticks } = niceScale(0, peak, 4)
+  const plotWidth = Math.max(width - MARGIN.left - MARGIN.right, 0)
+  const plotHeight = height - MARGIN.top - MARGIN.bottom
+  const band = plotWidth / months.length
+  const barWidth = Math.min(24, band * 0.62)
+  const y = (value: number) => MARGIN.top + plotHeight - (value / high) * plotHeight
+  const x = (index: number) => MARGIN.left + band * index + band / 2
+  const active = hovered === null ? undefined : months[hovered]
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.5 }}>
+      <Box component="div" sx={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', columnGap: 2, rowGap: 0.5 }}>
+        {LEGEND.map(item => (
+          <Box component="span" key={item.key} sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.75 }}>
+            <Box
+              component="span"
+              aria-hidden
+              sx={
+                item.line
+                  ? { inlineSize: 14, blockSize: 2, borderRadius: 1, bgcolor: item.color }
+                  : { inlineSize: 10, blockSize: 10, borderRadius: 0.5, bgcolor: item.color }
+              }
+            />
+            <Typography component="span" sx={{ fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}>
+              {item.label}
+            </Typography>
+          </Box>
+        ))}
+        <ButtonBase
+          onClick={() => setAsTable(shown => !shown)}
+          sx={{
+            marginInlineStart: 'auto',
+            fontFamily: CHART.font,
+            fontSize: 12,
+            color: CHART.ink,
+            textDecoration: 'underline',
+          }}
+        >
+          {asTable ? 'Show chart' : 'Show figures'}
+        </ButtonBase>
+      </Box>
+
+      {/* Measured whether the chart or the table shows, so the chart comes back at the current width */}
+      <Box component="div" ref={ref}>
+        {asTable ? (
+          <Box
+            component="table"
+            sx={{
+              inlineSize: '100%',
+              borderCollapse: 'collapse',
+              fontFamily: CHART.font,
+              fontSize: 12,
+              color: CHART.ink,
+            }}
+          >
+            <thead>
+              <tr>
+                {['Month', 'Produced', 'Used at home', 'Sent to grid', 'Home use'].map(heading => (
+                  <Box
+                    component="th"
+                    key={heading}
+                    sx={{
+                      paddingBlock: 0.5,
+                      textAlign: 'end',
+                      fontWeight: 500,
+                      color: CHART.inkSoft,
+                      '&:first-of-type': { textAlign: 'start' },
+                    }}
+                  >
+                    {heading}
+                  </Box>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {months.map(month => (
+                <Box component="tr" key={month.month} sx={{ borderBlockStart: `1px solid ${CHART.grid}` }}>
+                  <Box component="td" sx={{ paddingBlock: 0.5 }}>
+                    {month.month}
+                  </Box>
+                  {[month.productionKwh, month.selfUseKwh, month.exportKwh, month.consumptionKwh].map(
+                    (value, index) => (
+                      <Box component="td" key={index} sx={{ textAlign: 'end', fontVariantNumeric: 'tabular-nums' }}>
+                        {Math.round(value).toLocaleString('en')}
+                      </Box>
+                    )
+                  )}
+                </Box>
+              ))}
+            </tbody>
+          </Box>
+        ) : (
+          <Box component="div" sx={{ position: 'relative', blockSize: height }}>
+            {width > 0 && (
+              <svg
+                width={width}
+                height={height}
+                role="img"
+                aria-label="Solar production and home use by month"
+                onMouseLeave={() => setHovered(null)}
+              >
+                {ticks.map(tick => (
+                  <g key={tick}>
+                    <line
+                      x1={MARGIN.left}
+                      x2={width - MARGIN.right}
+                      y1={y(tick)}
+                      y2={y(tick)}
+                      stroke={tick === 0 ? CHART.axis : CHART.grid}
+                      strokeWidth={1}
+                    />
+                    <text
+                      x={MARGIN.left - 8}
+                      y={y(tick)}
+                      textAnchor="end"
+                      dominantBaseline="middle"
+                      fill={CHART.inkSoft}
+                      fontFamily={CHART.font}
+                      fontSize={11}
+                    >
+                      {tick.toLocaleString('en')}
+                    </text>
+                  </g>
+                ))}
+
+                {hovered !== null && (
+                  <rect
+                    x={MARGIN.left + band * hovered}
+                    y={MARGIN.top}
+                    width={band}
+                    height={plotHeight}
+                    fill={CHART.grid}
+                    opacity={0.6}
+                  />
+                )}
+
+                {months.map((month, index) => {
+                  const left = x(index) - barWidth / 2
+                  const selfTop = y(month.selfUseKwh)
+                  const exportTop = y(month.productionKwh)
+                  const exportHeight = Math.max(selfTop - exportTop - GAP, 0)
+
+                  return (
+                    <g key={month.month}>
+                      {exportHeight > 0.5 ? (
+                        <>
+                          <rect x={left} y={selfTop} width={barWidth} height={y(0) - selfTop} fill={SERIES.selfUse} />
+                          <path d={roundedTop(left, exportTop, barWidth, exportHeight)} fill={SERIES.exported} />
+                        </>
+                      ) : (
+                        <path d={roundedTop(left, selfTop, barWidth, y(0) - selfTop)} fill={SERIES.selfUse} />
+                      )}
+                      <text
+                        x={x(index)}
+                        y={height - 8}
+                        textAnchor="middle"
+                        fill={CHART.inkSoft}
+                        fontFamily={CHART.font}
+                        fontSize={11}
+                      >
+                        {/* A narrow chart keeps only the initial */}
+                        {band < 34 ? month.month.slice(0, 1) : month.month}
+                      </text>
+                    </g>
+                  )
+                })}
+
+                <polyline
+                  points={months.map((month, index) => `${x(index)},${y(month.consumptionKwh)}`).join(' ')}
+                  fill="none"
+                  stroke={SERIES.consumption}
+                  strokeWidth={2}
+                  strokeLinejoin="round"
+                  strokeLinecap="round"
+                />
+                {months.map((month, index) => (
+                  <circle
+                    key={month.month}
+                    cx={x(index)}
+                    cy={y(month.consumptionKwh)}
+                    r={4}
+                    fill={SERIES.consumption}
+                    stroke={CHART.surface}
+                    strokeWidth={2}
+                  />
+                ))}
+
+                {/* Hit areas a full band wide and the plot's height, larger than the marks */}
+                {months.map((month, index) => (
+                  <rect
+                    key={month.month}
+                    x={MARGIN.left + band * index}
+                    y={MARGIN.top}
+                    width={band}
+                    height={plotHeight}
+                    fill="transparent"
+                    onMouseEnter={() => setHovered(index)}
+                  />
+                ))}
+              </svg>
+            )}
+
+            {active !== undefined && hovered !== null && (
+              <Box
+                component="div"
+                role="tooltip"
+                sx={{
+                  position: 'absolute',
+                  insetBlockStart: 0,
+                  insetInlineStart: Math.min(Math.max(x(hovered) - 90, 0), Math.max(width - 180, 0)),
+                  inlineSize: 180,
+                  padding: 1.25,
+                  borderRadius: 1.5,
+                  bgcolor: CHART.surface,
+                  boxShadow: '0 6px 24px rgba(28, 40, 38, 0.16)',
+                  pointerEvents: 'none',
+                  fontFamily: CHART.font,
+                }}
+              >
+                <Typography sx={{ fontFamily: CHART.font, fontSize: 12, fontWeight: 600, color: CHART.ink }}>
+                  {active.month}
+                </Typography>
+                {[
+                  { label: 'Used at home', value: active.selfUseKwh, color: SERIES.selfUse },
+                  { label: 'Sent to grid', value: active.exportKwh, color: SERIES.exported },
+                  { label: 'Home use', value: active.consumptionKwh, color: SERIES.consumption },
+                ].map(row => (
+                  <Box component="div" key={row.label} sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+                    <Box
+                      component="span"
+                      aria-hidden
+                      sx={{ inlineSize: 8, blockSize: 8, borderRadius: '50%', bgcolor: row.color }}
+                    />
+                    <Typography
+                      component="span"
+                      sx={{ flex: 1, fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}
+                    >
+                      {row.label}
+                    </Typography>
+                    <Typography
+                      component="span"
+                      sx={{
+                        fontFamily: CHART.font,
+                        fontSize: 12,
+                        color: CHART.ink,
+                        fontVariantNumeric: 'tabular-nums',
+                      }}
+                    >
+                      {kwh(row.value)}
+                    </Typography>
+                  </Box>
+                ))}
+              </Box>
+            )}
+          </Box>
+        )}
+      </Box>
+    </Box>
+  )
+}
+```
+
+## A warning and a notice
+
+The plan has two rules. More panels than the roof holds is a `warning`: the dashboard keeps showing the figures, so the household sees what the larger system would do, but a survey cannot be booked until the panels fit. A north-facing roof is a `notice`: it informs and never blocks.
+
+```yaml
+invariants:
+  SolarPlan:
+    panelsFitRoof:
+      types:
+        - panelsExceedRoof
+    northFacing:
+      type: northFacing
+      severity: notice
+      message: A north-facing roof yields about 40 % less. An east-west layout on another roof usually pays back sooner.
+```
+
+```ts
+// More panels than the roof holds is a warning: the dashboard keeps showing the figures, and a survey cannot be
+// booked until the panel count fits. A north-facing roof is only a notice, so it never blocks the booking.
+export default phx.domain.implementCustomInvariants({
+  SolarPlan: {
+    panelsFitRoof: s => {
+      if (s.panels <= s.$roofPanelLimit) {
+        return []
+      }
+
+      return [
+        {
+          type: 'panelsExceedRoof',
+          severity: 'warning',
+          message: `${s.panels} panels need about ${s.$panelAreaM2} m² of roof; ${s.roofArea} m² holds at most ${s.$roofPanelLimit}. Lower the panel count or measure the roof again.`,
+        },
+      ]
+    },
+    northFacing: s => {
+      return s.orientation !== 'North'
+    },
+  },
+})
+```
+
+`PlannerInputs` shows both under the roof's inputs, from `phx.frontend.useFinalizeViolations()`, which lists the violations of the committed plan with their severity: the warning in amber, the notice in blue. `phx.frontend.useFinalizeActions()` reports the survey action `disabled` only for the warning.
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+
+import { PillField } from './PillField.js'
+import { SliderField } from './SliderField.js'
+import { SUNFOLD } from './tokens.js'
+
+interface GroupProps {
+  readonly title: string
+  // The invariant types whose message belongs under this group
+  readonly messageTypes?: readonly string[]
+  readonly children: ReactNode
+}
+
+// A group of inputs with the message of an invariant the group can resolve: a warning, which blocks the booking, in
+// amber, a notice, which only informs, in blue. `useFinalizeViolations` lists both.
+const Group = ({ title, messageTypes = [], children }: GroupProps) => {
+  const { violations } = phx.frontend.useFinalizeViolations()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const messages = (violations ?? []).filter(({ violation }) => messageTypes.includes(violation.type))
+
+  return (
+    <Box component="section" sx={{ display: 'grid', gap: 2 }}>
+      <Typography component="h3" sx={{ fontFamily: SUNFOLD.font, fontSize: 13, fontWeight: 600, color: SUNFOLD.muted }}>
+        {title}
+      </Typography>
+      {children}
+      {messages.map(({ violation }) => {
+        const isNotice = violation.severity === 'notice'
+
+        return (
+          <Typography
+            key={violation.type}
+            role={isNotice ? 'status' : 'alert'}
+            sx={{
+              paddingInline: 1.5,
+              paddingBlock: 1,
+              borderRadius: 2,
+              bgcolor: isNotice ? SUNFOLD.infoTint : SUNFOLD.warningTint,
+              color: isNotice ? SUNFOLD.info : SUNFOLD.warning,
+              fontFamily: SUNFOLD.font,
+              fontSize: 13,
+              lineHeight: 1.45,
+            }}
+          >
+            {resolve(violation.message)}
+          </Typography>
+        )
+      })}
+    </Box>
+  )
+}
+
+interface PlannerInputsProps {
+  readonly readOnly: boolean
+}
+
+// The household's inputs: the roof, the panels on it, the home's use and tariff, and the battery
+export const PlannerInputs = ({ readOnly }: PlannerInputsProps) => {
+  const plan = phx.frontend.useRootEntityState()
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 3.5 }}>
+      <Group title="Your roof" messageTypes={['panelsExceedRoof', 'northFacing']}>
+        <SliderField instanceName="roofArea" label="Usable roof area" step={1} readOnly={readOnly} />
+        <PillField instanceName="orientation" label="Facing" readOnly={readOnly} />
+        <SliderField instanceName="panels" label="Panels" step={1} readOnly={readOnly} />
+        <Typography sx={{ marginBlockStart: -1.5, fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>
+          430 W panels, 1.95 m² each. This roof holds up to {plan.$roofPanelLimit}.
+        </Typography>
+      </Group>
+      <Group title="Your home">
+        <SliderField instanceName="annualUse" label="Electricity used a year" step={100} readOnly={readOnly} />
+        <PillField instanceName="tariff" label="Tariff" readOnly={readOnly} />
+      </Group>
+      <Group title="Storage">
+        <PillField instanceName="battery" label="Home battery" readOnly={readOnly} />
+      </Group>
+    </Box>
+  )
+}
+```
+
+## Book a home survey
+
+The spec declares one finalize action. Its handler, `src/handlers/book-survey.ts`, stands in for the installer's booking service: it waits, then enters the `booked` navigation state. In that state the panel confirms the request and the inputs are locked until **Back to the plan**. A viewer of a shared configuration sees the cost and no button.
+
+```yaml
+components:
+  SolarPlan:
+    finalizeAction:
+      survey:
+        variant: primary
+        label: Book a home survey
+        title: Ask an installer to survey the roof and confirm the plan
+        icon: CalendarCheck
+        handler: bookSurvey
+```
+
+```tsx
+import { Alert, Box, Button, CircularProgress, Typography } from '@mui/material'
+
+import { SUNFOLD } from './tokens.js'
+
+interface SurveyPanelProps {
+  // On a phone the panel is a bar: the cost beside the button, without the hints
+  readonly compact: boolean
+}
+
+// The system's cost, the `price` component's value, and the spec's `survey` finalize action. A warning blocks the
+// booking and its `hints` say why; a notice does not. In the `booked` navigation state the panel confirms the
+// request instead.
+export const SurveyPanel = ({ compact }: SurveyPanelProps) => {
+  const cost = phx.frontend.useRootEntityPrice()
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const navigate = phx.frontend.useNavigate()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const isPending = primary?.isPending ?? false
+
+  if (navigationState === 'booked') {
+    return (
+      <Box component="div" role="status" sx={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+        <Box component="div" sx={{ display: 'grid', flex: 1 }}>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 16, fontWeight: 600, color: SUNFOLD.green }}>
+            Survey requested
+          </Typography>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 13, color: SUNFOLD.muted }}>
+            An installer calls within two working days.
+          </Typography>
+        </Box>
+        <Button
+          onClick={() => navigate('plan')}
+          sx={{
+            fontFamily: SUNFOLD.font,
+            fontSize: 13,
+            color: SUNFOLD.ink,
+            textTransform: 'none',
+            textDecoration: 'underline',
+          }}
+        >
+          Back to the plan
+        </Button>
+      </Box>
+    )
+  }
+
+  const showButton = primary !== null && !accessInfo.viewMode
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.25 }}>
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          flexDirection: compact ? 'row' : 'column',
+          alignItems: compact ? 'center' : 'stretch',
+          justifyContent: 'space-between',
+          gap: compact ? 2 : 1.5,
+        }}
+      >
+        <Box component="div" sx={{ display: 'grid' }}>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>Installed cost</Typography>
+          <Typography
+            sx={{ fontFamily: SUNFOLD.font, fontSize: compact ? 20 : 26, fontWeight: 600, color: SUNFOLD.ink }}
+          >
+            {cost}
+          </Typography>
+        </Box>
+        {showButton && (
+          <Button
+            variant="contained"
+            disableElevation
+            disabled={primary.disabled || isPending}
+            onClick={() => void primary.run()}
+            title={primary.title}
+            startIcon={isPending ? <CircularProgress size={16} color="inherit" /> : undefined}
+            sx={{
+              minBlockSize: 46,
+              paddingInline: 2.5,
+              borderRadius: 999,
+              bgcolor: SUNFOLD.green,
+              fontFamily: SUNFOLD.font,
+              fontSize: 14,
+              fontWeight: 500,
+              textTransform: 'none',
+              '&:hover': { bgcolor: SUNFOLD.greenDark },
+              '&.Mui-disabled': { bgcolor: SUNFOLD.line, color: SUNFOLD.muted },
+            }}
+          >
+            {isPending ? 'Booking…' : primary.label}
+          </Button>
+        )}
+      </Box>
+      {!compact && showButton && primary.disabled && hints && (
+        <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.warning }}>{hints}</Typography>
+      )}
+      {primary?.error && <Alert severity="error">The survey could not be booked: {primary.error.message}</Alert>}
+    </Box>
+  )
+}
+```
+
+## On a phone
+
+The same layout in a frame 390 pixels wide: the four figures in two rows, the inputs in a card below them, the charts stacked under the inputs, and the cost with **Book a home survey** in a bar at the bottom. Opened on its own from the sidebar, the **Phone** story sets Storybook's viewport to 390 × 844.
+
+## Test cases
+
+- The plan opens with 14 panels on a 42 m² south-facing roof, no battery, a flat rate and 4,500 kWh a year. The tiles read **6.0 kWp**, **6,020 kWh**, **30 %** and **8.2 years**, the installed cost is **€7,821.00**, and the split bar shows 30 % used at home.
+- In **Your solar year**, the summer columns are mostly sent to the grid and the winter ones mostly used at home, and the home's use is a line that is higher in winter. Hovering June shows 142 kWh used at home, 641 kWh sent to the grid and 315 kWh of home use.
+- Moving the pointer across **When it pays back** reads off the year; the curve crosses zero at the marked payback year.
+- A 10 kWh battery, the time-of-use tariff and 18 panels change every tile and chart: 7.7 kWp, 7,740 kWh, 44 % used at home and 9.8 years, at €16,027.00. The columns' home part grows.
+- 22 panels on the 42 m² roof show "22 panels need about 43 m² of roof; 42 m² holds at most 18. …" and disable **Book a home survey**; a roof of 52 m² clears it.
+- **North** shows the notice "A north-facing roof yields about 40 % less. …" in blue, lowers the production and lengthens the payback, and leaves **Book a home survey** enabled.
+- **Show figures** shows a table of the twelve months; **Show chart** brings the chart back.
+- **Book a home survey** shows a spinner and "Booking…", then "Survey requested"; the inputs are locked until **Back to the plan**.
+- In the **Phone** story the tiles sit in two rows, the inputs and charts scroll below, the same changes update every figure, and the bottom bar confirms the booking.
+- The browser console shows no errors, the page has no `canvas` element, and no model or texture is requested.
+
+## What this layout leaves out
+
+- **Read mode.** The inputs are inert and **Book a home survey** is hidden while `phx.frontend.useAccessService().accessInfo.viewMode` is set, but the example ships no read template; [Custom Layout → Serve read mode](?path=/docs/layouts-custom-layout--docs#serve-read-mode) shows one.
+- **Real yields and prices.** The model is an illustration. A deployed planner would read the site's irradiance and the household's tariff from data the project publishes, see [Data Sources](?path=/docs/phoenix-data-sources--docs).
+- **A dark theme.** The page is the installer's own light design; the configurator's theme does not switch it.
+- **The built-in arrangement.** Header, sidebar, footer, tabs and the preview start screen are not mounted; [Layout Slots](?path=/docs/phoenix-layout-slots--docs) lists every slot a project layout can mount.
+
+## Related pages
+
+- [Ardent Compressor](?path=/docs/layouts-gallery-ardent-compressor--docs) is a quote form with steps, and [Fenwick Window](?path=/docs/layouts-gallery-fenwick-window--docs) a live shop drawing; neither mounts a canvas either.
+- [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.
+- [Domain Model → Expressions](?path=/docs/phoenix-domain-model--docs#expressions) and [Domain Model → Invariants](?path=/docs/phoenix-domain-model--docs#invariants) describe declared expressions and severities.
+
+## 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:
+      - SolarPlan
+    aliases:
+      RootEntity:
+        - SolarPlan
+    commonTypes:
+      Orientation:
+        enum:
+          - South
+          - SouthEastWest
+          - EastWest
+          - North
+      Battery:
+        enum:
+          - None
+          - Kwh5
+          - Kwh10
+          - Kwh15
+      Tariff:
+        enum:
+          - Flat
+          - TimeOfUse
+          - ExportPlus
+    shapes:
+      SolarPlan:
+        roofArea:
+          type: number
+        orientation:
+          $ref: '#/model/latest/commonTypes/Orientation'
+        panels:
+          type: number
+        battery:
+          $ref: '#/model/latest/commonTypes/Battery'
+        tariff:
+          $ref: '#/model/latest/commonTypes/Tariff'
+        annualUse:
+          type: number
+
+presets:
+  - rootEntityType: SolarPlan
+    initialDomainEntities:
+      - id: SolarPlan-1
+        type: SolarPlan
+        roofArea: 42
+        orientation: South
+        panels: 14
+        battery: None
+        tariff: Flat
+        annualUse: 4500
+
+navigationStates:
+  - plan
+  - booked
+
+# Every figure on the dashboard: declared here, computed in src/expressions/solar.ts from the roof, the panels, the
+# battery, the tariff and the household's use
+expressions:
+  SolarPlan:
+    $systemKwp:
+      type: number
+    $roofPanelLimit:
+      type: number
+    $panelAreaM2:
+      type: number
+    $annualProductionKwh:
+      type: number
+    $monthly:
+      type: array
+      items:
+        type: object
+        properties:
+          month:
+            type: string
+          productionKwh:
+            type: number
+          consumptionKwh:
+            type: number
+          selfUseKwh:
+            type: number
+          exportKwh:
+            type: number
+        required:
+          - month
+          - productionKwh
+          - consumptionKwh
+          - selfUseKwh
+          - exportKwh
+        additionalProperties: false
+    $selfConsumption:
+      type: number
+    $selfSufficiency:
+      type: number
+    $annualSavings:
+      type: number
+    $systemCost:
+      type: number
+    $cumulativeSavings:
+      type: array
+      items:
+        type: number
+    $paybackYears:
+      type: number
+    $co2Tonnes:
+      type: number
+
+invariants:
+  SolarPlan:
+    panelsFitRoof:
+      types:
+        - panelsExceedRoof
+    northFacing:
+      type: northFacing
+      severity: notice
+      message: A north-facing roof yields about 40 % less. An east-west layout on another roof usually pays back sooner.
+
+components:
+  SolarPlan:
+    price:
+      main:
+        price:
+          $read: $systemCost
+        currency: EUR
+    finalizeAction:
+      survey:
+        variant: primary
+        label: Book a home survey
+        title: Ask an installer to survey the roof and confirm the plan
+        icon: CalendarCheck
+        handler: bookSurvey
+    genericDimension:
+      roofArea:
+        value:
+          $bind: roofArea
+        min: 10
+        max: 120
+        unit: m²
+        decimalPlaces: 0
+      panels:
+        value:
+          $bind: panels
+        min: 4
+        max: 40
+        unit: panels
+        decimalPlaces: 0
+      annualUse:
+        value:
+          $bind: annualUse
+        min: 1500
+        max: 12000
+        unit: kWh
+        decimalPlaces: 0
+    attributeSelection:
+      orientation:
+        value:
+          $bind: orientation
+        options:
+          - label: South
+            value: South
+          - label: South-east or south-west
+            value: SouthEastWest
+          - label: East and west
+            value: EastWest
+          - label: North
+            value: North
+      battery:
+        value:
+          $bind: battery
+        options:
+          - label: None
+            value: None
+          - label: 5 kWh
+            value: Kwh5
+          - label: 10 kWh
+            value: Kwh10
+          - label: 15 kWh
+            value: Kwh15
+      tariff:
+        value:
+          $bind: tariff
+        options:
+          - label: Flat rate
+            description: €0.32 per kWh bought, €0.08 per kWh sold
+            value: Flat
+          - label: Time of use
+            description: Cheap nights, dear evenings; a battery shifts the evening
+            value: TimeOfUse
+          - label: Export plus
+            description: €0.15 per kWh sold to the grid
+            value: ExportPlus
+```
+
+### ./src/\_charts/EnergySplitBar.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { CHART, SERIES } from './chart-style.js'
+
+// Where a year of solar power goes, as one bar split between the home and the grid, from the spec's `$monthly` and
+// `$selfConsumption` expressions. A battery moves the split towards the home.
+export const EnergySplitBar = () => {
+  const plan = phx.frontend.useRootEntityState()
+  const selfUse = plan.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+  const exported = plan.$monthly.reduce((sum, month) => sum + month.exportKwh, 0)
+  const share = plan.$selfConsumption
+  const parts = [
+    { key: 'home', label: 'Used at home', kwh: selfUse, share, color: SERIES.selfUse },
+    { key: 'grid', label: 'Sent to the grid', kwh: exported, share: 1 - share, color: SERIES.exported },
+  ]
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.5 }}>
+      <Box
+        component="div"
+        role="img"
+        aria-label={`${Math.round(share * 100)} % of the solar power is used at home`}
+        sx={{ display: 'flex', gap: '2px', blockSize: 20 }}
+      >
+        {parts.map((part, index) => (
+          <Box
+            component="span"
+            key={part.key}
+            sx={{
+              flexBasis: `${part.share * 100}%`,
+              minInlineSize: part.share > 0 ? 4 : 0,
+              bgcolor: part.color,
+              borderStartStartRadius: index === 0 ? 4 : 0,
+              borderEndStartRadius: index === 0 ? 4 : 0,
+              borderStartEndRadius: index === parts.length - 1 ? 4 : 0,
+              borderEndEndRadius: index === parts.length - 1 ? 4 : 0,
+              transition: 'flex-basis 240ms ease-out',
+            }}
+          />
+        ))}
+      </Box>
+      <Box component="div" sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 2 }}>
+        {parts.map(part => (
+          <Box component="div" key={part.key} sx={{ display: 'grid', gap: 0.25 }}>
+            <Box component="div" sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+              <Box
+                component="span"
+                aria-hidden
+                sx={{ inlineSize: 10, blockSize: 10, borderRadius: 0.5, bgcolor: part.color }}
+              />
+              <Typography sx={{ fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}>{part.label}</Typography>
+            </Box>
+            <Typography sx={{ fontFamily: CHART.font, fontSize: 20, fontWeight: 600, color: CHART.ink }}>
+              {Math.round(part.share * 100)} %
+            </Typography>
+            <Typography sx={{ fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}>
+              {Math.round(part.kwh).toLocaleString('en')} kWh a year
+            </Typography>
+          </Box>
+        ))}
+      </Box>
+      <Typography sx={{ fontFamily: CHART.font, fontSize: 13, color: CHART.ink }}>
+        Solar covers {Math.round(plan.$selfSufficiency * 100)} % of the home's {plan.annualUse.toLocaleString('en')}{' '}
+        kWh.
+      </Typography>
+    </Box>
+  )
+}
+```
+
+### ./src/\_charts/MonthlyEnergyChart.tsx
+
+```tsx
+import { Box, ButtonBase, Typography } from '@mui/material'
+import { useState } from 'react'
+
+import { CHART, SERIES } from './chart-style.js'
+import { niceScale } from './nice-scale.js'
+import { useWidth } from './use-width.js'
+
+const MARGIN = { top: 12, right: 8, bottom: 26, left: 48 }
+const GAP = 2
+const RADIUS = 4
+
+const kwh = (value: number) => {
+  return `${Math.round(value).toLocaleString('en')} kWh`
+}
+
+// A column segment whose top corners are rounded, so the stack ends in a 4px data-end and stays square at the
+// baseline
+const roundedTop = (x: number, y: number, width: number, height: number) => {
+  const r = Math.min(RADIUS, height, width / 2)
+
+  return `M${x},${y + height} V${y + r} Q${x},${y} ${x + r},${y} H${x + width - r} Q${x + width},${y} ${x + width},${y + r} V${y + height} Z`
+}
+
+const LEGEND = [
+  { key: 'selfUse', label: 'Solar used at home', color: SERIES.selfUse, line: false },
+  { key: 'exported', label: 'Solar sent to the grid', color: SERIES.exported, line: false },
+  { key: 'consumption', label: 'Home use', color: SERIES.consumption, line: true },
+]
+
+interface MonthlyEnergyChartProps {
+  readonly height: number
+}
+
+// Each month's solar production as a column split into what the home uses and what goes to the grid, with the
+// home's use as a line across it. All figures come from the spec's `$monthly` expression. Hovering a month shows its
+// figures; "Show figures" swaps the chart for a table of the same numbers.
+export const MonthlyEnergyChart = ({ height }: MonthlyEnergyChartProps) => {
+  const plan = phx.frontend.useRootEntityState()
+  const { ref, width } = useWidth()
+  const [hovered, setHovered] = useState<number | null>(null)
+  const [asTable, setAsTable] = useState(false)
+  const months = plan.$monthly
+  const peak = Math.max(...months.map(month => Math.max(month.productionKwh, month.consumptionKwh)))
+  const { high, ticks } = niceScale(0, peak, 4)
+  const plotWidth = Math.max(width - MARGIN.left - MARGIN.right, 0)
+  const plotHeight = height - MARGIN.top - MARGIN.bottom
+  const band = plotWidth / months.length
+  const barWidth = Math.min(24, band * 0.62)
+  const y = (value: number) => MARGIN.top + plotHeight - (value / high) * plotHeight
+  const x = (index: number) => MARGIN.left + band * index + band / 2
+  const active = hovered === null ? undefined : months[hovered]
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.5 }}>
+      <Box component="div" sx={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', columnGap: 2, rowGap: 0.5 }}>
+        {LEGEND.map(item => (
+          <Box component="span" key={item.key} sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.75 }}>
+            <Box
+              component="span"
+              aria-hidden
+              sx={
+                item.line
+                  ? { inlineSize: 14, blockSize: 2, borderRadius: 1, bgcolor: item.color }
+                  : { inlineSize: 10, blockSize: 10, borderRadius: 0.5, bgcolor: item.color }
+              }
+            />
+            <Typography component="span" sx={{ fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}>
+              {item.label}
+            </Typography>
+          </Box>
+        ))}
+        <ButtonBase
+          onClick={() => setAsTable(shown => !shown)}
+          sx={{
+            marginInlineStart: 'auto',
+            fontFamily: CHART.font,
+            fontSize: 12,
+            color: CHART.ink,
+            textDecoration: 'underline',
+          }}
+        >
+          {asTable ? 'Show chart' : 'Show figures'}
+        </ButtonBase>
+      </Box>
+
+      {/* Measured whether the chart or the table shows, so the chart comes back at the current width */}
+      <Box component="div" ref={ref}>
+        {asTable ? (
+          <Box
+            component="table"
+            sx={{
+              inlineSize: '100%',
+              borderCollapse: 'collapse',
+              fontFamily: CHART.font,
+              fontSize: 12,
+              color: CHART.ink,
+            }}
+          >
+            <thead>
+              <tr>
+                {['Month', 'Produced', 'Used at home', 'Sent to grid', 'Home use'].map(heading => (
+                  <Box
+                    component="th"
+                    key={heading}
+                    sx={{
+                      paddingBlock: 0.5,
+                      textAlign: 'end',
+                      fontWeight: 500,
+                      color: CHART.inkSoft,
+                      '&:first-of-type': { textAlign: 'start' },
+                    }}
+                  >
+                    {heading}
+                  </Box>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {months.map(month => (
+                <Box component="tr" key={month.month} sx={{ borderBlockStart: `1px solid ${CHART.grid}` }}>
+                  <Box component="td" sx={{ paddingBlock: 0.5 }}>
+                    {month.month}
+                  </Box>
+                  {[month.productionKwh, month.selfUseKwh, month.exportKwh, month.consumptionKwh].map(
+                    (value, index) => (
+                      <Box component="td" key={index} sx={{ textAlign: 'end', fontVariantNumeric: 'tabular-nums' }}>
+                        {Math.round(value).toLocaleString('en')}
+                      </Box>
+                    )
+                  )}
+                </Box>
+              ))}
+            </tbody>
+          </Box>
+        ) : (
+          <Box component="div" sx={{ position: 'relative', blockSize: height }}>
+            {width > 0 && (
+              <svg
+                width={width}
+                height={height}
+                role="img"
+                aria-label="Solar production and home use by month"
+                onMouseLeave={() => setHovered(null)}
+              >
+                {ticks.map(tick => (
+                  <g key={tick}>
+                    <line
+                      x1={MARGIN.left}
+                      x2={width - MARGIN.right}
+                      y1={y(tick)}
+                      y2={y(tick)}
+                      stroke={tick === 0 ? CHART.axis : CHART.grid}
+                      strokeWidth={1}
+                    />
+                    <text
+                      x={MARGIN.left - 8}
+                      y={y(tick)}
+                      textAnchor="end"
+                      dominantBaseline="middle"
+                      fill={CHART.inkSoft}
+                      fontFamily={CHART.font}
+                      fontSize={11}
+                    >
+                      {tick.toLocaleString('en')}
+                    </text>
+                  </g>
+                ))}
+
+                {hovered !== null && (
+                  <rect
+                    x={MARGIN.left + band * hovered}
+                    y={MARGIN.top}
+                    width={band}
+                    height={plotHeight}
+                    fill={CHART.grid}
+                    opacity={0.6}
+                  />
+                )}
+
+                {months.map((month, index) => {
+                  const left = x(index) - barWidth / 2
+                  const selfTop = y(month.selfUseKwh)
+                  const exportTop = y(month.productionKwh)
+                  const exportHeight = Math.max(selfTop - exportTop - GAP, 0)
+
+                  return (
+                    <g key={month.month}>
+                      {exportHeight > 0.5 ? (
+                        <>
+                          <rect x={left} y={selfTop} width={barWidth} height={y(0) - selfTop} fill={SERIES.selfUse} />
+                          <path d={roundedTop(left, exportTop, barWidth, exportHeight)} fill={SERIES.exported} />
+                        </>
+                      ) : (
+                        <path d={roundedTop(left, selfTop, barWidth, y(0) - selfTop)} fill={SERIES.selfUse} />
+                      )}
+                      <text
+                        x={x(index)}
+                        y={height - 8}
+                        textAnchor="middle"
+                        fill={CHART.inkSoft}
+                        fontFamily={CHART.font}
+                        fontSize={11}
+                      >
+                        {/* A narrow chart keeps only the initial */}
+                        {band < 34 ? month.month.slice(0, 1) : month.month}
+                      </text>
+                    </g>
+                  )
+                })}
+
+                <polyline
+                  points={months.map((month, index) => `${x(index)},${y(month.consumptionKwh)}`).join(' ')}
+                  fill="none"
+                  stroke={SERIES.consumption}
+                  strokeWidth={2}
+                  strokeLinejoin="round"
+                  strokeLinecap="round"
+                />
+                {months.map((month, index) => (
+                  <circle
+                    key={month.month}
+                    cx={x(index)}
+                    cy={y(month.consumptionKwh)}
+                    r={4}
+                    fill={SERIES.consumption}
+                    stroke={CHART.surface}
+                    strokeWidth={2}
+                  />
+                ))}
+
+                {/* Hit areas a full band wide and the plot's height, larger than the marks */}
+                {months.map((month, index) => (
+                  <rect
+                    key={month.month}
+                    x={MARGIN.left + band * index}
+                    y={MARGIN.top}
+                    width={band}
+                    height={plotHeight}
+                    fill="transparent"
+                    onMouseEnter={() => setHovered(index)}
+                  />
+                ))}
+              </svg>
+            )}
+
+            {active !== undefined && hovered !== null && (
+              <Box
+                component="div"
+                role="tooltip"
+                sx={{
+                  position: 'absolute',
+                  insetBlockStart: 0,
+                  insetInlineStart: Math.min(Math.max(x(hovered) - 90, 0), Math.max(width - 180, 0)),
+                  inlineSize: 180,
+                  padding: 1.25,
+                  borderRadius: 1.5,
+                  bgcolor: CHART.surface,
+                  boxShadow: '0 6px 24px rgba(28, 40, 38, 0.16)',
+                  pointerEvents: 'none',
+                  fontFamily: CHART.font,
+                }}
+              >
+                <Typography sx={{ fontFamily: CHART.font, fontSize: 12, fontWeight: 600, color: CHART.ink }}>
+                  {active.month}
+                </Typography>
+                {[
+                  { label: 'Used at home', value: active.selfUseKwh, color: SERIES.selfUse },
+                  { label: 'Sent to grid', value: active.exportKwh, color: SERIES.exported },
+                  { label: 'Home use', value: active.consumptionKwh, color: SERIES.consumption },
+                ].map(row => (
+                  <Box component="div" key={row.label} sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+                    <Box
+                      component="span"
+                      aria-hidden
+                      sx={{ inlineSize: 8, blockSize: 8, borderRadius: '50%', bgcolor: row.color }}
+                    />
+                    <Typography
+                      component="span"
+                      sx={{ flex: 1, fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}
+                    >
+                      {row.label}
+                    </Typography>
+                    <Typography
+                      component="span"
+                      sx={{
+                        fontFamily: CHART.font,
+                        fontSize: 12,
+                        color: CHART.ink,
+                        fontVariantNumeric: 'tabular-nums',
+                      }}
+                    >
+                      {kwh(row.value)}
+                    </Typography>
+                  </Box>
+                ))}
+              </Box>
+            )}
+          </Box>
+        )}
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_charts/PaybackChart.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { MouseEvent } from 'react'
+import { useState } from 'react'
+
+import { CHART } from './chart-style.js'
+import { niceScale } from './nice-scale.js'
+import { useWidth } from './use-width.js'
+
+const MARGIN = { top: 16, right: 16, bottom: 26, left: 56 }
+const LINE = '#1f6f54'
+const YEAR_TICKS = [0, 5, 10, 15, 20, 25]
+
+const euro = (value: number) => {
+  return value.toLocaleString('en-IE', { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 })
+}
+
+interface PaybackChartProps {
+  readonly height: number
+}
+
+// The money the system has returned, year by year over the panels' 25 years, from the spec's `$cumulativeSavings`
+// expression: it starts at minus the system's cost and crosses zero in the payback year, which is marked. Moving the
+// pointer across the chart reads off any year.
+export const PaybackChart = ({ height }: PaybackChartProps) => {
+  const plan = phx.frontend.useRootEntityState()
+  const { ref, width } = useWidth()
+  const [year, setYear] = useState<number | null>(null)
+  const totals = plan.$cumulativeSavings
+  const lastYear = totals.length - 1
+  const { low, high, ticks } = niceScale(Math.min(...totals), Math.max(...totals, 0), 4)
+  const plotWidth = Math.max(width - MARGIN.left - MARGIN.right, 0)
+  const plotHeight = height - MARGIN.top - MARGIN.bottom
+  const x = (value: number) => MARGIN.left + (value / lastYear) * plotWidth
+  const y = (value: number) => MARGIN.top + ((high - value) / (high - low)) * plotHeight
+  const points = totals.map((total, index) => `${x(index)},${y(total)}`)
+  const payback = plan.$paybackYears
+  const paysBack = Number.isFinite(payback) && payback <= lastYear
+  const hoveredTotal = year === null ? null : totals[year]
+
+  const handleMove = (event: MouseEvent<SVGRectElement>) => {
+    const bounds = event.currentTarget.getBoundingClientRect()
+    const fraction = (event.clientX - bounds.left) / bounds.width
+
+    setYear(Math.min(lastYear, Math.max(0, Math.round(fraction * lastYear))))
+  }
+
+  return (
+    <Box component="div" ref={ref} sx={{ position: 'relative', blockSize: height }}>
+      {width > 0 && (
+        <svg
+          width={width}
+          height={height}
+          role="img"
+          aria-label={
+            paysBack
+              ? `The system pays back after ${payback.toFixed(1)} years`
+              : 'The system does not pay back within 25 years'
+          }
+        >
+          {ticks.map(tick => (
+            <g key={tick}>
+              <line
+                x1={MARGIN.left}
+                x2={width - MARGIN.right}
+                y1={y(tick)}
+                y2={y(tick)}
+                stroke={tick === 0 ? CHART.axis : CHART.grid}
+                strokeWidth={1}
+              />
+              <text
+                x={MARGIN.left - 8}
+                y={y(tick)}
+                textAnchor="end"
+                dominantBaseline="middle"
+                fill={CHART.inkSoft}
+                fontFamily={CHART.font}
+                fontSize={11}
+              >
+                {tick === 0 ? '€0' : `${tick < 0 ? '−' : ''}€${Math.abs(tick / 1000)}k`}
+              </text>
+            </g>
+          ))}
+          {YEAR_TICKS.map(tick => (
+            <text
+              key={tick}
+              x={x(tick)}
+              y={height - 8}
+              textAnchor="middle"
+              fill={CHART.inkSoft}
+              fontFamily={CHART.font}
+              fontSize={11}
+            >
+              {tick === 0 ? 'Year 0' : tick}
+            </text>
+          ))}
+
+          {/* A wash between the line and zero: what is still owed below, what is earned above */}
+          <polygon points={`${x(0)},${y(0)} ${points.join(' ')} ${x(lastYear)},${y(0)}`} fill={LINE} opacity={0.1} />
+          <polyline
+            points={points.join(' ')}
+            fill="none"
+            stroke={LINE}
+            strokeWidth={2}
+            strokeLinejoin="round"
+            strokeLinecap="round"
+          />
+
+          {paysBack && (
+            <g>
+              <line
+                x1={x(payback)}
+                x2={x(payback)}
+                y1={y(0)}
+                y2={MARGIN.top + plotHeight}
+                stroke={CHART.axis}
+                strokeWidth={1}
+              />
+              <circle cx={x(payback)} cy={y(0)} r={5} fill={LINE} stroke={CHART.surface} strokeWidth={2} />
+              {/* Right of the point the line runs above zero and left of it below, so the label takes the empty side */}
+              <text
+                x={x(payback) + (x(payback) > width * 0.7 ? -10 : 10)}
+                y={x(payback) > width * 0.7 ? y(0) - 10 : y(0) + 20}
+                textAnchor={x(payback) > width * 0.7 ? 'end' : 'start'}
+                fill={CHART.ink}
+                fontFamily={CHART.font}
+                fontSize={12}
+                fontWeight={600}
+              >
+                Pays back in year {Math.ceil(payback)}
+              </text>
+            </g>
+          )}
+
+          {year !== null && hoveredTotal !== undefined && hoveredTotal !== null && (
+            <g>
+              <line
+                x1={x(year)}
+                x2={x(year)}
+                y1={MARGIN.top}
+                y2={MARGIN.top + plotHeight}
+                stroke={CHART.inkSoft}
+                strokeWidth={1}
+              />
+              <circle cx={x(year)} cy={y(hoveredTotal)} r={4} fill={LINE} stroke={CHART.surface} strokeWidth={2} />
+            </g>
+          )}
+          <rect
+            x={MARGIN.left}
+            y={MARGIN.top}
+            width={plotWidth}
+            height={plotHeight}
+            fill="transparent"
+            onMouseMove={handleMove}
+            onMouseLeave={() => setYear(null)}
+          />
+        </svg>
+      )}
+
+      {year !== null && hoveredTotal !== undefined && hoveredTotal !== null && (
+        <Box
+          component="div"
+          role="tooltip"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: 0,
+            insetInlineStart: Math.min(Math.max(x(year) - 80, 0), Math.max(width - 160, 0)),
+            inlineSize: 160,
+            padding: 1.25,
+            borderRadius: 1.5,
+            bgcolor: CHART.surface,
+            boxShadow: '0 6px 24px rgba(28, 40, 38, 0.16)',
+            pointerEvents: 'none',
+          }}
+        >
+          <Typography sx={{ fontFamily: CHART.font, fontSize: 12, fontWeight: 600, color: CHART.ink }}>
+            After year {year}
+          </Typography>
+          <Typography sx={{ fontFamily: CHART.font, fontSize: 12, color: CHART.inkSoft }}>
+            {hoveredTotal >= 0 ? `${euro(hoveredTotal)} ahead` : `${euro(-hoveredTotal)} still to recover`}
+          </Typography>
+        </Box>
+      )}
+    </Box>
+  )
+}
+```
+
+### ./src/\_charts/chart-style.ts
+
+```ts
+// The charts' series colours, in a fixed order and checked as a set for colour-vision deficiencies on the white
+// card. Two of them sit below 3:1 against white, so every chart keeps a legend, a tooltip and a table of its figures.
+export const SERIES = {
+  selfUse: '#e8770e',
+  exported: '#1baf7a',
+  consumption: '#2a78d6',
+} as const
+
+export const CHART = {
+  surface: '#ffffff',
+  ink: '#1c2826',
+  inkSoft: '#5b6664',
+  grid: '#e9e6df',
+  axis: '#c9c4b8',
+  font: "'Poppins', 'Helvetica Neue', Arial, sans-serif",
+} as const
+```
+
+### ./src/\_charts/nice-scale.ts
+
+```ts
+// Round axis bounds and ticks for a value range: steps of 1, 2 or 5 times a power of ten, about `count` of them
+export const niceScale = (min: number, max: number, count: number) => {
+  const span = Math.max(max - min, 1)
+  const raw = span / count
+  const magnitude = 10 ** Math.floor(Math.log10(raw))
+  const step = [1, 2, 5, 10].map(factor => factor * magnitude).find(candidate => candidate >= raw) ?? 10 * magnitude
+  const low = Math.floor(min / step) * step
+  const high = Math.ceil(max / step) * step
+  const ticks = Array.from({ length: Math.round((high - low) / step) + 1 }, (_, index) => low + index * step)
+
+  return { low, high, ticks }
+}
+```
+
+### ./src/\_charts/use-width.ts
+
+```ts
+import { useLayoutEffect, useRef, useState } from 'react'
+
+// The element's width in pixels, measured again whenever it changes, so a chart draws its text at its real size
+// instead of scaling a fixed drawing
+export const useWidth = () => {
+  const ref = useRef<HTMLDivElement>(null)
+  const [width, setWidth] = useState(0)
+
+  useLayoutEffect(() => {
+    const element = ref.current
+
+    if (element === null) {
+      return
+    }
+
+    const observer = new ResizeObserver(([entry]) => {
+      if (entry) {
+        setWidth(entry.contentRect.width)
+      }
+    })
+    observer.observe(element)
+
+    return () => observer.disconnect()
+  }, [])
+
+  return { ref, width }
+}
+```
+
+### ./src/\_shared/ChartCards.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+
+import { EnergySplitBar, MonthlyEnergyChart, PaybackChart } from '../_charts/index.js'
+import { CARD_SX, SUNFOLD } from './tokens.js'
+
+interface ChartCardProps {
+  readonly title: string
+  readonly subtitle: string
+  readonly area?: string
+  readonly children: ReactNode
+}
+
+const ChartCard = ({ title, subtitle, area, children }: ChartCardProps) => {
+  return (
+    <Box
+      component="section"
+      aria-label={title}
+      sx={{ ...CARD_SX, display: 'grid', alignContent: 'start', gap: 2, gridArea: area }}
+    >
+      <Box component="header" sx={{ display: 'grid', gap: 0.25 }}>
+        <Typography component="h2" sx={{ fontFamily: SUNFOLD.font, fontSize: 16, fontWeight: 600, color: SUNFOLD.ink }}>
+          {title}
+        </Typography>
+        <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>{subtitle}</Typography>
+      </Box>
+      {children}
+    </Box>
+  )
+}
+
+interface ChartCardsProps {
+  readonly compact: boolean
+}
+
+// The dashboard's charts: the year month by month across the full width, then the payback curve beside where the
+// power goes. On a phone they stack.
+export const ChartCards = ({ compact }: ChartCardsProps) => {
+  return (
+    <Box
+      component="div"
+      sx={{
+        display: 'grid',
+        gap: 2,
+        gridTemplateColumns: compact ? 'minmax(0, 1fr)' : 'minmax(0, 3fr) minmax(0, 2fr)',
+        gridTemplateAreas: compact ? '"monthly" "payback" "split"' : '"monthly monthly" "payback split"',
+      }}
+    >
+      <ChartCard
+        area="monthly"
+        title="Your solar year"
+        subtitle="Production by month, how much the home uses, and the home's own use"
+      >
+        <MonthlyEnergyChart height={compact ? 200 : 240} />
+      </ChartCard>
+      <ChartCard
+        area="payback"
+        title="When it pays back"
+        subtitle="Money returned after the installed cost, with prices rising 2 % a year"
+      >
+        <PaybackChart height={compact ? 190 : 210} />
+      </ChartCard>
+      <ChartCard
+        area="split"
+        title="Where the power goes"
+        subtitle="A year of production, split between the home and the grid"
+      >
+        <EnergySplitBar />
+      </ChartCard>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/DesktopPage.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { ChartCards } from './ChartCards.js'
+import { KpiTiles } from './KpiTiles.js'
+import { PlannerInputs } from './PlannerInputs.js'
+import { SurveyPanel } from './SurveyPanel.js'
+import { SUNFOLD } from './tokens.js'
+
+const SIDEBAR_WIDTH = 340
+
+// The desktop page: the inputs in a sidebar with the cost and the booking at its foot, and the dashboard beside it,
+// four figures above three charts
+export const DesktopPage = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  // A booked plan keeps its inputs until the household returns to the plan
+  const readOnly = accessInfo.viewMode || navigationState === 'booked'
+
+  return (
+    <Box
+      component="div"
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'grid',
+        gridTemplateColumns: `${SIDEBAR_WIDTH}px minmax(0, 1fr)`,
+        bgcolor: SUNFOLD.linen,
+        fontFamily: SUNFOLD.font,
+      }}
+    >
+      <Box
+        component="aside"
+        aria-label="Your plan"
+        sx={{
+          display: 'flex',
+          flexDirection: 'column',
+          minBlockSize: 0,
+          bgcolor: SUNFOLD.card,
+          borderInlineEnd: `1px solid ${SUNFOLD.line}`,
+        }}
+      >
+        <Box
+          component="div"
+          sx={{ display: 'flex', alignItems: 'center', gap: 1.25, paddingInline: 3, paddingBlock: 2.5 }}
+        >
+          <Box
+            component="span"
+            aria-hidden
+            sx={{
+              inlineSize: 26,
+              blockSize: 26,
+              borderRadius: '50%',
+              bgcolor: SUNFOLD.amber,
+              boxShadow: `0 0 0 5px ${SUNFOLD.amberTint}`,
+            }}
+          />
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 20, fontWeight: 600, color: SUNFOLD.ink }}>
+            sunfold
+          </Typography>
+        </Box>
+        <Box component="div" sx={{ flex: 1, minBlockSize: 0, overflowY: 'auto', paddingInline: 3, paddingBlockEnd: 3 }}>
+          <PlannerInputs readOnly={readOnly} />
+        </Box>
+        <Box component="div" sx={{ padding: 3, borderBlockStart: `1px solid ${SUNFOLD.line}` }}>
+          <SurveyPanel compact={false} />
+        </Box>
+      </Box>
+
+      <Box component="main" sx={{ minBlockSize: 0, overflowY: 'auto' }}>
+        <Box component="div" sx={{ display: 'grid', gap: 2.5, maxInlineSize: 1180, marginInline: 'auto', padding: 4 }}>
+          <Box component="header" sx={{ display: 'grid', gap: 0.5 }}>
+            <Typography
+              component="h1"
+              sx={{ fontFamily: SUNFOLD.font, fontSize: 28, fontWeight: 600, color: SUNFOLD.ink }}
+            >
+              Your solar plan
+            </Typography>
+            <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 14, color: SUNFOLD.muted }}>
+              Estimates for a home in central Europe. Every figure follows the plan on the left.
+            </Typography>
+          </Box>
+          <KpiTiles columns={4} />
+          <ChartCards compact={false} />
+        </Box>
+      </Box>
+
+      {/* Snackbars, such as a failed save, stack upwards from the dashboard's bottom right corner */}
+      <Box component="div" sx={{ position: 'absolute', insetBlockEnd: 24, insetInlineEnd: 24, inlineSize: 320 }}>
+        <LayoutSlots.DesktopSnackbarsRoot />
+      </Box>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/KpiTiles.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { CARD_SX, SUNFOLD } from './tokens.js'
+
+const euro = (value: number) => {
+  return value.toLocaleString('en-IE', { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 })
+}
+
+interface KpiTilesProps {
+  readonly columns: number
+}
+
+// The four figures a household asks first, each with the context that makes it mean something. Every value is an
+// expression of the spec, read from the root entity.
+export const KpiTiles = ({ columns }: KpiTilesProps) => {
+  const plan = phx.frontend.useRootEntityState()
+  const payback = plan.$paybackYears
+  const tiles = [
+    {
+      label: 'System size',
+      value: `${plan.$systemKwp.toFixed(1)} kWp`,
+      context: `${plan.panels} panels, ${plan.$panelAreaM2} m² of roof`,
+    },
+    {
+      label: 'Annual production',
+      value: `${Math.round(plan.$annualProductionKwh).toLocaleString('en')} kWh`,
+      context: `About ${plan.$co2Tonnes.toFixed(1)} t of CO₂ avoided a year`,
+    },
+    {
+      label: 'Self-consumption',
+      value: `${Math.round(plan.$selfConsumption * 100)} %`,
+      context: 'of the solar power is used at home',
+    },
+    {
+      label: 'Payback',
+      value: Number.isFinite(payback) ? `${payback.toFixed(1)} years` : 'Over 25 years',
+      context: `${euro(plan.$annualSavings)} saved in the first year`,
+    },
+  ]
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gap: 2 }}>
+      {tiles.map(tile => (
+        <Box
+          component="section"
+          key={tile.label}
+          aria-label={tile.label}
+          sx={{ ...CARD_SX, display: 'grid', gap: 0.5, padding: 2 }}
+        >
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 13, color: SUNFOLD.muted }}>{tile.label}</Typography>
+          <Typography
+            sx={{
+              fontFamily: SUNFOLD.font,
+              fontSize: columns > 2 ? 30 : 24,
+              fontWeight: 600,
+              lineHeight: 1.15,
+              color: SUNFOLD.ink,
+            }}
+          >
+            {tile.value}
+          </Typography>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>{tile.context}</Typography>
+        </Box>
+      ))}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/PhonePage.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { ChartCards } from './ChartCards.js'
+import { KpiTiles } from './KpiTiles.js'
+import { PlannerInputs } from './PlannerInputs.js'
+import { SurveyPanel } from './SurveyPanel.js'
+import { CARD_SX, SUNFOLD } from './tokens.js'
+
+// The phone page: one scrolling column with the figures first, the inputs below them and the charts last, and the
+// cost with the booking in a bar at the bottom
+export const PhonePage = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const readOnly = accessInfo.viewMode || navigationState === 'booked'
+
+  return (
+    <Box
+      component="div"
+      sx={{
+        position: 'absolute',
+        inset: 0,
+        display: 'grid',
+        gridTemplateRows: 'minmax(0, 1fr) auto',
+        bgcolor: SUNFOLD.linen,
+        fontFamily: SUNFOLD.font,
+      }}
+    >
+      <Box component="main" sx={{ minBlockSize: 0, overflowY: 'auto' }}>
+        <Box component="div" sx={{ display: 'grid', gap: 2, padding: 2 }}>
+          <Box component="header" sx={{ display: 'flex', alignItems: 'center', gap: 1.25 }}>
+            <Box
+              component="span"
+              aria-hidden
+              sx={{
+                inlineSize: 22,
+                blockSize: 22,
+                borderRadius: '50%',
+                bgcolor: SUNFOLD.amber,
+                boxShadow: `0 0 0 4px ${SUNFOLD.amberTint}`,
+              }}
+            />
+            <Typography
+              component="h1"
+              sx={{ fontFamily: SUNFOLD.font, fontSize: 20, fontWeight: 600, color: SUNFOLD.ink }}
+            >
+              Your solar plan
+            </Typography>
+          </Box>
+          <KpiTiles columns={2} />
+          <Box component="div" sx={CARD_SX}>
+            <PlannerInputs readOnly={readOnly} />
+          </Box>
+          <ChartCards compact />
+        </Box>
+      </Box>
+      <Box
+        component="footer"
+        sx={{
+          padding: 2,
+          bgcolor: SUNFOLD.card,
+          borderBlockStart: `1px solid ${SUNFOLD.line}`,
+          boxShadow: '0 -8px 24px rgba(28, 40, 38, 0.08)',
+        }}
+      >
+        <SurveyPanel compact />
+      </Box>
+      <LayoutSlots.MobileSnackbarsRoot />
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/PillField.tsx
+
+```tsx
+import { Box, ButtonBase, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import { SUNFOLD } from './tokens.js'
+
+// Arrow keys move the selection between the pills, as in a native radio group
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface PillFieldProps {
+  readonly instanceName: string
+  readonly label: string
+  readonly readOnly: boolean
+}
+
+// One `attributeSelection` of the spec as a row of pills, with the chosen option's description below it
+export const PillField = ({ instanceName, label, readOnly }: PillFieldProps) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const planId = phx.frontend.useRootEntityId()
+  const { value, options } = phx.frontend.useAttributeSelection(planId, instanceName)
+  const selected = options.find(option => option.value === value)
+  const labelId = `sunfold-${instanceName}-label`
+
+  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 (
+    <Box component="div" sx={{ display: 'grid', gap: 0.75 }}>
+      <Typography id={labelId} sx={{ fontFamily: SUNFOLD.font, fontSize: 14, color: SUNFOLD.ink }}>
+        {label}
+      </Typography>
+      <Box
+        component="div"
+        role="radiogroup"
+        aria-labelledby={labelId}
+        sx={{ display: 'flex', flexWrap: 'wrap', gap: 0.75 }}
+      >
+        {options.map((option, index) => {
+          const isSelected = option.value === value
+
+          return (
+            <ButtonBase
+              key={String(option.value)}
+              role="radio"
+              aria-checked={isSelected}
+              tabIndex={isSelected ? 0 : -1}
+              disabled={readOnly && !isSelected}
+              onClick={readOnly ? undefined : option.onSelect}
+              onKeyDown={readOnly ? undefined : event => handleKeyDown(event, index)}
+              sx={{
+                paddingInline: 1.5,
+                paddingBlock: 0.75,
+                borderRadius: 999,
+                border: `1px solid ${isSelected ? SUNFOLD.green : SUNFOLD.line}`,
+                bgcolor: isSelected ? SUNFOLD.green : SUNFOLD.card,
+                color: isSelected ? SUNFOLD.card : SUNFOLD.ink,
+                fontFamily: SUNFOLD.font,
+                fontSize: 13,
+                fontWeight: isSelected ? 500 : 400,
+                transition: 'background-color 120ms',
+                '&:hover': { borderColor: SUNFOLD.green },
+                '&.Mui-focusVisible': { outline: `2px solid ${SUNFOLD.amber}`, outlineOffset: 2 },
+              }}
+            >
+              {resolve(option.title)}
+            </ButtonBase>
+          )
+        })}
+      </Box>
+      {selected?.description && (
+        <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>
+          {resolve(selected.description)}
+        </Typography>
+      )}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/PlannerInputs.tsx
+
+```tsx
+import { Box, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+
+import { PillField } from './PillField.js'
+import { SliderField } from './SliderField.js'
+import { SUNFOLD } from './tokens.js'
+
+interface GroupProps {
+  readonly title: string
+  // The invariant types whose message belongs under this group
+  readonly messageTypes?: readonly string[]
+  readonly children: ReactNode
+}
+
+// A group of inputs with the message of an invariant the group can resolve: a warning, which blocks the booking, in
+// amber, a notice, which only informs, in blue. `useFinalizeViolations` lists both.
+const Group = ({ title, messageTypes = [], children }: GroupProps) => {
+  const { violations } = phx.frontend.useFinalizeViolations()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const messages = (violations ?? []).filter(({ violation }) => messageTypes.includes(violation.type))
+
+  return (
+    <Box component="section" sx={{ display: 'grid', gap: 2 }}>
+      <Typography component="h3" sx={{ fontFamily: SUNFOLD.font, fontSize: 13, fontWeight: 600, color: SUNFOLD.muted }}>
+        {title}
+      </Typography>
+      {children}
+      {messages.map(({ violation }) => {
+        const isNotice = violation.severity === 'notice'
+
+        return (
+          <Typography
+            key={violation.type}
+            role={isNotice ? 'status' : 'alert'}
+            sx={{
+              paddingInline: 1.5,
+              paddingBlock: 1,
+              borderRadius: 2,
+              bgcolor: isNotice ? SUNFOLD.infoTint : SUNFOLD.warningTint,
+              color: isNotice ? SUNFOLD.info : SUNFOLD.warning,
+              fontFamily: SUNFOLD.font,
+              fontSize: 13,
+              lineHeight: 1.45,
+            }}
+          >
+            {resolve(violation.message)}
+          </Typography>
+        )
+      })}
+    </Box>
+  )
+}
+
+interface PlannerInputsProps {
+  readonly readOnly: boolean
+}
+
+// The household's inputs: the roof, the panels on it, the home's use and tariff, and the battery
+export const PlannerInputs = ({ readOnly }: PlannerInputsProps) => {
+  const plan = phx.frontend.useRootEntityState()
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 3.5 }}>
+      <Group title="Your roof" messageTypes={['panelsExceedRoof', 'northFacing']}>
+        <SliderField instanceName="roofArea" label="Usable roof area" step={1} readOnly={readOnly} />
+        <PillField instanceName="orientation" label="Facing" readOnly={readOnly} />
+        <SliderField instanceName="panels" label="Panels" step={1} readOnly={readOnly} />
+        <Typography sx={{ marginBlockStart: -1.5, fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>
+          430 W panels, 1.95 m² each. This roof holds up to {plan.$roofPanelLimit}.
+        </Typography>
+      </Group>
+      <Group title="Your home">
+        <SliderField instanceName="annualUse" label="Electricity used a year" step={100} readOnly={readOnly} />
+        <PillField instanceName="tariff" label="Tariff" readOnly={readOnly} />
+      </Group>
+      <Group title="Storage">
+        <PillField instanceName="battery" label="Home battery" readOnly={readOnly} />
+      </Group>
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/SliderField.tsx
+
+```tsx
+import { Box, Slider, Typography } from '@mui/material'
+
+import { SUNFOLD } from './tokens.js'
+
+interface SliderFieldProps {
+  readonly instanceName: string
+  readonly label: string
+  readonly step: number
+  readonly readOnly: boolean
+}
+
+// One `genericDimension` of the spec as a slider with its value and unit above it. Dragging stages each value, so
+// every tile and chart follows the thumb, and letting go commits it.
+export const SliderField = ({ instanceName, label, step, readOnly }: SliderFieldProps) => {
+  const planId = phx.frontend.useRootEntityId()
+  const dimension = phx.frontend.useGenericDimension(planId, instanceName)
+  const labelId = `sunfold-${instanceName}-label`
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 0.25 }}>
+      <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 2 }}>
+        <Typography id={labelId} sx={{ fontFamily: SUNFOLD.font, fontSize: 14, color: SUNFOLD.ink }}>
+          {label}
+        </Typography>
+        <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 15, fontWeight: 600, color: SUNFOLD.ink }}>
+          {dimension.value.toLocaleString('en')} {dimension.unit}
+        </Typography>
+      </Box>
+      <Slider
+        value={dimension.value}
+        min={dimension.min ?? 0}
+        max={dimension.max ?? 100}
+        step={step}
+        disabled={readOnly}
+        onChange={(_, value) => dimension.update(Array.isArray(value) ? (value[0] ?? 0) : value)}
+        onChangeCommitted={() => dimension.resolve()}
+        slotProps={{ input: { 'aria-labelledby': labelId } }}
+        sx={{
+          color: SUNFOLD.green,
+          '& .MuiSlider-rail': { bgcolor: SUNFOLD.line, opacity: 1 },
+          '& .MuiSlider-thumb': {
+            inlineSize: 18,
+            blockSize: 18,
+            bgcolor: SUNFOLD.card,
+            border: `3px solid ${SUNFOLD.green}`,
+          },
+        }}
+      />
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/SurveyPanel.tsx
+
+```tsx
+import { Alert, Box, Button, CircularProgress, Typography } from '@mui/material'
+
+import { SUNFOLD } from './tokens.js'
+
+interface SurveyPanelProps {
+  // On a phone the panel is a bar: the cost beside the button, without the hints
+  readonly compact: boolean
+}
+
+// The system's cost, the `price` component's value, and the spec's `survey` finalize action. A warning blocks the
+// booking and its `hints` say why; a notice does not. In the `booked` navigation state the panel confirms the
+// request instead.
+export const SurveyPanel = ({ compact }: SurveyPanelProps) => {
+  const cost = phx.frontend.useRootEntityPrice()
+  const { primary, hints } = phx.frontend.useFinalizeActions()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const navigate = phx.frontend.useNavigate()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const isPending = primary?.isPending ?? false
+
+  if (navigationState === 'booked') {
+    return (
+      <Box component="div" role="status" sx={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+        <Box component="div" sx={{ display: 'grid', flex: 1 }}>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 16, fontWeight: 600, color: SUNFOLD.green }}>
+            Survey requested
+          </Typography>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 13, color: SUNFOLD.muted }}>
+            An installer calls within two working days.
+          </Typography>
+        </Box>
+        <Button
+          onClick={() => navigate('plan')}
+          sx={{
+            fontFamily: SUNFOLD.font,
+            fontSize: 13,
+            color: SUNFOLD.ink,
+            textTransform: 'none',
+            textDecoration: 'underline',
+          }}
+        >
+          Back to the plan
+        </Button>
+      </Box>
+    )
+  }
+
+  const showButton = primary !== null && !accessInfo.viewMode
+
+  return (
+    <Box component="div" sx={{ display: 'grid', gap: 1.25 }}>
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          flexDirection: compact ? 'row' : 'column',
+          alignItems: compact ? 'center' : 'stretch',
+          justifyContent: 'space-between',
+          gap: compact ? 2 : 1.5,
+        }}
+      >
+        <Box component="div" sx={{ display: 'grid' }}>
+          <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.muted }}>Installed cost</Typography>
+          <Typography
+            sx={{ fontFamily: SUNFOLD.font, fontSize: compact ? 20 : 26, fontWeight: 600, color: SUNFOLD.ink }}
+          >
+            {cost}
+          </Typography>
+        </Box>
+        {showButton && (
+          <Button
+            variant="contained"
+            disableElevation
+            disabled={primary.disabled || isPending}
+            onClick={() => void primary.run()}
+            title={primary.title}
+            startIcon={isPending ? <CircularProgress size={16} color="inherit" /> : undefined}
+            sx={{
+              minBlockSize: 46,
+              paddingInline: 2.5,
+              borderRadius: 999,
+              bgcolor: SUNFOLD.green,
+              fontFamily: SUNFOLD.font,
+              fontSize: 14,
+              fontWeight: 500,
+              textTransform: 'none',
+              '&:hover': { bgcolor: SUNFOLD.greenDark },
+              '&.Mui-disabled': { bgcolor: SUNFOLD.line, color: SUNFOLD.muted },
+            }}
+          >
+            {isPending ? 'Booking…' : primary.label}
+          </Button>
+        )}
+      </Box>
+      {!compact && showButton && primary.disabled && hints && (
+        <Typography sx={{ fontFamily: SUNFOLD.font, fontSize: 12, color: SUNFOLD.warning }}>{hints}</Typography>
+      )}
+      {primary?.error && <Alert severity="error">The survey could not be booked: {primary.error.message}</Alert>}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/tokens.ts
+
+```ts
+// Sunfold's palette and type: warm linen, a deep green ink and the amber of the logo. Poppins is the brand's typeface;
+// the stack falls back to system fonts where it is not loaded.
+export const SUNFOLD = {
+  linen: '#f6f3ec',
+  card: '#ffffff',
+  ink: '#1c2826',
+  muted: '#5b6664',
+  line: '#e7e2d8',
+  green: '#1f6f54',
+  greenDark: '#17583f',
+  amber: '#f2a516',
+  amberTint: '#fff4dc',
+  warning: '#9a4b00',
+  warningTint: '#fff3e0',
+  info: '#2a5c8a',
+  infoTint: '#e9f1f9',
+  font: "'Poppins', 'Helvetica Neue', Arial, sans-serif",
+} as const
+
+export const CARD_SX = {
+  padding: 2.5,
+  borderRadius: 3,
+  bgcolor: SUNFOLD.card,
+  boxShadow: '0 1px 2px rgba(28, 40, 38, 0.06)',
+  border: `1px solid ${SUNFOLD.line}`,
+} as const
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { DesktopPage } from '../_shared/DesktopPage.js'
+import { PhonePage } from '../_shared/PhonePage.js'
+import { SUNFOLD } from '../_shared/tokens.js'
+
+// A planning dashboard with no scene: the layout never mounts `LayoutSlots.SharedCanvas`, and every tile and chart is
+// React and SVG drawn from the spec's expressions
+const ConfiguratorLayout = () => {
+  // `null` until the container has been measured
+  const viewports = phx.frontend.useActiveViewports()
+  const isDesktop = viewports?.includes('desktop') ?? false
+
+  return (
+    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: SUNFOLD.linen }}>
+      <LayoutSlots.Services />
+      {viewports !== null && (isDesktop ? <DesktopPage /> : <PhonePage />)}
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/expressions/solar.ts
+
+```ts
+const PANEL_KWP = 0.43
+const PANEL_AREA_M2 = 1.95
+// Vents, chimneys and the edge clearance leave about 85 % of a roof for panels
+const USABLE_ROOF = 0.85
+// A south-facing kWp in central Europe yields about 1,000 kWh a year
+const YIELD_KWH_PER_KWP = 1000
+const ORIENTATION_FACTOR = { South: 1, SouthEastWest: 0.95, EastWest: 0.82, North: 0.6 }
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+// The share of the year's sun and of the household's use that falls in each month
+const SUN_SHARE = [0.04, 0.045, 0.08, 0.105, 0.125, 0.13, 0.13, 0.115, 0.09, 0.065, 0.04, 0.035]
+const USE_SHARE = [0.1, 0.09, 0.088, 0.08, 0.075, 0.07, 0.07, 0.072, 0.076, 0.085, 0.094, 0.1]
+const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+const BATTERY_KWH = { None: 0, Kwh5: 5, Kwh10: 10, Kwh15: 15 }
+const BATTERY_PRICE = { None: 0, Kwh5: 3600, Kwh10: 6400, Kwh15: 8900 }
+const TARIFF = {
+  Flat: { buy: 0.32, sell: 0.08, shiftBonus: 0 },
+  TimeOfUse: { buy: 0.29, sell: 0.1, shiftBonus: 0.09 },
+  ExportPlus: { buy: 0.32, sell: 0.15, shiftBonus: 0 },
+}
+// Panels lose half a percent a year; electricity gets 2 % dearer a year
+const DEGRADATION = 0.995
+const PRICE_GROWTH = 1.02
+const YEARS = 25
+
+export default phx.domain.implementCustomExpressions({
+  SolarPlan: {
+    $systemKwp: s => {
+      return s.panels * PANEL_KWP
+    },
+    $roofPanelLimit: s => {
+      return Math.floor((s.roofArea * USABLE_ROOF) / PANEL_AREA_M2)
+    },
+    // The roof the panels cover, rounded up to whole square metres, as the tiles and the roof warning quote it
+    $panelAreaM2: s => {
+      return Math.ceil(s.panels * PANEL_AREA_M2)
+    },
+    $annualProductionKwh: s => {
+      return s.$systemKwp * YIELD_KWH_PER_KWP * ORIENTATION_FACTOR[s.orientation]
+    },
+    // Each month's production and use, and how the production splits between the home and the grid. Without a
+    // battery the home uses solar power only while the sun shines; a battery carries the surplus into the evening,
+    // one charge a day, and covers the evening but not the early morning.
+    $monthly: s => {
+      const batteryKwh = BATTERY_KWH[s.battery] * 0.9
+
+      return MONTHS.map((month, index) => {
+        const productionKwh = s.$annualProductionKwh * (SUN_SHARE[index] ?? 0)
+        const consumptionKwh = s.annualUse * (USE_SHARE[index] ?? 0)
+        const direct = Math.min(productionKwh * 0.55, consumptionKwh * 0.45)
+        const stored = Math.min(
+          productionKwh - direct,
+          batteryKwh * (DAYS[index] ?? 30),
+          (consumptionKwh - direct) * 0.6
+        )
+        const selfUseKwh = direct + stored
+
+        return { month, productionKwh, consumptionKwh, selfUseKwh, exportKwh: productionKwh - selfUseKwh }
+      })
+    },
+    $selfConsumption: s => {
+      const selfUse = s.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+
+      return s.$annualProductionKwh > 0 ? selfUse / s.$annualProductionKwh : 0
+    },
+    $selfSufficiency: s => {
+      const selfUse = s.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+
+      return selfUse / s.annualUse
+    },
+    // A year's saving: power the home no longer buys, power sold to the grid, and on a time-of-use tariff the
+    // evening power a battery shifts away from the dear hours
+    $annualSavings: s => {
+      const tariff = TARIFF[s.tariff]
+      const selfUse = s.$monthly.reduce((sum, month) => sum + month.selfUseKwh, 0)
+      const exported = s.$monthly.reduce((sum, month) => sum + month.exportKwh, 0)
+      const shifted = s.battery === 'None' ? 0 : selfUse * 0.4
+
+      return selfUse * tariff.buy + exported * tariff.sell + shifted * tariff.shiftBonus
+    },
+    $systemCost: s => {
+      return Math.round(1500 + s.$systemKwp * 1050 + BATTERY_PRICE[s.battery])
+    },
+    // The money the system has returned at the end of each year, starting at minus its cost in year 0
+    $cumulativeSavings: s => {
+      return Array.from({ length: YEARS + 1 }, (_, year) => {
+        const earned = Array.from(
+          { length: year },
+          (__, past) => s.$annualSavings * (PRICE_GROWTH * DEGRADATION) ** past
+        ).reduce((sum, value) => sum + value, 0)
+
+        return earned - s.$systemCost
+      })
+    },
+    // The year the running total crosses zero, between whole years; beyond the panels' 25 years it is `Infinity`
+    $paybackYears: s => {
+      const totals = s.$cumulativeSavings
+      const year = totals.findIndex(total => total >= 0)
+
+      if (year <= 0) {
+        return year === 0 ? 0 : Infinity
+      }
+
+      const before = totals[year - 1] ?? 0
+      const after = totals[year] ?? 0
+
+      return year - 1 + -before / (after - before)
+    },
+    $co2Tonnes: s => {
+      return (s.$annualProductionKwh * 0.35) / 1000
+    },
+  },
+})
+```
+
+### ./src/handlers/book-survey.ts
+
+```ts
+import { useCallback } from 'react'
+
+// Stands in for the installer's booking service: the request takes a moment, then the page shows the confirmation
+export default phx.frontend.createPhoenixHandler('bookSurvey', () => {
+  const navigate = phx.frontend.useNavigate()
+
+  return {
+    handler: useCallback(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1200))
+      navigate('booked')
+    }, [navigate]),
+  }
+})
+```
+
+### ./src/invariants/solar.ts
+
+```ts
+// More panels than the roof holds is a warning: the dashboard keeps showing the figures, and a survey cannot be
+// booked until the panel count fits. A north-facing roof is only a notice, so it never blocks the booking.
+export default phx.domain.implementCustomInvariants({
+  SolarPlan: {
+    panelsFitRoof: s => {
+      if (s.panels <= s.$roofPanelLimit) {
+        return []
+      }
+
+      return [
+        {
+          type: 'panelsExceedRoof',
+          severity: 'warning',
+          message: `${s.panels} panels need about ${s.$panelAreaM2} m² of roof; ${s.roofArea} m² holds at most ${s.$roofPanelLimit}. Lower the panel count or measure the roof again.`,
+        },
+      ]
+    },
+    northFacing: s => {
+      return s.orientation !== 'North'
+    },
+  },
+})
+```
+
+</details>