From 9ebc3828ba2c0266338a26484903b2d815dc18ee Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 16:37:40 +0100
Subject: [PATCH 01/40] feat: add minimal preview base layout for page type
 previews

---
 src/server/plugins/engine/views/preview-layout.html | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 src/server/plugins/engine/views/preview-layout.html

diff --git a/src/server/plugins/engine/views/preview-layout.html b/src/server/plugins/engine/views/preview-layout.html
new file mode 100644
index 000000000..cb0dbe444
--- /dev/null
+++ b/src/server/plugins/engine/views/preview-layout.html
@@ -0,0 +1 @@
+{% block content %}{% endblock %}

From e187021f669f064492035a259ea6d128f1e2bda7 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 16:39:47 +0100
Subject: [PATCH 02/40] feat: add generate-page-previews module with renderPage
 and writePagePreviewPartial

---
 scripts/generate-page-previews.js      |  44 ++++++++
 scripts/generate-page-previews.test.js | 139 +++++++++++++++++++++++++
 2 files changed, 183 insertions(+)
 create mode 100644 scripts/generate-page-previews.js
 create mode 100644 scripts/generate-page-previews.test.js

diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
new file mode 100644
index 000000000..63c5bb135
--- /dev/null
+++ b/scripts/generate-page-previews.js
@@ -0,0 +1,44 @@
+import fs from 'fs'
+import path from 'path'
+
+import { buildPartialMdx } from './generate-component-previews.js'
+
+import { environment } from '~/src/server/plugins/nunjucks/environment.js'
+
+/**
+ * Render a single page fixture context to an HTML string.
+ * Passes baseLayoutPath: 'preview-layout.html' to strip the GOV.UK page wrapper,
+ * leaving only the {% block content %} output from the page template.
+ * @param {object} context
+ * @param {string} viewName
+ * @returns {string}
+ */
+export function renderPage(context, viewName) {
+  return environment.render(`${viewName}.html`, {
+    ...context,
+    baseLayoutPath: 'preview-layout.html'
+  })
+}
+
+/**
+ * Renders all variants (or single context) for a page fixture and writes the
+ * MDX partial to previewsDir/<slug>.mdx.
+ * @param {string} previewsDir
+ * @param {string} slug
+ * @param {{ viewName: string, context?: object, variants?: Array<{label: string, context: object}> }} fixture
+ */
+export function writePagePreviewPartial(previewsDir, slug, fixture) {
+  fs.mkdirSync(previewsDir, { recursive: true })
+
+  const renders = fixture.variants
+    ? fixture.variants.map(({ label, context }) => ({
+        label,
+        html: renderPage(context, fixture.viewName)
+      }))
+    : [{ html: renderPage(fixture.context, fixture.viewName) }]
+
+  fs.writeFileSync(
+    path.join(previewsDir, `${slug}.mdx`),
+    buildPartialMdx(renders)
+  )
+}
diff --git a/scripts/generate-page-previews.test.js b/scripts/generate-page-previews.test.js
new file mode 100644
index 000000000..9a257b2c2
--- /dev/null
+++ b/scripts/generate-page-previews.test.js
@@ -0,0 +1,139 @@
+// @ts-nocheck
+
+jest.mock('fs', () => ({
+  mkdirSync: jest.fn(),
+  writeFileSync: jest.fn()
+}))
+
+jest.mock('~/src/server/plugins/nunjucks/environment.js', () => ({
+  environment: { render: jest.fn() }
+}))
+
+jest.mock('./generate-component-previews.js', () => ({
+  buildPartialMdx: jest.fn().mockReturnValue('<Preview MDX />')
+}))
+
+import { mkdirSync, writeFileSync } from 'fs'
+
+import { buildPartialMdx } from './generate-component-previews.js'
+import {
+  renderPage,
+  writePagePreviewPartial
+} from './generate-page-previews.js'
+
+import { environment } from '~/src/server/plugins/nunjucks/environment.js'
+
+describe('renderPage', () => {
+  beforeEach(() => {
+    environment.render.mockReturnValue('<h1 class="govuk-heading-l">Page</h1>')
+  })
+
+  it('calls environment.render with the correct template name', () => {
+    renderPage({ pageTitle: 'Test' }, 'index')
+    expect(environment.render).toHaveBeenCalledWith(
+      'index.html',
+      expect.objectContaining({ pageTitle: 'Test' })
+    )
+  })
+
+  it('overrides baseLayoutPath with preview-layout.html', () => {
+    renderPage(
+      { pageTitle: 'Test', baseLayoutPath: 'something-else.html' },
+      'summary'
+    )
+    expect(environment.render).toHaveBeenCalledWith(
+      'summary.html',
+      expect.objectContaining({ baseLayoutPath: 'preview-layout.html' })
+    )
+  })
+
+  it('returns the rendered HTML string', () => {
+    environment.render.mockReturnValue('<h1>Check your answers</h1>')
+    const result = renderPage({ pageTitle: 'Check your answers' }, 'summary')
+    expect(result).toBe('<h1>Check your answers</h1>')
+  })
+})
+
+describe('writePagePreviewPartial', () => {
+  beforeEach(() => {
+    environment.render.mockReturnValue('<div>page html</div>')
+    buildPartialMdx.mockReturnValue('<Preview MDX />')
+  })
+
+  it('creates the output directory', () => {
+    writePagePreviewPartial('/out/_previews', 'page-controller', {
+      viewName: 'index',
+      context: { pageTitle: 'Question' }
+    })
+    expect(mkdirSync).toHaveBeenCalledWith('/out/_previews', {
+      recursive: true
+    })
+  })
+
+  it('writes MDX to the correct path', () => {
+    writePagePreviewPartial('/out/_previews', 'summary-page-controller', {
+      viewName: 'summary',
+      context: { pageTitle: 'Check your answers' }
+    })
+    expect(writeFileSync).toHaveBeenCalledWith(
+      '/out/_previews/summary-page-controller.mdx',
+      '<Preview MDX />'
+    )
+  })
+
+  it('passes a single unlabelled render to buildPartialMdx for a flat fixture', () => {
+    writePagePreviewPartial('/out/_previews', 'page-controller', {
+      viewName: 'index',
+      context: { pageTitle: 'Question' }
+    })
+    expect(buildPartialMdx).toHaveBeenCalledWith([
+      { html: '<div>page html</div>' }
+    ])
+  })
+
+  it('passes labelled renders to buildPartialMdx for a variant fixture', () => {
+    writePagePreviewPartial('/out/_previews', 'file-upload-page-controller', {
+      viewName: 'file-upload',
+      variants: [
+        { label: 'No files uploaded', context: { pageTitle: 'Upload' } },
+        { label: 'With files uploaded', context: { pageTitle: 'Upload' } }
+      ]
+    })
+    expect(buildPartialMdx).toHaveBeenCalledWith([
+      { label: 'No files uploaded', html: '<div>page html</div>' },
+      { label: 'With files uploaded', html: '<div>page html</div>' }
+    ])
+  })
+
+  it('renders each variant context independently', () => {
+    environment.render
+      .mockReturnValueOnce('<div>empty</div>')
+      .mockReturnValueOnce('<div>with files</div>')
+
+    writePagePreviewPartial('/out/_previews', 'file-upload-page-controller', {
+      viewName: 'file-upload',
+      variants: [
+        {
+          label: 'No files uploaded',
+          context: { pageTitle: 'Upload', formAction: null }
+        },
+        {
+          label: 'With files uploaded',
+          context: { pageTitle: 'Upload', formAction: 'preview' }
+        }
+      ]
+    })
+
+    expect(environment.render).toHaveBeenCalledTimes(2)
+    expect(environment.render).toHaveBeenNthCalledWith(
+      1,
+      'file-upload.html',
+      expect.objectContaining({ formAction: null })
+    )
+    expect(environment.render).toHaveBeenNthCalledWith(
+      2,
+      'file-upload.html',
+      expect.objectContaining({ formAction: 'preview' })
+    )
+  })
+})

From f63c8d4b6cbe4cf7cd762bb543706469f32578c0 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 16:57:08 +0100
Subject: [PATCH 03/40] feat: export generatePageMd and add previewSlug support
 for page type previews

---
 scripts/generate-component-docs.js      | 14 ++++++-
 scripts/generate-component-docs.test.js | 51 ++++++++++++++++++++++++-
 2 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/scripts/generate-component-docs.js b/scripts/generate-component-docs.js
index 81458ec01..84838f918 100644
--- a/scripts/generate-component-docs.js
+++ b/scripts/generate-component-docs.js
@@ -895,11 +895,12 @@ export function generatePageExample(
  * @param {string} examplePath
  * @param {number} sidebarPosition
  */
-function generatePageMd(
+export function generatePageMd(
   controllerKey,
   uniqueProps,
   examplePath,
-  sidebarPosition
+  sidebarPosition,
+  previewSlug = null
 ) {
   const description = metadata.pages[controllerKey]
   if (!description) return null
@@ -908,11 +909,16 @@ function generatePageMd(
   const isDefault = controllerKey === 'PageController'
   const links = metadata.pageLinks?.[controllerKey] ?? []
 
+  const previewImport = previewSlug
+    ? [``, `import Preview from './_previews/${previewSlug}.mdx'`]
+    : []
+
   const lines = [
     `---`,
     `sidebar_label: "${label}"`,
     `sidebar_position: ${sidebarPosition}`,
     `---`,
+    ...previewImport,
     ``,
     `# ${label}`,
     ``,
@@ -933,6 +939,10 @@ function generatePageMd(
     lines.push(`**Controller value:** \`"${controllerKey}"\``, ``)
   }
 
+  if (previewSlug) {
+    lines.push(`## Preview`, ``, `<Preview />`, ``)
+  }
+
   lines.push(
     `## JSON definition`,
     ``,
diff --git a/scripts/generate-component-docs.test.js b/scripts/generate-component-docs.test.js
index 74823e0b3..48031b662 100644
--- a/scripts/generate-component-docs.test.js
+++ b/scripts/generate-component-docs.test.js
@@ -39,7 +39,7 @@ jest.mock('fs', () => ({
   readdirSync: jest.fn(),
   readFileSync: jest.fn().mockImplementation((filePath) => {
     if (String(filePath ?? '').includes('component-metadata.json')) {
-      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
+      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
     }
     return ''
   }),
@@ -55,6 +55,7 @@ import {
   generateComponentMd,
   generateExample,
   generatePageExample,
+  generatePageMd,
   placeholderForType,
   setNestedValue,
   simplifyType,
@@ -289,6 +290,54 @@ describe('Component Documentation Generator', () => {
     })
   })
 
+  describe('generatePageMd with preview', () => {
+    it('includes preview import when previewSlug is provided', () => {
+      const result = generatePageMd(
+        'PageController',
+        [],
+        '/page-path',
+        1,
+        'page-controller'
+      )
+      expect(result).toContain(
+        "import Preview from './_previews/page-controller.mdx'"
+      )
+    })
+
+    it('includes ## Preview section and <Preview /> when previewSlug is provided', () => {
+      const result = generatePageMd(
+        'PageController',
+        [],
+        '/page-path',
+        1,
+        'page-controller'
+      )
+      expect(result).toContain('## Preview')
+      expect(result).toContain('<Preview />')
+    })
+
+    it('places ## Preview before ## JSON definition', () => {
+      const result = generatePageMd(
+        'SummaryPageController',
+        [],
+        '/summary',
+        1,
+        'summary-page-controller'
+      )
+      const previewIdx = result.indexOf('## Preview')
+      const jsonIdx = result.indexOf('## JSON definition')
+      expect(previewIdx).toBeGreaterThan(-1)
+      expect(previewIdx).toBeLessThan(jsonIdx)
+    })
+
+    it('omits import, ## Preview, and <Preview /> when previewSlug is absent', () => {
+      const result = generatePageMd('PageController', [], '/page-path', 1)
+      expect(result).not.toContain('import Preview')
+      expect(result).not.toContain('## Preview')
+      expect(result).not.toContain('<Preview />')
+    })
+  })
+
   describe('controllerLabel', () => {
     it('strips Controller suffix and formats words', () => {
       expect(controllerLabel('RepeatPageController')).toBe('Repeat Page')

From 460974ba708cacc8b4d1b07e1dcb4d4174b24864 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 17:03:05 +0100
Subject: [PATCH 04/40] docs: add missing JSDoc @param for previewSlug in
 generatePageMd

---
 scripts/generate-component-docs.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/generate-component-docs.js b/scripts/generate-component-docs.js
index 84838f918..2f7c527e4 100644
--- a/scripts/generate-component-docs.js
+++ b/scripts/generate-component-docs.js
@@ -894,6 +894,7 @@ export function generatePageExample(
  * @param {Array<{name: string, type: string, optional: boolean}>} uniqueProps
  * @param {string} examplePath
  * @param {number} sidebarPosition
+ * @param {string|null} [previewSlug]
  */
 export function generatePageMd(
   controllerKey,

From 365b4478ab3e103abd378a8d3e414be7eb396117 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 17:22:28 +0100
Subject: [PATCH 05/40] feat: add page-preview-fixtures with static context for
 all 6 page types

---
 scripts/page-preview-fixtures.js      | 190 ++++++++++++++++++++++++++
 scripts/page-preview-fixtures.test.js |  70 ++++++++++
 2 files changed, 260 insertions(+)
 create mode 100644 scripts/page-preview-fixtures.js
 create mode 100644 scripts/page-preview-fixtures.test.js

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
new file mode 100644
index 000000000..83d4e552b
--- /dev/null
+++ b/scripts/page-preview-fixtures.js
@@ -0,0 +1,190 @@
+import { ComponentType } from '@defra/forms-model'
+
+import { fixtures as componentFixtures } from './component-preview-fixtures.js'
+
+import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.js'
+
+/**
+ * Derives a GOV.UK Frontend view model from the canonical component fixture.
+ * Handles both flat fixtures (def/model/payload at top level) and variant
+ * fixtures (variants array). When variantLabel is provided, finds the matching
+ * variant; otherwise uses the first variant (or the flat fixture itself).
+ * @param {string} name - Component fixture key, e.g. 'TextField'
+ * @param {string} [variantLabel] - Variant label, e.g. 'No files uploaded'
+ * @returns {object}
+ */
+function componentViewModel(name, variantLabel) {
+  const fixture = componentFixtures[name]
+  const variant = fixture.variants
+    ? (fixture.variants.find((v) => v.label === variantLabel) ??
+      fixture.variants[0])
+    : fixture
+  const component = createComponent(variant.def, { model: variant.model })
+  return component?.getViewModel(variant.payload, []) ?? {}
+}
+
+/** @type {Record<string, { viewName: string, context?: object, variants?: Array<{label: string, context: object}> }>} */
+export const pageFixtures = {
+  PageController: {
+    viewName: 'index',
+    context: {
+      pageTitle: 'What is your full name?',
+      showTitle: true,
+      page: { allowContinue: true },
+      allowSaveAndExit: false,
+      components: [
+        {
+          type: ComponentType.TextField,
+          model: componentViewModel('TextField')
+        }
+      ]
+    }
+  },
+
+  StartPageController: {
+    viewName: 'index',
+    context: {
+      pageTitle: 'Apply for a licence',
+      showTitle: true,
+      isStartPage: true,
+      page: { allowContinue: true },
+      allowSaveAndExit: false,
+      components: []
+    }
+  },
+
+  TerminalPageController: {
+    viewName: 'index',
+    context: {
+      pageTitle: 'You are not eligible',
+      showTitle: true,
+      page: { allowContinue: false },
+      components: [
+        {
+          type: ComponentType.Html,
+          model: {
+            content:
+              '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>'
+          }
+        }
+      ]
+    }
+  },
+
+  RepeatPageController: {
+    viewName: 'repeat-list-summary',
+    variants: [
+      {
+        label: 'No items',
+        context: {
+          pageTitle: 'People',
+          showTitle: true,
+          checkAnswers: [],
+          allowSaveAndExit: false
+        }
+      },
+      {
+        label: 'One item',
+        context: {
+          pageTitle: 'People',
+          showTitle: true,
+          allowSaveAndExit: false,
+          checkAnswers: [
+            {
+              summaryList: {
+                rows: [
+                  {
+                    key: { text: 'Full name' },
+                    value: { text: 'Sarah Phillips' },
+                    actions: { items: [{ href: '#', text: 'Remove' }] }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    ]
+  },
+
+  FileUploadPageController: {
+    viewName: 'file-upload',
+    get variants() {
+      return [
+        {
+          label: 'No files uploaded',
+          context: {
+            pageTitle: 'Upload a document',
+            showTitle: true,
+            formAction: 'preview',
+            componentsBefore: [],
+            components: [],
+            formComponent: {
+              type: ComponentType.FileUploadField,
+              model: componentViewModel('FileUploadField', 'No files uploaded')
+            }
+          }
+        },
+        {
+          label: 'With files uploaded',
+          context: {
+            pageTitle: 'Upload a document',
+            showTitle: true,
+            formAction: 'preview',
+            componentsBefore: [],
+            components: [],
+            formComponent: {
+              type: ComponentType.FileUploadField,
+              model: componentViewModel(
+                'FileUploadField',
+                'With files uploaded'
+              )
+            }
+          }
+        }
+      ]
+    }
+  },
+
+  SummaryPageController: {
+    viewName: 'summary',
+    context: {
+      pageTitle: 'Check your answers',
+      allowSaveAndExit: false,
+      checkAnswers: [
+        {
+          summaryList: {
+            rows: [
+              {
+                key: { text: 'Full name' },
+                value: { text: 'Sarah Phillips' },
+                actions: {
+                  items: [
+                    {
+                      href: '#',
+                      text: 'Change',
+                      visuallyHiddenText: 'full name'
+                    }
+                  ]
+                }
+              },
+              {
+                key: { text: 'Email address' },
+                value: { text: 'sarah@example.gov.uk' },
+                actions: {
+                  items: [
+                    {
+                      href: '#',
+                      text: 'Change',
+                      visuallyHiddenText: 'email address'
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
new file mode 100644
index 000000000..b0bebb196
--- /dev/null
+++ b/scripts/page-preview-fixtures.test.js
@@ -0,0 +1,70 @@
+// @ts-nocheck
+
+jest.mock(
+  '~/src/server/plugins/engine/components/helpers/components.ts',
+  () => ({ createComponent: jest.fn() })
+)
+
+import { pageFixtures } from './page-preview-fixtures.js'
+
+import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.ts'
+
+beforeEach(() => {
+  createComponent.mockReturnValue({
+    getViewModel: jest.fn().mockReturnValue({ id: 'field', name: 'field' })
+  })
+})
+
+describe('page-preview-fixtures', () => {
+  it('all 6 expected page types are present', () => {
+    const expected = [
+      'PageController',
+      'StartPageController',
+      'TerminalPageController',
+      'RepeatPageController',
+      'FileUploadPageController',
+      'SummaryPageController'
+    ]
+    for (const key of expected) {
+      expect(pageFixtures[key]).toBeDefined()
+    }
+  })
+
+  it('every fixture has a viewName string', () => {
+    for (const [_key, fixture] of Object.entries(pageFixtures)) {
+      expect(typeof fixture.viewName).toBe('string')
+    }
+  })
+
+  it('every fixture has either context or variants, not neither', () => {
+    for (const [_key, fixture] of Object.entries(pageFixtures)) {
+      const hasContext = !!fixture.context
+      const hasVariants = !!fixture.variants
+      expect(hasContext || hasVariants).toBe(true)
+    }
+  })
+
+  it('variant fixtures have label and context on every variant', () => {
+    const variantFixtures = Object.entries(pageFixtures).filter(
+      ([, fixture]) => fixture.variants
+    )
+    expect(variantFixtures.length).toBeGreaterThan(0)
+    for (const [, fixture] of variantFixtures) {
+      for (const variant of fixture.variants) {
+        expect(typeof variant.label).toBe('string')
+        expect(variant.context).toBeDefined()
+      }
+    }
+  })
+
+  it('FileUploadPageController and RepeatPageController have exactly 2 variants', () => {
+    expect(pageFixtures.FileUploadPageController.variants).toHaveLength(2)
+    expect(pageFixtures.RepeatPageController.variants).toHaveLength(2)
+  })
+
+  it('FileUploadPageController variants reference the FileUploadField component fixture', () => {
+    // createComponent should have been called when the module was loaded
+    // (context objects are evaluated at module load time)
+    expect(createComponent).toHaveBeenCalled()
+  })
+})

From 878271590d4ad64bd965cecabbf3b99ad02d885f Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 17:24:15 +0100
Subject: [PATCH 06/40] fix: access formComponent.model in test to trigger lazy
 getter evaluation

---
 scripts/page-preview-fixtures.test.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
index b0bebb196..10d0ac22c 100644
--- a/scripts/page-preview-fixtures.test.js
+++ b/scripts/page-preview-fixtures.test.js
@@ -63,8 +63,9 @@ describe('page-preview-fixtures', () => {
   })
 
   it('FileUploadPageController variants reference the FileUploadField component fixture', () => {
-    // createComponent should have been called when the module was loaded
-    // (context objects are evaluated at module load time)
+    for (const variant of pageFixtures.FileUploadPageController.variants) {
+      const _model = variant.context.formComponent.model // trigger lazy getter
+    }
     expect(createComponent).toHaveBeenCalled()
   })
 })

From 779640d6840d19f1382d730a38de6a045597c23e Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 17:32:53 +0100
Subject: [PATCH 07/40] fix: remove silent fallback in componentViewModel,
 strengthen test assertion

---
 scripts/page-preview-fixtures.js      |  2 +-
 scripts/page-preview-fixtures.test.js | 13 +++++++++++--
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 83d4e552b..a6b540524 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -20,7 +20,7 @@ function componentViewModel(name, variantLabel) {
       fixture.variants[0])
     : fixture
   const component = createComponent(variant.def, { model: variant.model })
-  return component?.getViewModel(variant.payload, []) ?? {}
+  return component.getViewModel(variant.payload, [])
 }
 
 /** @type {Record<string, { viewName: string, context?: object, variants?: Array<{label: string, context: object}> }>} */
diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
index 10d0ac22c..079ef1f9b 100644
--- a/scripts/page-preview-fixtures.test.js
+++ b/scripts/page-preview-fixtures.test.js
@@ -2,9 +2,15 @@
 
 jest.mock(
   '~/src/server/plugins/engine/components/helpers/components.ts',
-  () => ({ createComponent: jest.fn() })
+  () => ({
+    createComponent: jest.fn().mockReturnValue({
+      getViewModel: jest.fn().mockReturnValue({ id: 'field', name: 'field' })
+    })
+  })
 )
 
+import { ComponentType } from '@defra/forms-model'
+
 import { pageFixtures } from './page-preview-fixtures.js'
 
 import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.ts'
@@ -66,6 +72,9 @@ describe('page-preview-fixtures', () => {
     for (const variant of pageFixtures.FileUploadPageController.variants) {
       const _model = variant.context.formComponent.model // trigger lazy getter
     }
-    expect(createComponent).toHaveBeenCalled()
+    expect(createComponent).toHaveBeenCalledWith(
+      expect.objectContaining({ type: ComponentType.FileUploadField }),
+      expect.anything()
+    )
   })
 })

From a38e1475a03ec5bc6cd0d5b746c98090e9b47833 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 18:25:32 +0100
Subject: [PATCH 08/40] feat: wire page type previews into docs generation
 pipeline

---
 scripts/generate-component-docs.js      | 20 +++++++++++++++++---
 scripts/generate-component-docs.test.js |  8 ++++++++
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/scripts/generate-component-docs.js b/scripts/generate-component-docs.js
index 2f7c527e4..eabb48e51 100644
--- a/scripts/generate-component-docs.js
+++ b/scripts/generate-component-docs.js
@@ -7,6 +7,8 @@ import ts from 'typescript'
 
 import { fixtures } from './component-preview-fixtures.js'
 import { writePreviewPartial } from './generate-component-previews.js'
+import { writePagePreviewPartial } from './generate-page-previews.js'
+import { pageFixtures } from './page-preview-fixtures.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -1103,6 +1105,8 @@ function main() {
     fs.rmSync(pagesOutputDir, { recursive: true, force: true })
   }
   fs.mkdirSync(pagesOutputDir, { recursive: true })
+  const pagePreviewsDir = path.resolve(pagesOutputDir, '_previews')
+  fs.mkdirSync(pagePreviewsDir, { recursive: true })
 
   // Parse sources
   const interfaces = parseComponentInterfaces(componentsDtsPath)
@@ -1191,13 +1195,23 @@ function main() {
     }
     const { props: uniqueProps = [], examplePath = '/page-path' } =
       pageInterfaces[key] ?? {}
-    const content = generatePageMd(key, uniqueProps, examplePath, i + 1)
+    const fixture = pageFixtures[key]
+    const content = generatePageMd(
+      key,
+      uniqueProps,
+      examplePath,
+      i + 1,
+      fixture ? slug : null
+    )
     if (content) {
-      fs.writeFileSync(path.join(pagesOutputDir, `${slug}.md`), content)
+      fs.writeFileSync(path.join(pagesOutputDir, `${slug}.mdx`), content)
+    }
+    if (fixture) {
+      writePagePreviewPartial(pagePreviewsDir, slug, fixture)
     }
   }
 
-  fs.writeFileSync(path.join(pagesOutputDir, 'index.md'), generatePagesIndex())
+  fs.writeFileSync(path.join(pagesOutputDir, 'index.mdx'), generatePagesIndex())
 
   console.log(
     `Generated ${componentOrder.length} component pages and ${Object.keys(metadata.pages).length} page type pages.`
diff --git a/scripts/generate-component-docs.test.js b/scripts/generate-component-docs.test.js
index 48031b662..9bb042cb2 100644
--- a/scripts/generate-component-docs.test.js
+++ b/scripts/generate-component-docs.test.js
@@ -30,6 +30,14 @@ jest.mock('./component-preview-fixtures.js', () => ({
   fixtures: {}
 }))
 
+jest.mock('./generate-page-previews.js', () => ({
+  writePagePreviewPartial: jest.fn()
+}))
+
+jest.mock('./page-preview-fixtures.js', () => ({
+  pageFixtures: {}
+}))
+
 // jest.mock factories are hoisted before variable declarations, so the
 // component-metadata.json payload must be inlined rather than referenced.
 jest.mock('fs', () => ({

From 936cb21139e5e1e520c62e6945f3a6163f870bc2 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Wed, 13 May 2026 20:41:08 +0100
Subject: [PATCH 09/40] fix: update generatePagesIndex links from .md to .mdx

---
 scripts/generate-component-docs.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/generate-component-docs.js b/scripts/generate-component-docs.js
index eabb48e51..b35738358 100644
--- a/scripts/generate-component-docs.js
+++ b/scripts/generate-component-docs.js
@@ -1045,7 +1045,7 @@ function generatePagesIndex() {
   for (const [key, description] of Object.entries(metadata.pages)) {
     const label = controllerLabel(key)
     const slug = controllerSlug(key)
-    lines.push(`- [**${label}**](./${slug}.md) — ${description}`)
+    lines.push(`- [**${label}**](./${slug}.mdx) — ${description}`)
   }
 
   lines.push(``)

From 4b7516d3ed2f40cf23bf94e785051c0816e16d03 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:21:25 +0100
Subject: [PATCH 10/40] feat: replace preview-layout with GOV.UK div-based page
 shell

---
 .../plugins/engine/views/preview-layout.html  | 41 ++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/src/server/plugins/engine/views/preview-layout.html b/src/server/plugins/engine/views/preview-layout.html
index cb0dbe444..250902a31 100644
--- a/src/server/plugins/engine/views/preview-layout.html
+++ b/src/server/plugins/engine/views/preview-layout.html
@@ -1 +1,40 @@
-{% block content %}{% endblock %}
+{% from "govuk/components/phase-banner/macro.njk" import govukPhaseBanner %}
+
+<div class="govuk-header" style="background:#1d70b8">
+  <div class="govuk-header__container" style="border-bottom-color:#1d70b8">
+    <div class="govuk-header__logo">
+      <span class="govuk-header__logotype">
+        <span class="govuk-header__logotype-text">GOV.UK</span>
+      </span>
+    </div>
+    <div class="govuk-header__content">
+      <span class="govuk-header__service-name">
+        Example service
+        <strong class="govuk-tag" style="margin-left:8px;background:#fd0;color:#0b0c0c;font-size:12px">
+          Example layout
+        </strong>
+      </span>
+    </div>
+  </div>
+</div>
+
+<div class="govuk-width-container">
+  {{ govukPhaseBanner({ tag: { text: 'Beta' }, html: 'This is a new service.' }) }}
+  <div class="govuk-main-wrapper">
+    {% block content %}{% endblock %}
+  </div>
+</div>
+
+<div class="govuk-footer">
+  <div class="govuk-footer__meta">
+    <div class="govuk-footer__meta-item govuk-footer__meta-item--grow">
+      <span class="govuk-footer__licence-description">
+        All content is available under the
+        <a class="govuk-footer__link" href="#">Open Government Licence v3.0</a>
+      </span>
+    </div>
+    <div class="govuk-footer__meta-item">
+      <span class="govuk-footer__copyright-logo">© Crown copyright</span>
+    </div>
+  </div>
+</div>

From 1049229d8765ef8e5f1ab2d53db0bc8a0e530faa Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:24:58 +0100
Subject: [PATCH 11/40] =?UTF-8?q?feat:=20PageController=20preview=20?=
 =?UTF-8?q?=E2=80=94=20two=20variants=20(single=20question,=20multiple=20q?=
 =?UTF-8?q?uestions)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/page-preview-fixtures.js      | 47 ++++++++++++++++++++-------
 scripts/page-preview-fixtures.test.js | 39 ++++++++++++++++++++++
 2 files changed, 75 insertions(+), 11 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index a6b540524..009eceba8 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -27,18 +27,43 @@ function componentViewModel(name, variantLabel) {
 export const pageFixtures = {
   PageController: {
     viewName: 'index',
-    context: {
-      pageTitle: 'What is your full name?',
-      showTitle: true,
-      page: { allowContinue: true },
-      allowSaveAndExit: false,
-      components: [
-        {
-          type: ComponentType.TextField,
-          model: componentViewModel('TextField')
+    variants: [
+      {
+        label: 'Single question',
+        context: {
+          showTitle: false,
+          page: { allowContinue: true },
+          allowSaveAndExit: false,
+          get components() {
+            const model = componentViewModel('TextField')
+            model.label.isPageHeading = true
+            model.label.classes = 'govuk-label--l'
+            return [{ type: ComponentType.TextField, model }]
+          }
         }
-      ]
-    }
+      },
+      {
+        label: 'Multiple questions',
+        context: {
+          pageTitle: 'Tell us about yourself',
+          showTitle: true,
+          page: { allowContinue: true },
+          allowSaveAndExit: false,
+          get components() {
+            return [
+              {
+                type: ComponentType.TextField,
+                model: componentViewModel('TextField')
+              },
+              {
+                type: ComponentType.DatePartsField,
+                model: componentViewModel('DatePartsField')
+              }
+            ]
+          }
+        }
+      }
+    ]
   },
 
   StartPageController: {
diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
index 079ef1f9b..0d2f18a5f 100644
--- a/scripts/page-preview-fixtures.test.js
+++ b/scripts/page-preview-fixtures.test.js
@@ -77,4 +77,43 @@ describe('page-preview-fixtures', () => {
       expect.anything()
     )
   })
+
+  it('PageController has exactly 2 variants', () => {
+    expect(pageFixtures.PageController.variants).toHaveLength(2)
+  })
+
+  it('PageController single question variant sets isPageHeading and govuk-label--l on the TextField label', () => {
+    const mockLabel = {
+      text: 'What is your full name?',
+      classes: 'govuk-label--s'
+    }
+    createComponent.mockReturnValue({
+      getViewModel: jest
+        .fn()
+        .mockReturnValue({
+          id: 'full-name',
+          name: 'full-name',
+          label: mockLabel
+        })
+    })
+    const singleVariant = pageFixtures.PageController.variants[0]
+    const [component] = singleVariant.context.components
+    expect(component.model.label.isPageHeading).toBe(true)
+    expect(component.model.label.classes).toBe('govuk-label--l')
+  })
+
+  it('PageController single question variant has showTitle false', () => {
+    expect(pageFixtures.PageController.variants[0].context.showTitle).toBe(
+      false
+    )
+  })
+
+  it('PageController multiple questions variant has showTitle true', () => {
+    expect(pageFixtures.PageController.variants[1].context.showTitle).toBe(true)
+  })
+
+  it('PageController multiple questions variant has two components', () => {
+    const multiVariant = pageFixtures.PageController.variants[1]
+    expect(multiVariant.context.components).toHaveLength(2)
+  })
 })

From 1e1731800f856c4a8cc824f57f73676ecb3ad104 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:33:21 +0100
Subject: [PATCH 12/40] fix: custom preview-layout classes, disable form
 submission, remove padding and phase banner

---
 docs/assets/css/docusaurus.scss               | 52 +++++++++++++++++++
 scripts/generate-component-previews.js        |  5 +-
 scripts/generate-component-previews.test.js   | 11 ++++
 scripts/generate-page-previews.js             |  7 ++-
 scripts/generate-page-previews.test.js        | 29 ++++++++---
 .../plugins/engine/views/preview-layout.html  | 47 ++++-------------
 6 files changed, 103 insertions(+), 48 deletions(-)

diff --git a/docs/assets/css/docusaurus.scss b/docs/assets/css/docusaurus.scss
index 97f2eaa48..81c291578 100644
--- a/docs/assets/css/docusaurus.scss
+++ b/docs/assets/css/docusaurus.scss
@@ -80,6 +80,58 @@
   color: #505a5f;
 }
 
+.app-page-preview__header {
+  background: #1d70b8;
+  padding: 10px 20px;
+  display: flex;
+  align-items: center;
+  gap: 20px;
+  margin-bottom: 0;
+}
+
+.app-page-preview__logo {
+  color: #ffffff;
+  font-weight: 700;
+  font-size: 18px;
+  font-family: sans-serif;
+}
+
+.app-page-preview__service-name {
+  color: #ffffff;
+  font-weight: 400;
+  font-size: 16px;
+  font-family: sans-serif;
+}
+
+.app-page-preview__tag {
+  background: #fd0;
+  color: #0b0c0c;
+  font-size: 12px;
+  font-weight: 700;
+  padding: 2px 8px;
+  margin-left: 8px;
+  display: inline-block;
+  vertical-align: middle;
+}
+
+.app-page-preview__main {
+  padding: 20px;
+  background: #ffffff;
+}
+
+.app-page-preview__footer {
+  background: #f3f2f1;
+  border-top: 1px solid #b1b4b6;
+  padding: 10px 20px;
+  font-size: 14px;
+  color: #505a5f;
+  font-family: sans-serif;
+}
+
+.component-preview--page {
+  padding: 0;
+}
+
 @media (min-width: 48.125em) {
   .govuk-template--rebranded .app-masthead .govuk-grid-row {
     display: flex;
diff --git a/scripts/generate-component-previews.js b/scripts/generate-component-previews.js
index 53ac39f3f..7fcf546b7 100644
--- a/scripts/generate-component-previews.js
+++ b/scripts/generate-component-previews.js
@@ -50,9 +50,10 @@ export function renderComponent(fixture) {
 /**
  * Build the MDX partial content from one or more rendered HTML strings.
  * @param {Array<{ label?: string, html: string }>} renders
+ * @param {string} [wrapperClass]
  * @returns {string}
  */
-export function buildPartialMdx(renders) {
+export function buildPartialMdx(renders, wrapperClass = 'component-preview') {
   return renders
     .map(({ label, html }) => {
       const escaped = html.replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
@@ -67,7 +68,7 @@ export function buildPartialMdx(renders) {
       const labelLine = safeLabel
         ? `<h3 className="govuk-heading-s">${safeLabel}</h3>\n`
         : ''
-      return `${labelLine}<div className="component-preview">\n  <div dangerouslySetInnerHTML={{ __html: \`${escaped}\` }} />\n</div>`
+      return `${labelLine}<div className="${wrapperClass}">\n  <div dangerouslySetInnerHTML={{ __html: \`${escaped}\` }} />\n</div>`
     })
     .join('\n\n')
 }
diff --git a/scripts/generate-component-previews.test.js b/scripts/generate-component-previews.test.js
index 09d7aa6ec..52413f536 100644
--- a/scripts/generate-component-previews.test.js
+++ b/scripts/generate-component-previews.test.js
@@ -116,6 +116,17 @@ describe('buildPartialMdx', () => {
     expect(result).toContain('\\`backtick\\`')
     expect(result).toContain('\\' + dollarBrace + 'expr}')
   })
+
+  it('uses custom wrapperClass when provided', () => {
+    const result = buildPartialMdx(
+      [{ html: '<input>' }],
+      'component-preview component-preview--page'
+    )
+    expect(result).toContain(
+      'className="component-preview component-preview--page"'
+    )
+    expect(result).not.toContain('className="component-preview"')
+  })
 })
 
 describe('renderComponent', () => {
diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
index 63c5bb135..13de5a76d 100644
--- a/scripts/generate-page-previews.js
+++ b/scripts/generate-page-previews.js
@@ -14,10 +14,13 @@ import { environment } from '~/src/server/plugins/nunjucks/environment.js'
  * @returns {string}
  */
 export function renderPage(context, viewName) {
-  return environment.render(`${viewName}.html`, {
+  const html = environment.render(`${viewName}.html`, {
     ...context,
     baseLayoutPath: 'preview-layout.html'
   })
+  return html
+    .replace(/<form\b[^>]*>/g, '<div class="app-page-preview__form">')
+    .replace(/<\/form>/g, '</div>')
 }
 
 /**
@@ -39,6 +42,6 @@ export function writePagePreviewPartial(previewsDir, slug, fixture) {
 
   fs.writeFileSync(
     path.join(previewsDir, `${slug}.mdx`),
-    buildPartialMdx(renders)
+    buildPartialMdx(renders, 'component-preview component-preview--page')
   )
 }
diff --git a/scripts/generate-page-previews.test.js b/scripts/generate-page-previews.test.js
index 9a257b2c2..187e3d6fd 100644
--- a/scripts/generate-page-previews.test.js
+++ b/scripts/generate-page-previews.test.js
@@ -52,6 +52,17 @@ describe('renderPage', () => {
     const result = renderPage({ pageTitle: 'Check your answers' }, 'summary')
     expect(result).toBe('<h1>Check your answers</h1>')
   })
+
+  it('replaces <form> tags with divs to prevent form submission', () => {
+    environment.render.mockReturnValue(
+      '<form method="post" novalidate><button class="govuk-button">Continue</button></form>'
+    )
+    const result = renderPage({ pageTitle: 'Test' }, 'index')
+    expect(result).not.toContain('<form')
+    expect(result).not.toContain('</form>')
+    expect(result).toContain('<div class="app-page-preview__form">')
+    expect(result).toContain('</div>')
+  })
 })
 
 describe('writePagePreviewPartial', () => {
@@ -86,9 +97,10 @@ describe('writePagePreviewPartial', () => {
       viewName: 'index',
       context: { pageTitle: 'Question' }
     })
-    expect(buildPartialMdx).toHaveBeenCalledWith([
-      { html: '<div>page html</div>' }
-    ])
+    expect(buildPartialMdx).toHaveBeenCalledWith(
+      [{ html: '<div>page html</div>' }],
+      'component-preview component-preview--page'
+    )
   })
 
   it('passes labelled renders to buildPartialMdx for a variant fixture', () => {
@@ -99,10 +111,13 @@ describe('writePagePreviewPartial', () => {
         { label: 'With files uploaded', context: { pageTitle: 'Upload' } }
       ]
     })
-    expect(buildPartialMdx).toHaveBeenCalledWith([
-      { label: 'No files uploaded', html: '<div>page html</div>' },
-      { label: 'With files uploaded', html: '<div>page html</div>' }
-    ])
+    expect(buildPartialMdx).toHaveBeenCalledWith(
+      [
+        { label: 'No files uploaded', html: '<div>page html</div>' },
+        { label: 'With files uploaded', html: '<div>page html</div>' }
+      ],
+      'component-preview component-preview--page'
+    )
   })
 
   it('renders each variant context independently', () => {
diff --git a/src/server/plugins/engine/views/preview-layout.html b/src/server/plugins/engine/views/preview-layout.html
index 250902a31..f174776d5 100644
--- a/src/server/plugins/engine/views/preview-layout.html
+++ b/src/server/plugins/engine/views/preview-layout.html
@@ -1,40 +1,13 @@
-{% from "govuk/components/phase-banner/macro.njk" import govukPhaseBanner %}
-
-<div class="govuk-header" style="background:#1d70b8">
-  <div class="govuk-header__container" style="border-bottom-color:#1d70b8">
-    <div class="govuk-header__logo">
-      <span class="govuk-header__logotype">
-        <span class="govuk-header__logotype-text">GOV.UK</span>
-      </span>
-    </div>
-    <div class="govuk-header__content">
-      <span class="govuk-header__service-name">
-        Example service
-        <strong class="govuk-tag" style="margin-left:8px;background:#fd0;color:#0b0c0c;font-size:12px">
-          Example layout
-        </strong>
-      </span>
-    </div>
-  </div>
+<div class="app-page-preview__header">
+  <span class="app-page-preview__logo">GOV.UK</span>
+  <span class="app-page-preview__service-name">
+    Example service
+    <span class="app-page-preview__tag">Example layout</span>
+  </span>
 </div>
-
-<div class="govuk-width-container">
-  {{ govukPhaseBanner({ tag: { text: 'Beta' }, html: 'This is a new service.' }) }}
-  <div class="govuk-main-wrapper">
-    {% block content %}{% endblock %}
-  </div>
+<div class="app-page-preview__main">
+  {% block content %}{% endblock %}
 </div>
-
-<div class="govuk-footer">
-  <div class="govuk-footer__meta">
-    <div class="govuk-footer__meta-item govuk-footer__meta-item--grow">
-      <span class="govuk-footer__licence-description">
-        All content is available under the
-        <a class="govuk-footer__link" href="#">Open Government Licence v3.0</a>
-      </span>
-    </div>
-    <div class="govuk-footer__meta-item">
-      <span class="govuk-footer__copyright-logo">© Crown copyright</span>
-    </div>
-  </div>
+<div class="app-page-preview__footer">
+  © Crown copyright
 </div>

From 7cca73fc46b7cafa57d9f074ea555c0a9beaf11b Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:44:49 +0100
Subject: [PATCH 13/40] feat: include FileUploadField component in
 FileUploadPageController JSON example

---
 scripts/component-metadata.json         | 11 +++++++++++
 scripts/generate-component-docs.js      |  3 +++
 scripts/generate-component-docs.test.js | 20 +++++++++++++++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/scripts/component-metadata.json b/scripts/component-metadata.json
index d50cb9a8c..cec83fde7 100644
--- a/scripts/component-metadata.json
+++ b/scripts/component-metadata.json
@@ -121,5 +121,16 @@
     "repeat.options.title": "Label displayed per repeated item in the list summary.",
     "repeat.schema.min": "Minimum number of items the user must add.",
     "repeat.schema.max": "Maximum number of items the user can add. Cannot exceed 200."
+  },
+  "pageExampleComponents": {
+    "FileUploadPageController": [
+      {
+        "type": "FileUploadField",
+        "name": "upload",
+        "title": "Upload a document",
+        "options": {},
+        "schema": {}
+      }
+    ]
   }
 }
diff --git a/scripts/generate-component-docs.js b/scripts/generate-component-docs.js
index b35738358..de4bb262f 100644
--- a/scripts/generate-component-docs.js
+++ b/scripts/generate-component-docs.js
@@ -888,6 +888,9 @@ export function generatePageExample(
     setNestedValue(example, prop.name, placeholderForType(prop.type))
   }
 
+  const exampleComponents = metadata.pageExampleComponents?.[controllerKey]
+  if (exampleComponents) example.components = exampleComponents
+
   return example
 }
 
diff --git a/scripts/generate-component-docs.test.js b/scripts/generate-component-docs.test.js
index 9bb042cb2..bfe01aab7 100644
--- a/scripts/generate-component-docs.test.js
+++ b/scripts/generate-component-docs.test.js
@@ -47,7 +47,7 @@ jest.mock('fs', () => ({
   readdirSync: jest.fn(),
   readFileSync: jest.fn().mockImplementation((filePath) => {
     if (String(filePath ?? '').includes('component-metadata.json')) {
-      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
+      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."},"pageExampleComponents":{"FileUploadPageController":[{"type":"FileUploadField","name":"upload","title":"Upload a document","options":{},"schema":{}}]}}'
     }
     return ''
   }),
@@ -296,6 +296,24 @@ describe('Component Documentation Generator', () => {
       expect(result.repeat.options.name).toBe('')
       expect(result.repeat).not.toHaveProperty('schema')
     })
+
+    it('injects pageExampleComponents.components when an entry exists for the controllerKey', () => {
+      const result = generatePageExample('FileUploadPageController', [])
+      expect(result.components).toEqual([
+        {
+          type: 'FileUploadField',
+          name: 'upload',
+          title: 'Upload a document',
+          options: {},
+          schema: {}
+        }
+      ])
+    })
+
+    it('does not add components when pageExampleComponents has no entry for the controllerKey', () => {
+      const result = generatePageExample('PageController', [])
+      expect(result).not.toHaveProperty('components')
+    })
   })
 
   describe('generatePageMd with preview', () => {

From 7bbee4d44376de9b12784401e240fe52aaf80f64 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:49:22 +0100
Subject: [PATCH 14/40] fix: remove GOV.UK logo, example tag, and footer
 content from preview-layout

---
 src/server/plugins/engine/views/preview-layout.html | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/src/server/plugins/engine/views/preview-layout.html b/src/server/plugins/engine/views/preview-layout.html
index f174776d5..4af2593ca 100644
--- a/src/server/plugins/engine/views/preview-layout.html
+++ b/src/server/plugins/engine/views/preview-layout.html
@@ -1,13 +1,9 @@
 <div class="app-page-preview__header">
-  <span class="app-page-preview__logo">GOV.UK</span>
   <span class="app-page-preview__service-name">
     Example service
-    <span class="app-page-preview__tag">Example layout</span>
   </span>
 </div>
 <div class="app-page-preview__main">
   {% block content %}{% endblock %}
 </div>
-<div class="app-page-preview__footer">
-  © Crown copyright
-</div>
+<div class="app-page-preview__footer"></div>

From 7950fc65d26ed54997f80559f68e65343063d0f8 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:50:01 +0100
Subject: [PATCH 15/40] chore: remove unused app-page-preview__logo and __tag
 CSS rules

---
 docs/assets/css/docusaurus.scss | 19 -------------------
 1 file changed, 19 deletions(-)

diff --git a/docs/assets/css/docusaurus.scss b/docs/assets/css/docusaurus.scss
index 81c291578..d44335b11 100644
--- a/docs/assets/css/docusaurus.scss
+++ b/docs/assets/css/docusaurus.scss
@@ -85,17 +85,9 @@
   padding: 10px 20px;
   display: flex;
   align-items: center;
-  gap: 20px;
   margin-bottom: 0;
 }
 
-.app-page-preview__logo {
-  color: #ffffff;
-  font-weight: 700;
-  font-size: 18px;
-  font-family: sans-serif;
-}
-
 .app-page-preview__service-name {
   color: #ffffff;
   font-weight: 400;
@@ -103,17 +95,6 @@
   font-family: sans-serif;
 }
 
-.app-page-preview__tag {
-  background: #fd0;
-  color: #0b0c0c;
-  font-size: 12px;
-  font-weight: 700;
-  padding: 2px 8px;
-  margin-left: 8px;
-  display: inline-block;
-  vertical-align: middle;
-}
-
 .app-page-preview__main {
   padding: 20px;
   background: #ffffff;

From 354cced5218a1ada2c06509169b575ab31b97547 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:51:13 +0100
Subject: [PATCH 16/40] fix: bold service name text in page preview header

---
 docs/assets/css/docusaurus.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/assets/css/docusaurus.scss b/docs/assets/css/docusaurus.scss
index d44335b11..1be6614f8 100644
--- a/docs/assets/css/docusaurus.scss
+++ b/docs/assets/css/docusaurus.scss
@@ -90,7 +90,7 @@
 
 .app-page-preview__service-name {
   color: #ffffff;
-  font-weight: 400;
+  font-weight: 700;
   font-size: 16px;
   font-family: sans-serif;
 }

From a28b7f136e719f7789abc48029b0096f1b5c7fa7 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:54:22 +0100
Subject: [PATCH 17/40] fix: include FileUploadField in components array so
 file list renders in page preview

---
 scripts/page-preview-fixtures.js | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 009eceba8..ef15614da 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -143,7 +143,15 @@ export const pageFixtures = {
             showTitle: true,
             formAction: 'preview',
             componentsBefore: [],
-            components: [],
+            components: [
+              {
+                type: ComponentType.FileUploadField,
+                model: componentViewModel(
+                  'FileUploadField',
+                  'No files uploaded'
+                )
+              }
+            ],
             formComponent: {
               type: ComponentType.FileUploadField,
               model: componentViewModel('FileUploadField', 'No files uploaded')
@@ -157,7 +165,15 @@ export const pageFixtures = {
             showTitle: true,
             formAction: 'preview',
             componentsBefore: [],
-            components: [],
+            components: [
+              {
+                type: ComponentType.FileUploadField,
+                model: componentViewModel(
+                  'FileUploadField',
+                  'With files uploaded'
+                )
+              }
+            ],
             formComponent: {
               type: ComponentType.FileUploadField,
               model: componentViewModel(

From 3d926f00df900004315183e37029627e310cbaf4 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:56:07 +0100
Subject: [PATCH 18/40] =?UTF-8?q?fix:=20RepeatPageController=20preview=20?=
 =?UTF-8?q?=E2=80=94=20single=20context=20with=20three=20items?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/page-preview-fixtures.js      | 56 +++++++++++++--------------
 scripts/page-preview-fixtures.test.js | 15 +++----
 2 files changed, 32 insertions(+), 39 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index ef15614da..fabcf87d8 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -98,38 +98,34 @@ export const pageFixtures = {
 
   RepeatPageController: {
     viewName: 'repeat-list-summary',
-    variants: [
-      {
-        label: 'No items',
-        context: {
-          pageTitle: 'People',
-          showTitle: true,
-          checkAnswers: [],
-          allowSaveAndExit: false
-        }
-      },
-      {
-        label: 'One item',
-        context: {
-          pageTitle: 'People',
-          showTitle: true,
-          allowSaveAndExit: false,
-          checkAnswers: [
-            {
-              summaryList: {
-                rows: [
-                  {
-                    key: { text: 'Full name' },
-                    value: { text: 'Sarah Phillips' },
-                    actions: { items: [{ href: '#', text: 'Remove' }] }
-                  }
-                ]
+    context: {
+      pageTitle: 'People',
+      showTitle: true,
+      allowSaveAndExit: false,
+      checkAnswers: [
+        {
+          summaryList: {
+            rows: [
+              {
+                key: { text: 'Full name' },
+                value: { text: 'Sarah Phillips' },
+                actions: { items: [{ href: '#', text: 'Remove' }] }
+              },
+              {
+                key: { text: 'Full name' },
+                value: { text: 'David Jones' },
+                actions: { items: [{ href: '#', text: 'Remove' }] }
+              },
+              {
+                key: { text: 'Full name' },
+                value: { text: 'Emma Wilson' },
+                actions: { items: [{ href: '#', text: 'Remove' }] }
               }
-            }
-          ]
+            ]
+          }
         }
-      }
-    ]
+      ]
+    }
   },
 
   FileUploadPageController: {
diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
index 0d2f18a5f..3b474c7da 100644
--- a/scripts/page-preview-fixtures.test.js
+++ b/scripts/page-preview-fixtures.test.js
@@ -63,9 +63,8 @@ describe('page-preview-fixtures', () => {
     }
   })
 
-  it('FileUploadPageController and RepeatPageController have exactly 2 variants', () => {
+  it('FileUploadPageController has exactly 2 variants', () => {
     expect(pageFixtures.FileUploadPageController.variants).toHaveLength(2)
-    expect(pageFixtures.RepeatPageController.variants).toHaveLength(2)
   })
 
   it('FileUploadPageController variants reference the FileUploadField component fixture', () => {
@@ -88,13 +87,11 @@ describe('page-preview-fixtures', () => {
       classes: 'govuk-label--s'
     }
     createComponent.mockReturnValue({
-      getViewModel: jest
-        .fn()
-        .mockReturnValue({
-          id: 'full-name',
-          name: 'full-name',
-          label: mockLabel
-        })
+      getViewModel: jest.fn().mockReturnValue({
+        id: 'full-name',
+        name: 'full-name',
+        label: mockLabel
+      })
     })
     const singleVariant = pageFixtures.PageController.variants[0]
     const [component] = singleVariant.context.components

From 0da154f527212975dde630960495807124dafff8 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 00:58:45 +0100
Subject: [PATCH 19/40] fix: repeat page title, add page.allowContinue to file
 upload fixtures for Continue button

---
 scripts/page-preview-fixtures.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index fabcf87d8..6747d3f5f 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -99,7 +99,7 @@ export const pageFixtures = {
   RepeatPageController: {
     viewName: 'repeat-list-summary',
     context: {
-      pageTitle: 'People',
+      pageTitle: 'Add members of your household',
       showTitle: true,
       allowSaveAndExit: false,
       checkAnswers: [
@@ -138,6 +138,7 @@ export const pageFixtures = {
             pageTitle: 'Upload a document',
             showTitle: true,
             formAction: 'preview',
+            page: { allowContinue: true },
             componentsBefore: [],
             components: [
               {
@@ -160,6 +161,7 @@ export const pageFixtures = {
             pageTitle: 'Upload a document',
             showTitle: true,
             formAction: 'preview',
+            page: { allowContinue: true },
             componentsBefore: [],
             components: [
               {

From b6355552497c80c95cccc18f7c73146952dea249 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 08:48:47 +0100
Subject: [PATCH 20/40] refactor: move exampleComponents from
 component-metadata.json to page fixture, extract sidebarPosition var

---
 scripts/component-metadata.json         | 11 -----------
 scripts/generate-component-docs.js      | 22 ++++++++++++++++------
 scripts/generate-component-docs.test.js | 25 ++++++++++++++++++-------
 scripts/page-preview-fixtures.js        |  9 +++++++++
 4 files changed, 43 insertions(+), 24 deletions(-)

diff --git a/scripts/component-metadata.json b/scripts/component-metadata.json
index cec83fde7..d50cb9a8c 100644
--- a/scripts/component-metadata.json
+++ b/scripts/component-metadata.json
@@ -121,16 +121,5 @@
     "repeat.options.title": "Label displayed per repeated item in the list summary.",
     "repeat.schema.min": "Minimum number of items the user must add.",
     "repeat.schema.max": "Maximum number of items the user can add. Cannot exceed 200."
-  },
-  "pageExampleComponents": {
-    "FileUploadPageController": [
-      {
-        "type": "FileUploadField",
-        "name": "upload",
-        "title": "Upload a document",
-        "options": {},
-        "schema": {}
-      }
-    ]
   }
 }
diff --git a/scripts/generate-component-docs.js b/scripts/generate-component-docs.js
index de4bb262f..da55ea3fd 100644
--- a/scripts/generate-component-docs.js
+++ b/scripts/generate-component-docs.js
@@ -865,12 +865,14 @@ export function controllerSlug(controllerKey) {
  * @param {string} controllerKey
  * @param {Array<{name: string, type: string, optional: boolean}>} uniqueProps
  * @param {string} [examplePath]
+ * @param {Array<object>|null} [exampleComponents]
  * @returns {Record<string, unknown>}
  */
 export function generatePageExample(
   controllerKey,
   uniqueProps,
-  examplePath = '/page-path'
+  examplePath = '/page-path',
+  exampleComponents = null
 ) {
   const controllerValue =
     controllerKey === 'PageController' ? null : controllerKey
@@ -888,7 +890,6 @@ export function generatePageExample(
     setNestedValue(example, prop.name, placeholderForType(prop.type))
   }
 
-  const exampleComponents = metadata.pageExampleComponents?.[controllerKey]
   if (exampleComponents) example.components = exampleComponents
 
   return example
@@ -900,13 +901,15 @@ export function generatePageExample(
  * @param {string} examplePath
  * @param {number} sidebarPosition
  * @param {string|null} [previewSlug]
+ * @param {Array<object>|null} [exampleComponents]
  */
 export function generatePageMd(
   controllerKey,
   uniqueProps,
   examplePath,
   sidebarPosition,
-  previewSlug = null
+  previewSlug = null,
+  exampleComponents = null
 ) {
   const description = metadata.pages[controllerKey]
   if (!description) return null
@@ -954,7 +957,12 @@ export function generatePageMd(
     ``,
     '```json',
     JSON.stringify(
-      generatePageExample(controllerKey, uniqueProps, examplePath),
+      generatePageExample(
+        controllerKey,
+        uniqueProps,
+        examplePath,
+        exampleComponents
+      ),
       null,
       2
     ),
@@ -1199,12 +1207,14 @@ function main() {
     const { props: uniqueProps = [], examplePath = '/page-path' } =
       pageInterfaces[key] ?? {}
     const fixture = pageFixtures[key]
+    const sidebarPosition = i + 1
     const content = generatePageMd(
       key,
       uniqueProps,
       examplePath,
-      i + 1,
-      fixture ? slug : null
+      sidebarPosition,
+      fixture ? slug : null,
+      fixture?.exampleComponents ?? null
     )
     if (content) {
       fs.writeFileSync(path.join(pagesOutputDir, `${slug}.mdx`), content)
diff --git a/scripts/generate-component-docs.test.js b/scripts/generate-component-docs.test.js
index bfe01aab7..6173fec50 100644
--- a/scripts/generate-component-docs.test.js
+++ b/scripts/generate-component-docs.test.js
@@ -47,7 +47,7 @@ jest.mock('fs', () => ({
   readdirSync: jest.fn(),
   readFileSync: jest.fn().mockImplementation((filePath) => {
     if (String(filePath ?? '').includes('component-metadata.json')) {
-      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."},"pageExampleComponents":{"FileUploadPageController":[{"type":"FileUploadField","name":"upload","title":"Upload a document","options":{},"schema":{}}]}}'
+      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
     }
     return ''
   }),
@@ -297,9 +297,8 @@ describe('Component Documentation Generator', () => {
       expect(result.repeat).not.toHaveProperty('schema')
     })
 
-    it('injects pageExampleComponents.components when an entry exists for the controllerKey', () => {
-      const result = generatePageExample('FileUploadPageController', [])
-      expect(result.components).toEqual([
+    it('injects exampleComponents into the example when provided', () => {
+      const components = [
         {
           type: 'FileUploadField',
           name: 'upload',
@@ -307,11 +306,23 @@ describe('Component Documentation Generator', () => {
           options: {},
           schema: {}
         }
-      ])
+      ]
+      const result = generatePageExample(
+        'FileUploadPageController',
+        [],
+        '/file-upload',
+        components
+      )
+      expect(result.components).toEqual(components)
     })
 
-    it('does not add components when pageExampleComponents has no entry for the controllerKey', () => {
-      const result = generatePageExample('PageController', [])
+    it('does not add components when exampleComponents is null', () => {
+      const result = generatePageExample(
+        'PageController',
+        [],
+        '/page-path',
+        null
+      )
       expect(result).not.toHaveProperty('components')
     })
   })
diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 6747d3f5f..63abb1d44 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -130,6 +130,15 @@ export const pageFixtures = {
 
   FileUploadPageController: {
     viewName: 'file-upload',
+    exampleComponents: [
+      {
+        type: 'FileUploadField',
+        name: 'upload',
+        title: 'Upload a document',
+        options: {},
+        schema: {}
+      }
+    ],
     get variants() {
       return [
         {

From 750b987c253fb5eb969c05c5bda798297019cdb9 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 08:51:34 +0100
Subject: [PATCH 21/40] docs: simplify componentViewModel JSDoc

---
 scripts/page-preview-fixtures.js | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 63abb1d44..029e89b74 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -5,12 +5,12 @@ import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.js'
 
 /**
- * Derives a GOV.UK Frontend view model from the canonical component fixture.
- * Handles both flat fixtures (def/model/payload at top level) and variant
- * fixtures (variants array). When variantLabel is provided, finds the matching
- * variant; otherwise uses the first variant (or the flat fixture itself).
- * @param {string} name - Component fixture key, e.g. 'TextField'
- * @param {string} [variantLabel] - Variant label, e.g. 'No files uploaded'
+ * Builds a component view model from the named component fixture so page
+ * fixtures can reuse the same data as component previews without duplicating
+ * component definitions. Supports variant fixtures — pass a label to select
+ * a specific variant, or omit it to use the first (or only) variant.
+ * @param {string} name - e.g. 'FileUploadField'
+ * @param {string} [variantLabel] - e.g. 'No files uploaded'
  * @returns {object}
  */
 function componentViewModel(name, variantLabel) {

From 3c344642befa17aff06d9510eea9f4034c2f7937 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 08:56:36 +0100
Subject: [PATCH 22/40] =?UTF-8?q?refactor:=20componentViewModel=20returns?=
 =?UTF-8?q?=20{type,=20model}=20=E2=80=94=20callers=20no=20longer=20repeat?=
 =?UTF-8?q?=20the=20type?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/page-preview-fixtures.js | 60 +++++++++++---------------------
 1 file changed, 21 insertions(+), 39 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 029e89b74..d2b414523 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -11,7 +11,7 @@ import { createComponent } from '~/src/server/plugins/engine/components/helpers/
  * a specific variant, or omit it to use the first (or only) variant.
  * @param {string} name - e.g. 'FileUploadField'
  * @param {string} [variantLabel] - e.g. 'No files uploaded'
- * @returns {object}
+ * @returns {{ type: string, model: object }}
  */
 function componentViewModel(name, variantLabel) {
   const fixture = componentFixtures[name]
@@ -20,7 +20,10 @@ function componentViewModel(name, variantLabel) {
       fixture.variants[0])
     : fixture
   const component = createComponent(variant.def, { model: variant.model })
-  return component.getViewModel(variant.payload, [])
+  return {
+    type: variant.def.type,
+    model: component.getViewModel(variant.payload, [])
+  }
 }
 
 /** @type {Record<string, { viewName: string, context?: object, variants?: Array<{label: string, context: object}> }>} */
@@ -35,10 +38,10 @@ export const pageFixtures = {
           page: { allowContinue: true },
           allowSaveAndExit: false,
           get components() {
-            const model = componentViewModel('TextField')
-            model.label.isPageHeading = true
-            model.label.classes = 'govuk-label--l'
-            return [{ type: ComponentType.TextField, model }]
+            const component = componentViewModel('TextField')
+            component.model.label.isPageHeading = true
+            component.model.label.classes = 'govuk-label--l'
+            return [component]
           }
         }
       },
@@ -51,14 +54,8 @@ export const pageFixtures = {
           allowSaveAndExit: false,
           get components() {
             return [
-              {
-                type: ComponentType.TextField,
-                model: componentViewModel('TextField')
-              },
-              {
-                type: ComponentType.DatePartsField,
-                model: componentViewModel('DatePartsField')
-              }
+              componentViewModel('TextField'),
+              componentViewModel('DatePartsField')
             ]
           }
         }
@@ -150,18 +147,12 @@ export const pageFixtures = {
             page: { allowContinue: true },
             componentsBefore: [],
             components: [
-              {
-                type: ComponentType.FileUploadField,
-                model: componentViewModel(
-                  'FileUploadField',
-                  'No files uploaded'
-                )
-              }
+              componentViewModel('FileUploadField', 'No files uploaded')
             ],
-            formComponent: {
-              type: ComponentType.FileUploadField,
-              model: componentViewModel('FileUploadField', 'No files uploaded')
-            }
+            formComponent: componentViewModel(
+              'FileUploadField',
+              'No files uploaded'
+            )
           }
         },
         {
@@ -173,21 +164,12 @@ export const pageFixtures = {
             page: { allowContinue: true },
             componentsBefore: [],
             components: [
-              {
-                type: ComponentType.FileUploadField,
-                model: componentViewModel(
-                  'FileUploadField',
-                  'With files uploaded'
-                )
-              }
+              componentViewModel('FileUploadField', 'With files uploaded')
             ],
-            formComponent: {
-              type: ComponentType.FileUploadField,
-              model: componentViewModel(
-                'FileUploadField',
-                'With files uploaded'
-              )
-            }
+            formComponent: componentViewModel(
+              'FileUploadField',
+              'With files uploaded'
+            )
           }
         }
       ]

From d6d0a4919bb2b2448af8e36a4618be2ee13498cb Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 10:32:46 +0100
Subject: [PATCH 23/40] refactor: use real page controllers via getViewModel
 for PageController, StartPage, Terminal previews

---
 scripts/page-preview-fixtures.js | 165 ++++++++++++++++++++-----------
 1 file changed, 108 insertions(+), 57 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index d2b414523..18b0418c5 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -1,4 +1,4 @@
-import { ComponentType } from '@defra/forms-model'
+import { FormModel } from '../.server/server/plugins/engine/models/FormModel.js'
 
 import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
@@ -26,73 +26,124 @@ function componentViewModel(name, variantLabel) {
   }
 }
 
+/**
+ * Instantiates the real page controller for the given page definition and
+ * calls getViewModel with a minimal mock request/context. The controller
+ * handles showTitle, label sizing, isPageHeading, allowContinue, and viewName
+ * automatically — no manual fixture properties needed for these.
+ * @param {object} pageDef - Page definition (path, title, controller, components)
+ * @param {object} [state] - Optional form state to pass as the payload
+ * @returns {{ viewName: string, context: object }}
+ */
+function pageViewContext(pageDef, state = {}) {
+  const model = new FormModel(
+    {
+      name: 'preview',
+      schema: 2,
+      startPage: pageDef.path,
+      sections: [],
+      conditions: [],
+      lists: [],
+      pages: [pageDef]
+    },
+    { basePath: '/preview' }
+  )
+  const [controller] = model.pages
+  const mockContext = {
+    payload: state,
+    errors: undefined,
+    evaluationState: {},
+    paths: [],
+    state
+  }
+  return {
+    viewName: controller.viewName,
+    context: controller.getViewModel(
+      {
+        query: {},
+        params: {},
+        path: pageDef.path,
+        url: { search: '' },
+        server: { plugins: { 'forms-engine-plugin': {} } }
+      },
+      mockContext
+    )
+  }
+}
+
 /** @type {Record<string, { viewName: string, context?: object, variants?: Array<{label: string, context: object}> }>} */
 export const pageFixtures = {
   PageController: {
     viewName: 'index',
-    variants: [
-      {
-        label: 'Single question',
-        context: {
-          showTitle: false,
-          page: { allowContinue: true },
-          allowSaveAndExit: false,
-          get components() {
-            const component = componentViewModel('TextField')
-            component.model.label.isPageHeading = true
-            component.model.label.classes = 'govuk-label--l'
-            return [component]
-          }
-        }
-      },
-      {
-        label: 'Multiple questions',
-        context: {
-          pageTitle: 'Tell us about yourself',
-          showTitle: true,
-          page: { allowContinue: true },
-          allowSaveAndExit: false,
-          get components() {
-            return [
-              componentViewModel('TextField'),
-              componentViewModel('DatePartsField')
+    get variants() {
+      return [
+        {
+          label: 'Single question',
+          context: pageViewContext({
+            path: '/pagepath',
+            title: 'What is your full name?',
+            components: [
+              {
+                type: 'TextField',
+                name: 'fullname',
+                title: 'What is your full name?',
+                hint: 'As shown on your passport',
+                options: {},
+                schema: {}
+              }
             ]
-          }
-        }
-      }
-    ]
-  },
-
-  StartPageController: {
-    viewName: 'index',
-    context: {
-      pageTitle: 'Apply for a licence',
-      showTitle: true,
-      isStartPage: true,
-      page: { allowContinue: true },
-      allowSaveAndExit: false,
-      components: []
-    }
-  },
-
-  TerminalPageController: {
-    viewName: 'index',
-    context: {
-      pageTitle: 'You are not eligible',
-      showTitle: true,
-      page: { allowContinue: false },
-      components: [
+          }).context
+        },
         {
-          type: ComponentType.Html,
-          model: {
-            content:
-              '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>'
-          }
+          label: 'Multiple questions',
+          context: pageViewContext({
+            path: '/pagepath',
+            title: 'Tell us about yourself',
+            components: [
+              {
+                type: 'TextField',
+                name: 'fullname',
+                title: 'What is your full name?',
+                options: {},
+                schema: {}
+              },
+              {
+                type: 'DatePartsField',
+                name: 'dob',
+                title: 'What is your date of birth?',
+                hint: 'For example, 27 3 2007',
+                options: {},
+                schema: {}
+              }
+            ]
+          }).context
         }
       ]
     }
   },
 
+  StartPageController: pageViewContext({
+    path: '/start',
+    controller: 'StartPageController',
+    title: 'Apply for a licence',
+    components: []
+  }),
+
+  TerminalPageController: pageViewContext({
+    path: '/ineligible',
+    controller: 'TerminalPageController',
+    title: 'You are not eligible',
+    components: [
+      {
+        type: 'Html',
+        name: 'eligibility',
+        content:
+          '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
+        options: {}
+      }
+    ]
+  }),
+
   RepeatPageController: {
     viewName: 'repeat-list-summary',
     context: {

From 4775986b05d2df0e1d2763a72523b6f1b81b881d Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 10:34:19 +0100
Subject: [PATCH 24/40] chore: type mock request as FormContextRequest in
 pageViewContext

---
 scripts/page-preview-fixtures.js | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 18b0418c5..bf6fbf9d0 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -56,18 +56,17 @@ function pageViewContext(pageDef, state = {}) {
     paths: [],
     state
   }
+  /** @type {import('~/src/server/plugins/engine/types.js').FormContextRequest} */
+  const mockRequest = {
+    query: {},
+    params: {},
+    path: pageDef.path,
+    url: { search: '' },
+    server: { plugins: { 'forms-engine-plugin': {} } }
+  }
   return {
     viewName: controller.viewName,
-    context: controller.getViewModel(
-      {
-        query: {},
-        params: {},
-        path: pageDef.path,
-        url: { search: '' },
-        server: { plugins: { 'forms-engine-plugin': {} } }
-      },
-      mockContext
-    )
+    context: controller.getViewModel(mockRequest, mockContext)
   }
 }
 

From e68010bc46008e935c3c95634cec57b9e1ad2c55 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 10:55:11 +0100
Subject: [PATCH 25/40] =?UTF-8?q?fix:=20engine=20V2,=20summary=20page,=20f?=
 =?UTF-8?q?orce=20access=20in=20pageViewContext=20=E2=80=94=20restores=20C?=
 =?UTF-8?q?ontinue=20button?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/page-preview-fixtures.js | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index bf6fbf9d0..d7405bdde 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -1,5 +1,8 @@
+import { Engine } from '@defra/forms-model'
+
 import { FormModel } from '../.server/server/plugins/engine/models/FormModel.js'
 
+
 import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
 import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.js'
@@ -40,11 +43,20 @@ function pageViewContext(pageDef, state = {}) {
     {
       name: 'preview',
       schema: 2,
+      engine: Engine.V2,
       startPage: pageDef.path,
       sections: [],
       conditions: [],
       lists: [],
-      pages: [pageDef]
+      pages: [
+        pageDef,
+        {
+          path: '/summary',
+          controller: 'SummaryPageController',
+          title: 'Check your answers',
+          components: []
+        }
+      ]
     },
     { basePath: '/preview' }
   )
@@ -54,14 +66,15 @@ function pageViewContext(pageDef, state = {}) {
     errors: undefined,
     evaluationState: {},
     paths: [],
-    state
+    state,
+    isForceAccess: true
   }
   /** @type {import('~/src/server/plugins/engine/types.js').FormContextRequest} */
   const mockRequest = {
-    query: {},
+    query: { force: 'true' },
     params: {},
     path: pageDef.path,
-    url: { search: '' },
+    url: { search: '?force=true' },
     server: { plugins: { 'forms-engine-plugin': {} } }
   }
   return {

From e7bcc105ba9bc2ac7e38ad83c5f62ef4f9958464 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 11:03:14 +0100
Subject: [PATCH 26/40] =?UTF-8?q?refactor:=20derive=20viewName=20from=20pa?=
 =?UTF-8?q?geViewContext=20=E2=80=94=20remove=20hardcoded=20index?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/page-preview-fixtures.js | 81 +++++++++++++++-----------------
 1 file changed, 38 insertions(+), 43 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index d7405bdde..555403208 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -2,7 +2,6 @@ import { Engine } from '@defra/forms-model'
 
 import { FormModel } from '../.server/server/plugins/engine/models/FormModel.js'
 
-
 import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
 import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.js'
@@ -85,54 +84,50 @@ function pageViewContext(pageDef, state = {}) {
 
 /** @type {Record<string, { viewName: string, context?: object, variants?: Array<{label: string, context: object}> }>} */
 export const pageFixtures = {
-  PageController: {
-    viewName: 'index',
-    get variants() {
-      return [
+  PageController: (() => {
+    const single = pageViewContext({
+      path: '/pagepath',
+      title: 'What is your full name?',
+      components: [
         {
-          label: 'Single question',
-          context: pageViewContext({
-            path: '/pagepath',
-            title: 'What is your full name?',
-            components: [
-              {
-                type: 'TextField',
-                name: 'fullname',
-                title: 'What is your full name?',
-                hint: 'As shown on your passport',
-                options: {},
-                schema: {}
-              }
-            ]
-          }).context
+          type: 'TextField',
+          name: 'fullname',
+          title: 'What is your full name?',
+          hint: 'As shown on your passport',
+          options: {},
+          schema: {}
+        }
+      ]
+    })
+    const multiple = pageViewContext({
+      path: '/pagepath',
+      title: 'Tell us about yourself',
+      components: [
+        {
+          type: 'TextField',
+          name: 'fullname',
+          title: 'What is your full name?',
+          options: {},
+          schema: {}
         },
         {
-          label: 'Multiple questions',
-          context: pageViewContext({
-            path: '/pagepath',
-            title: 'Tell us about yourself',
-            components: [
-              {
-                type: 'TextField',
-                name: 'fullname',
-                title: 'What is your full name?',
-                options: {},
-                schema: {}
-              },
-              {
-                type: 'DatePartsField',
-                name: 'dob',
-                title: 'What is your date of birth?',
-                hint: 'For example, 27 3 2007',
-                options: {},
-                schema: {}
-              }
-            ]
-          }).context
+          type: 'DatePartsField',
+          name: 'dob',
+          title: 'What is your date of birth?',
+          hint: 'For example, 27 3 2007',
+          options: {},
+          schema: {}
         }
       ]
+    })
+    return {
+      viewName: single.viewName,
+      variants: [
+        { label: 'Single question', context: single.context },
+        { label: 'Multiple questions', context: multiple.context }
+      ]
     }
-  },
+  })(),
 
   StartPageController: pageViewContext({
     path: '/start',

From 3274a126fa1ff9641a67aedc51b5f0a87d495357 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Thu, 14 May 2026 11:13:41 +0100
Subject: [PATCH 27/40] =?UTF-8?q?refactor:=20viewName=20moves=20into=20con?=
 =?UTF-8?q?text.page=20=E2=80=94=20renderPage=20reads=20from=20context.pag?=
 =?UTF-8?q?e.viewName?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/generate-page-previews.js      |  17 +--
 scripts/generate-page-previews.test.js |  59 +++++++----
 scripts/page-preview-fixtures.js       | 141 +++++++++++++------------
 scripts/page-preview-fixtures.test.js  |   9 +-
 4 files changed, 126 insertions(+), 100 deletions(-)

diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
index 13de5a76d..934f1e31d 100644
--- a/scripts/generate-page-previews.js
+++ b/scripts/generate-page-previews.js
@@ -7,14 +7,15 @@ import { environment } from '~/src/server/plugins/nunjucks/environment.js'
 
 /**
  * Render a single page fixture context to an HTML string.
- * Passes baseLayoutPath: 'preview-layout.html' to strip the GOV.UK page wrapper,
- * leaving only the {% block content %} output from the page template.
+ * Reads the view name from context.page.viewName — set automatically by the
+ * real page controller via getViewModel, or manually on the page stub for
+ * fixtures that don't use pageViewContext.
+ * Passes baseLayoutPath: 'preview-layout.html' to strip the GOV.UK page wrapper.
  * @param {object} context
- * @param {string} viewName
  * @returns {string}
  */
-export function renderPage(context, viewName) {
-  const html = environment.render(`${viewName}.html`, {
+export function renderPage(context) {
+  const html = environment.render(`${context.page.viewName}.html`, {
     ...context,
     baseLayoutPath: 'preview-layout.html'
   })
@@ -28,7 +29,7 @@ export function renderPage(context, viewName) {
  * MDX partial to previewsDir/<slug>.mdx.
  * @param {string} previewsDir
  * @param {string} slug
- * @param {{ viewName: string, context?: object, variants?: Array<{label: string, context: object}> }} fixture
+ * @param {{ context?: object, variants?: Array<{label: string, context: object}> }} fixture
  */
 export function writePagePreviewPartial(previewsDir, slug, fixture) {
   fs.mkdirSync(previewsDir, { recursive: true })
@@ -36,9 +37,9 @@ export function writePagePreviewPartial(previewsDir, slug, fixture) {
   const renders = fixture.variants
     ? fixture.variants.map(({ label, context }) => ({
         label,
-        html: renderPage(context, fixture.viewName)
+        html: renderPage(context)
       }))
-    : [{ html: renderPage(fixture.context, fixture.viewName) }]
+    : [{ html: renderPage(fixture.context) }]
 
   fs.writeFileSync(
     path.join(previewsDir, `${slug}.mdx`),
diff --git a/scripts/generate-page-previews.test.js b/scripts/generate-page-previews.test.js
index 187e3d6fd..869aab76f 100644
--- a/scripts/generate-page-previews.test.js
+++ b/scripts/generate-page-previews.test.js
@@ -28,8 +28,8 @@ describe('renderPage', () => {
     environment.render.mockReturnValue('<h1 class="govuk-heading-l">Page</h1>')
   })
 
-  it('calls environment.render with the correct template name', () => {
-    renderPage({ pageTitle: 'Test' }, 'index')
+  it('calls environment.render with the template name from context.page.viewName', () => {
+    renderPage({ pageTitle: 'Test', page: { viewName: 'index' } })
     expect(environment.render).toHaveBeenCalledWith(
       'index.html',
       expect.objectContaining({ pageTitle: 'Test' })
@@ -37,10 +37,11 @@ describe('renderPage', () => {
   })
 
   it('overrides baseLayoutPath with preview-layout.html', () => {
-    renderPage(
-      { pageTitle: 'Test', baseLayoutPath: 'something-else.html' },
-      'summary'
-    )
+    renderPage({
+      pageTitle: 'Test',
+      baseLayoutPath: 'something-else.html',
+      page: { viewName: 'summary' }
+    })
     expect(environment.render).toHaveBeenCalledWith(
       'summary.html',
       expect.objectContaining({ baseLayoutPath: 'preview-layout.html' })
@@ -49,7 +50,10 @@ describe('renderPage', () => {
 
   it('returns the rendered HTML string', () => {
     environment.render.mockReturnValue('<h1>Check your answers</h1>')
-    const result = renderPage({ pageTitle: 'Check your answers' }, 'summary')
+    const result = renderPage({
+      pageTitle: 'Check your answers',
+      page: { viewName: 'summary' }
+    })
     expect(result).toBe('<h1>Check your answers</h1>')
   })
 
@@ -57,7 +61,10 @@ describe('renderPage', () => {
     environment.render.mockReturnValue(
       '<form method="post" novalidate><button class="govuk-button">Continue</button></form>'
     )
-    const result = renderPage({ pageTitle: 'Test' }, 'index')
+    const result = renderPage({
+      pageTitle: 'Test',
+      page: { viewName: 'index' }
+    })
     expect(result).not.toContain('<form')
     expect(result).not.toContain('</form>')
     expect(result).toContain('<div class="app-page-preview__form">')
@@ -73,8 +80,7 @@ describe('writePagePreviewPartial', () => {
 
   it('creates the output directory', () => {
     writePagePreviewPartial('/out/_previews', 'page-controller', {
-      viewName: 'index',
-      context: { pageTitle: 'Question' }
+      context: { pageTitle: 'Question', page: { viewName: 'index' } }
     })
     expect(mkdirSync).toHaveBeenCalledWith('/out/_previews', {
       recursive: true
@@ -83,8 +89,10 @@ describe('writePagePreviewPartial', () => {
 
   it('writes MDX to the correct path', () => {
     writePagePreviewPartial('/out/_previews', 'summary-page-controller', {
-      viewName: 'summary',
-      context: { pageTitle: 'Check your answers' }
+      context: {
+        pageTitle: 'Check your answers',
+        page: { viewName: 'summary' }
+      }
     })
     expect(writeFileSync).toHaveBeenCalledWith(
       '/out/_previews/summary-page-controller.mdx',
@@ -94,8 +102,7 @@ describe('writePagePreviewPartial', () => {
 
   it('passes a single unlabelled render to buildPartialMdx for a flat fixture', () => {
     writePagePreviewPartial('/out/_previews', 'page-controller', {
-      viewName: 'index',
-      context: { pageTitle: 'Question' }
+      context: { pageTitle: 'Question', page: { viewName: 'index' } }
     })
     expect(buildPartialMdx).toHaveBeenCalledWith(
       [{ html: '<div>page html</div>' }],
@@ -105,10 +112,15 @@ describe('writePagePreviewPartial', () => {
 
   it('passes labelled renders to buildPartialMdx for a variant fixture', () => {
     writePagePreviewPartial('/out/_previews', 'file-upload-page-controller', {
-      viewName: 'file-upload',
       variants: [
-        { label: 'No files uploaded', context: { pageTitle: 'Upload' } },
-        { label: 'With files uploaded', context: { pageTitle: 'Upload' } }
+        {
+          label: 'No files uploaded',
+          context: { pageTitle: 'Upload', page: { viewName: 'file-upload' } }
+        },
+        {
+          label: 'With files uploaded',
+          context: { pageTitle: 'Upload', page: { viewName: 'file-upload' } }
+        }
       ]
     })
     expect(buildPartialMdx).toHaveBeenCalledWith(
@@ -126,15 +138,22 @@ describe('writePagePreviewPartial', () => {
       .mockReturnValueOnce('<div>with files</div>')
 
     writePagePreviewPartial('/out/_previews', 'file-upload-page-controller', {
-      viewName: 'file-upload',
       variants: [
         {
           label: 'No files uploaded',
-          context: { pageTitle: 'Upload', formAction: null }
+          context: {
+            pageTitle: 'Upload',
+            formAction: null,
+            page: { viewName: 'file-upload' }
+          }
         },
         {
           label: 'With files uploaded',
-          context: { pageTitle: 'Upload', formAction: 'preview' }
+          context: {
+            pageTitle: 'Upload',
+            formAction: 'preview',
+            page: { viewName: 'file-upload' }
+          }
         }
       ]
     })
diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 555403208..40185b6e1 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -35,7 +35,7 @@ function componentViewModel(name, variantLabel) {
  * automatically — no manual fixture properties needed for these.
  * @param {object} pageDef - Page definition (path, title, controller, components)
  * @param {object} [state] - Optional form state to pass as the payload
- * @returns {{ viewName: string, context: object }}
+ * @returns {object}
  */
 function pageViewContext(pageDef, state = {}) {
   const model = new FormModel(
@@ -76,84 +76,86 @@ function pageViewContext(pageDef, state = {}) {
     url: { search: '?force=true' },
     server: { plugins: { 'forms-engine-plugin': {} } }
   }
-  return {
-    viewName: controller.viewName,
-    context: controller.getViewModel(mockRequest, mockContext)
-  }
+  return controller.getViewModel(mockRequest, mockContext)
 }
 
-/** @type {Record<string, { viewName: string, context?: object, variants?: Array<{label: string, context: object}> }>} */
+/** @type {Record<string, { context?: object, variants?: Array<{label: string, context: object}> }>} */
 export const pageFixtures = {
-  PageController: (() => {
-    const single = pageViewContext({
-      path: '/pagepath',
-      title: 'What is your full name?',
-      components: [
-        {
-          type: 'TextField',
-          name: 'fullname',
+  PageController: {
+    variants: [
+      {
+        label: 'Single question',
+        context: pageViewContext({
+          path: '/pagepath',
           title: 'What is your full name?',
-          hint: 'As shown on your passport',
-          options: {},
-          schema: {}
-        }
-      ]
+          components: [
+            {
+              type: 'TextField',
+              name: 'fullname',
+              title: 'What is your full name?',
+              hint: 'As shown on your passport',
+              options: {},
+              schema: {}
+            }
+          ]
+        })
+      },
+      {
+        label: 'Multiple questions',
+        context: pageViewContext({
+          path: '/pagepath',
+          title: 'Tell us about yourself',
+          components: [
+            {
+              type: 'TextField',
+              name: 'fullname',
+              title: 'What is your full name?',
+              options: {},
+              schema: {}
+            },
+            {
+              type: 'DatePartsField',
+              name: 'dob',
+              title: 'What is your date of birth?',
+              hint: 'For example, 27 3 2007',
+              options: {},
+              schema: {}
+            }
+          ]
+        })
+      }
+    ]
+  },
+
+  StartPageController: {
+    context: pageViewContext({
+      path: '/start',
+      controller: 'StartPageController',
+      title: 'Apply for a licence',
+      components: []
     })
-    const multiple = pageViewContext({
-      path: '/pagepath',
-      title: 'Tell us about yourself',
+  },
+
+  TerminalPageController: {
+    context: pageViewContext({
+      path: '/ineligible',
+      controller: 'TerminalPageController',
+      title: 'You are not eligible',
       components: [
         {
-          type: 'TextField',
-          name: 'fullname',
-          title: 'What is your full name?',
-          options: {},
-          schema: {}
-        },
-        {
-          type: 'DatePartsField',
-          name: 'dob',
-          title: 'What is your date of birth?',
-          hint: 'For example, 27 3 2007',
-          options: {},
-          schema: {}
+          type: 'Html',
+          name: 'eligibility',
+          content:
+            '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
+          options: {}
         }
       ]
     })
-    return {
-      viewName: single.viewName,
-      variants: [
-        { label: 'Single question', context: single.context },
-        { label: 'Multiple questions', context: multiple.context }
-      ]
-    }
-  })(),
-
-  StartPageController: pageViewContext({
-    path: '/start',
-    controller: 'StartPageController',
-    title: 'Apply for a licence',
-    components: []
-  }),
-
-  TerminalPageController: pageViewContext({
-    path: '/ineligible',
-    controller: 'TerminalPageController',
-    title: 'You are not eligible',
-    components: [
-      {
-        type: 'Html',
-        name: 'eligibility',
-        content:
-          '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
-        options: {}
-      }
-    ]
-  }),
+  },
 
   RepeatPageController: {
-    viewName: 'repeat-list-summary',
     context: {
+      page: { viewName: 'repeat-list-summary' },
       pageTitle: 'Add members of your household',
       showTitle: true,
       allowSaveAndExit: false,
@@ -184,7 +186,6 @@ export const pageFixtures = {
   },
 
   FileUploadPageController: {
-    viewName: 'file-upload',
     exampleComponents: [
       {
         type: 'FileUploadField',
@@ -202,7 +203,7 @@ export const pageFixtures = {
             pageTitle: 'Upload a document',
             showTitle: true,
             formAction: 'preview',
-            page: { allowContinue: true },
+            page: { viewName: 'file-upload', allowContinue: true },
             componentsBefore: [],
             components: [
               componentViewModel('FileUploadField', 'No files uploaded')
@@ -219,7 +220,7 @@ export const pageFixtures = {
             pageTitle: 'Upload a document',
             showTitle: true,
             formAction: 'preview',
-            page: { allowContinue: true },
+            page: { viewName: 'file-upload', allowContinue: true },
             componentsBefore: [],
             components: [
               componentViewModel('FileUploadField', 'With files uploaded')
@@ -235,8 +236,8 @@ export const pageFixtures = {
   },
 
   SummaryPageController: {
-    viewName: 'summary',
     context: {
+      page: { viewName: 'summary' },
       pageTitle: 'Check your answers',
       allowSaveAndExit: false,
       checkAnswers: [
diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
index 3b474c7da..528b6a500 100644
--- a/scripts/page-preview-fixtures.test.js
+++ b/scripts/page-preview-fixtures.test.js
@@ -36,9 +36,14 @@ describe('page-preview-fixtures', () => {
     }
   })
 
-  it('every fixture has a viewName string', () => {
+  it('every fixture context has a page.viewName string', () => {
     for (const [_key, fixture] of Object.entries(pageFixtures)) {
-      expect(typeof fixture.viewName).toBe('string')
+      const contexts = fixture.variants
+        ? fixture.variants.map((v) => v.context)
+        : [fixture.context]
+      for (const context of contexts) {
+        expect(typeof context.page?.viewName).toBe('string')
+      }
     }
   })
 

From 659e5e169e706c47988a42239a174775bdf4fd78 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 10:16:28 +0100
Subject: [PATCH 28/40] =?UTF-8?q?refactor:=20all=206=20page=20controllers?=
 =?UTF-8?q?=20use=20pageViewContext=20=E2=80=94=20drop=20componentViewMode?=
 =?UTF-8?q?l,=20simplify=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/page-preview-fixtures.js      | 284 ++++++++++++--------------
 scripts/page-preview-fixtures.test.js |  82 +-------
 2 files changed, 142 insertions(+), 224 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 40185b6e1..e051719ae 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -4,69 +4,58 @@ import { FormModel } from '../.server/server/plugins/engine/models/FormModel.js'
 
 import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
-import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.js'
-
-/**
- * Builds a component view model from the named component fixture so page
- * fixtures can reuse the same data as component previews without duplicating
- * component definitions. Supports variant fixtures — pass a label to select
- * a specific variant, or omit it to use the first (or only) variant.
- * @param {string} name - e.g. 'FileUploadField'
- * @param {string} [variantLabel] - e.g. 'No files uploaded'
- * @returns {{ type: string, model: object }}
- */
-function componentViewModel(name, variantLabel) {
-  const fixture = componentFixtures[name]
-  const variant = fixture.variants
-    ? (fixture.variants.find((v) => v.label === variantLabel) ??
-      fixture.variants[0])
-    : fixture
-  const component = createComponent(variant.def, { model: variant.model })
-  return {
-    type: variant.def.type,
-    model: component.getViewModel(variant.payload, [])
-  }
+const SUMMARY_PAGE_DEF = {
+  path: '/summary',
+  controller: 'SummaryPageController',
+  title: 'Check your answers',
+  components: []
 }
 
 /**
  * Instantiates the real page controller for the given page definition and
- * calls getViewModel with a minimal mock request/context. The controller
- * handles showTitle, label sizing, isPageHeading, allowContinue, and viewName
- * automatically — no manual fixture properties needed for these.
- * @param {object} pageDef - Page definition (path, title, controller, components)
- * @param {object} [state] - Optional form state to pass as the payload
+ * calls getViewModel (or an optional invoke callback) with a minimal mock
+ * request/context. The controller handles showTitle, label sizing,
+ * isPageHeading, allowContinue, and viewName automatically.
+ * @param {object} pageDef - Page definition for the preview page
+ * @param {object} [options]
+ * @param {object} [options.state] - Form state passed as both payload and state
+ * @param {object[]} [options.additionalPageDefs] - Extra page defs to include before pageDef (e.g. question pages before a summary)
+ * @param {(controller: object, model: object, request: object, context: object) => object} [options.invoke] - Override which method to call; defaults to getViewModel
  * @returns {object}
  */
-function pageViewContext(pageDef, state = {}) {
+function pageViewContext(
+  pageDef,
+  { state = {}, payload, additionalPageDefs = [], invoke } = {}
+) {
+  const isSummary = pageDef.controller === 'SummaryPageController'
+  const allPageDefs = [
+    ...additionalPageDefs,
+    pageDef,
+    ...(isSummary ? [] : [SUMMARY_PAGE_DEF])
+  ]
   const model = new FormModel(
     {
       name: 'preview',
       schema: 2,
       engine: Engine.V2,
-      startPage: pageDef.path,
+      startPage: allPageDefs[0].path,
       sections: [],
       conditions: [],
       lists: [],
-      pages: [
-        pageDef,
-        {
-          path: '/summary',
-          controller: 'SummaryPageController',
-          title: 'Check your answers',
-          components: []
-        }
-      ]
+      pages: allPageDefs
     },
     { basePath: '/preview' }
   )
-  const [controller] = model.pages
+  const controller = model.pages[additionalPageDefs.length]
   const mockContext = {
-    payload: state,
+    payload: payload ?? state,
     errors: undefined,
-    evaluationState: {},
+    evaluationState: state,
+    relevantState: state,
     paths: [],
     state,
-    isForceAccess: true
+    isForceAccess: true,
+    relevantPages: model.pages.filter((p) => p.viewName !== 'summary')
   }
   /** @type {import('~/src/server/plugins/engine/types.js').FormContextRequest} */
   const mockRequest = {
@@ -76,7 +65,9 @@ function pageViewContext(pageDef, state = {}) {
     url: { search: '?force=true' },
     server: { plugins: { 'forms-engine-plugin': {} } }
   }
-  return controller.getViewModel(mockRequest, mockContext)
+  return invoke
+    ? invoke(controller, model, mockRequest, mockContext)
+    : controller.getViewModel(mockRequest, mockContext)
 }
 
 /** @type {Record<string, { context?: object, variants?: Array<{label: string, context: object}> }>} */
@@ -154,126 +145,121 @@ export const pageFixtures = {
   },
 
   RepeatPageController: {
-    context: {
-      page: { viewName: 'repeat-list-summary' },
-      pageTitle: 'Add members of your household',
-      showTitle: true,
-      allowSaveAndExit: false,
-      checkAnswers: [
-        {
-          summaryList: {
-            rows: [
-              {
-                key: { text: 'Full name' },
-                value: { text: 'Sarah Phillips' },
-                actions: { items: [{ href: '#', text: 'Remove' }] }
-              },
-              {
-                key: { text: 'Full name' },
-                value: { text: 'David Jones' },
-                actions: { items: [{ href: '#', text: 'Remove' }] }
-              },
-              {
-                key: { text: 'Full name' },
-                value: { text: 'Emma Wilson' },
-                actions: { items: [{ href: '#', text: 'Remove' }] }
-              }
-            ]
+    context: pageViewContext(
+      {
+        path: '/people',
+        controller: 'RepeatPageController',
+        title: 'People',
+        repeat: {
+          options: { name: 'people', title: 'Person' },
+          schema: { min: 1, max: 25 }
+        },
+        components: [
+          {
+            type: 'TextField',
+            name: 'fullname',
+            title: 'Full name',
+            options: {},
+            schema: {}
           }
-        }
-      ]
-    }
+        ]
+      },
+      {
+        invoke: (ctrl, _model, req, ctx) =>
+          ctrl.getListSummaryViewModel(req, ctx, [
+            { itemId: '1', fullname: 'Sarah Phillips' },
+            { itemId: '2', fullname: 'David Jones' },
+            { itemId: '3', fullname: 'Emma Wilson' }
+          ])
+      }
+    )
   },
 
   FileUploadPageController: {
-    exampleComponents: [
+    exampleComponents: [componentFixtures['FileUploadField'].variants[0].def],
+    variants: [
       {
-        type: 'FileUploadField',
-        name: 'upload',
-        title: 'Upload a document',
-        options: {},
-        schema: {}
-      }
-    ],
-    get variants() {
-      return [
-        {
-          label: 'No files uploaded',
-          context: {
-            pageTitle: 'Upload a document',
-            showTitle: true,
-            formAction: 'preview',
-            page: { viewName: 'file-upload', allowContinue: true },
-            componentsBefore: [],
-            components: [
-              componentViewModel('FileUploadField', 'No files uploaded')
-            ],
-            formComponent: componentViewModel(
-              'FileUploadField',
-              'No files uploaded'
-            )
+        label: 'No files uploaded',
+        context: pageViewContext(
+          {
+            path: '/upload',
+            controller: 'FileUploadPageController',
+            title: 'Upload a document',
+            components: [componentFixtures['FileUploadField'].variants[0].def]
+          },
+          {
+            state: {
+              upload: {
+                '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+              }
+            }
           }
-        },
-        {
-          label: 'With files uploaded',
-          context: {
-            pageTitle: 'Upload a document',
-            showTitle: true,
-            formAction: 'preview',
-            page: { viewName: 'file-upload', allowContinue: true },
-            componentsBefore: [],
-            components: [
-              componentViewModel('FileUploadField', 'With files uploaded')
-            ],
-            formComponent: componentViewModel(
-              'FileUploadField',
-              'With files uploaded'
-            )
+        )
+      },
+      {
+        label: 'With files uploaded',
+        context: pageViewContext(
+          {
+            path: '/upload',
+            controller: 'FileUploadPageController',
+            title: 'Upload a document',
+            components: [componentFixtures['FileUploadField'].variants[0].def]
+          },
+          {
+            state: {
+              upload: {
+                '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+              }
+            },
+            payload: componentFixtures['FileUploadField'].variants.find(
+              (v) => v.label === 'With files uploaded'
+            ).payload
           }
-        }
-      ]
-    }
+        )
+      }
+    ]
   },
 
   SummaryPageController: {
-    context: {
-      page: { viewName: 'summary' },
-      pageTitle: 'Check your answers',
-      allowSaveAndExit: false,
-      checkAnswers: [
-        {
-          summaryList: {
-            rows: [
+    context: pageViewContext(
+      {
+        path: '/summary',
+        controller: 'SummaryPageController',
+        title: 'Check your answers',
+        components: []
+      },
+      {
+        additionalPageDefs: [
+          {
+            path: '/name',
+            title: 'Full name',
+            components: [
               {
-                key: { text: 'Full name' },
-                value: { text: 'Sarah Phillips' },
-                actions: {
-                  items: [
-                    {
-                      href: '#',
-                      text: 'Change',
-                      visuallyHiddenText: 'full name'
-                    }
-                  ]
-                }
-              },
+                type: 'TextField',
+                name: 'fullname',
+                title: 'Full name',
+                options: {},
+                schema: {}
+              }
+            ]
+          },
+          {
+            path: '/email',
+            title: 'Email',
+            components: [
               {
-                key: { text: 'Email address' },
-                value: { text: 'sarah@example.gov.uk' },
-                actions: {
-                  items: [
-                    {
-                      href: '#',
-                      text: 'Change',
-                      visuallyHiddenText: 'email address'
-                    }
-                  ]
-                }
+                type: 'EmailAddressField',
+                name: 'email',
+                title: 'Email address',
+                options: {},
+                schema: {}
               }
             ]
           }
-        }
-      ]
-    }
+        ],
+        state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
+        invoke: (ctrl, _model, req, ctx) => ctrl.getSummaryViewModel(req, ctx)
+      }
+    )
   }
 }
diff --git a/scripts/page-preview-fixtures.test.js b/scripts/page-preview-fixtures.test.js
index 528b6a500..e2517bc45 100644
--- a/scripts/page-preview-fixtures.test.js
+++ b/scripts/page-preview-fixtures.test.js
@@ -1,26 +1,7 @@
 // @ts-nocheck
 
-jest.mock(
-  '~/src/server/plugins/engine/components/helpers/components.ts',
-  () => ({
-    createComponent: jest.fn().mockReturnValue({
-      getViewModel: jest.fn().mockReturnValue({ id: 'field', name: 'field' })
-    })
-  })
-)
-
-import { ComponentType } from '@defra/forms-model'
-
 import { pageFixtures } from './page-preview-fixtures.js'
 
-import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.ts'
-
-beforeEach(() => {
-  createComponent.mockReturnValue({
-    getViewModel: jest.fn().mockReturnValue({ id: 'field', name: 'field' })
-  })
-})
-
 describe('page-preview-fixtures', () => {
   it('all 6 expected page types are present', () => {
     const expected = [
@@ -36,7 +17,13 @@ describe('page-preview-fixtures', () => {
     }
   })
 
-  it('every fixture context has a page.viewName string', () => {
+  it('every fixture has either context or variants', () => {
+    for (const [_key, fixture] of Object.entries(pageFixtures)) {
+      expect(!!fixture.context || !!fixture.variants).toBe(true)
+    }
+  })
+
+  it('every context has a page.viewName string', () => {
     for (const [_key, fixture] of Object.entries(pageFixtures)) {
       const contexts = fixture.variants
         ? fixture.variants.map((v) => v.context)
@@ -47,14 +34,6 @@ describe('page-preview-fixtures', () => {
     }
   })
 
-  it('every fixture has either context or variants, not neither', () => {
-    for (const [_key, fixture] of Object.entries(pageFixtures)) {
-      const hasContext = !!fixture.context
-      const hasVariants = !!fixture.variants
-      expect(hasContext || hasVariants).toBe(true)
-    }
-  })
-
   it('variant fixtures have label and context on every variant', () => {
     const variantFixtures = Object.entries(pageFixtures).filter(
       ([, fixture]) => fixture.variants
@@ -71,51 +50,4 @@ describe('page-preview-fixtures', () => {
   it('FileUploadPageController has exactly 2 variants', () => {
     expect(pageFixtures.FileUploadPageController.variants).toHaveLength(2)
   })
-
-  it('FileUploadPageController variants reference the FileUploadField component fixture', () => {
-    for (const variant of pageFixtures.FileUploadPageController.variants) {
-      const _model = variant.context.formComponent.model // trigger lazy getter
-    }
-    expect(createComponent).toHaveBeenCalledWith(
-      expect.objectContaining({ type: ComponentType.FileUploadField }),
-      expect.anything()
-    )
-  })
-
-  it('PageController has exactly 2 variants', () => {
-    expect(pageFixtures.PageController.variants).toHaveLength(2)
-  })
-
-  it('PageController single question variant sets isPageHeading and govuk-label--l on the TextField label', () => {
-    const mockLabel = {
-      text: 'What is your full name?',
-      classes: 'govuk-label--s'
-    }
-    createComponent.mockReturnValue({
-      getViewModel: jest.fn().mockReturnValue({
-        id: 'full-name',
-        name: 'full-name',
-        label: mockLabel
-      })
-    })
-    const singleVariant = pageFixtures.PageController.variants[0]
-    const [component] = singleVariant.context.components
-    expect(component.model.label.isPageHeading).toBe(true)
-    expect(component.model.label.classes).toBe('govuk-label--l')
-  })
-
-  it('PageController single question variant has showTitle false', () => {
-    expect(pageFixtures.PageController.variants[0].context.showTitle).toBe(
-      false
-    )
-  })
-
-  it('PageController multiple questions variant has showTitle true', () => {
-    expect(pageFixtures.PageController.variants[1].context.showTitle).toBe(true)
-  })
-
-  it('PageController multiple questions variant has two components', () => {
-    const multiVariant = pageFixtures.PageController.variants[1]
-    expect(multiVariant.context.components).toHaveLength(2)
-  })
 })

From f277b2b87d3da64195502c4f887293549ce0d223 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 10:26:43 +0100
Subject: [PATCH 29/40] fix: isForceAccess false restores Change/Remove links;
 patch listSummaryViewName for Repeat

---
 scripts/page-preview-fixtures.js | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index e051719ae..126952e46 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -54,7 +54,7 @@ function pageViewContext(
     relevantState: state,
     paths: [],
     state,
-    isForceAccess: true,
+    isForceAccess: false,
     relevantPages: model.pages.filter((p) => p.viewName !== 'summary')
   }
   /** @type {import('~/src/server/plugins/engine/types.js').FormContextRequest} */
@@ -165,12 +165,17 @@ export const pageFixtures = {
         ]
       },
       {
-        invoke: (ctrl, _model, req, ctx) =>
-          ctrl.getListSummaryViewModel(req, ctx, [
+        invoke: (ctrl, _model, req, ctx) => {
+          const vm = ctrl.getListSummaryViewModel(req, ctx, [
             { itemId: '1', fullname: 'Sarah Phillips' },
             { itemId: '2', fullname: 'David Jones' },
             { itemId: '3', fullname: 'Emma Wilson' }
           ])
+          return {
+            ...vm,
+            page: { ...vm.page, viewName: ctrl.listSummaryViewName }
+          }
+        }
       }
     )
   },

From 4675b6bfc8aea20674061b4d93e43054db0150df Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 11:05:54 +0100
Subject: [PATCH 30/40] fix: remove force query param so FileUploadField shows
 Remove links

---
 scripts/page-preview-fixtures.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 126952e46..17e463edb 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -59,10 +59,10 @@ function pageViewContext(
   }
   /** @type {import('~/src/server/plugins/engine/types.js').FormContextRequest} */
   const mockRequest = {
-    query: { force: 'true' },
+    query: {},
     params: {},
     path: pageDef.path,
-    url: { search: '?force=true' },
+    url: { search: '' },
     server: { plugins: { 'forms-engine-plugin': {} } }
   }
   return invoke

From 382109314a0df5295cf267488390ef130ccf331b Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 11:33:42 +0100
Subject: [PATCH 31/40] feat: neutralise all hrefs in page previews to prevent
 navigation

---
 scripts/generate-page-previews.js      |  1 +
 scripts/generate-page-previews.test.js | 13 +++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
index 934f1e31d..b6fc6a13b 100644
--- a/scripts/generate-page-previews.js
+++ b/scripts/generate-page-previews.js
@@ -22,6 +22,7 @@ export function renderPage(context) {
   return html
     .replace(/<form\b[^>]*>/g, '<div class="app-page-preview__form">')
     .replace(/<\/form>/g, '</div>')
+    .replace(/href="[^"]*"/g, 'href="#"')
 }
 
 /**
diff --git a/scripts/generate-page-previews.test.js b/scripts/generate-page-previews.test.js
index 869aab76f..b2d551551 100644
--- a/scripts/generate-page-previews.test.js
+++ b/scripts/generate-page-previews.test.js
@@ -57,6 +57,19 @@ describe('renderPage', () => {
     expect(result).toBe('<h1>Check your answers</h1>')
   })
 
+  it('replaces all href values with # to neutralise links', () => {
+    environment.render.mockReturnValue(
+      '<a href="/some/path" class="govuk-link">Change</a><a href="/another?q=1">Remove</a>'
+    )
+    const result = renderPage({
+      pageTitle: 'Test',
+      page: { viewName: 'index' }
+    })
+    expect(result).not.toContain('href="/some/path"')
+    expect(result).not.toContain('href="/another?q=1"')
+    expect(result).toContain('href="#"')
+  })
+
   it('replaces <form> tags with divs to prevent form submission', () => {
     environment.render.mockReturnValue(
       '<form method="post" novalidate><button class="govuk-button">Continue</button></form>'

From 17d1501a92ab34a7ac740b25854b11d3c5bc886f Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 12:31:16 +0100
Subject: [PATCH 32/40] docs: explain interactive element neutralisation in
 renderPage

---
 scripts/generate-page-previews.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
index b6fc6a13b..420b31a3a 100644
--- a/scripts/generate-page-previews.js
+++ b/scripts/generate-page-previews.js
@@ -19,6 +19,7 @@ export function renderPage(context) {
     ...context,
     baseLayoutPath: 'preview-layout.html'
   })
+  // Neutralise interactive elements — this is documentation, not a working service.
   return html
     .replace(/<form\b[^>]*>/g, '<div class="app-page-preview__form">')
     .replace(/<\/form>/g, '</div>')

From b747bbae73301bd6792d44829418cf8a172d5903 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 14:07:25 +0100
Subject: [PATCH 33/40] rename invoke

---
 scripts/page-preview-fixtures.js | 91 +++++++++++++++++---------------
 1 file changed, 47 insertions(+), 44 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 17e463edb..ee1551c64 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -20,18 +20,24 @@ const SUMMARY_PAGE_DEF = {
  * @param {object} [options]
  * @param {object} [options.state] - Form state passed as both payload and state
  * @param {object[]} [options.additionalPageDefs] - Extra page defs to include before pageDef (e.g. question pages before a summary)
- * @param {(controller: object, model: object, request: object, context: object) => object} [options.invoke] - Override which method to call; defaults to getViewModel
+ * @param {boolean} [options.appendSummary] - Append SUMMARY_PAGE_DEF after pageDef; pass false when pageDef IS the summary page
+ * @param {(controller: object, model: object, request: object, context: object) => object} [options.getViewModelOverride] - Override which method to call; defaults to getViewModel
  * @returns {object}
  */
 function pageViewContext(
   pageDef,
-  { state = {}, payload, additionalPageDefs = [], invoke } = {}
+  {
+    state = {},
+    payload,
+    additionalPageDefs = [],
+    appendSummary = true,
+    getViewModelOverride
+  } = {}
 ) {
-  const isSummary = pageDef.controller === 'SummaryPageController'
   const allPageDefs = [
     ...additionalPageDefs,
     pageDef,
-    ...(isSummary ? [] : [SUMMARY_PAGE_DEF])
+    ...(appendSummary ? [SUMMARY_PAGE_DEF] : [])
   ]
   const model = new FormModel(
     {
@@ -57,7 +63,7 @@ function pageViewContext(
     isForceAccess: false,
     relevantPages: model.pages.filter((p) => p.viewName !== 'summary')
   }
-  /** @type {import('~/src/server/plugins/engine/types.js').FormContextRequest} */
+  /** @type {FormContextRequest} */
   const mockRequest = {
     query: {},
     params: {},
@@ -65,12 +71,30 @@ function pageViewContext(
     url: { search: '' },
     server: { plugins: { 'forms-engine-plugin': {} } }
   }
-  return invoke
-    ? invoke(controller, model, mockRequest, mockContext)
+  return getViewModelOverride
+    ? getViewModelOverride(controller, model, mockRequest, mockContext)
     : controller.getViewModel(mockRequest, mockContext)
 }
 
-/** @type {Record<string, { context?: object, variants?: Array<{label: string, context: object}> }>} */
+const fileUploadDef = componentFixtures['FileUploadField'].variants[0].def
+const fileUploadWithFilesPayload = componentFixtures[
+  'FileUploadField'
+].variants.find((v) => v.label === 'With files uploaded').payload
+
+const fileUploadPageDef = {
+  path: '/upload',
+  controller: 'FileUploadPageController',
+  title: 'Upload a document',
+  components: [fileUploadDef]
+}
+
+const fileUploadState = {
+  upload: {
+    '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+  }
+}
+
+/** @type {Record<string, PageFixture>} */
 export const pageFixtures = {
   PageController: {
     variants: [
@@ -165,7 +189,7 @@ export const pageFixtures = {
         ]
       },
       {
-        invoke: (ctrl, _model, req, ctx) => {
+        getViewModelOverride: (ctrl, _model, req, ctx) => {
           const vm = ctrl.getListSummaryViewModel(req, ctx, [
             { itemId: '1', fullname: 'Sarah Phillips' },
             { itemId: '2', fullname: 'David Jones' },
@@ -181,46 +205,18 @@ export const pageFixtures = {
   },
 
   FileUploadPageController: {
-    exampleComponents: [componentFixtures['FileUploadField'].variants[0].def],
+    exampleComponents: [fileUploadDef],
     variants: [
       {
         label: 'No files uploaded',
-        context: pageViewContext(
-          {
-            path: '/upload',
-            controller: 'FileUploadPageController',
-            title: 'Upload a document',
-            components: [componentFixtures['FileUploadField'].variants[0].def]
-          },
-          {
-            state: {
-              upload: {
-                '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
-              }
-            }
-          }
-        )
+        context: pageViewContext(fileUploadPageDef, { state: fileUploadState })
       },
       {
         label: 'With files uploaded',
-        context: pageViewContext(
-          {
-            path: '/upload',
-            controller: 'FileUploadPageController',
-            title: 'Upload a document',
-            components: [componentFixtures['FileUploadField'].variants[0].def]
-          },
-          {
-            state: {
-              upload: {
-                '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
-              }
-            },
-            payload: componentFixtures['FileUploadField'].variants.find(
-              (v) => v.label === 'With files uploaded'
-            ).payload
-          }
-        )
+        context: pageViewContext(fileUploadPageDef, {
+          state: fileUploadState,
+          payload: fileUploadWithFilesPayload
+        })
       }
     ]
   },
@@ -234,6 +230,7 @@ export const pageFixtures = {
         components: []
       },
       {
+        appendSummary: false,
         additionalPageDefs: [
           {
             path: '/name',
@@ -263,8 +260,14 @@ export const pageFixtures = {
           }
         ],
         state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
-        invoke: (ctrl, _model, req, ctx) => ctrl.getSummaryViewModel(req, ctx)
+        getViewModelOverride: (ctrl, _model, req, ctx) =>
+          ctrl.getSummaryViewModel(req, ctx)
       }
     )
   }
 }
+
+/**
+ * @typedef {import('~/src/server/plugins/engine/types.js').FormContextRequest} FormContextRequest
+ * @typedef {{ context?: object, variants?: Array<{label: string, context: object}> }} PageFixture
+ */

From 0bd7c4b539b669eb332910fb7890eb9297c8c88c Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 14:36:56 +0100
Subject: [PATCH 34/40] cleanup

---
 scripts/page-preview-fixtures.js | 269 +++++++++++++++----------------
 1 file changed, 134 insertions(+), 135 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index ee1551c64..5a6d9f5ea 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -13,32 +13,25 @@ const SUMMARY_PAGE_DEF = {
 
 /**
  * Instantiates the real page controller for the given page definition and
- * calls getViewModel (or an optional invoke callback) with a minimal mock
+ * calls getViewModel (or an optional override) with a minimal mock
  * request/context. The controller handles showTitle, label sizing,
  * isPageHeading, allowContinue, and viewName automatically.
- * @param {object} pageDef - Page definition for the preview page
- * @param {object} [options]
- * @param {object} [options.state] - Form state passed as both payload and state
- * @param {object[]} [options.additionalPageDefs] - Extra page defs to include before pageDef (e.g. question pages before a summary)
- * @param {boolean} [options.appendSummary] - Append SUMMARY_PAGE_DEF after pageDef; pass false when pageDef IS the summary page
+ * @param {object} options
+ * @param {object[]} options.pages - All page defs; SUMMARY_PAGE_DEF is always appended automatically
+ * @param {string} [options.renderPage] - Path of the page to render; defaults to pages[0].path
+ * @param {object} [options.state] - Form state
+ * @param {object} [options.payload] - Form payload; defaults to state
  * @param {(controller: object, model: object, request: object, context: object) => object} [options.getViewModelOverride] - Override which method to call; defaults to getViewModel
  * @returns {object}
  */
-function pageViewContext(
-  pageDef,
-  {
-    state = {},
-    payload,
-    additionalPageDefs = [],
-    appendSummary = true,
-    getViewModelOverride
-  } = {}
-) {
-  const allPageDefs = [
-    ...additionalPageDefs,
-    pageDef,
-    ...(appendSummary ? [SUMMARY_PAGE_DEF] : [])
-  ]
+function pageViewContext({
+  pages,
+  renderPage = pages[0].path,
+  state = {},
+  payload,
+  getViewModelOverride
+}) {
+  const allPageDefs = [...pages, SUMMARY_PAGE_DEF]
   const model = new FormModel(
     {
       name: 'preview',
@@ -52,7 +45,7 @@ function pageViewContext(
     },
     { basePath: '/preview' }
   )
-  const controller = model.pages[additionalPageDefs.length]
+  const controller = model.pages.find((p) => p.path === renderPage)
   const mockContext = {
     payload: payload ?? state,
     errors: undefined,
@@ -67,7 +60,7 @@ function pageViewContext(
   const mockRequest = {
     query: {},
     params: {},
-    path: pageDef.path,
+    path: renderPage,
     url: { search: '' },
     server: { plugins: { 'forms-engine-plugin': {} } }
   }
@@ -101,16 +94,20 @@ export const pageFixtures = {
       {
         label: 'Single question',
         context: pageViewContext({
-          path: '/pagepath',
-          title: 'What is your full name?',
-          components: [
+          pages: [
             {
-              type: 'TextField',
-              name: 'fullname',
+              path: '/pagepath',
               title: 'What is your full name?',
-              hint: 'As shown on your passport',
-              options: {},
-              schema: {}
+              components: [
+                {
+                  type: 'TextField',
+                  name: 'fullname',
+                  title: 'What is your full name?',
+                  hint: 'As shown on your passport',
+                  options: {},
+                  schema: {}
+                }
+              ]
             }
           ]
         })
@@ -118,23 +115,27 @@ export const pageFixtures = {
       {
         label: 'Multiple questions',
         context: pageViewContext({
-          path: '/pagepath',
-          title: 'Tell us about yourself',
-          components: [
-            {
-              type: 'TextField',
-              name: 'fullname',
-              title: 'What is your full name?',
-              options: {},
-              schema: {}
-            },
+          pages: [
             {
-              type: 'DatePartsField',
-              name: 'dob',
-              title: 'What is your date of birth?',
-              hint: 'For example, 27 3 2007',
-              options: {},
-              schema: {}
+              path: '/pagepath',
+              title: 'Tell us about yourself',
+              components: [
+                {
+                  type: 'TextField',
+                  name: 'fullname',
+                  title: 'What is your full name?',
+                  options: {},
+                  schema: {}
+                },
+                {
+                  type: 'DatePartsField',
+                  name: 'dob',
+                  title: 'What is your date of birth?',
+                  hint: 'For example, 27 3 2007',
+                  options: {},
+                  schema: {}
+                }
+              ]
             }
           ]
         })
@@ -144,64 +145,72 @@ export const pageFixtures = {
 
   StartPageController: {
     context: pageViewContext({
-      path: '/start',
-      controller: 'StartPageController',
-      title: 'Apply for a licence',
-      components: []
+      pages: [
+        {
+          path: '/start',
+          controller: 'StartPageController',
+          title: 'Apply for a licence',
+          components: []
+        }
+      ]
     })
   },
 
   TerminalPageController: {
     context: pageViewContext({
-      path: '/ineligible',
-      controller: 'TerminalPageController',
-      title: 'You are not eligible',
-      components: [
+      pages: [
         {
-          type: 'Html',
-          name: 'eligibility',
-          content:
-            '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
-          options: {}
+          path: '/ineligible',
+          controller: 'TerminalPageController',
+          title: 'You are not eligible',
+          components: [
+            {
+              type: 'Html',
+              name: 'eligibility',
+              content:
+                '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
+              options: {}
+            }
+          ]
         }
       ]
     })
   },
 
   RepeatPageController: {
-    context: pageViewContext(
-      {
-        path: '/people',
-        controller: 'RepeatPageController',
-        title: 'People',
-        repeat: {
-          options: { name: 'people', title: 'Person' },
-          schema: { min: 1, max: 25 }
-        },
-        components: [
-          {
-            type: 'TextField',
-            name: 'fullname',
-            title: 'Full name',
-            options: {},
-            schema: {}
-          }
-        ]
-      },
-      {
-        getViewModelOverride: (ctrl, _model, req, ctx) => {
-          const vm = ctrl.getListSummaryViewModel(req, ctx, [
-            { itemId: '1', fullname: 'Sarah Phillips' },
-            { itemId: '2', fullname: 'David Jones' },
-            { itemId: '3', fullname: 'Emma Wilson' }
-          ])
-          return {
-            ...vm,
-            page: { ...vm.page, viewName: ctrl.listSummaryViewName }
-          }
+    context: pageViewContext({
+      pages: [
+        {
+          path: '/people',
+          controller: 'RepeatPageController',
+          title: 'People',
+          repeat: {
+            options: { name: 'people', title: 'Person' },
+            schema: { min: 1, max: 25 }
+          },
+          components: [
+            {
+              type: 'TextField',
+              name: 'fullname',
+              title: 'Full name',
+              options: {},
+              schema: {}
+            }
+          ]
+        }
+      ],
+      getViewModelOverride: (ctrl, _model, req, ctx) => {
+        const vm = ctrl.getListSummaryViewModel(req, ctx, [
+          { itemId: '1', fullname: 'Sarah Phillips' },
+          { itemId: '2', fullname: 'David Jones' },
+          { itemId: '3', fullname: 'Emma Wilson' }
+        ])
+        return {
+          ...vm,
+          page: { ...vm.page, viewName: ctrl.listSummaryViewName }
         }
       }
-    )
+    })
   },
 
   FileUploadPageController: {
@@ -209,11 +218,15 @@ export const pageFixtures = {
     variants: [
       {
         label: 'No files uploaded',
-        context: pageViewContext(fileUploadPageDef, { state: fileUploadState })
+        context: pageViewContext({
+          pages: [fileUploadPageDef],
+          state: fileUploadState
+        })
       },
       {
         label: 'With files uploaded',
-        context: pageViewContext(fileUploadPageDef, {
+        context: pageViewContext({
+          pages: [fileUploadPageDef],
           state: fileUploadState,
           payload: fileUploadWithFilesPayload
         })
@@ -222,48 +235,34 @@ export const pageFixtures = {
   },
 
   SummaryPageController: {
-    context: pageViewContext(
-      {
-        path: '/summary',
-        controller: 'SummaryPageController',
-        title: 'Check your answers',
-        components: []
-      },
-      {
-        appendSummary: false,
-        additionalPageDefs: [
-          {
-            path: '/name',
-            title: 'Full name',
-            components: [
-              {
-                type: 'TextField',
-                name: 'fullname',
-                title: 'Full name',
-                options: {},
-                schema: {}
-              }
-            ]
-          },
-          {
-            path: '/email',
-            title: 'Email',
-            components: [
-              {
-                type: 'EmailAddressField',
-                name: 'email',
-                title: 'Email address',
-                options: {},
-                schema: {}
-              }
-            ]
-          }
-        ],
-        state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
-        getViewModelOverride: (ctrl, _model, req, ctx) =>
-          ctrl.getSummaryViewModel(req, ctx)
-      }
-    )
+    context: pageViewContext({
+      pages: [
+        {
+          path: '/details',
+          title: 'Your details',
+          components: [
+            {
+              type: 'TextField',
+              name: 'fullname',
+              title: 'Full name',
+              options: {},
+              schema: {}
+            },
+            {
+              type: 'EmailAddressField',
+              name: 'email',
+              title: 'Email address',
+              options: {},
+              schema: {}
+            }
+          ]
+        }
+      ],
+      renderPage: '/summary',
+      state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
+      getViewModelOverride: (ctrl, _model, req, ctx) =>
+        ctrl.getSummaryViewModel(req, ctx)
+    })
   }
 }
 

From 28c83e453690a5afe8fd05eaa5548871d6082bfe Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 14:47:55 +0100
Subject: [PATCH 35/40] more changes

---
 scripts/page-preview-fixtures.js | 52 ++++++++++++++++++--------------
 1 file changed, 30 insertions(+), 22 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 5a6d9f5ea..43f0ba425 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -69,23 +69,9 @@ function pageViewContext({
     : controller.getViewModel(mockRequest, mockContext)
 }
 
-const fileUploadDef = componentFixtures['FileUploadField'].variants[0].def
-const fileUploadWithFilesPayload = componentFixtures[
+const fileUploadWithFilesVariant = componentFixtures[
   'FileUploadField'
-].variants.find((v) => v.label === 'With files uploaded').payload
-
-const fileUploadPageDef = {
-  path: '/upload',
-  controller: 'FileUploadPageController',
-  title: 'Upload a document',
-  components: [fileUploadDef]
-}
-
-const fileUploadState = {
-  upload: {
-    '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
-  }
-}
+].variants.find((v) => v.label === 'With files uploaded')
 
 /** @type {Record<string, PageFixture>} */
 export const pageFixtures = {
@@ -214,21 +200,43 @@ export const pageFixtures = {
   },
 
   FileUploadPageController: {
-    exampleComponents: [fileUploadDef],
+    exampleComponents: [fileUploadWithFilesVariant.def],
     variants: [
       {
         label: 'No files uploaded',
         context: pageViewContext({
-          pages: [fileUploadPageDef],
-          state: fileUploadState
+          pages: [
+            {
+              path: '/upload',
+              controller: 'FileUploadPageController',
+              title: 'Upload a document',
+              components: [fileUploadWithFilesVariant.def]
+            }
+          ],
+          state: {
+            upload: {
+              '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+            }
+          }
         })
       },
       {
         label: 'With files uploaded',
         context: pageViewContext({
-          pages: [fileUploadPageDef],
-          state: fileUploadState,
-          payload: fileUploadWithFilesPayload
+          pages: [
+            {
+              path: '/upload',
+              controller: 'FileUploadPageController',
+              title: 'Upload a document',
+              components: [fileUploadWithFilesVariant.def]
+            }
+          ],
+          state: {
+            upload: {
+              '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+            }
+          },
+          payload: fileUploadWithFilesVariant.payload
         })
       }
     ]

From 40f4a7f397a8ed72412e52175d240de45643f3e5 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 14:59:02 +0100
Subject: [PATCH 36/40] improve docs

---
 scripts/page-preview-fixtures.js | 86 ++++++++++++++++++--------------
 1 file changed, 49 insertions(+), 37 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 43f0ba425..a3d871eb9 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -1,4 +1,4 @@
-import { Engine } from '@defra/forms-model'
+import { ComponentType, ControllerType, Engine } from '@defra/forms-model'
 
 import { FormModel } from '../.server/server/plugins/engine/models/FormModel.js'
 
@@ -6,7 +6,7 @@ import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
 const SUMMARY_PAGE_DEF = {
   path: '/summary',
-  controller: 'SummaryPageController',
+  controller: ControllerType.Summary,
   title: 'Check your answers',
   components: []
 }
@@ -16,13 +16,8 @@ const SUMMARY_PAGE_DEF = {
  * calls getViewModel (or an optional override) with a minimal mock
  * request/context. The controller handles showTitle, label sizing,
  * isPageHeading, allowContinue, and viewName automatically.
- * @param {object} options
- * @param {object[]} options.pages - All page defs; SUMMARY_PAGE_DEF is always appended automatically
- * @param {string} [options.renderPage] - Path of the page to render; defaults to pages[0].path
- * @param {object} [options.state] - Form state
- * @param {object} [options.payload] - Form payload; defaults to state
- * @param {(controller: object, model: object, request: object, context: object) => object} [options.getViewModelOverride] - Override which method to call; defaults to getViewModel
- * @returns {object}
+ * @param {PageViewContextOptions} options
+ * @returns {PageViewModel}
  */
 function pageViewContext({
   pages,
@@ -70,7 +65,7 @@ function pageViewContext({
 }
 
 const fileUploadWithFilesVariant = componentFixtures[
-  'FileUploadField'
+  ComponentType.FileUploadField
 ].variants.find((v) => v.label === 'With files uploaded')
 
 /** @type {Record<string, PageFixture>} */
@@ -86,7 +81,7 @@ export const pageFixtures = {
               title: 'What is your full name?',
               components: [
                 {
-                  type: 'TextField',
+                  type: ComponentType.TextField,
                   name: 'fullname',
                   title: 'What is your full name?',
                   hint: 'As shown on your passport',
@@ -107,14 +102,14 @@ export const pageFixtures = {
               title: 'Tell us about yourself',
               components: [
                 {
-                  type: 'TextField',
+                  type: ComponentType.TextField,
                   name: 'fullname',
                   title: 'What is your full name?',
                   options: {},
                   schema: {}
                 },
                 {
-                  type: 'DatePartsField',
+                  type: ComponentType.DatePartsField,
                   name: 'dob',
                   title: 'What is your date of birth?',
                   hint: 'For example, 27 3 2007',
@@ -134,7 +129,7 @@ export const pageFixtures = {
       pages: [
         {
           path: '/start',
-          controller: 'StartPageController',
+          controller: ControllerType.Start,
           title: 'Apply for a licence',
           components: []
         }
@@ -147,11 +142,11 @@ export const pageFixtures = {
       pages: [
         {
           path: '/ineligible',
-          controller: 'TerminalPageController',
+          controller: ControllerType.Terminal,
           title: 'You are not eligible',
           components: [
             {
-              type: 'Html',
+              type: ComponentType.Html,
               name: 'eligibility',
               content:
                 '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
@@ -168,7 +163,7 @@ export const pageFixtures = {
       pages: [
         {
           path: '/people',
-          controller: 'RepeatPageController',
+          controller: ControllerType.Repeat,
           title: 'People',
           repeat: {
             options: { name: 'people', title: 'Person' },
@@ -176,7 +171,7 @@ export const pageFixtures = {
           },
           components: [
             {
-              type: 'TextField',
+              type: ComponentType.TextField,
               name: 'fullname',
               title: 'Full name',
               options: {},
@@ -186,14 +181,15 @@ export const pageFixtures = {
         }
       ],
       getViewModelOverride: (ctrl, _model, req, ctx) => {
-        const vm = ctrl.getListSummaryViewModel(req, ctx, [
+        const repeat = /** @type {RepeatPageController} */ (ctrl)
+        const vm = repeat.getListSummaryViewModel(req, ctx, [
           { itemId: '1', fullname: 'Sarah Phillips' },
           { itemId: '2', fullname: 'David Jones' },
           { itemId: '3', fullname: 'Emma Wilson' }
         ])
         return {
           ...vm,
-          page: { ...vm.page, viewName: ctrl.listSummaryViewName }
+          page: { ...vm.page, viewName: repeat.listSummaryViewName }
         }
       }
     })
@@ -208,16 +204,18 @@ export const pageFixtures = {
           pages: [
             {
               path: '/upload',
-              controller: 'FileUploadPageController',
+              controller: ControllerType.FileUpload,
               title: 'Upload a document',
               components: [fileUploadWithFilesVariant.def]
             }
           ],
-          state: {
-            upload: {
-              '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
-            }
-          }
+          state: /** @type {FormState} */ (
+            /** @type {unknown} */ ({
+              upload: {
+                '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+              }
+            })
+          )
         })
       },
       {
@@ -226,16 +224,18 @@ export const pageFixtures = {
           pages: [
             {
               path: '/upload',
-              controller: 'FileUploadPageController',
+              controller: ControllerType.FileUpload,
               title: 'Upload a document',
               components: [fileUploadWithFilesVariant.def]
             }
           ],
-          state: {
-            upload: {
-              '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
-            }
-          },
+          state: /** @type {FormState} */ (
+            /** @type {unknown} */ ({
+              upload: {
+                '/upload': { upload: { uploadUrl: 'preview' }, files: [] }
+              }
+            })
+          ),
           payload: fileUploadWithFilesVariant.payload
         })
       }
@@ -250,14 +250,14 @@ export const pageFixtures = {
           title: 'Your details',
           components: [
             {
-              type: 'TextField',
+              type: ComponentType.TextField,
               name: 'fullname',
               title: 'Full name',
               options: {},
               schema: {}
             },
             {
-              type: 'EmailAddressField',
+              type: ComponentType.EmailAddressField,
               name: 'email',
               title: 'Email address',
               options: {},
@@ -268,13 +268,25 @@ export const pageFixtures = {
       ],
       renderPage: '/summary',
       state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
-      getViewModelOverride: (ctrl, _model, req, ctx) =>
-        ctrl.getSummaryViewModel(req, ctx)
+      getViewModelOverride: (ctrl, _model, req, ctx) => {
+        const summary = /** @type {SummaryPageController} */ (ctrl)
+        return summary.getSummaryViewModel(req, ctx)
+      }
     })
   }
 }
 
 /**
+ * @typedef {import('@defra/forms-model').ComponentDef} ComponentDef
+ * @typedef {import('@defra/forms-model').Page} Page
+ * @typedef {import('~/src/server/plugins/engine/types.js').FormContext} FormContext
  * @typedef {import('~/src/server/plugins/engine/types.js').FormContextRequest} FormContextRequest
- * @typedef {{ context?: object, variants?: Array<{label: string, context: object}> }} PageFixture
+ * @typedef {import('~/src/server/plugins/engine/types.js').FormState} FormState
+ * @typedef {import('~/src/server/plugins/engine/types.js').PageViewModel} PageViewModel
+ * @typedef {import('~/src/server/plugins/engine/pageControllers/PageController.js').PageController} PageController
+ * @typedef {import('~/src/server/plugins/engine/pageControllers/RepeatPageController.js').RepeatPageController} RepeatPageController
+ * @typedef {import('~/src/server/plugins/engine/pageControllers/SummaryPageController.js').SummaryPageController} SummaryPageController
+ * @typedef {{ label: string, context: PageViewModel }} PageFixtureVariant
+ * @typedef {{ context?: PageViewModel, variants?: PageFixtureVariant[], exampleComponents?: ComponentDef[] }} PageFixture
+ * @typedef {{ pages: Page[], renderPage?: string, state?: FormState, payload?: FormState, getViewModelOverride?: (controller: PageController, model: FormModel, request: FormContextRequest, context: FormContext) => PageViewModel }} PageViewContextOptions
  */

From 3016a528de998fe78cdbc6aab0d2a76d964ef571 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 15:12:16 +0100
Subject: [PATCH 37/40] move preview template into doc scripts dir

---
 scripts/generate-page-previews.js                        | 9 ++++++++-
 .../plugins/engine/views => scripts}/preview-layout.html | 0
 2 files changed, 8 insertions(+), 1 deletion(-)
 rename {src/server/plugins/engine/views => scripts}/preview-layout.html (100%)

diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
index 420b31a3a..0670033bf 100644
--- a/scripts/generate-page-previews.js
+++ b/scripts/generate-page-previews.js
@@ -1,16 +1,23 @@
 import fs from 'fs'
 import path from 'path'
+import { fileURLToPath } from 'url'
 
 import { buildPartialMdx } from './generate-component-previews.js'
 
 import { environment } from '~/src/server/plugins/nunjucks/environment.js'
 
+// Make preview-layout.html discoverable by name within the Nunjucks environment.
+const scriptsDir = fileURLToPath(new URL('.', import.meta.url))
+for (const loader of environment.loaders ?? []) {
+  if (loader.searchPaths) loader.searchPaths.push(scriptsDir)
+}
+
 /**
  * Render a single page fixture context to an HTML string.
  * Reads the view name from context.page.viewName — set automatically by the
  * real page controller via getViewModel, or manually on the page stub for
  * fixtures that don't use pageViewContext.
- * Passes baseLayoutPath: 'preview-layout.html' to strip the GOV.UK page wrapper.
+ * Passes baseLayoutPath to strip the GOV.UK page wrapper.
  * @param {object} context
  * @returns {string}
  */
diff --git a/src/server/plugins/engine/views/preview-layout.html b/scripts/preview-layout.html
similarity index 100%
rename from src/server/plugins/engine/views/preview-layout.html
rename to scripts/preview-layout.html

From c88a33aa738f3a354025e21480eb7aa8c424bd07 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 17:01:19 +0100
Subject: [PATCH 38/40] fix types

---
 scripts/generate-page-previews.js | 12 ++--
 scripts/page-preview-fixtures.js  | 98 +++++++++++++++++++------------
 2 files changed, 67 insertions(+), 43 deletions(-)

diff --git a/scripts/generate-page-previews.js b/scripts/generate-page-previews.js
index 0670033bf..c87d1e4bb 100644
--- a/scripts/generate-page-previews.js
+++ b/scripts/generate-page-previews.js
@@ -8,7 +8,7 @@ import { environment } from '~/src/server/plugins/nunjucks/environment.js'
 
 // Make preview-layout.html discoverable by name within the Nunjucks environment.
 const scriptsDir = fileURLToPath(new URL('.', import.meta.url))
-for (const loader of environment.loaders ?? []) {
+for (const loader of /** @type {any} */ (environment).loaders ?? []) {
   if (loader.searchPaths) loader.searchPaths.push(scriptsDir)
 }
 
@@ -18,7 +18,7 @@ for (const loader of environment.loaders ?? []) {
  * real page controller via getViewModel, or manually on the page stub for
  * fixtures that don't use pageViewContext.
  * Passes baseLayoutPath to strip the GOV.UK page wrapper.
- * @param {object} context
+ * @param {PageViewModelBase} context
  * @returns {string}
  */
 export function renderPage(context) {
@@ -38,7 +38,7 @@ export function renderPage(context) {
  * MDX partial to previewsDir/<slug>.mdx.
  * @param {string} previewsDir
  * @param {string} slug
- * @param {{ context?: object, variants?: Array<{label: string, context: object}> }} fixture
+ * @param {{ context?: PageViewModelBase, variants?: Array<{label: string, context: PageViewModelBase}> }} fixture
  */
 export function writePagePreviewPartial(previewsDir, slug, fixture) {
   fs.mkdirSync(previewsDir, { recursive: true })
@@ -48,10 +48,14 @@ export function writePagePreviewPartial(previewsDir, slug, fixture) {
         label,
         html: renderPage(context)
       }))
-    : [{ html: renderPage(fixture.context) }]
+    : [{ html: renderPage(/** @type {PageViewModelBase} */ (fixture.context)) }]
 
   fs.writeFileSync(
     path.join(previewsDir, `${slug}.mdx`),
     buildPartialMdx(renders, 'component-preview component-preview--page')
   )
 }
+
+/**
+ * @typedef {import('~/src/server/plugins/engine/types.js').PageViewModelBase} PageViewModelBase
+ */
diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index a3d871eb9..e7a5e4f5e 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -1,15 +1,17 @@
 import { ComponentType, ControllerType, Engine } from '@defra/forms-model'
 
-import { FormModel } from '../.server/server/plugins/engine/models/FormModel.js'
-
 import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
-const SUMMARY_PAGE_DEF = {
-  path: '/summary',
-  controller: ControllerType.Summary,
-  title: 'Check your answers',
-  components: []
-}
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+
+
+const SUMMARY_PAGE_DEF =
+  /** @type {import('@defra/forms-model').PageSummary} */ ({
+    path: '/summary',
+    controller: ControllerType.Summary,
+    title: 'Check your answers',
+    components: []
+  })
 
 /**
  * Instantiates the real page controller for the given page definition and
@@ -41,32 +43,39 @@ function pageViewContext({
     { basePath: '/preview' }
   )
   const controller = model.pages.find((p) => p.path === renderPage)
-  const mockContext = {
-    payload: payload ?? state,
-    errors: undefined,
-    evaluationState: state,
-    relevantState: state,
-    paths: [],
-    state,
-    isForceAccess: false,
-    relevantPages: model.pages.filter((p) => p.viewName !== 'summary')
-  }
-  /** @type {FormContextRequest} */
-  const mockRequest = {
-    query: {},
-    params: {},
-    path: renderPage,
-    url: { search: '' },
-    server: { plugins: { 'forms-engine-plugin': {} } }
-  }
+  if (!controller)
+    throw new Error(`No page controller found for '${renderPage}'`)
+  const mockContext = /** @type {FormContext} */ (
+    /** @type {unknown} */ ({
+      payload: payload ?? state,
+      errors: undefined,
+      evaluationState: state,
+      relevantState: state,
+      paths: [],
+      state,
+      isForceAccess: false,
+      relevantPages: model.pages.filter((p) => p.viewName !== 'summary')
+    })
+  )
+  const mockRequest = /** @type {FormContextRequest} */ (
+    /** @type {unknown} */ ({
+      query: {},
+      params: {},
+      path: renderPage,
+      url: { search: '' },
+      server: { plugins: { 'forms-engine-plugin': {} } }
+    })
+  )
   return getViewModelOverride
     ? getViewModelOverride(controller, model, mockRequest, mockContext)
-    : controller.getViewModel(mockRequest, mockContext)
+    : controller.getViewModel(/** @type {any} */ (mockRequest), mockContext)
 }
 
-const fileUploadWithFilesVariant = componentFixtures[
-  ComponentType.FileUploadField
-].variants.find((v) => v.label === 'With files uploaded')
+const fileUploadWithFilesVariant = /** @type {any} */ (
+  componentFixtures[ComponentType.FileUploadField]
+)?.variants?.find(
+  (/** @type {{ label: string }} */ v) => v.label === 'With files uploaded'
+)
 
 /** @type {Record<string, PageFixture>} */
 export const pageFixtures = {
@@ -79,6 +88,7 @@ export const pageFixtures = {
             {
               path: '/pagepath',
               title: 'What is your full name?',
+              next: [],
               components: [
                 {
                   type: ComponentType.TextField,
@@ -100,6 +110,7 @@ export const pageFixtures = {
             {
               path: '/pagepath',
               title: 'Tell us about yourself',
+              next: [],
               components: [
                 {
                   type: ComponentType.TextField,
@@ -113,8 +124,7 @@ export const pageFixtures = {
                   name: 'dob',
                   title: 'What is your date of birth?',
                   hint: 'For example, 27 3 2007',
-                  options: {},
-                  schema: {}
+                  options: {}
                 }
               ]
             }
@@ -131,6 +141,7 @@ export const pageFixtures = {
           path: '/start',
           controller: ControllerType.Start,
           title: 'Apply for a licence',
+          next: [],
           components: []
         }
       ]
@@ -144,10 +155,12 @@ export const pageFixtures = {
           path: '/ineligible',
           controller: ControllerType.Terminal,
           title: 'You are not eligible',
+          next: [],
           components: [
             {
               type: ComponentType.Html,
               name: 'eligibility',
+              title: '',
               content:
                 '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
               options: {}
@@ -165,6 +178,7 @@ export const pageFixtures = {
           path: '/people',
           controller: ControllerType.Repeat,
           title: 'People',
+          next: [],
           repeat: {
             options: { name: 'people', title: 'Person' },
             schema: { min: 1, max: 25 }
@@ -187,10 +201,12 @@ export const pageFixtures = {
           { itemId: '2', fullname: 'David Jones' },
           { itemId: '3', fullname: 'Emma Wilson' }
         ])
-        return {
-          ...vm,
-          page: { ...vm.page, viewName: repeat.listSummaryViewName }
-        }
+        return /** @type {PageViewModel} */ (
+          /** @type {unknown} */ ({
+            ...vm,
+            page: { ...vm.page, viewName: repeat.listSummaryViewName }
+          })
+        )
       }
     })
   },
@@ -206,6 +222,7 @@ export const pageFixtures = {
               path: '/upload',
               controller: ControllerType.FileUpload,
               title: 'Upload a document',
+              next: [],
               components: [fileUploadWithFilesVariant.def]
             }
           ],
@@ -226,6 +243,7 @@ export const pageFixtures = {
               path: '/upload',
               controller: ControllerType.FileUpload,
               title: 'Upload a document',
+              next: [],
               components: [fileUploadWithFilesVariant.def]
             }
           ],
@@ -248,6 +266,7 @@ export const pageFixtures = {
         {
           path: '/details',
           title: 'Your details',
+          next: [],
           components: [
             {
               type: ComponentType.TextField,
@@ -260,8 +279,7 @@ export const pageFixtures = {
               type: ComponentType.EmailAddressField,
               name: 'email',
               title: 'Email address',
-              options: {},
-              schema: {}
+              options: {}
             }
           ]
         }
@@ -270,7 +288,9 @@ export const pageFixtures = {
       state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
       getViewModelOverride: (ctrl, _model, req, ctx) => {
         const summary = /** @type {SummaryPageController} */ (ctrl)
-        return summary.getSummaryViewModel(req, ctx)
+        return /** @type {PageViewModel} */ (
+          /** @type {unknown} */ (summary.getSummaryViewModel(req, ctx))
+        )
       }
     })
   }

From a6f67bea315c29130f2e6ea942e72e6b27c7c787 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 17:21:34 +0100
Subject: [PATCH 39/40] format fix

---
 scripts/page-preview-fixtures.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index e7a5e4f5e..48477b5a7 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -4,7 +4,6 @@ import { fixtures as componentFixtures } from './component-preview-fixtures.js'
 
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 
-
 const SUMMARY_PAGE_DEF =
   /** @type {import('@defra/forms-model').PageSummary} */ ({
     path: '/summary',

From 146eb53225fb436e04142d279e968b1daff73f85 Mon Sep 17 00:00:00 2001
From: Alex Luckett <alex@nodepoint.co.uk>
Date: Fri, 15 May 2026 17:24:20 +0100
Subject: [PATCH 40/40] remove title prop for html component

---
 scripts/page-preview-fixtures.js | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/scripts/page-preview-fixtures.js b/scripts/page-preview-fixtures.js
index 48477b5a7..12b91e8b1 100644
--- a/scripts/page-preview-fixtures.js
+++ b/scripts/page-preview-fixtures.js
@@ -156,14 +156,13 @@ export const pageFixtures = {
           title: 'You are not eligible',
           next: [],
           components: [
-            {
+            /** @type {ComponentDef} */ ({
               type: ComponentType.Html,
               name: 'eligibility',
-              title: '',
               content:
                 '<p class="govuk-body">You do not meet the eligibility criteria for this service.</p>',
               options: {}
-            }
+            })
           ]
         }
       ]