@startsimpli/ui 0.4.141 → 0.4.143

package/src/components/history/RecordHistoryPanel.tsx

@@ -49,26 +49,51 @@
  *    = {"enabled": false}` on the type (or the reserved `"*"` row). That is a
  *    decision somebody made, not a silent door, so it gets different words —
  *    "history is not recorded for this kind of record" — and it is said only
- *    when the host passes `historyEnabled={false}`. The panel cannot see the
- *    setting itself: it only holds a revisions client, and the revisions
- *    envelope does not carry the resolved policy. Otherwise the empty state
+ *    when the policy says so: the host's `historyEnabled={false}`, or — since
+ *    bd startsim-jkkn7.17 put the resolved policy on the revisions envelope —
+ *    `history.enabled: false` on the first page. Otherwise the empty state
  *    says "no edits recorded" and nothing more — and never "never changed".
+ *
+ * ── RESTORE (bd startsim-zkyk4; route bd startsim-ti1yv) ────────────────────
+ *
+ * "Restore this value" on a changed field and "Restore this version" on a row,
+ * offered only when the host injects `client.restore` and only where it would
+ * change something. Nothing is written until {@link RestoreConfirmDialog} has
+ * shown what will move, computed from the trail this panel already holds by the
+ * same backwards undo the server runs. Every restore carries the version the
+ * HOST holds (`currentVersion`, read at confirm time so an autosave in between
+ * is honoured) — the route 428s without one — and a 412 reuses StaleSaveDialog,
+ * where only an explicit "restore anyway" adopts the version the refusal named.
+ * A narrowed (`?field=`) trail is that field's own, so it never offers a
+ * whole-record restore.
  */
-import { ReactNode, useMemo } from 'react';
-import { useInfiniteQuery } from '@tanstack/react-query';
-import { Bot, FilePlus2, Pencil, ShieldAlert, Tag } from 'lucide-react';
+import { ReactNode, useCallback, useMemo, useRef, useState } from 'react';
+import { useInfiniteQuery, useQueryClient } from '@tanstack/react-query';
+import { Bot, FilePlus2, Pencil, ShieldAlert, Tag, Undo2, X } from 'lucide-react';
 
 import { ActivityTimeline, type ActivityTimelineItem } from '../ActivityTimeline';
 import { ErrorState } from '../states';
 import { RevisionFields } from './RevisionFields';
+import { RestoreConfirmDialog } from './RestoreConfirmDialog';
+import { StaleSaveDialog } from './StaleSaveDialog';
+import type { StaleSaveConflict } from './useConditionalSave';
+import { newestRevision } from './conditional-write';
+import {
+  latestFieldVersions,
+  parseRestoreOutcome,
+  restorePreview,
+  type ParsedRestoreOutcome,
+  type RestorePreview,
+} from './restore';
 import {
   COLLAPSE_WINDOW_MS,
   foldRevisions,
+  normalizeRevision,
   sittingHeadline,
   sittingSummary,
   type RevisionSitting,
 } from './revision-history';
-import type { EntityRevision, RevisionClient, RevisionPage } from './types';
+import type { EntityRevision, RestoreRequest, RevisionClient, RevisionPage } from './types';
 import {
   RECORD_HISTORY_PANEL_DEFAULTS,
   type RecordHistoryPanelClassNames,
@@ -82,6 +107,7 @@ export const REVISION_ENTRY_TYPES = {
   renamed: 'revision_renamed',
   attempt: 'revision_attempt',
   machine: 'revision_machine',
+  restored: 'revision_restored',
 } as const;
 
 const DEFAULT_ICONS = {
@@ -90,10 +116,14 @@ const DEFAULT_ICONS = {
   [REVISION_ENTRY_TYPES.renamed]: Tag,
   [REVISION_ENTRY_TYPES.attempt]: ShieldAlert,
   [REVISION_ENTRY_TYPES.machine]: Bot,
+  [REVISION_ENTRY_TYPES.restored]: Undo2,
 };
 
-function entryType(sitting: RevisionSitting): string {
+/** The timeline entry type for a sitting. Exported so the cross-record feed
+ *  (RecordActivityPanel) icons a row exactly as this panel does. */
+export function revisionEntryType(sitting: RevisionSitting): string {
   if (sitting.isAttempt) return REVISION_ENTRY_TYPES.attempt;
+  if (sitting.restoredFrom !== undefined) return REVISION_ENTRY_TYPES.restored;
   if (sitting.action === 'created') return REVISION_ENTRY_TYPES.created;
   if (sitting.actorKind === 'machine') return REVISION_ENTRY_TYPES.machine;
   if (Object.keys(sitting.changed).length === 0 && sitting.name) {
@@ -102,10 +132,12 @@ function entryType(sitting: RevisionSitting): string {
   return REVISION_ENTRY_TYPES.updated;
 }
 
+export const REVISION_ENTRY_ICONS = DEFAULT_ICONS;
+
 /** The version this sitting spans. Shown because `version` is the chain's own
  *  gapless sequence, which is the only thing a reader (or a later span-blame
  *  pass) can use to tell a complete trail from a lossy one. */
-function versionNote(sitting: RevisionSitting): string {
+export function versionNote(sitting: RevisionSitting): string {
   return sitting.fromVersion === sitting.toVersion
     ? `v${sitting.toVersion}`
     : `v${sitting.fromVersion}–v${sitting.toVersion}`;
@@ -154,6 +186,38 @@ export interface RecordHistoryPanelProps {
   historyEnabled?: boolean;
   /** The sentence shown when {@link historyEnabled} is `false`. */
   declaredOffNote?: ReactNode;
+  /** Narrow the trail to one field — `?field=` on the read (bd startsim-jkkn7.8).
+   *  What `FieldAttribution` opens. A narrowed panel offers no whole-record
+   *  restore: the narrowed read misses name changes and held-back attempts
+   *  (bd startsim-jkkn7.18), so a preview over it would be partial. */
+  field?: string;
+  /** "Show all fields" while narrowed. Omit to hide the control. */
+  onClearField?: () => void;
+  /** Narrow from inside a row ("only this field's history"). Omit to hide. */
+  onNarrowToField?: (field: string) => void;
+  /** The version the HOST holds for this record — what a restore asserts. A
+   *  function is read at confirm time, so a draft editor can pass its live
+   *  conditional-save version and an autosave between opening the dialog and
+   *  confirming it does not turn the restore into a 412 against the reviewer's
+   *  own save. Falls back to the newest loaded revision on an unnarrowed trail. */
+  currentVersion?: number | (() => number | undefined);
+  /** Whether the viewer may write this record. Restore is offered only when the
+   *  client has `restore` AND this is not `false`. */
+  canRestore?: boolean;
+  /**
+   * Runs before the restore is sent, and BEFORE `currentVersion` is read — the
+   * host's chance to stop pending autosaves and flush unsaved typing, so nothing
+   * lands after the restore with the old text and nothing typed is lost. May
+   * return a cleanup, run once the restore has settled either way (success,
+   * refusal or 412). THROWING ABORTS the restore with the error's message: a
+   * flush that was itself refused must not be followed by a restore.
+   */
+  beforeRestore?: () => void | (() => void) | Promise<void | (() => void)>;
+  /** After a restore landed. The host reloads its own state (an editor's local
+   *  copy) from `outcome.record`; the panel re-reads its trail itself. */
+  onRestored?: (outcome: Extract<ParsedRestoreOutcome, { kind: 'restored' }>) => void | Promise<void>;
+  /** "this draft", "this topic" — for the confirm and stale dialogs. */
+  recordLabel?: string;
   /** An extra caveat under the trail, for a host that knows something about
    *  this record's coverage the panel cannot. None by default: since bd
    *  startsim-jkkn7.6 every write path records, and a standing "some edits may
@@ -185,23 +249,183 @@ export function RecordHistoryPanel({
   declaredOffNote =
     'History is not recorded for this kind of record — it has been switched off for this type, so new edits do not appear here.',
   incompleteNote = null,
+  field,
+  onClearField,
+  onNarrowToField,
+  currentVersion,
+  canRestore,
+  beforeRestore,
+  onRestored,
+  recordLabel = 'this record',
   classNames = {},
 }: RecordHistoryPanelProps) {
   const cx = { ...RECORD_HISTORY_PANEL_DEFAULTS, ...classNames };
-  const declaredOff = historyEnabled === false;
+  const queryClient = useQueryClient();
 
   const query = useInfiniteQuery<RevisionPage>({
-    queryKey: [...queryKey, { pageSize, windowMs }],
-    queryFn: ({ pageParam }) => client.list({ page: pageParam as number, pageSize }),
+    queryKey: [...queryKey, { pageSize, windowMs, field: field ?? null }],
+    queryFn: ({ pageParam }) =>
+      client.list({ page: pageParam as number, pageSize, ...(field ? { field } : {}) }),
     initialPageParam: 1,
     getNextPageParam: (last, all) => (last?.next ? all.length + 1 : undefined),
   });
 
+  // The host's word wins; otherwise the envelope's resolved policy
+  // (bd startsim-jkkn7.17). Absent from both says nothing.
+  const envelopePolicy = query.data?.pages?.[0]?.history;
+  const declaredOff = (historyEnabled ?? envelopePolicy?.enabled) === false;
+
   const revisions = useMemo<EntityRevision[]>(
     () => (query.data?.pages ?? []).flatMap((p) => p?.results ?? []),
     [query.data],
   );
 
+  /* ------------------------------------------------------------------ */
+  /*  RESTORE                                                            */
+  /* ------------------------------------------------------------------ */
+
+  const restoreEnabled = typeof client.restore === 'function' && canRestore !== false;
+  const latest = useMemo(() => latestFieldVersions(revisions), [revisions]);
+  const newestLoaded = useMemo(
+    () => normalizeRevision(newestRevision(revisions) ?? { id: '', version: 0 }).version,
+    [revisions],
+  );
+
+  const [pending, setPending] = useState<{ target: number; fields?: string[] } | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [restoreError, setRestoreError] = useState<string | null>(null);
+  const [conflict, setConflict] = useState<StaleSaveConflict | null>(null);
+  const [done, setDone] = useState<string | null>(null);
+  /** The request a 412 refused, kept so "restore anyway" re-sends exactly it. */
+  const refused = useRef<RestoreRequest | null>(null);
+  const inFlight = useRef(false);
+
+  const preview = useMemo<RestorePreview | null>(
+    () =>
+      pending
+        ? restorePreview(revisions, pending.target, {
+            ...(pending.fields ? { fields: pending.fields } : {}),
+            narrowed: !!field,
+          })
+        : null,
+    [pending, revisions, field],
+  );
+
+  const heldVersion = useCallback((): number | undefined => {
+    const held = typeof currentVersion === 'function' ? currentVersion() : currentVersion;
+    if (typeof held === 'number' && Number.isInteger(held)) return held;
+    // Only an UNNARROWED trail's newest row is the record's current version.
+    return field ? undefined : newestLoaded || undefined;
+  }, [currentVersion, field, newestLoaded]);
+
+  const refresh = useCallback(
+    () => queryClient.invalidateQueries({ queryKey: [...queryKey] }),
+    [queryClient, queryKey],
+  );
+
+  const send = useCallback(
+    async (request: RestoreRequest) => {
+      if (!client.restore || inFlight.current) return;
+      inFlight.current = true;
+      setBusy(true);
+      setRestoreError(null);
+      let outcome: unknown;
+      try {
+        outcome = await client.restore(request);
+      } catch (error) {
+        outcome = error;
+      }
+      const parsed = parseRestoreOutcome(outcome);
+      try {
+        if (parsed.kind === 'restored') {
+          setPending(null);
+          setConflict(null);
+          refused.current = null;
+          const moved = parsed.summary.fields;
+          const from = `v${parsed.summary.restoredFrom ?? request.version}`;
+          setDone(
+            parsed.summary.revision === null
+              ? `Nothing to restore — already as it was at ${from}.`
+              : `Restored ${moved.length ? moved.map(fieldLabel).join(', ') : 'the record'} from ${from}, saved as v${parsed.summary.revision}.`,
+          );
+          await onRestored?.(parsed);
+          await refresh();
+        } else if (parsed.kind === 'stale') {
+          // NOT retried. The record moved since the version the host holds; a
+          // person decides, in the same dialog an editor's stale save uses.
+          setPending(null);
+          refused.current = request;
+          const next: StaleSaveConflict = {
+            ...(parsed.currentVersion !== undefined ? { currentVersion: parsed.currentVersion } : {}),
+            ...(parsed.detail ? { detail: parsed.detail } : {}),
+            sentVersion: request.expectedVersion,
+            refusedBody: { ...request },
+          };
+          setConflict(next);
+          try {
+            const page = await client.list({ page: 1, pageSize: 1 });
+            const row = newestRevision(page?.results);
+            setConflict((cur) =>
+              cur === next
+                ? row
+                  ? { ...cur, changedBy: normalizeRevision(row) }
+                  : { ...cur, identityGap: 'empty' }
+                : cur,
+            );
+          } catch {
+            setConflict((cur) => (cur === next ? { ...cur, identityGap: 'error' } : cur));
+          }
+        } else {
+          setRestoreError(parsed.message);
+        }
+      } finally {
+        inFlight.current = false;
+        setBusy(false);
+      }
+    },
+    [client, fieldLabel, onRestored, refresh],
+  );
+
+  const confirmRestore = useCallback(async () => {
+    if (!pending || inFlight.current) return;
+    let cleanup: void | (() => void);
+    setBusy(true);
+    try {
+      cleanup = await beforeRestore?.();
+    } catch (error) {
+      setBusy(false);
+      setRestoreError(
+        (error instanceof Error && error.message) ||
+          'Your unsaved edits could not be saved first, so nothing was restored.',
+      );
+      return;
+    }
+    try {
+      // Read AFTER the host flushed: its version may have just advanced.
+      const expectedVersion = heldVersion();
+      if (expectedVersion === undefined) {
+        setBusy(false);
+        setRestoreError(
+          'The current version of this record is not known here, so a restore cannot be checked against it. Reload and try again.',
+        );
+        return;
+      }
+      await send({
+        version: pending.target,
+        ...(pending.fields ? { fields: pending.fields } : {}),
+        expectedVersion,
+      });
+    } finally {
+      if (typeof cleanup === 'function') cleanup();
+    }
+  }, [pending, heldVersion, beforeRestore, send]);
+
+  const openRestore = useCallback((target: number, fields?: string[]) => {
+    setRestoreError(null);
+    setDone(null);
+    setPending({ target, ...(fields ? { fields } : {}) });
+  }, []);
+
   // THE FOLD RUNS OVER THE ACCUMULATION, never per page. See the header.
   const sittings = useMemo(() => foldRevisions(revisions, windowMs), [revisions, windowMs]);
 
@@ -209,7 +433,7 @@ export function RecordHistoryPanel({
     () =>
       sittings.map((sitting) => ({
         id: sitting.id,
-        type: entryType(sitting),
+        type: revisionEntryType(sitting),
         title: sittingHeadline(sitting, fieldLabel),
         occurredAt: sitting.at,
         actor: { email: sitting.actorLabel || undefined, id: sitting.actorSub || undefined },
@@ -221,9 +445,26 @@ export function RecordHistoryPanel({
         tone: sitting.isAttempt ? 'warn' : undefined,
         subtitle: versionNote(sitting),
         note: sitting.saves > 1 ? sittingSummary(sitting) : undefined,
-        detail: <RevisionFields sitting={sitting} fieldLabel={fieldLabel} />,
+        detail: (
+          <RevisionFields
+            sitting={sitting}
+            fieldLabel={fieldLabel}
+            {...(onNarrowToField && !field ? { onNarrowToField } : {})}
+            {...(restoreEnabled && !sitting.isAttempt
+              ? {
+                  // Only where a later row moved the field: on the row whose
+                  // value IS the current one, a restore changes nothing.
+                  canRestoreField: (f: string) => (latest[f] ?? -1) > sitting.toVersion,
+                  onRestoreField: (f: string) => openRestore(sitting.toVersion, [f]),
+                  ...(!field && sitting.toVersion < newestLoaded
+                    ? { onRestoreVersion: () => openRestore(sitting.toVersion) }
+                    : {}),
+                }
+              : {})}
+          />
+        ),
       })),
-    [sittings, fieldLabel],
+    [sittings, fieldLabel, restoreEnabled, latest, field, newestLoaded, openRestore, onNarrowToField],
   );
 
   // Sentence 1 — only when some loaded row really is unknown, so a tenant past
@@ -267,6 +508,30 @@ export function RecordHistoryPanel({
         {headerAside}
       </div>
 
+      {field && (
+        <p className={cx.notice} data-testid="record-history-narrowed">
+          Showing changes to <code className="rounded bg-muted px-1 text-foreground">{fieldLabel(field)}</code>{' '}
+          only.{' '}
+          {onClearField && (
+            <button
+              type="button"
+              data-testid="record-history-clear-field"
+              onClick={onClearField}
+              className="inline-flex items-center gap-0.5 underline underline-offset-2 hover:text-foreground"
+            >
+              <X className="h-3 w-3" aria-hidden="true" />
+              Show all fields
+            </button>
+          )}
+        </p>
+      )}
+
+      {done && (
+        <p className={cx.notice} role="status" data-testid="restore-done">
+          {done}
+        </p>
+      )}
+
       {anyUnknownKind && (
         <p className={cx.notice} data-testid="record-history-unknown-kind">
           Entries marked <strong className="font-medium text-foreground">machine</strong> were
@@ -334,6 +599,57 @@ export function RecordHistoryPanel({
           {incompleteNote}
         </p>
       )}
+
+      {restoreEnabled && (
+        <>
+          <RestoreConfirmDialog
+            open={pending !== null}
+            preview={preview}
+            {...(pending?.fields ? { fields: pending.fields } : {})}
+            recordLabel={recordLabel}
+            fieldLabel={fieldLabel}
+            busy={busy}
+            error={restoreError}
+            onConfirm={() => void confirmRestore()}
+            onCancel={() => {
+              setPending(null);
+              setRestoreError(null);
+            }}
+          />
+          <StaleSaveDialog
+            conflict={conflict}
+            open={conflict !== null}
+            recordLabel={recordLabel}
+            whilePhrase="after you opened its history"
+            reassurance="Nothing was restored. Restoring now would replace their change too."
+            dismissLabel="Cancel"
+            reviewLabel="See what changed"
+            keepMineLabel="Restore anyway, replacing their change"
+            busy={busy}
+            fieldLabel={fieldLabel}
+            onDismiss={() => {
+              setConflict(null);
+              refused.current = null;
+            }}
+            onReviewChange={() => {
+              setConflict(null);
+              refused.current = null;
+              void refresh();
+            }}
+            // The ONLY path that adopts the version the refusal named — a person
+            // has been shown who changed it and chose to replace it anyway.
+            {...(conflict?.currentVersion !== undefined
+              ? {
+                  onKeepMine: () => {
+                    const request = refused.current;
+                    if (!request || conflict?.currentVersion === undefined) return;
+                    void send({ ...request, expectedVersion: conflict.currentVersion });
+                  },
+                }
+              : {})}
+          />
+        </>
+      )}
     </section>
   );
 }

package/src/components/history/RestoreConfirmDialog.tsx

@@ -0,0 +1,244 @@
+'use client';
+
+/**
+ * RestoreConfirmDialog — "this is what will change", before anything is written
+ * (bd startsim-zkyk4).
+ *
+ * A restore is an ordinary new write that REPLACES whatever the field holds now —
+ * often somebody else's text, which is the very case restore exists for. So the
+ * dialog never asks "are you sure?" in the abstract: it shows each field that
+ * would move, from its current value to the restored one, with the same line
+ * diff the history rows use, and it names the two cases where the honest answer
+ * is "nothing to restore" or "we cannot say".
+ *
+ * Pure — no fetching, no react-query — like StaleSaveDialog beside it. The panel
+ * computed the preview from the trail it already holds ({@link restorePreview}),
+ * and owns the call.
+ */
+import { useEffect, useRef, type ReactNode } from 'react';
+
+import { DiffViewer } from '../diff';
+import type { RestorePreview, RestoreSide } from './restore';
+import { unifiedTextDiff } from './text-diff';
+import {
+  STALE_SAVE_DIALOG_DEFAULTS,
+  type StaleSaveDialogClassNames,
+} from './stale-save-dialog-default-class-names';
+
+export interface RestoreConfirmDialogProps {
+  open: boolean;
+  preview: RestorePreview | null;
+  /** The field being restored, or undefined for the whole record. */
+  fields?: string[];
+  recordLabel?: string;
+  fieldLabel?: (field: string) => string;
+  busy?: boolean;
+  /** The server's sentence for a refusal other than 412. */
+  error?: string | null;
+  onConfirm: () => void;
+  onCancel: () => void;
+  children?: ReactNode;
+  /** Shares the stale-save dialog's chrome, so the two modals read as one family. */
+  classNames?: StaleSaveDialogClassNames;
+}
+
+function text(side: RestoreSide): string {
+  if (!side.has) return '';
+  const v = side.value;
+  if (typeof v === 'string') return v;
+  if (v === null) return 'null';
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}
+
+function Side({ label, side }: { label: string; side: RestoreSide }) {
+  return (
+    <div className="min-w-0">
+      <div className="mb-1 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">{label}</div>
+      {side.has ? (
+        <pre className="max-h-32 overflow-y-auto whitespace-pre-wrap break-words rounded border border-border bg-muted/40 p-2 font-mono text-xs">
+          {text(side)}
+        </pre>
+      ) : (
+        <p className="rounded border border-dashed border-border p-2 text-xs text-muted-foreground">
+          <span aria-hidden="true">—</span> not set
+        </p>
+      )}
+    </div>
+  );
+}
+
+export function RestoreConfirmDialog({
+  open,
+  preview,
+  fields,
+  recordLabel = 'this record',
+  fieldLabel = (f) => f,
+  busy = false,
+  error,
+  onConfirm,
+  onCancel,
+  children,
+  classNames,
+}: RestoreConfirmDialogProps) {
+  const css = { ...STALE_SAVE_DIALOG_DEFAULTS, ...classNames };
+  const cancelRef = useRef<HTMLButtonElement | null>(null);
+  const visible = open && preview !== null;
+
+  useEffect(() => {
+    if (!visible) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && !busy) onCancel();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [visible, busy, onCancel]);
+
+  // Focus lands on Cancel — the control that cannot write.
+  useEffect(() => {
+    if (visible) cancelRef.current?.focus();
+  }, [visible]);
+
+  if (!visible || !preview) return null;
+
+  const target = `v${preview.target}`;
+  const what = fields?.length
+    ? fields.map(fieldLabel).join(', ')
+    : recordLabel;
+  const blocked = preview.unknowable.length > 0;
+  const count = preview.changes.length + (preview.name ? 1 : 0);
+
+  return (
+    <div
+      className={css.backdrop}
+      data-testid="restore-confirm-backdrop"
+      onClick={(event) => {
+        if (event.target === event.currentTarget && !busy) onCancel();
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="restore-confirm-title"
+        className={`${css.dialog} max-w-2xl`}
+        data-testid="restore-confirm-dialog"
+      >
+        <div className={css.header}>
+          <h2 id="restore-confirm-title" className={css.title}>
+            Restore {what} to how it was at {target}?
+          </h2>
+          <p className={css.reassurance}>
+            {preview.noop
+              ? `Nothing would change — ${fields?.length ? 'this value is' : 'the record is'} already as it was at ${target}.`
+              : `This saves a new version. Nothing is deleted: the current ${count === 1 ? 'value stays' : 'values stay'} in the history and can be restored again.`}
+          </p>
+        </div>
+
+        <div className={`${css.body} max-h-[60vh] overflow-y-auto`}>
+          {!preview.complete && (
+            <p className={css.notice} data-testid="restore-incomplete">
+              Not every change since {target} is loaded here, so this list may be incomplete. The
+              server works out the restore from the full history.
+            </p>
+          )}
+
+          {preview.changes.map((change) => {
+            const diffable =
+              change.current.has &&
+              change.restored.has &&
+              typeof change.current.value === 'string' &&
+              typeof change.restored.value === 'string';
+            return (
+              <section
+                key={change.field}
+                className="@container space-y-2"
+                data-testid={`restore-preview-${change.field}`}
+              >
+                <h3 className="text-xs font-medium text-foreground">
+                  <code className="rounded bg-muted px-1">{fieldLabel(change.field)}</code>
+                  {!change.restored.has && (
+                    <span className="ms-2 text-muted-foreground">will be cleared</span>
+                  )}
+                </h3>
+                <div className="grid gap-3 @sm:grid-cols-2">
+                  <Side label="Now" side={change.current} />
+                  <Side label={`After restore (${target})`} side={change.restored} />
+                </div>
+                {diffable && (
+                  <DiffViewer
+                    diff={unifiedTextDiff(
+                      String(change.current.value),
+                      String(change.restored.value),
+                      change.field,
+                    )}
+                    emptyLabel="No line-level change"
+                    className="max-h-56 overflow-auto rounded border border-border"
+                  />
+                )}
+              </section>
+            );
+          })}
+
+          {preview.name && (
+            <section className="@container space-y-2" data-testid="restore-preview-name">
+              <h3 className="text-xs font-medium text-foreground">name (title)</h3>
+              <div className="grid gap-3 @sm:grid-cols-2">
+                <Side label="Now" side={preview.name.current} />
+                <Side label={`After restore (${target})`} side={preview.name.restored} />
+              </div>
+            </section>
+          )}
+
+          {preview.withheld.length > 0 && (
+            <p className={css.notice} data-testid="restore-withheld">
+              Left as they are: {preview.withheld.map(fieldLabel).join(', ')} — your access does
+              not include reading {preview.withheld.length === 1 ? 'that field' : 'those fields'}, so
+              a restore does not touch {preview.withheld.length === 1 ? 'it' : 'them'}.
+            </p>
+          )}
+
+          {blocked && (
+            <p className={css.notice} data-testid="restore-unknowable">
+              The history stored only part of {preview.unknowable.map(fieldLabel).join(', ')} after{' '}
+              {target}, so its value then is not known exactly and cannot be restored.
+              {fields?.length ? '' : ' Restore the other fields one at a time instead.'}
+            </p>
+          )}
+
+          {error && (
+            <p role="alert" className="text-sm text-foreground" data-testid="restore-error">
+              {error}
+            </p>
+          )}
+
+          {children}
+        </div>
+
+        <div className={css.footer}>
+          <button
+            type="button"
+            ref={cancelRef}
+            className={css.secondaryAction}
+            data-testid="restore-cancel"
+            disabled={busy}
+            onClick={onCancel}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            className={css.primaryAction}
+            data-testid="restore-confirm"
+            disabled={busy || preview.noop || blocked}
+            onClick={onConfirm}
+          >
+            {busy ? 'Restoring…' : fields?.length ? 'Restore this value' : 'Restore this version'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}