@prenta/admin 0.92.0 → 0.94.0

package/src/views/page-editor/VersionHistoryPanel.tsx

@@ -0,0 +1,302 @@
+'use client'
+
+import { useMemo, useState } from 'react'
+import { History, Loader2, RotateCcw, X } from 'lucide-react'
+import {
+  diffVersions,
+  groupChangesBySection,
+  type FieldChange,
+  type SectionChangeGroup,
+} from '../../lib/version-diff.js'
+import {
+  groupVersionsByDay,
+  initials,
+  timeLabel,
+  versionKind,
+  type PageVersion,
+} from '../../lib/version-history.js'
+
+export interface VersionHistoryPanelProps {
+  versions: PageVersion[]
+  loading: boolean
+  error: string | null
+  /** Index into `versions`; 0 is the newest, which is "current". */
+  selectedIndex: number
+  onSelect: (index: number) => void
+  onClose: () => void
+  onRestore: (version: PageVersion) => void
+  restoring: boolean
+  canRestore: boolean
+}
+
+/**
+ * Version history, as a takeover of the editing rail.
+ *
+ * It is deliberately NOT a dialog. History here is about comparing *renders*:
+ * picking a version puts it on the canvas, and the changed sections light up
+ * there. A modal would cover the very thing it exists to let you look at, and
+ * a right-hand drawer would push the canvas around while you compare against
+ * it. Overlaying the rail leaves the canvas exactly where it was, at exactly
+ * the size it was, so the only thing that changes between two versions is the
+ * page itself.
+ *
+ * Absolutely positioned over the rail's own box (the rail is `relative`) so it
+ * inherits the user's chosen rail width and needs no width of its own.
+ */
+export function VersionHistoryPanel({
+  versions,
+  loading,
+  error,
+  selectedIndex,
+  onSelect,
+  onClose,
+  onRestore,
+  restoring,
+  canRestore,
+}: VersionHistoryPanelProps) {
+  /**
+   * Disclosure FOLLOWS selection rather than being tracked separately.
+   *
+   * They are the same act: the selected version is what the canvas renders,
+   * and the expanded diff is the list of what to look for on it. Held apart,
+   * the two drift — the parent can move the selection (the review bar's "Back
+   * to current" does exactly that), and the diff then describes one version
+   * while the canvas shows another, with Restore stranded on a row nobody can
+   * see. Only "did the user collapse the row they are on" needs remembering.
+   */
+  const [collapsed, setCollapsed] = useState(false)
+  const expandedId = collapsed ? null : (versions[selectedIndex]?.id ?? null)
+
+  const days = useMemo(() => groupVersionsByDay(versions), [versions])
+
+  // Diff each version against the one before it, so a row reports what that
+  // save DID rather than how it differs from the present.
+  const changesByVersion = useMemo(() => {
+    const map = new Map<string, FieldChange[]>()
+    versions.forEach((version, index) => {
+      map.set(version.id, diffVersions(version.sections, versions[index + 1]?.sections))
+    })
+    return map
+  }, [versions])
+
+  return (
+    <div
+      className="bg-card absolute inset-0 z-45 flex flex-col"
+      role="region"
+      aria-label="Version history"
+    >
+      <div className="border-border flex shrink-0 items-center gap-2 border-b py-2.5 pr-2.5 pl-3.5">
+        <History className="text-brand h-3.5 w-3.5" aria-hidden />
+        <h2 className="text-foreground flex-1 text-[12.5px] font-semibold">Version history</h2>
+        <span className="text-muted-foreground text-[11px] tabular-nums">
+          {versions.length} version{versions.length === 1 ? '' : 's'}
+        </span>
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close version history"
+          title="Close version history"
+          className="prenta-touch-target text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-6.5 w-6.5 items-center justify-center rounded-md transition-colors"
+        >
+          <X className="h-3.5 w-3.5" aria-hidden />
+        </button>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        {loading ? (
+          <div className="flex items-center justify-center py-16">
+            <Loader2 className="text-muted-foreground h-5 w-5 animate-spin" aria-hidden />
+            <span className="sr-only">Loading version history</span>
+          </div>
+        ) : error ? (
+          <p className="text-destructive px-3.5 py-10 text-center text-sm">{error}</p>
+        ) : versions.length === 0 ? (
+          <p className="text-muted-foreground px-3.5 py-10 text-center text-sm">
+            No versions yet. Every save adds one.
+          </p>
+        ) : (
+          days.map((day) => (
+            // Keyed on the group's first version, NOT on its label. Grouping
+            // walks consecutive runs, so an out-of-order page yields two
+            // non-adjacent groups both labelled "Today" — `groupVersionsByDay`
+            // has a test asserting exactly that — and a label key would collide.
+            <section key={day.versions[0]?.id ?? day.label}>
+              <h3 className="text-muted-foreground bg-muted border-border sticky top-0 z-2 border-b px-3.5 pt-2.5 pb-1.5 text-[10px] font-bold tracking-[0.7px] uppercase">
+                {day.label}
+              </h3>
+              {day.versions.map((version) => {
+                const index = versions.indexOf(version)
+                return (
+                  <VersionRow
+                    key={version.id}
+                    version={version}
+                    index={index}
+                    changes={changesByVersion.get(version.id) ?? []}
+                    selected={index === selectedIndex}
+                    expanded={expandedId === version.id}
+                    onToggle={() => {
+                      // Re-clicking the row you are on collapses it; clicking
+                      // any other selects it, which is also what opens it.
+                      if (index === selectedIndex) setCollapsed((prev) => !prev)
+                      else {
+                        setCollapsed(false)
+                        onSelect(index)
+                      }
+                    }}
+                    onRestore={() => onRestore(version)}
+                    restoring={restoring}
+                    canRestore={canRestore}
+                  />
+                )
+              })}
+            </section>
+          ))
+        )}
+      </div>
+    </div>
+  )
+}
+
+const TONE_CLASS: Record<string, string> = {
+  live: 'bg-success/15 text-success',
+  draft: 'bg-warning/15 text-warning',
+  neutral: 'bg-muted text-muted-foreground',
+  danger: 'bg-destructive/15 text-destructive',
+}
+
+function VersionRow({
+  version,
+  index,
+  changes,
+  selected,
+  expanded,
+  onToggle,
+  onRestore,
+  restoring,
+  canRestore,
+}: {
+  version: PageVersion
+  index: number
+  changes: FieldChange[]
+  selected: boolean
+  expanded: boolean
+  onToggle: () => void
+  onRestore: () => void
+  restoring: boolean
+  canRestore: boolean
+}) {
+  const kind = versionKind(version.changeType)
+  const isCurrent = index === 0
+  const groups = groupChangesBySection(changes)
+  const time = timeLabel(version.createdAt)
+
+  return (
+    <div className="border-border border-b">
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-expanded={expanded}
+        className={`flex w-full items-center gap-2.5 py-2.5 pr-2.5 pl-3 text-left transition-colors ${
+          selected ? 'bg-accent shadow-[inset_2px_0_0_var(--acc)]' : 'hover:bg-accent/60'
+        }`}
+      >
+        <span
+          className="bg-muted text-muted-foreground flex h-6 w-6 shrink-0 items-center justify-center rounded-full text-[9.5px] font-semibold"
+          aria-hidden
+        >
+          {initials(version.author.name)}
+        </span>
+
+        <span className="min-w-0 flex-1">
+          <span className="text-foreground flex items-center gap-1.5 text-xs font-semibold">
+            {time}
+            {isCurrent && (
+              <span className="bg-accent text-accent-foreground rounded px-1.5 py-px text-[8.5px] font-bold tracking-[0.4px] uppercase">
+                Current
+              </span>
+            )}
+          </span>
+          <span className="text-muted-foreground mt-px block truncate text-[10.5px]">
+            {version.author.name} ·{' '}
+            {changes.length
+              ? `${changes.length} change${changes.length === 1 ? '' : 's'}`
+              : 'no content changes'}
+          </span>
+        </span>
+
+        <span
+          className={`shrink-0 rounded px-1.5 py-px text-[8.5px] font-bold tracking-[0.4px] uppercase ${
+            TONE_CLASS[kind.tone] ?? TONE_CLASS.neutral
+          }`}
+        >
+          {kind.label}
+        </span>
+      </button>
+
+      {/*
+       * Opens on `expanded` alone — NOT on `expanded && changes.length`.
+       *
+       * Restore lives in here, and a version can legitimately have no computed
+       * diff: the oldest one held has no predecessor to compare against, and a
+       * metadata-only save changes no section. Gating the whole block on a
+       * non-empty diff makes exactly those versions reviewable but not
+       * restorable, which is the wrong way round — the oldest version is the
+       * one a rollback most often wants.
+       */}
+      {expanded && (
+        <div className="flex flex-col gap-2.5 pt-0 pr-3 pb-3 pl-[38px]">
+          {groups.length > 0 ? (
+            groups.map((group) => <ChangeGroup key={group.sectionId} group={group} />)
+          ) : (
+            <p className="text-muted-foreground text-[11px] leading-[1.45]">
+              No section changes to show against the version before it.
+            </p>
+          )}
+
+          {/* Restore is offered only on the row being reviewed, and never on the
+              newest one — "restore the version you are already looking at" is a
+              no-op dressed up as an action. */}
+          {selected && !isCurrent && canRestore && (
+            <button
+              type="button"
+              onClick={onRestore}
+              disabled={restoring}
+              className="border-border text-foreground hover:bg-accent inline-flex items-center justify-center gap-1.5 rounded-lg border px-3 py-1.5 text-xs font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50"
+            >
+              {restoring ? (
+                <Loader2 className="h-3 w-3 animate-spin" aria-hidden />
+              ) : (
+                <RotateCcw className="h-3 w-3" aria-hidden />
+              )}
+              Restore this version
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function ChangeGroup({ group }: { group: SectionChangeGroup }) {
+  return (
+    <div>
+      <h4 className="text-foreground/80 mb-1 text-[9.5px] font-bold tracking-[0.4px] uppercase">
+        {group.sectionName}
+      </h4>
+      {group.changes.map((change, i) => (
+        <div key={`${change.field}-${i}`} className={i > 0 ? 'mt-1.5' : undefined}>
+          <div className="text-muted-foreground text-[9.5px] font-bold tracking-[0.3px]">
+            {change.field}
+          </div>
+          {/* Colour is not the only carrier: the old value is struck through
+              and the pair is ordered old-then-new, both of which survive a
+              reader who cannot separate red from green. */}
+          <div className="text-destructive text-[11px] leading-[1.45] line-through decoration-1">
+            {change.from}
+          </div>
+          <div className="text-success text-[11px] leading-[1.45]">{change.to}</div>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/views/page-editor/reflow-context.ts

@@ -0,0 +1,43 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+import type { BreakpointId } from '../../lib/breakpoints.js'
+import type { ReflowBaseline } from '../../lib/reflow-baseline.js'
+
+/**
+ * What the reflow guard needs that a field editor cannot know by itself.
+ *
+ * A context rather than props because the guard hangs off individual fields
+ * several levels down (inspector → field → repeater row → field), and threading
+ * five props through every renderer for a feature that only some field types
+ * use makes every one of them harder to read.
+ *
+ * The default is inert — no canvas, no baseline — so a field rendered outside a
+ * page editor (a repeater in a modal, a test) simply shows no guard rather than
+ * needing a provider to exist.
+ */
+export interface ReflowContextValue {
+  /** The live `.prenta-canvas` element the probe clones. */
+  canvas: HTMLElement | null
+  /** Section the inspector is editing — scopes field lookup. */
+  sectionId: string | null
+  baseline: ReflowBaseline | null
+  /** Breakpoint the canvas is showing. */
+  device: BreakpointId
+  /** Take the canvas to a breakpoint so the editor can look at it. */
+  onProof: (id: BreakpointId) => void
+}
+
+const INERT: ReflowContextValue = {
+  canvas: null,
+  sectionId: null,
+  baseline: null,
+  device: 'wide',
+  onProof: () => {},
+}
+
+export const ReflowContext = createContext<ReflowContextValue>(INERT)
+
+export function useReflowContext(): ReflowContextValue {
+  return useContext(ReflowContext)
+}

package/src/views/page-editor/sections/ByTheNumbersSection.tsx

@@ -16,13 +16,14 @@ export function ByTheNumbersSection({ section }: { section: PageSection }) {
   return (
     <div className="mx-auto max-w-5xl px-6 text-center">
       {heading && (
-        <h2 className="text-foreground text-2xl font-semibold tracking-tight sm:text-3xl">
+        <h2 className="text-foreground @pv-md:text-3xl @pv-2xl:text-4xl text-2xl font-semibold tracking-tight">
           {heading}
         </h2>
       )}
       {body && <p className="text-muted-foreground mx-auto mt-4 max-w-2xl text-base">{body}</p>}
+      {/* Handoff: stats collapse to 2-up below 900, and to 1-up below 460. */}
       {stats.length > 0 && (
-        <dl className="mt-10 grid grid-cols-1 gap-8 sm:grid-cols-3">
+        <dl className="@pv-sm:grid-cols-2 @pv-lg:grid-cols-3 mt-10 grid grid-cols-1 gap-8">
           {stats.map((s, i) => (
             <div key={i}>
               <dt className="text-brand text-4xl font-semibold tracking-tight">

package/src/views/page-editor/sections/CtaBannerSection.tsx

@@ -9,7 +9,9 @@ export function CtaBannerSection({ section }: { section: PageSection }) {
 
   return (
     <div className="mx-auto max-w-3xl px-6 text-center">
-      <h2 className="text-2xl font-semibold tracking-tight sm:text-3xl">{heading}</h2>
+      <h2 className="@pv-md:text-3xl @pv-2xl:text-4xl text-2xl font-semibold tracking-tight">
+        {heading}
+      </h2>
       {body && (
         <p
           className={`mx-auto mt-3 max-w-xl text-base ${dark ? 'text-brand-foreground/80' : 'text-muted-foreground'}`}

package/src/views/page-editor/sections/FeatureHighlightSection.tsx

@@ -18,7 +18,7 @@ export function FeatureHighlightSection({ section }: { section: PageSection }) {
           {label}
         </span>
       )}
-      <h2 className="text-foreground text-2xl font-semibold tracking-tight sm:text-3xl">
+      <h2 className="text-foreground @pv-md:text-3xl @pv-2xl:text-4xl text-2xl font-semibold tracking-tight">
         {heading}
       </h2>
       {body && <p className="text-muted-foreground mt-4 text-base leading-relaxed">{body}</p>}
@@ -47,7 +47,8 @@ export function FeatureHighlightSection({ section }: { section: PageSection }) {
 
   return (
     <div className="mx-auto max-w-5xl px-6">
-      <div className="flex flex-col items-center gap-10 md:flex-row">
+      {/* Handoff: image+text stacks below 700. */}
+      <div className="@pv-md:flex-row flex flex-col items-center gap-10">
         {imageLeft ? (
           <>
             {media}

package/src/views/page-editor/sections/GallerySection.tsx

@@ -15,12 +15,16 @@ export function GallerySection({ section }: { section: PageSection }) {
   const images: GalleryImage[] = Array.isArray(c.images) ? (c.images as GalleryImage[]) : []
   const withUrl = images.filter((img) => img && typeof img.url === 'string' && img.url)
 
+  // Ascending min-width container queries only: the column count is chosen
+  // from content, so mixing min- and max-width variants here would depend on
+  // Tailwind's variant sort order to resolve — the exact ambiguity the handoff
+  // warns about for data-driven grids.
   const cols =
     columns === 2
-      ? 'sm:grid-cols-2'
+      ? '@pv-sm:grid-cols-2'
       : columns === 4
-        ? 'sm:grid-cols-2 lg:grid-cols-4'
-        : 'sm:grid-cols-3'
+        ? '@pv-sm:grid-cols-2 @pv-xl:grid-cols-4'
+        : '@pv-sm:grid-cols-2 @pv-lg:grid-cols-3'
 
   return (
     <div className="mx-auto max-w-5xl px-6">

package/src/views/page-editor/sections/HeroBannerSection.tsx

@@ -17,12 +17,12 @@ export function HeroBannerSection({ section }: { section: PageSection }) {
           {eyebrow}
         </p>
       )}
-      <h1 className="text-3xl leading-tight font-semibold tracking-tight sm:text-5xl">
+      <h1 className="@pv-md:text-5xl @pv-2xl:text-6xl text-3xl leading-tight font-semibold tracking-tight">
         {heading || 'Your headline goes here'}
       </h1>
       {body && (
         <p
-          className={`mx-auto mt-5 max-w-2xl text-base sm:text-lg ${dark ? 'text-brand-foreground/80' : 'text-muted-foreground'}`}
+          className={`@pv-md:text-lg mx-auto mt-5 max-w-2xl text-base ${dark ? 'text-brand-foreground/80' : 'text-muted-foreground'}`}
         >
           {body}
         </p>

package/src/views/page-editor/sections/MissionSection.tsx

@@ -12,12 +12,14 @@ export function MissionSection({ section }: { section: PageSection }) {
   return (
     <div className={`max-w-3xl px-6 ${align}`}>
       {heading && (
-        <h2 className="text-foreground text-2xl font-semibold tracking-tight sm:text-3xl">
+        <h2 className="text-foreground @pv-md:text-3xl @pv-2xl:text-4xl text-2xl font-semibold tracking-tight">
           {heading}
         </h2>
       )}
       {body && (
-        <p className="text-muted-foreground mt-4 text-base leading-relaxed sm:text-lg">{body}</p>
+        <p className="text-muted-foreground @pv-md:text-lg mt-4 text-base leading-relaxed">
+          {body}
+        </p>
       )}
     </div>
   )

package/src/views/page-editor/sections/PullQuoteSection.tsx

@@ -13,7 +13,9 @@ export function PullQuoteSection({ section }: { section: PageSection }) {
   return (
     <figure className="mx-auto max-w-3xl px-6">
       <blockquote className="border-brand border-l-4 pl-6">
-        <p className="text-foreground text-xl leading-relaxed font-medium sm:text-2xl">“{quote}”</p>
+        <p className="text-foreground @pv-md:text-2xl text-xl leading-relaxed font-medium">
+          “{quote}”
+        </p>
       </blockquote>
       {(attribution || role) && (
         <figcaption className="text-muted-foreground mt-3 pl-6 text-sm">

package/src/views/page-editor/sections/RelatedPostsSection.tsx

@@ -27,7 +27,8 @@ export function RelatedPostsSection({
           url: undefined as string | undefined,
         }))
 
-  const cols = count >= 4 ? 'sm:grid-cols-2 lg:grid-cols-4' : 'sm:grid-cols-3'
+  const cols =
+    count >= 4 ? '@pv-sm:grid-cols-2 @pv-xl:grid-cols-4' : '@pv-sm:grid-cols-2 @pv-lg:grid-cols-3'
 
   return (
     <div className="mx-auto max-w-5xl px-6">

package/src/views/page-editor/sections/SectionRenderer.tsx

@@ -45,10 +45,62 @@ export function hasCanvasRenderer(sectionType: string): boolean {
   return CANVAS_RENDERED_TYPES.has(sectionType)
 }
 
-/** Dispatch a section's body component by type. Shared by editor + preview. */
+/**
+ * Dispatch a section's body component by type. Shared by editor + preview.
+ *
+ * RESOLUTION ORDER — consumer-supplied renderer, then built-in, then
+ * placeholder. The consumer's renderer wins for EVERY type, including the
+ * built-ins, because that is the whole point of the `sectionRenderers` prop:
+ * hand the admin the same components the public site registers and the canvas
+ * shows what actually ships.
+ *
+ * Until this order was corrected the map was consulted only for types the
+ * switch below did not know, so a consumer passing
+ * `DEFAULT_SECTION_RENDERERS` from `@prenta/sections-react` had their hero,
+ * text, feature, stats and cta silently ignored — the canvas rendered the
+ * admin's own approximations while claiming to preview the page. Those
+ * approximations differ in font size, weight and breakpoint, so copy that fit
+ * on two lines in the canvas could wrap to three on the site.
+ *
+ * The built-ins below remain the fallback for consumers who pass nothing.
+ */
 function SectionBody({ section, context }: { section: PageSection; context?: PostRenderContext }) {
   const customRenderers = useAdminSectionRenderers()
 
+  const Supplied = customRenderers[section.sectionType]
+  if (Supplied) {
+    // The renderer contract types `settings` as an open record (matching the
+    // sections-react wire shape); the admin's concrete `SectionSettings`
+    // interface is the same object at runtime but has no index signature, so
+    // bridge the nominal gap here.
+    const wireSection = {
+      ...section,
+      settings: { ...section.settings } as Record<string, unknown>,
+    }
+    // Rendered as a component (not invoked inline) so a throw happens inside
+    // the boundary's subtree and is actually caught. A consumer renderer that
+    // breaks falls back to the built-in rather than blanking the editor.
+    return (
+      <ErrorBoundary
+        key={section.id}
+        fallback={<BuiltInSectionBody section={section} context={context} />}
+      >
+        <Supplied section={wireSection} ctx={context} options={ADMIN_RENDER_OPTIONS} />
+      </ErrorBoundary>
+    )
+  }
+
+  return <BuiltInSectionBody section={section} context={context} />
+}
+
+/** The admin's own approximations, used when the consumer supplies nothing. */
+function BuiltInSectionBody({
+  section,
+  context,
+}: {
+  section: PageSection
+  context?: PostRenderContext
+}) {
   switch (section.sectionType) {
     case 'hero':
       return <HeroBannerSection section={section} />
@@ -74,33 +126,11 @@ function SectionBody({ section, context }: { section: PageSection; context?: Pos
       return <EmbedSection section={section} />
     case 'widget-embed':
       return <WidgetEmbedSection section={section} />
-    default: {
-      // Custom (config-declared) and unmanaged types: use a consumer-supplied
-      // canvas renderer when one is registered (see admin-renderers.tsx).
-      // Consumer code can throw, so a per-section error boundary falls back
-      // to the structural placeholder instead of taking down the editor.
-      const Custom = customRenderers[section.sectionType]
-      if (Custom) {
-        // The renderer contract types `settings` as an open record (matching
-        // the sections-react wire shape); the admin's concrete
-        // `SectionSettings` interface is the same object at runtime but has
-        // no index signature, so bridge the nominal gap here.
-        const wireSection = {
-          ...section,
-          settings: { ...section.settings } as Record<string, unknown>,
-        }
-        // Rendered as a component (not invoked inline) so a throw happens
-        // inside the boundary's subtree and is actually caught.
-        return (
-          <ErrorBoundary key={section.id} fallback={<PlaceholderSection section={section} />}>
-            <Custom section={wireSection} ctx={context} options={ADMIN_RENDER_OPTIONS} />
-          </ErrorBoundary>
-        )
-      }
-      // No renderer registered: a neutral placeholder keeps the canvas
-      // reflecting the section's presence + order instead of a blank gap.
+    default:
+      // Config-declared custom types and unmanaged sections with no supplied
+      // renderer: a neutral placeholder keeps the canvas reflecting the
+      // section's presence and order instead of leaving a blank gap.
       return <PlaceholderSection section={section} />
-    }
   }
 }
 
@@ -134,6 +164,18 @@ export interface SectionRendererProps {
   registerRef?: (id: string, el: HTMLElement | null) => void
   /** Live post data for post-oriented section renderers (pages omit this). */
   context?: PostRenderContext
+  /**
+   * Reviewing a past version: the canvas is a read-only render of a snapshot.
+   *
+   * A SEPARATE flag from `editable`, not a second use of it. Both modes
+   * suppress click-to-select and the hover outline, so it is tempting to fold
+   * them together — but review mode has to keep showing a label on the
+   * sections that changed, which is the entire reason it exists. One shared
+   * suppression rule hides exactly the thing the mode is for.
+   */
+  reviewing?: boolean
+  /** This section differs from the version immediately before the one shown. */
+  changed?: boolean
 }
 
 /**
@@ -149,31 +191,70 @@ export function SectionRenderer({
   onSelect,
   registerRef,
   context,
+  reviewing = false,
+  changed = false,
 }: SectionRendererProps) {
   const settings = section.settings ?? {}
-  const hidden = editable && !section.visible
+  // A snapshot's hidden sections stay muted: the page is still being shown as
+  // the editor's own view of it, and a hidden section that rendered solid here
+  // would misreport what was live at that moment.
+  const chromed = editable || reviewing
+  const hidden = chromed && !section.visible
+  // Review mode is read-only. Click-to-select would edit the CURRENT page
+  // while the canvas shows a past one.
+  const interactive = editable && !reviewing
 
   return (
     <section
       ref={(el) => registerRef?.(section.id, el)}
       data-section-id={section.id}
+      data-editable={interactive ? 'true' : undefined}
+      data-selected={interactive && selected ? 'true' : undefined}
+      data-reviewing={reviewing ? 'true' : undefined}
+      data-changed={reviewing && changed ? 'true' : undefined}
       id={settings.anchorId || undefined}
       className={`relative ${backgroundClass(settings)} ${paddingClass(settings)} ${
         settings.cssClass ?? ''
       } ${hidden ? 'opacity-40' : ''} ${
-        editable ? 'cursor-pointer outline-2 -outline-offset-2 transition-[outline]' : ''
-      } ${selected ? 'outline outline-violet-500' : 'outline-transparent'}`}
-      onClick={editable ? () => onSelect?.(section.id) : undefined}
+        interactive
+          ? 'cursor-pointer outline-2 -outline-offset-2 motion-safe:transition-[outline-color] motion-safe:duration-150'
+          : ''
+      } ${
+        reviewing
+          ? changed
+            ? 'outline-warning outline-2 -outline-offset-2 outline-dashed'
+            : 'outline-transparent'
+          : selected
+            ? 'outline outline-violet-500'
+            : interactive
+              ? 'outline-transparent hover:outline hover:outline-[color-mix(in_oklab,var(--acc)_40%,transparent)]'
+              : 'outline-transparent'
+      }`}
+      onClick={interactive ? () => onSelect?.(section.id) : undefined}
       // Selection is a convenience in the editor; the section list is the
       // primary, fully-accessible control surface, so this stays a region.
-      aria-label={editable ? `${section.name} section` : undefined}
+      aria-label={
+        reviewing && changed
+          ? `${section.name} section — changed in this version`
+          : interactive
+            ? `${section.name} section`
+            : undefined
+      }
     >
-      {editable && selected && (
+      {interactive && selected && (
         <span className="bg-brand pointer-events-none absolute top-0 left-0 z-10 rounded-br-md px-2 py-0.5 text-xs font-medium text-white">
           {section.name}
         </span>
       )}
-      {editable && hidden && (
+      {/* Persistent, not hover-revealed: while reviewing, this label IS the
+          finding. Unchanged sections get no label at all, so the marked ones
+          are legible at a glance down a scaled-down page. */}
+      {reviewing && changed && (
+        <span className="bg-warning text-warning-foreground pointer-events-none absolute top-0 left-0 z-10 rounded-br-md px-2 py-0.5 text-xs font-medium">
+          {section.name} — changed
+        </span>
+      )}
+      {chromed && hidden && (
         <span className="bg-foreground pointer-events-none absolute top-0 right-0 z-10 rounded-bl-md px-2 py-0.5 text-xs font-medium text-white">
           Hidden
         </span>