@prenta/admin 0.92.0 → 0.94.0

package/src/lib/reflow-probe.ts

@@ -0,0 +1,299 @@
+import { BREAKPOINTS, type BreakpointId } from './breakpoints.js'
+
+/**
+ * Measures how a field's copy wraps at every breakpoint, by laying it out for
+ * real rather than estimating.
+ *
+ * ── Why not a class chain ─────────────────────────────────────────────────
+ *
+ * The design handoff specifies rebuilding each probe from a hardcoded list of
+ * wrapper classes per guarded field, and warns twice that a width cap outside
+ * that list makes the guard lie — at wide breakpoints only, so it looks correct
+ * on mobile. By the handoff's own account that list drifted twice.
+ *
+ * A chain is a second source of truth that has to track the renderers' markup
+ * by hand. Worse here: the prototype had semantic classes (`.pv-hero-h`), while
+ * these components are styled with Tailwind utility strings that Prettier's
+ * plugin reorders on save. And a chain written in the admin cannot describe a
+ * consumer's own registered renderer at all.
+ *
+ * So the probe measures the REAL element: the caller renders the actual section
+ * into a hidden host, and this module finds the field by its `data-cms-field`
+ * marker — the same attribute the click-to-edit bridge uses. There is nothing
+ * to keep in sync, and a renderer refactor cannot silently invalidate it.
+ *
+ * ── Why one host, resized ─────────────────────────────────────────────────
+ *
+ * Six widths are measured by resizing a single rendered copy, not by rendering
+ * six. Layout is recomputed either way; React reconciliation is not.
+ */
+
+/** A field's wrap count at one breakpoint. */
+export interface FieldLineCount {
+  id: BreakpointId
+  lines: number
+}
+
+/**
+ * Line count from an element's laid-out height.
+ *
+ * Falls back to `fontSize * 1.25` when `line-height` computes to `normal`,
+ * which it does for any element that never set one. Rounding rather than
+ * flooring: sub-pixel line heights accumulate, and 2.97 lines is three.
+ */
+export function linesFromMetrics(height: number, lineHeight: number, fontSize: number): number {
+  const effective = Number.isFinite(lineHeight) && lineHeight > 0 ? lineHeight : fontSize * 1.25
+  if (!Number.isFinite(effective) || effective <= 0) return 1
+  // An empty field still occupies one line's worth of intent.
+  return Math.max(1, Math.round(height / effective))
+}
+
+/**
+ * How many lines an element's text actually occupies.
+ *
+ * Counts LINE BOXES via a Range over the element's contents, deduplicated by
+ * their top edge. Dividing the element's height by its line-height — the
+ * obvious approach, and what the prototype does — counts padding as text: a
+ * button reading "Get Started" measured 2 lines, because its vertical padding
+ * came to roughly another line's worth of height. Every padded element was
+ * over-reported, which is most CTAs and every boxed heading.
+ *
+ * Rects are deduplicated by rounded top edge because a range spanning nested
+ * inline elements (a `<strong>` mid-sentence, an icon in a button) yields one
+ * rect per fragment, not per line.
+ *
+ * Falls back to the height ratio when the range produces nothing — an element
+ * whose content is a single replaced node, or a layout engine that gives no
+ * rects for empty text.
+ */
+export function countLines(el: HTMLElement): number {
+  const doc = el.ownerDocument
+  try {
+    const range = doc.createRange()
+    range.selectNodeContents(el)
+    const rects = Array.from(range.getClientRects()).filter((r) => r.height > 0)
+    range.detach?.()
+    if (rects.length > 0) {
+      const tops = new Set(rects.map((r) => Math.round(r.top)))
+      return Math.max(1, tops.size)
+    }
+  } catch {
+    // No Range support (or a detached document) — fall through to metrics.
+  }
+
+  const cs = getComputedStyle(el)
+  return linesFromMetrics(
+    el.getBoundingClientRect().height,
+    Number.parseFloat(cs.lineHeight),
+    Number.parseFloat(cs.fontSize),
+  )
+}
+
+/**
+ * The off-screen host.
+ *
+ * `left: -99999px`, never `display: none` — a hidden element has no layout, so
+ * every measurement would be zero. `visibility: hidden` would keep layout but
+ * also keep the element in the accessibility tree; moving it off-screen and
+ * marking it `aria-hidden` keeps it out of both the viewport and the a11y tree
+ * while still being laid out.
+ *
+ * MOUNT IT INSIDE `.prenta-admin`, never on `document.body`. Type tokens and
+ * the font stack are scoped to that root, so a host outside it lays text out in
+ * the document's default font and every measurement is taken at the wrong
+ * metrics. Caught by `e2e/reflow-probe.spec.ts` on its first run: a button
+ * measured 127px on the canvas and 139px in a body-mounted probe.
+ *
+ * Use `mountProbeHost` rather than appending by hand.
+ */
+export function createProbeHost(doc: Document = document): HTMLElement {
+  const host = doc.createElement('div')
+  host.setAttribute('aria-hidden', 'true')
+  host.dataset.reflowProbe = 'true'
+  Object.assign(host.style, {
+    position: 'fixed',
+    left: '-99999px',
+    top: '0',
+    // Never inherit the rail's width — the probe sets its own per breakpoint.
+    width: 'auto',
+    pointerEvents: 'none',
+  })
+  return host
+}
+
+/**
+ * Attach a probe host in the only place it measures correctly.
+ *
+ * Returns a detach function. Falls back to `document.body` only when no admin
+ * root exists (it always does in the app) — and callers should treat a
+ * fallback mount as untrustworthy rather than silently measuring.
+ */
+export function mountProbeHost(
+  host: HTMLElement,
+  doc: Document = document,
+): { detach: () => void; scoped: boolean } {
+  const root = doc.querySelector('.prenta-admin')
+  const parent = root ?? doc.body
+  parent.appendChild(host)
+  return { detach: () => host.remove(), scoped: Boolean(root) }
+}
+
+/**
+ * Measure one field across every breakpoint.
+ *
+ * `container` must carry the same class chain the canvas uses
+ * (`prenta-canvas`, which supplies the query container). Its width is set per
+ * breakpoint, so it must not be width-constrained by a parent.
+ *
+ * `scope` narrows to one section and is REQUIRED whenever the container holds
+ * more than one, because `data-cms-field` paths are unique only within a
+ * section — every section has a `heading` and a `body`. Without it a whole page
+ * silently measures the first section's field and reports it for all of them.
+ * (That mistake is what `e2e/reflow-probe.spec.ts` caught on its second run.)
+ *
+ * Returns `null` when the field cannot be found — the canvas is rendering a
+ * component without `data-cms-field` markers, so there is nothing to measure.
+ * Reporting a line count from the wrong element would be worse than reporting
+ * none: an editor reads a number as a fact.
+ */
+export function measureFieldAcrossBreakpoints(
+  container: HTMLElement,
+  fieldPath: string,
+  scope?: string,
+): FieldLineCount[] | null {
+  const field = `[data-cms-field="${CSS.escape(fieldPath)}"]`
+  const selector = scope ? `${scope} ${field}` : field
+  if (!container.querySelector(selector)) return null
+
+  const previousWidth = container.style.width
+  const out: FieldLineCount[] = []
+
+  for (const bp of BREAKPOINTS) {
+    container.style.width = `${bp.width}px`
+    // Re-query inside the loop: a renderer may swap elements between layouts
+    // (a grid that becomes a stack can remount its children).
+    const el = container.querySelector(selector)
+    out.push({ id: bp.id, lines: el ? countLines(el as HTMLElement) : 1 })
+  }
+
+  container.style.width = previousWidth
+  return out
+}
+
+/** What a probe pass produces for one field. */
+export interface FieldReflow {
+  current: FieldLineCount[]
+  baseline: FieldLineCount[]
+}
+
+/**
+ * Measure a field's wrapping now and as published, from the live canvas.
+ *
+ * The whole `.prenta-canvas` is cloned, not just the target section. Cloning
+ * the section alone would require rebuilding whatever sits between the canvas
+ * root and the section — which is the class-chain problem again, in a smaller
+ * disguise. `e2e/reflow-probe.spec.ts` asserts the whole-canvas clone
+ * reproduces every field's rendered width exactly; nothing asserts that for a
+ * hand-rebuilt wrapper.
+ *
+ * The baseline is measured by writing the published string into the SAME cloned
+ * element and re-measuring, rather than by rendering the published section. The
+ * two differ in exactly one field, so everything else — width caps, siblings,
+ * grid tracks — is held identical by construction rather than by hoping a second
+ * render matches.
+ *
+ * `baselineText` of `undefined` means the field has no published version (a new
+ * section), so there is no change to report and current is echoed as baseline.
+ *
+ * Returns `null` when the section or field is absent from the canvas — a
+ * consumer's renderer may carry no `data-cms-field` markers, and a line count
+ * read off the wrong element is worse than none.
+ */
+export function probeFieldReflow(options: {
+  canvas: HTMLElement
+  sectionId: string
+  fieldPath: string
+  baselineText: string | undefined
+  doc?: Document
+}): FieldReflow | null {
+  const { canvas, sectionId, fieldPath, baselineText, doc = document } = options
+
+  const sectionSel = `[data-section-id="${CSS.escape(sectionId)}"]`
+  const fieldSel = `${sectionSel} [data-cms-field="${CSS.escape(fieldPath)}"]`
+  if (!canvas.querySelector(fieldSel)) return null
+
+  const host = createProbeHost(doc)
+  const clone = canvas.cloneNode(true) as HTMLElement
+  // The canvas is scaled to fit its column. A transform does not change layout
+  // width, but it does scale the measured rects — and line height is read from
+  // a rect. Left on, every count would be off by the scale factor.
+  clone.style.transform = 'none'
+  clone.style.maxWidth = 'none'
+  host.appendChild(clone)
+
+  const { detach, scoped } = mountProbeHost(host, doc)
+  // Outside `.prenta-admin` the type tokens don't apply and every measurement
+  // is taken in the document's default font. Report nothing rather than that.
+  if (!scoped) {
+    detach()
+    return null
+  }
+
+  try {
+    const current = measureFieldAcrossBreakpoints(clone, fieldPath, sectionSel)
+    if (!current) return null
+    if (baselineText === undefined) return { current, baseline: current }
+
+    const el = clone.querySelector(fieldSel)
+    if (!el) return { current, baseline: current }
+    el.textContent = baselineText
+    const baseline = measureFieldAcrossBreakpoints(clone, fieldPath, sectionSel)
+    return { current, baseline: baseline ?? current }
+  } finally {
+    detach()
+  }
+}
+
+export type ReflowSeverity = 'same' | 'grew' | 'grew-badly'
+
+/**
+ * Compare a field's current wrapping against its published baseline.
+ *
+ * Only growth is flagged. Copy that got shorter cannot break a layout that
+ * already held the longer version, so reporting it would be noise on exactly
+ * the edit an editor was asked to make.
+ */
+export function reflowSeverity(current: number, baseline: number): ReflowSeverity {
+  const delta = current - baseline
+  if (delta <= 0) return 'same'
+  return delta === 1 ? 'grew' : 'grew-badly'
+}
+
+/**
+ * The breakpoint worth proofing on: the biggest jump, and on a tie the
+ * narrowest width. A tie means the same damage happens at several sizes, and
+ * the narrowest is where it is most likely to look broken.
+ */
+export function worstBreakpoint(
+  current: FieldLineCount[],
+  baseline: FieldLineCount[],
+): BreakpointId | null {
+  const widthOf = (id: BreakpointId) => BREAKPOINTS.find((b) => b.id === id)?.width ?? 0
+  let worst: { id: BreakpointId; delta: number } | null = null
+
+  for (const c of current) {
+    const b = baseline.find((x) => x.id === c.id)
+    if (!b) continue
+    const delta = c.lines - b.lines
+    if (delta <= 0) continue
+    if (
+      !worst ||
+      delta > worst.delta ||
+      (delta === worst.delta && widthOf(c.id) < widthOf(worst.id))
+    ) {
+      worst = { id: c.id, delta }
+    }
+  }
+
+  return worst?.id ?? null
+}

package/src/lib/seo-service.ts

@@ -11,6 +11,7 @@
 import type { BrandAlignmentScoreResult } from '@prenta/core/brand-voice'
 import type { SEOAnalysisResult } from '@prenta/core/seo/analysis'
 import { cmsApi } from './api.js'
+import type { MaxImagePreview } from '@prenta/core/seo/robots-directives'
 
 /**
  * `cmsApi` never throws — it returns `{ error, status }` on a network/HTTP
@@ -182,6 +183,12 @@ export interface SeoContentRecord {
   twitterImageId: string | null
   noindex: boolean
   nofollow: boolean
+  /** Blocks text snippets, and with them AI Overview and chat citations. */
+  nosnippet: boolean
+  /** Blocks cached copies. */
+  noarchive: boolean
+  /** Largest image preview a result may show. */
+  maxImagePreview: MaxImagePreview
   structuredDataType: string | null
   structuredData: Record<string, unknown> | null
   /** llms.txt curation: AUTO (heuristic), ALWAYS (pin), NEVER (exclude). */
@@ -232,6 +239,9 @@ export interface SeoFieldPayload {
   twitterImage?: string
   noindex?: boolean
   nofollow?: boolean
+  nosnippet?: boolean
+  noarchive?: boolean
+  maxImagePreview?: MaxImagePreview
   structuredDataType?: string
   structuredData?: Record<string, unknown>
   llmsInclude?: LlmsInclude

package/src/lib/version-diff.ts

@@ -0,0 +1,376 @@
+/**
+ * Field-level diff between two page snapshots.
+ *
+ * One of the three parts of the page-builder handoff specified as real logic
+ * rather than mockup ("the version diff — field-level, computed from full
+ * snapshots, and its output drives the changed-section outlines on the
+ * canvas"). Nothing here is display-only: the same result feeds the history
+ * panel's per-field list AND the set of sections the canvas outlines while
+ * reviewing, so the two can never disagree about what changed.
+ *
+ * Pure over `PageSection[]`, with no React and no fetching, because the diff
+ * is asked for in three different places (panel rows, canvas outlines, the
+ * review bar's count) and recomputing it from the same inputs has to be free
+ * of side effects.
+ */
+import {
+  getSectionType,
+  resolveRepeaterField,
+  type SectionFieldDef,
+} from '../views/page-editor/section-types.js'
+import type { PageSection } from './page-editor-service.js'
+
+/** One changed field on one section. */
+export interface FieldChange {
+  sectionId: string
+  /** Editor-facing section name, captured so the panel needn't re-look it up. */
+  sectionName: string
+  /** Human label for the field ("Heading"), from the section registry. */
+  field: string
+  /** Formatted previous value; `—` when absent. */
+  from: string
+  /** Formatted new value; `—` when absent. */
+  to: string
+}
+
+/** Changes for one section, in the order the sections appear on the page. */
+export interface SectionChangeGroup {
+  sectionId: string
+  sectionName: string
+  changes: FieldChange[]
+}
+
+/**
+ * Labels for the keys that are not content fields and so have no entry in the
+ * section registry. Visibility earns its place here: hiding a section is the
+ * one structural change a design-owned CMS lets an editor make, so a history
+ * that silently dropped it would be missing the only structural edit there is.
+ */
+const META_LABELS: Record<string, string> = {
+  visible: 'Visibility',
+  name: 'Section name',
+}
+
+const SETTING_LABELS: Record<string, string> = {
+  backgroundType: 'Background type',
+  backgroundColor: 'Background colour',
+  paddingY: 'Vertical padding',
+  anchorId: 'Anchor id',
+  cssClass: 'CSS class',
+}
+
+const EMPTY = '—'
+
+/**
+ * Label a content key through the section registry — the same definitions the
+ * inspector renders from, so the diff reads in the words the editor typed
+ * under. Falls back to the raw key for content on a custom or unmanaged type
+ * the registry does not describe: a key is uglier than a label but it is true,
+ * whereas omitting the row would hide a real change.
+ */
+function contentFieldLabel(sectionType: string, key: string): string {
+  const def = getSectionType(sectionType)
+  const field = def?.fields.find((f: SectionFieldDef) => f.key === key)
+  return field?.label ?? key
+}
+
+/**
+ * The repeater shape behind a content key, or null when the field is not one.
+ *
+ * Goes through `resolveRepeaterField` rather than reading `field.fields`
+ * directly: `stats` and `gallery` are shorthand presets whose sub-fields are
+ * supplied by the registry, not spelled out on the definition, so reading the
+ * raw property finds nothing and the diff falls back to raw keys ("value"
+ * instead of "Value") on the two repeaters that ship by default.
+ */
+function repeaterFor(sectionType: string, key: string) {
+  const def = getSectionType(sectionType)
+  const field = def?.fields.find((f: SectionFieldDef) => f.key === key)
+  return field ? resolveRepeaterField(field) : null
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Values that all render as `—` and must therefore compare as equal.
+ *
+ * Without this, tightening the comparison from formatted strings to structure
+ * would start reporting `'' → undefined` as a change, emitting rows that read
+ * "— → —". Blank is blank however it is spelled.
+ */
+function isBlank(value: unknown): boolean {
+  if (value === null || value === undefined) return true
+  if (typeof value === 'string') return value.trim() === ''
+  if (Array.isArray(value)) return value.length === 0
+  if (isPlainObject(value)) return Object.keys(value).length === 0
+  return false
+}
+
+/**
+ * Structural equality, which is what decides whether a field changed.
+ *
+ * This deliberately does NOT go through {@link formatValue}. Comparing the
+ * display strings is the obvious shortcut and it silently loses real edits:
+ * `formatValue` collapses an array to "N items", so retyping a stats row while
+ * keeping the row count formats identically on both sides and the field reports
+ * no change — no row in the panel, and no outline on the canvas. That is
+ * precisely the edit the reviewer is looking for.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (isBlank(a) && isBlank(b)) return true
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]))
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+    for (const key of keys) if (!deepEqual(a[key], b[key])) return false
+    return true
+  }
+  return false
+}
+
+/**
+ * Render a value as the one line the diff shows.
+ *
+ * Lossy on purpose — a repeater row expanded in full would bury the change it
+ * is reporting. It is used for DISPLAY ONLY; {@link deepEqual} decides whether
+ * a field changed, and repeater rows are descended into by
+ * {@link compareRepeater} so a collapsed summary never has to stand in for a
+ * change it cannot show.
+ */
+export function formatValue(value: unknown): string {
+  if (value === null || value === undefined) return EMPTY
+  if (typeof value === 'string') return value.trim() === '' ? EMPTY : value
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No'
+  if (typeof value === 'number') return String(value)
+  if (Array.isArray(value)) {
+    if (value.length === 0) return EMPTY
+    return `${value.length} item${value.length === 1 ? '' : 's'}`
+  }
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    for (const key of ['name', 'title', 'label', 'url', 'alt']) {
+      const candidate = record[key]
+      if (typeof candidate === 'string' && candidate.trim() !== '') return candidate
+    }
+    const count = Object.keys(record).length
+    return count === 0 ? EMPTY : `${count} field${count === 1 ? '' : 's'}`
+  }
+  return String(value)
+}
+
+/** Visibility reads as a state, not a boolean — "No" is not a useful diff. */
+function formatVisible(value: unknown): string {
+  return value === false ? 'Hidden' : 'Shown'
+}
+
+function push(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  field: string,
+  from: string,
+  to: string,
+): void {
+  out.push({ sectionId: section.id, sectionName: section.name, field, from, to })
+}
+
+function compare(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  field: string,
+  before: unknown,
+  after: unknown,
+  format: (v: unknown) => string = formatValue,
+): void {
+  if (deepEqual(before, after)) return
+  push(out, section, field, format(before), format(after))
+}
+
+/**
+ * Diff a repeater (stats rows, gallery images, FAQ entries) row by row.
+ *
+ * A single "2 items → 2 items" row would be worse than useless: it is the one
+ * case where the summary cannot express the change, and the reviewer's next
+ * question — *which* row — has no answer. Descending gives
+ * "Stats · Row 2 · Value" and a real before/after.
+ */
+function compareRepeater(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  sectionType: string,
+  key: string,
+  label: string,
+  before: readonly unknown[],
+  after: readonly unknown[],
+): void {
+  const repeater = repeaterFor(sectionType, key)
+  // The registry's own noun for a row ("Stat", "Image") when it has one.
+  const rowNoun = repeater?.rowLabel ?? 'Row'
+  const subLabel = (subKey: string) =>
+    repeater?.fields.find((f: SectionFieldDef) => f.key === subKey)?.label ?? subKey
+
+  for (let i = 0; i < Math.max(before.length, after.length); i++) {
+    const rowLabel = `${label} · ${rowNoun} ${i + 1}`
+    const prev = before[i]
+    const next = after[i]
+
+    if (prev === undefined) {
+      push(out, section, rowLabel, EMPTY, 'Added')
+      continue
+    }
+    if (next === undefined) {
+      push(out, section, rowLabel, 'Present', 'Removed')
+      continue
+    }
+    if (deepEqual(prev, next)) continue
+
+    // Rows are normally objects of sub-fields; anything else (a bare string in
+    // a legacy gallery, say) still gets a row rather than being skipped.
+    if (!isPlainObject(prev) || !isPlainObject(next)) {
+      push(out, section, rowLabel, formatValue(prev), formatValue(next))
+      continue
+    }
+
+    for (const subKey of new Set([...Object.keys(prev), ...Object.keys(next)])) {
+      compare(out, section, `${rowLabel} · ${subLabel(subKey)}`, prev[subKey], next[subKey])
+    }
+  }
+}
+
+/** One content field: descends into repeaters, otherwise a plain comparison. */
+function compareContentField(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  sectionType: string,
+  key: string,
+  before: unknown,
+  after: unknown,
+): void {
+  if (deepEqual(before, after)) return
+
+  const label = contentFieldLabel(sectionType, key)
+  const beforeRows = Array.isArray(before) ? before : null
+  const afterRows = Array.isArray(after) ? after : null
+
+  if (beforeRows && afterRows) {
+    compareRepeater(out, section, sectionType, key, label, beforeRows, afterRows)
+    return
+  }
+
+  push(out, section, label, formatValue(before), formatValue(after))
+}
+
+/**
+ * Compute what changed going FROM `older` TO `newer`.
+ *
+ * Diffing version *i* against version *i+1* therefore yields what changed *in*
+ * version *i* — the framing the history panel needs, where each row answers
+ * "what did this save do?" rather than "how does this differ from now?".
+ *
+ * `older` is optional because the earliest version in a list has nothing
+ * before it. That case is no changes, not "everything was added": the oldest
+ * snapshot we happen to hold is not the moment the page came into existence,
+ * and reporting every field as new would say it was.
+ */
+export function diffVersions(
+  newer: readonly PageSection[],
+  older: readonly PageSection[] | null | undefined,
+): FieldChange[] {
+  if (!older) return []
+
+  const out: FieldChange[] = []
+  const olderById = new Map(older.map((s) => [s.id, s]))
+
+  for (const next of newer) {
+    const prev = olderById.get(next.id)
+
+    if (!prev) {
+      out.push({
+        sectionId: next.id,
+        sectionName: next.name,
+        field: 'Section',
+        from: EMPTY,
+        to: 'Added',
+      })
+      continue
+    }
+
+    if (next.name !== prev.name) {
+      compare(out, next, META_LABELS.name!, prev.name, next.name)
+    }
+    compare(out, next, META_LABELS.visible!, prev.visible, next.visible, formatVisible)
+
+    // Union of both key sets: a field cleared to undefined only appears in the
+    // older snapshot, and clearing a heading is exactly the kind of edit a
+    // history is consulted about.
+    const contentKeys = new Set([
+      ...Object.keys(prev.content ?? {}),
+      ...Object.keys(next.content ?? {}),
+    ])
+    for (const key of contentKeys) {
+      compareContentField(
+        out,
+        next,
+        next.sectionType,
+        key,
+        prev.content?.[key],
+        next.content?.[key],
+      )
+    }
+
+    const settingKeys = new Set([
+      ...Object.keys(prev.settings ?? {}),
+      ...Object.keys(next.settings ?? {}),
+    ])
+    for (const key of settingKeys) {
+      compare(
+        out,
+        next,
+        SETTING_LABELS[key] ?? key,
+        (prev.settings as Record<string, unknown>)?.[key],
+        (next.settings as Record<string, unknown>)?.[key],
+      )
+    }
+  }
+
+  // Sections present before and gone after. Reported against the OLD section's
+  // name because the new snapshot has nothing to name it with.
+  const newerIds = new Set(newer.map((s) => s.id))
+  for (const gone of older) {
+    if (newerIds.has(gone.id)) continue
+    out.push({
+      sectionId: gone.id,
+      sectionName: gone.name,
+      field: 'Section',
+      from: 'Present',
+      to: 'Removed',
+    })
+  }
+
+  return out
+}
+
+/**
+ * Group changes by section, preserving first-seen order so the panel lists
+ * them top-to-bottom in the order they appear on the page.
+ */
+export function groupChangesBySection(changes: readonly FieldChange[]): SectionChangeGroup[] {
+  const groups = new Map<string, SectionChangeGroup>()
+  for (const change of changes) {
+    let group = groups.get(change.sectionId)
+    if (!group) {
+      group = { sectionId: change.sectionId, sectionName: change.sectionName, changes: [] }
+      groups.set(change.sectionId, group)
+    }
+    group.changes.push(change)
+  }
+  return [...groups.values()]
+}
+
+/** The ids the canvas outlines while reviewing a version. */
+export function changedSectionIds(changes: readonly FieldChange[]): Set<string> {
+  return new Set(changes.map((c) => c.sectionId))
+}