@prenta/admin 0.93.0 → 0.94.0

package/src/__tests__/lib/version-diff.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest'
+import {
+  changedSectionIds,
+  diffVersions,
+  formatValue,
+  groupChangesBySection,
+} from '../../lib/version-diff.js'
+import type { PageSection } from '../../lib/page-editor-service.js'
+
+function section(overrides: Partial<PageSection> & { id: string }): PageSection {
+  return {
+    sectionType: 'hero',
+    name: 'Hero Banner',
+    visible: true,
+    content: {},
+    settings: {},
+    ...overrides,
+  }
+}
+
+describe('formatValue', () => {
+  it('renders absent and blank values as an em dash so an empty diff cell is never blank', () => {
+    expect(formatValue(null)).toBe('—')
+    expect(formatValue(undefined)).toBe('—')
+    expect(formatValue('')).toBe('—')
+    expect(formatValue('   ')).toBe('—')
+    expect(formatValue([])).toBe('—')
+    expect(formatValue({})).toBe('—')
+  })
+
+  it('summarises structured values rather than dumping them', () => {
+    expect(formatValue([{ value: '1' }, { value: '2' }])).toBe('2 items')
+    expect(formatValue([{ value: '1' }])).toBe('1 item')
+    expect(formatValue({ name: 'hero.jpg', url: '/m/hero.jpg' })).toBe('hero.jpg')
+    // No name-ish key: fall back to a shape description, not "[object Object]".
+    expect(formatValue({ x: 1, y: 2 })).toBe('2 fields')
+  })
+
+  it('reads booleans and numbers as words the panel can show', () => {
+    expect(formatValue(true)).toBe('Yes')
+    expect(formatValue(false)).toBe('No')
+    expect(formatValue(0)).toBe('0')
+  })
+})
+
+describe('diffVersions', () => {
+  it('labels content fields through the section registry, not by raw key', () => {
+    const before = [section({ id: 's1', content: { heading: 'Old headline' } })]
+    const after = [section({ id: 's1', content: { heading: 'New headline' } })]
+
+    const changes = diffVersions(after, before)
+
+    expect(changes).toEqual([
+      {
+        sectionId: 's1',
+        sectionName: 'Hero Banner',
+        // 'heading' is `label: 'Heading'` on the hero type in the registry.
+        field: 'Heading',
+        from: 'Old headline',
+        to: 'New headline',
+      },
+    ])
+  })
+
+  it('falls back to the raw key for a type the registry does not describe', () => {
+    const before = [section({ id: 's1', sectionType: 'opal-pricing', content: { tiers: 'a' } })]
+    const after = [section({ id: 's1', sectionType: 'opal-pricing', content: { tiers: 'b' } })]
+
+    expect(diffVersions(after, before)[0]?.field).toBe('tiers')
+  })
+
+  it('reports a field cleared to nothing — the key exists only in the older snapshot', () => {
+    const before = [section({ id: 's1', content: { heading: 'Something' } })]
+    const after = [section({ id: 's1', content: {} })]
+
+    expect(diffVersions(after, before)).toEqual([
+      { sectionId: 's1', sectionName: 'Hero Banner', field: 'Heading', from: 'Something', to: '—' },
+    ])
+  })
+
+  it('reports visibility as a state, because hiding a section is the one structural edit there is', () => {
+    const before = [section({ id: 's1', visible: true })]
+    const after = [section({ id: 's1', visible: false })]
+
+    expect(diffVersions(after, before)).toEqual([
+      {
+        sectionId: 's1',
+        sectionName: 'Hero Banner',
+        field: 'Visibility',
+        from: 'Shown',
+        to: 'Hidden',
+      },
+    ])
+  })
+
+  it('reports added and removed sections', () => {
+    const before = [section({ id: 's1' })]
+    const after = [section({ id: 's1' }), section({ id: 's2', name: 'CTA', sectionType: 'cta' })]
+
+    expect(diffVersions(after, before)).toEqual([
+      { sectionId: 's2', sectionName: 'CTA', field: 'Section', from: '—', to: 'Added' },
+    ])
+
+    expect(diffVersions(before, after)).toEqual([
+      { sectionId: 's2', sectionName: 'CTA', field: 'Section', from: 'Present', to: 'Removed' },
+    ])
+  })
+
+  it('reports nothing when the snapshots match', () => {
+    const same = [section({ id: 's1', content: { heading: 'Same' } })]
+    expect(diffVersions(same, [section({ id: 's1', content: { heading: 'Same' } })])).toEqual([])
+  })
+
+  it('reports nothing against a missing predecessor', () => {
+    // The oldest version we hold is not the moment the page was created, so
+    // reporting every field as "added" would state something false.
+    expect(diffVersions([section({ id: 's1', content: { heading: 'x' } })], undefined)).toEqual([])
+    expect(diffVersions([section({ id: 's1' })], null)).toEqual([])
+  })
+
+  it('does not report a settings key that was merely absent versus explicitly default', () => {
+    // `{}` and `{ backgroundType: undefined }` format identically, so neither
+    // produces a row. Without this the first save after a schema addition
+    // would light up every section on the canvas.
+    const before = [section({ id: 's1', settings: {} })]
+    const after = [section({ id: 's1', settings: { backgroundType: undefined } as never })]
+    expect(diffVersions(after, before)).toEqual([])
+  })
+
+  it('labels known settings and reports a real background change', () => {
+    const before = [section({ id: 's1', settings: { backgroundType: 'none' } })]
+    const after = [section({ id: 's1', settings: { backgroundType: 'solid' } })]
+
+    expect(diffVersions(after, before)).toEqual([
+      {
+        sectionId: 's1',
+        sectionName: 'Hero Banner',
+        field: 'Background type',
+        from: 'none',
+        to: 'solid',
+      },
+    ])
+  })
+})
+
+describe('diffVersions — structured fields', () => {
+  const stats = (rows: Array<{ value: string; label: string }>) =>
+    section({ id: 's1', sectionType: 'stats', name: 'By The Numbers', content: { stats: rows } })
+
+  it('catches an edit that keeps the row count', () => {
+    // The bug this exists for: deciding "did it change" from the DISPLAY
+    // summary collapses an array to "2 items", so retyping a row while keeping
+    // the count formats identically on both sides and the field reports no
+    // change — no panel row AND no outline on the canvas, which is exactly the
+    // edit a reviewer opened history to find.
+    const before = [
+      stats([
+        { value: '10k', label: 'Users' },
+        { value: '99%', label: 'Uptime' },
+      ]),
+    ]
+    const after = [
+      stats([
+        { value: '20k', label: 'Users' },
+        { value: '99%', label: 'Uptime' },
+      ]),
+    ]
+
+    const changes = diffVersions(after, before)
+
+    expect(changes).toHaveLength(1)
+    expect(changes[0]?.from).toBe('10k')
+    expect(changes[0]?.to).toBe('20k')
+    // Named down to the row and the sub-field, so "which one" has an answer.
+    expect(changes[0]?.field).toBe('Stats · Stat 1 · Value')
+    expect(changedSectionIds(changes).has('s1')).toBe(true)
+  })
+
+  it('never emits a row whose before and after both read as a bare count', () => {
+    const before = [
+      stats([
+        { value: 'a', label: 'x' },
+        { value: 'b', label: 'y' },
+      ]),
+    ]
+    const after = [
+      stats([
+        { value: 'c', label: 'x' },
+        { value: 'd', label: 'y' },
+      ]),
+    ]
+
+    for (const change of diffVersions(after, before)) {
+      expect(change.from).not.toBe(change.to)
+      expect(change.from).not.toMatch(/^\d+ items?$/)
+    }
+  })
+
+  it('reports added and removed rows', () => {
+    const before = [stats([{ value: '10k', label: 'Users' }])]
+    const after = [
+      stats([
+        { value: '10k', label: 'Users' },
+        { value: '99%', label: 'Uptime' },
+      ]),
+    ]
+
+    expect(diffVersions(after, before)).toEqual([
+      expect.objectContaining({ field: 'Stats · Stat 2', from: '—', to: 'Added' }),
+    ])
+    expect(diffVersions(before, after)).toEqual([
+      expect.objectContaining({ field: 'Stats · Stat 2', from: 'Present', to: 'Removed' }),
+    ])
+  })
+
+  it('catches a nested change inside a media object', () => {
+    // Same failure one level down: two media objects with the same `name` used
+    // to format identically while pointing at different files.
+    const media = (url: string) => ({ name: 'hero.jpg', url })
+    const before = [section({ id: 's1', content: { imageUrl: media('/a.jpg') } })]
+    const after = [section({ id: 's1', content: { imageUrl: media('/b.jpg') } })]
+
+    expect(diffVersions(after, before)).toHaveLength(1)
+  })
+
+  it('treats every spelling of blank as unchanged', () => {
+    // Tightening the comparison must not start reporting "— → —".
+    for (const [before, after] of [
+      ['', null],
+      [null, undefined],
+      [undefined, '   '],
+      [[], undefined],
+      [{}, null],
+    ] as Array<[unknown, unknown]>) {
+      const changes = diffVersions(
+        [section({ id: 's1', content: { heading: after } })],
+        [section({ id: 's1', content: { heading: before } })],
+      )
+      expect(changes, `${JSON.stringify(before)} → ${JSON.stringify(after)}`).toEqual([])
+    }
+  })
+
+  it('reports an unchanged repeater as no change at all', () => {
+    const rows = [{ value: '10k', label: 'Users' }]
+    expect(diffVersions([stats(rows)], [stats([...rows.map((r) => ({ ...r }))])])).toEqual([])
+  })
+})
+
+describe('groupChangesBySection', () => {
+  it('groups by section in first-seen order', () => {
+    const before = [
+      section({ id: 's1', content: { heading: 'a', body: 'a' } }),
+      section({ id: 's2', name: 'CTA', sectionType: 'cta', content: { heading: 'a' } }),
+    ]
+    const after = [
+      section({ id: 's1', content: { heading: 'b', body: 'b' } }),
+      section({ id: 's2', name: 'CTA', sectionType: 'cta', content: { heading: 'b' } }),
+    ]
+
+    const groups = groupChangesBySection(diffVersions(after, before))
+
+    expect(groups.map((g) => g.sectionId)).toEqual(['s1', 's2'])
+    expect(groups[0]?.changes).toHaveLength(2)
+    expect(groups[1]?.changes).toHaveLength(1)
+  })
+})
+
+describe('changedSectionIds', () => {
+  it('collapses several changes on one section to a single outline', () => {
+    const before = [section({ id: 's1', content: { heading: 'a', body: 'a' } })]
+    const after = [section({ id: 's1', content: { heading: 'b', body: 'b' } })]
+
+    const ids = changedSectionIds(diffVersions(after, before))
+
+    expect(ids.size).toBe(1)
+    expect(ids.has('s1')).toBe(true)
+  })
+})

package/src/__tests__/lib/version-history.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest'
+import {
+  dayLabel,
+  groupVersionsByDay,
+  initials,
+  toPageVersion,
+  versionKind,
+  type PageVersion,
+} from '../../lib/version-history.js'
+
+const NOW = new Date('2026-08-02T17:00:00Z')
+
+function version(id: string, createdAt: string): PageVersion {
+  return {
+    id,
+    changeType: 'UPDATE',
+    createdAt,
+    author: { id: 'u1', name: 'Sarah Mills' },
+    sections: [],
+  }
+}
+
+describe('toPageVersion', () => {
+  it('lifts the section snapshot out of the version payload', () => {
+    const mapped = toPageVersion({
+      id: 'v1',
+      changeType: 'PUBLISH',
+      createdAt: '2026-08-02T12:00:00Z',
+      data: {
+        sections: [
+          { id: 's1', sectionType: 'hero', name: 'Hero', visible: true, content: {}, settings: {} },
+        ],
+      },
+      changedBy: { id: 'u1', name: 'Sarah Mills', email: 's@example.com' },
+    })
+
+    expect(mapped.sections).toHaveLength(1)
+    expect(mapped.sections[0]?.id).toBe('s1')
+    expect(mapped.changeType).toBe('PUBLISH')
+    expect(mapped.author.name).toBe('Sarah Mills')
+  })
+
+  it('preserves an unmanaged section rather than dropping it from the snapshot', () => {
+    // Coercing a snapshot more strictly than the live document reads would
+    // make an externally-managed section look deleted in every version.
+    const mapped = toPageVersion({
+      id: 'v1',
+      changeType: 'UPDATE',
+      createdAt: '2026-08-02T12:00:00Z',
+      data: {
+        sections: [
+          { id: 's1', sectionType: 'opal-pricing', name: 'Pricing', visible: true, content: {} },
+        ],
+      },
+    })
+
+    expect(mapped.sections).toHaveLength(1)
+    expect(mapped.sections[0]?.sectionType).toBe('opal-pricing')
+  })
+
+  it('falls back through name → email → a real word for the avatar', () => {
+    expect(
+      toPageVersion({ id: 'v', changeType: 'UPDATE', createdAt: '', data: null }).author.name,
+    ).toBe('Unknown')
+
+    expect(
+      toPageVersion({
+        id: 'v',
+        changeType: 'UPDATE',
+        createdAt: '',
+        data: null,
+        changedBy: { id: 'u', name: '  ', email: 'a@b.com' },
+      }).author.name,
+    ).toBe('a@b.com')
+  })
+
+  it('yields no sections for a version whose payload has none', () => {
+    expect(
+      toPageVersion({ id: 'v', changeType: 'DELETE', createdAt: '', data: {} }).sections,
+    ).toEqual([])
+  })
+})
+
+describe('versionKind', () => {
+  it('marks a published snapshot as the one a visitor could have seen', () => {
+    expect(versionKind('PUBLISH')).toEqual({ label: 'Published', tone: 'live' })
+  })
+
+  it('calls UPDATE "Saved", never "Draft"', () => {
+    // Every row written before cms-core started recording PUBLISH is an UPDATE
+    // whether or not it went live, so "Draft" would be false for those.
+    expect(versionKind('UPDATE').label).toBe('Saved')
+  })
+
+  it('distinguishes a rollback from authored content', () => {
+    expect(versionKind('RESTORE').label).toBe('Restored')
+  })
+
+  it('degrades to a neutral label for an unrecognised type', () => {
+    expect(versionKind('SOMETHING_NEW').label).toBe('Saved')
+  })
+})
+
+describe('dayLabel', () => {
+  it('names today and yesterday', () => {
+    expect(dayLabel('2026-08-02T09:00:00', NOW)).toBe('Today')
+    expect(dayLabel('2026-08-01T23:59:00', NOW)).toBe('Yesterday')
+  })
+
+  it('drops the year within the current one and keeps it outside', () => {
+    expect(dayLabel('2026-07-27T09:00:00', NOW)).not.toMatch(/2026/)
+    expect(dayLabel('2025-07-27T09:00:00', NOW)).toMatch(/2025/)
+  })
+
+  it('does not throw on an unparseable timestamp', () => {
+    expect(dayLabel('not-a-date', NOW)).toBe('Unknown date')
+  })
+})
+
+describe('groupVersionsByDay', () => {
+  it('groups consecutive runs and keeps newest-first order', () => {
+    const groups = groupVersionsByDay(
+      [
+        version('v5', '2026-08-02T16:12:00'),
+        version('v4', '2026-08-02T11:03:00'),
+        version('v3', '2026-08-01T17:47:00'),
+        version('v1', '2026-07-27T09:30:00'),
+      ],
+      NOW,
+    )
+
+    expect(groups.map((g) => g.label)).toEqual(['Today', 'Yesterday', expect.stringMatching(/Jul/)])
+    expect(groups[0]?.versions.map((v) => v.id)).toEqual(['v5', 'v4'])
+  })
+
+  it('does not merge two non-adjacent runs that share a label', () => {
+    // A Map keyed on the label would silently reorder an unsorted page into
+    // something that reads as chronological but is not.
+    const groups = groupVersionsByDay(
+      [
+        version('a', '2026-08-02T16:00:00'),
+        version('b', '2026-08-01T16:00:00'),
+        version('c', '2026-08-02T09:00:00'),
+      ],
+      NOW,
+    )
+
+    expect(groups.map((g) => g.label)).toEqual(['Today', 'Yesterday', 'Today'])
+  })
+
+  it('returns nothing for an empty list', () => {
+    expect(groupVersionsByDay([], NOW)).toEqual([])
+  })
+})
+
+describe('initials', () => {
+  it('takes first and last for a full name, two letters for one word', () => {
+    expect(initials('Sarah Mills')).toBe('SM')
+    expect(initials('Sarah Jane Mills')).toBe('SM')
+    expect(initials('sarah')).toBe('SA')
+  })
+
+  it('never renders an empty monogram', () => {
+    expect(initials('   ')).toBe('?')
+  })
+})

package/src/__tests__/styles/responsive-layer.test.ts

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The responsive + accessibility layer (`src/styles/responsive.css`), ported
+ * from the design bundle's `design-system/cms-responsive.css`.
+ *
+ * Every way this breaks is invisible: a stylesheet that stops being imported,
+ * a rule whose class hook was renamed in a component, or a token override
+ * placed before the token it overrides all produce a page that renders
+ * perfectly and simply lacks the behaviour. None of it raises an error, and
+ * none of it shows up in a screenshot taken at a desktop width with a mouse.
+ *
+ * Reads the source rather than a compiled bundle so the suite does not depend
+ * on a build step; the entry-point assertion is what ties the two together.
+ */
+
+const PKG = fileURLToPath(new URL('../../../', import.meta.url))
+const read = (rel: string) => readFileSync(PKG + rel, 'utf8')
+
+const responsive = read('src/styles/responsive.css')
+const theme = read('src/styles/theme.css')
+const tokens = read('src/styles/prenta-tokens.css')
+
+describe('responsive + accessibility layer', () => {
+  it('is imported by theme.css, which both entry points pull in', () => {
+    // `build-input.css` (precompiled) and `tailwind.css` (advanced) each
+    // import theme.css and nothing else of ours, so importing from there is
+    // what puts this layer in front of every consumer.
+    expect(theme).toContain("@import './responsive.css'")
+    expect(read('src/styles/build-input.css')).toContain("@import './theme.css'")
+    expect(read('src/styles/tailwind.css')).toContain("@import './theme.css'")
+  })
+
+  it('is imported AFTER the token block it overrides', () => {
+    // Same specificity, so source order alone decides. Imported first, the
+    // prefers-contrast block would parse, match, and change nothing.
+    expect(theme.indexOf("@import './prenta-tokens.css'")).toBeLessThan(
+      theme.indexOf("@import './responsive.css'"),
+    )
+  })
+
+  it('scopes every rule to the admin root', () => {
+    // The admin renders inside consumer applications. A bare `:focus-visible`
+    // or `@media print` rule here would restyle the host's own pages.
+    const selectors = responsive
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.endsWith('{') && !line.startsWith('@'))
+
+    expect(selectors.length).toBeGreaterThan(10)
+    for (const selector of selectors) {
+      expect(selector, `unscoped selector: ${selector}`).toMatch(/\.prenta-admin/)
+    }
+  })
+
+  it('raises contrast rather than lowering it, in both themes', () => {
+    // The shipped --muted is already an AA correction over the handoff's own
+    // value (see prenta-tokens.css). A "more contrast" preference that moved
+    // it the other way would be worse than not honouring the preference.
+    const luminance = (hex: string) => {
+      const n = parseInt(hex.slice(1), 16)
+      return ((n >> 16) & 255) * 0.299 + ((n >> 8) & 255) * 0.587 + (n & 255) * 0.114
+    }
+    const declaration = (css: string, name: string, from = 0) => {
+      const match = new RegExp(`${name}:\\s*(#[0-9a-f]{6})`, 'i').exec(css.slice(from))
+      return match?.[1] ?? null
+    }
+
+    const contrastBlock = responsive.slice(responsive.indexOf('@media (prefers-contrast: more)'))
+    const darkStart = contrastBlock.indexOf('[data-theme=')
+
+    for (const name of ['--muted', '--sub', '--bdr']) {
+      const base = declaration(tokens, name)!
+      const raised = declaration(contrastBlock.slice(0, darkStart), name)!
+      // Light theme: darker text and borders on a light surface.
+      expect(luminance(raised), `light ${name}`).toBeLessThan(luminance(base))
+
+      const darkBase = declaration(
+        tokens,
+        name,
+        tokens.indexOf(".prenta-admin[data-theme='dark']"),
+      )!
+      const darkRaised = declaration(contrastBlock.slice(darkStart), name)!
+      // Dark theme: lighter, on a dark surface.
+      expect(luminance(darkRaised), `dark ${name}`).toBeGreaterThan(luminance(darkBase))
+    }
+  })
+
+  it('grows touch targets only under a coarse pointer', () => {
+    const coarse = responsive.slice(
+      responsive.indexOf('@media (pointer: coarse)'),
+      responsive.indexOf('@media (min-width: 2000px)'),
+    )
+    expect(coarse).toContain('min-height: 44px')
+    expect(coarse).toContain('min-width: 44px')
+    // A 26px button is right with a mouse. No control floor is imposed outside
+    // this block — the 44px that appears in the stacked-layout rules is the
+    // collapsed strip's own height, not a minimum applied to a control.
+    const elsewhere = responsive.replace(coarse, '').replace(/\/\*[\s\S]*?\*\//g, '')
+    expect(elsewhere).not.toMatch(/min-(height|width):\s*44px/)
+  })
+
+  it('grows the switch by its hit area, never by its box', () => {
+    // A switch positions its thumb against the track. Stretching the track to
+    // 44px leaves the thumb floating in dead space — the one carve-out the
+    // design bundle makes, and for this reason.
+    const hit = responsive.slice(responsive.indexOf('.prenta-touch-hit::after'))
+    expect(hit).toContain('position: absolute')
+    expect(hit.slice(0, hit.indexOf('}'))).not.toContain('min-height')
+  })
+
+  it('overrides the rail width with !important, because it is set inline', () => {
+    // The rail is drag-resizable and its width is an inline style, which no
+    // class can beat. Without this the stacked layout silently keeps a
+    // 360px-wide rail on a 390px screen.
+    const stacked = responsive.slice(responsive.indexOf('@media (max-width: 900px)'))
+    expect(stacked).toMatch(/\.prenta-editor-rail\s*\{[^}]*width:\s*100%\s*!important/)
+  })
+})
+
+describe('class hooks the layer targets', () => {
+  // A rule whose hook was renamed in a component is dead CSS with no error.
+  const hooks: Array<[string, string]> = [
+    ['prenta-skip-link', 'src/layout/primitives/AdminShell.tsx'],
+    ['prenta-editor-rail', 'src/components/EditorRail.tsx'],
+    ['prenta-editor-rail-collapsed', 'src/components/EditorRail.tsx'],
+    ['prenta-rail-label', 'src/components/EditorRail.tsx'],
+    ['prenta-editor-body', 'src/views/page-editor/PageSectionEditor.tsx'],
+    ['prenta-editor-header', 'src/views/page-editor/EditorTopBar.tsx'],
+    ['prenta-editor-inspector', 'src/views/page-editor/SectionInspector.tsx'],
+    ['prenta-canvas-scroll', 'src/views/page-editor/EditorCanvas.tsx'],
+    ['prenta-canvas-fit', 'src/views/page-editor/EditorCanvas.tsx'],
+    ['prenta-touch-target', 'src/components/EditorRail.tsx'],
+    ['prenta-touch-hit', 'src/components/page-tab/DirectiveSwitch.tsx'],
+  ]
+
+  for (const [hook, file] of hooks) {
+    it(`${hook} is applied in ${file.split('/').pop()}`, () => {
+      expect(responsive, `${hook} is unused in responsive.css`).toContain(hook)
+      expect(read(file), `${hook} is not applied by any component`).toContain(hook)
+    })
+  }
+
+  it('points the skip link at a target that exists', () => {
+    const shell = read('src/layout/primitives/AdminShell.tsx')
+    expect(shell).toContain('href="#prenta-main"')
+    expect(shell).toContain('id="prenta-main"')
+  })
+})

package/src/__tests__/views/canvas-review-mode.render.test.tsx

@@ -0,0 +1,94 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { SectionRenderer } from '../../views/page-editor/sections/SectionRenderer.js'
+import type { PageSection } from '../../lib/page-editor-service.js'
+
+afterEach(cleanup)
+
+const SECTION: PageSection = {
+  id: 's1',
+  sectionType: 'hero',
+  name: 'Hero Banner',
+  visible: true,
+  content: { heading: 'A headline' },
+  settings: {},
+}
+
+function sectionEl(): HTMLElement {
+  const el = document.querySelector('[data-section-id="s1"]')
+  if (!el) throw new Error('section not rendered')
+  return el as HTMLElement
+}
+
+describe('SectionRenderer — review mode', () => {
+  it('marks a changed section and names the change in its label', () => {
+    render(<SectionRenderer section={SECTION} editable reviewing changed />)
+
+    expect(screen.getByText('Hero Banner — changed')).toBeTruthy()
+    expect(sectionEl().getAttribute('data-changed')).toBe('true')
+    expect(sectionEl().className).toContain('outline-dashed')
+  })
+
+  it('leaves an unchanged section unlabelled and unoutlined', () => {
+    render(<SectionRenderer section={SECTION} editable reviewing changed={false} />)
+
+    expect(screen.queryByText(/— changed/)).toBeNull()
+    expect(sectionEl().getAttribute('data-changed')).toBeNull()
+    expect(sectionEl().className).not.toContain('outline-dashed')
+  })
+
+  it('keeps the changed label even though review mode suppresses editing chrome', () => {
+    // The trap the handoff calls out by name: review mode and site-preview
+    // mode both drop the cursor, the hover outline and the section label, so
+    // it is tempting to share one suppression rule. Doing that hides the one
+    // label review mode exists to show.
+    render(<SectionRenderer section={SECTION} editable reviewing changed selected />)
+
+    expect(sectionEl().getAttribute('data-editable')).toBeNull()
+    expect(sectionEl().className).not.toContain('cursor-pointer')
+    // The selection label is gone…
+    expect(screen.queryByText('Hero Banner')).toBeNull()
+    // …and the changed label is not.
+    expect(screen.getByText('Hero Banner — changed')).toBeTruthy()
+  })
+
+  it('does not select a section while reviewing — that would edit the current page', () => {
+    const onSelect = vi.fn()
+    render(<SectionRenderer section={SECTION} editable reviewing changed onSelect={onSelect} />)
+
+    fireEvent.click(sectionEl())
+
+    expect(onSelect).not.toHaveBeenCalled()
+  })
+
+  it('still selects normally when not reviewing', () => {
+    const onSelect = vi.fn()
+    render(<SectionRenderer section={SECTION} editable onSelect={onSelect} />)
+
+    fireEvent.click(sectionEl())
+
+    expect(onSelect).toHaveBeenCalledWith('s1')
+    expect(sectionEl().getAttribute('data-editable')).toBe('true')
+  })
+
+  it('names the change in the accessible name, not only in colour and a dashed border', () => {
+    render(<SectionRenderer section={SECTION} editable reviewing changed />)
+    expect(sectionEl().getAttribute('aria-label')).toBe(
+      'Hero Banner section — changed in this version',
+    )
+  })
+
+  it('keeps a hidden section muted in a snapshot, as it was when saved', () => {
+    render(
+      <SectionRenderer
+        section={{ ...SECTION, visible: false }}
+        editable
+        reviewing
+        changed={false}
+      />,
+    )
+    expect(sectionEl().className).toContain('opacity-40')
+    expect(screen.getByText('Hidden')).toBeTruthy()
+  })
+})