@gogitcms/design-system 0.16.0-next.1 → 0.16.0-next.11

package/src/components/ContentBrowser.tsx

@@ -6,7 +6,7 @@ import { Text } from "./Text";
 import { Icon } from "./Icon";
 import { Button, IconButton } from "./Button";
 import { Input } from "./Input";
-import { Avatar, Badge, DiffStat, Divider, SectionLabel } from "./primitives";
+import { Avatar, Badge, CheckBox, DiffStat, Divider, SectionLabel } from "./primitives";
 import { NavRow } from "./NavRow";
 import { AppShell, MobileScreen, Pane, TopBar, ThemeToggle } from "./layout";
 import { Segment, type SegmentItem } from "./Segment";
@@ -15,6 +15,7 @@ import { BranchMenu, type BranchRef } from "./BranchMenu";
 import { ProjectMenu, type ProjectRef } from "./ProjectMenu";
 import { ChangeDetail, type DocumentChange, type FieldConflict, type ConflictChoice } from "./ChangeDetail";
 import { ApplyChangesModal, type MergeProgress } from "./ApplyChangesModal";
+import { ProtectedBranchModal } from "./ProtectedBranchModal";
 import { NotificationBell, type NotificationItem } from "./Notifications";
 import {
   CollabInput,
@@ -22,6 +23,7 @@ import {
   PresenceField,
   PresenceAvatars,
   useCollabRegister,
+  writeCollabValue,
   useCollabMirror,
   useCollabSynced,
   useCollabValue,
@@ -29,15 +31,21 @@ import {
   useCollabPeersUnder,
 } from "./CollabField";
 import { clamp, reorder, slotAtX } from "./reorder";
-import { MediaField, MediaProvider, DocumentPathProvider } from "./MediaField";
+import { MediaField, MediaProvider, DocumentPathProvider, useFieldMedia } from "./MediaField";
+import { ReferenceField, ReferenceProvider } from "./ReferenceField";
+import { DocumentDetails } from "./DocumentDetails";
+import type { ReferenceApi, ReferenceDef } from "../references";
 import { MediaBrowser } from "./MediaBrowser";
 import { FormsBrowser } from "./FormsBrowser";
 import { FORMS_NAV_KEY, formsNavKey, isFormsNavKey, parseFormsNavKey, type FormsApi } from "../forms";
+import { type HistoryApi } from "../history";
+import { DocumentHistory } from "./DocumentHistory";
 import {
   MEDIA_NAV_KEY,
   mediaNavKey,
   isMediaNavKey,
   parseMediaNavKey,
+  type FieldMediaApi,
   type MediaApi,
   type MediaSetInfo,
   type StoreAs,
@@ -71,6 +79,12 @@ export type EntryField = {
   // field these describe its *items*, making each one a media picker.
   media?: string;
   storeAs?: string;
+  // For a document picker (`component: "reference"`, or an array whose items
+  // are references): what the field points at and stores. An object-shaped
+  // reference's `fields` are the derived children — the key child and the
+  // embedded copies — which the server recomputes on every save and the
+  // editor shows read-only (docs/references.md).
+  reference?: ReferenceDef;
   value: unknown;
   // Item type for an array field (string | number | boolean | object).
   of?: string;
@@ -111,6 +125,16 @@ export type FieldSlotArgs = {
   // CRDT and publish presence.
   collab?: CollabApi;
   path?: string;
+  // Bumped when the host replaces this field's value outright rather than the
+  // user editing it — restoring it from a past version. A controlled control
+  // needs nothing from this (it already re-renders with the new value), but the
+  // body editor does: in a live session it ignores `value` and mirrors the
+  // shared fragment, so "the value changed" is not a thing it can observe.
+  resetNonce?: number;
+  // Media access scoped to this field — open the picker, resolve the paths the
+  // document holds — so a host control can embed and display images from the
+  // media library. Absent when the host provides no media api.
+  media?: FieldMediaApi;
 };
 export type RenderField = (args: FieldSlotArgs) => React.ReactNode;
 
@@ -326,6 +350,15 @@ export type ContentBrowserProps = {
   // already separated from the frontmatter.
   onEntryDraft?: (draft: EntrySaveChange, entry: CmsEntry) => void;
 
+  // Which field of an open document has keyboard focus, as the author moves
+  // between controls: the field's dotted path (`title`, `seo.description`,
+  // `blocks.0.heading`), or null when nothing in that document is focused.
+  // Web only — it reads the DOM's focus events. This is what lets a preview
+  // ring the part of the page the author is editing (§4.4 of the preview
+  // design), and it is separate from live collaboration: a lone author gets
+  // it too.
+  onFieldFocus?: (entryId: string, path: string | null) => void;
+
   // Optional per-field renderer. When it returns a node for a field, that node
   // replaces the built-in control (used to inject the markdown body editor).
   renderField?: RenderField;
@@ -336,9 +369,22 @@ export type ContentBrowserProps = {
   // store gets.
   media?: MediaApi;
 
+  // References data seam, the same split (docs/references.md §6): the DS owns
+  // the document picker and the "Referenced by" list, the host owns fetching.
+  // Omitted → reference fields render read-only.
+  references?: ReferenceApi;
+
   // Forms data seam, the same split (docs/forms.md §10.2). Omitted → the Forms
   // surface never renders, which is what a config declaring no forms looks like.
   forms?: FormsApi;
+
+  // Document-history data seam, the same split again: the DS owns the version
+  // browser and its ephemeral state, the host owns fetching. Provided → an open
+  // document's header gains a history button, and pressing it gives that
+  // column's body over to the version browser. Omitted → no affordance at all,
+  // which is what a deployment with no provider (local mode, desktop) gets: a
+  // feature the user never sees beats one that errors when clicked.
+  history?: HistoryApi;
   // The selected submission's id, and the reporter for taps — bound to the URL
   // by the host exactly as document selection is.
   selectedSubmissionId?: string | null;
@@ -465,6 +511,9 @@ export type ContentBrowserProps = {
   canApplyChanges?: boolean;
   applyOpen?: boolean;
   applySummary?: string;
+  // Why applying opens a change request instead of merging (see
+  // ApplyChangesModal.reviewReason). Absent for a direct merge.
+  applyReviewReason?: string;
   applyProgress?: MergeProgress;
   applyConflictCount?: number;
   onConfirmApply?: () => void;
@@ -478,6 +527,19 @@ export type ContentBrowserProps = {
   changeRequestOpen?: boolean;
   changeRequestUrl?: string;
   creatingChangeRequest?: boolean;
+
+  // Protected-branch save prompt. The server refuses a save to a branch the
+  // provider protects; the host catches that, sets protectedBranch to the branch
+  // name, and this modal offers the one thing that resolves it — a branch to put
+  // the edit on. onCreateBranchAndSave receives the name; the host creates the
+  // branch and applies the pending edit to it in one server call.
+  protectedBranch?: string;
+  protectedBranchDocument?: string;
+  protectedBranchSuggestedName?: string;
+  creatingProtectedBranch?: boolean;
+  protectedBranchError?: string | null;
+  onCreateBranchAndSave?: (name: string) => void;
+  onCancelProtectedSave?: () => void;
   onCreateChangeRequest?: (explanation: string) => void;
   onViewChangeRequest?: () => void;
 
@@ -743,8 +805,45 @@ type FieldControlProps = {
   // When this number changes, the field programmatically focuses itself (used to
   // jump to a peer's field from its presence avatar).
   focusSignal?: number;
+  // Bumped when this field's value was replaced by the host rather than typed —
+  // restored from a past version. Only the host-supplied body editor needs it
+  // (see FieldSlotArgs.resetNonce); every built-in control is controlled and
+  // re-renders from `value` on its own.
+  resetNonce?: number;
+  // The field's full dotted path, when the caller knows better than
+  // "parent path + field name" — a list item, whose control is named after
+  // the list but sits at `list.<index>`.
+  fieldPath?: string;
 };
 
+// The dotted path of the field being rendered, for the controls under it:
+// a group's children append their names to it, a list's items append their
+// index. It exists so every control can carry its own path as a DOM
+// attribute (`data-cms-field`) without any of them threading a prop through
+// — the focus reporting in EntryDetail reads that attribute off whichever
+// element the keyboard lands in.
+//
+// Deliberately separate from the collab `path` prop: that one is threaded
+// only where a CRDT binding exists (top-level fields and drilled-in groups),
+// whereas this is present for every field including list items, which the
+// collab layer treats as one register.
+const FieldPathContext = React.createContext<string>("");
+
+function FieldControl(props: FieldControlProps) {
+  const prefix = React.useContext(FieldPathContext);
+  const fullPath = props.fieldPath ?? (prefix ? `${prefix}.${props.field.name}` : props.field.name);
+  return (
+    <FieldPathContext.Provider value={fullPath}>
+      <View
+        // @ts-expect-error react-native-web maps dataSet -> data-* attributes
+        dataSet={{ cmsField: fullPath }}
+      >
+        <FieldControlInner {...props} />
+      </View>
+    </FieldPathContext.Provider>
+  );
+}
+
 // The scalar type an array's `of` maps to when rendering item controls.
 function ofToType(of?: string): string {
   switch (of) {
@@ -755,8 +854,8 @@ function ofToType(of?: string): string {
   }
 }
 
-function FieldControl(props: FieldControlProps) {
-  const { field, value, onChange, renderField, readOnly = false, error, hideLabel, onOpenGroup, collab, path, focusSignal } = props;
+function FieldControlInner(props: FieldControlProps) {
+  const { field, value, onChange, renderField, readOnly = false, error, hideLabel, onOpenGroup, collab, path, focusSignal, resetNonce } = props;
   const t = useTheme();
   const label = hideLabel ? "" : field.label || field.name;
   // A text field participates in live collaboration when the document has a
@@ -767,9 +866,14 @@ function FieldControl(props: FieldControlProps) {
   ) : null;
   const labelNode = label ? <Text variant="label" color="tertiary">{label}</Text> : null;
 
+  // Media for a host-supplied control. The picker element is mounted only when
+  // the slot actually renders this field, so a form full of built-in controls
+  // carries no extra modals.
+  const fieldMedia = useFieldMedia({ set: field.media, storeAs: field.storeAs });
+
   // Host-supplied control (e.g. the markdown editor) takes precedence.
   if (renderField) {
-    const custom = renderField({ field, value, onChange, readOnly, collab: collabText, path });
+    const custom = renderField({ field, value, onChange, readOnly, collab: collabText, path, resetNonce, media: fieldMedia.media });
     if (custom != null && custom !== false) {
       return (
         <View style={{ gap: t.space(2) }}>
@@ -780,6 +884,7 @@ function FieldControl(props: FieldControlProps) {
             custom
           )}
           {errorNode}
+          {fieldMedia.picker}
         </View>
       );
     }
@@ -787,6 +892,28 @@ function FieldControl(props: FieldControlProps) {
 
   const comp = resolveComponent(field);
 
+  // ---- references ----------------------------------------------------------
+  // Like media, one component for two field types: a string stores the key, an
+  // object stores the key plus the server-computed copies. Checked before the
+  // type branches for the same reason media is.
+  if (comp === "reference" && field.reference) {
+    return (
+      <View style={{ gap: t.space(2) }}>
+        {labelNode}
+        <ReferenceField
+          value={value}
+          onChange={onChange}
+          shape={field.type === "object" ? "object" : "string"}
+          def={field.reference}
+          embedFields={field.fields}
+          readOnly={readOnly}
+          error={!!error}
+        />
+        {errorNode}
+      </View>
+    );
+  }
+
   // ---- media ------------------------------------------------------------
   // Checked before the type-specific branches because `media` is the one
   // component valid for two different field types: a string field stores a path,
@@ -1590,13 +1717,19 @@ function ListControl({
     fields: field.fields,
     value: null,
     ...(field.media ? { component: "media", media: field.media, storeAs: field.storeAs } : {}),
+    // An array that declares a reference makes each item a document picker, the
+    // same way an array naming a media set makes each item a media picker.
+    ...(field.reference ? { component: "reference", reference: field.reference } : {}),
   };
 
+  // The list's own path, from the FieldControl wrapping this control; an item
+  // sits at `<list>.<index>`.
+  const listPath = React.useContext(FieldPathContext);
   return (
     <View style={{ gap: t.space(2) }}>
       {items.map((it, i) => (
         <ItemFrame key={i} index={i} count={items.length} readOnly={readOnly || !canRemove} onRemove={() => removeItem(i)} onMove={(d) => moveItem(i, d)}>
-          <FieldControl field={itemField} value={it} onChange={(v) => setItem(i, v)} renderField={renderField} readOnly={readOnly} hideLabel />
+          <FieldControl field={itemField} value={it} onChange={(v) => setItem(i, v)} renderField={renderField} readOnly={readOnly} hideLabel fieldPath={listPath ? `${listPath}.${i}` : String(i)} />
         </ItemFrame>
       ))}
       {!readOnly && canAdd ? (
@@ -1636,15 +1769,25 @@ function MixedListControl({
     onChange(next);
   };
   const addItem = () => onChange([...items, { [key]: variants[0]?.name ?? "" }]);
+  const listPath = React.useContext(FieldPathContext);
 
   return (
     <View style={{ gap: t.space(2) }}>
       {items.map((it, i) => {
         const variantName = String(it?.[key] ?? "");
         const variant = variants.find((v) => v.name === variantName);
+        const itemPath = listPath ? `${listPath}.${i}` : String(i);
         return (
           <ItemFrame key={i} index={i} count={items.length} readOnly={readOnly || !canRemove} onRemove={() => removeItem(i)} onMove={(d) => moveItem(i, d)}>
-            <View style={{ gap: t.space(2) }}>
+            {/* The item's fields compose under `<list>.<index>`; the item
+                itself carries that path so focusing its variant picker
+                reports the item rather than the whole list. */}
+            <FieldPathContext.Provider value={itemPath}>
+            <View
+              style={{ gap: t.space(2) }}
+              // @ts-expect-error react-native-web maps dataSet -> data-* attributes
+              dataSet={{ cmsField: itemPath }}
+            >
               <SelectControl
                 value={variantName}
                 options={variants.map((v) => v.name)}
@@ -1662,6 +1805,7 @@ function MixedListControl({
                 />
               ) : null}
             </View>
+            </FieldPathContext.Provider>
           </ItemFrame>
         );
       })}
@@ -1697,6 +1841,9 @@ function BodyField({
     format: "markdown",
     value,
   };
+  // The schema-less body names no media set; the picker opens on the first
+  // configured one and writes public paths.
+  const fieldMedia = useFieldMedia({});
   // The slot's onChange is unknown-typed (plugin fields may emit any shape);
   // a body control only ever emits markdown strings.
   const custom = renderField?.({
@@ -1704,15 +1851,25 @@ function BodyField({
     value,
     onChange: (v) => onChange(typeof v === "string" ? v : String(v ?? "")),
     readOnly,
+    media: fieldMedia.media,
   });
   return (
-    <View style={{ gap: t.space(2), flex: 1 }}>
+    <View
+      style={{ gap: t.space(2), flex: 1 }}
+      // The schema-less body is the document's one field; a preview rings
+      // it under the same name the schema form would give it.
+      // @ts-expect-error react-native-web maps dataSet -> data-* attributes
+      dataSet={{ cmsField: "body" }}
+    >
       <View style={{ flexDirection: "row", justifyContent: "space-between", alignItems: "center" }}>
         <Text variant="label" color="tertiary">Body</Text>
         <Text variant="monoSm" color="tertiary">Markdown</Text>
       </View>
       {custom != null && custom !== false ? (
-        custom
+        <>
+          {custom}
+          {fieldMedia.picker}
+        </>
       ) : (
         <View
           style={{
@@ -2385,14 +2542,18 @@ function PromptDialog({
   );
 }
 
-// DetailMenu is the "..." menu in the detail header: Rename / Move to folder /
-// Delete, each shown only when its handler is provided. Delete has an inline
-// confirm step; Rename/Move open a PromptDialog owned by EntryDetail.
+// DetailMenu is the "..." menu in the detail header: Details / Rename / Move to
+// folder / Delete, each shown only when its handler is provided. Details is a
+// read (metadata and references, see DocumentDetails) and so is offered on
+// read-only documents too; Delete has an inline confirm step; Rename/Move open
+// a PromptDialog owned by EntryDetail.
 function DetailMenu({
+  onDetails,
   onRename,
   onMove,
   onDelete,
 }: {
+  onDetails?: () => void;
   onRename?: () => void;
   onMove?: () => void;
   onDelete?: () => void;
@@ -2423,6 +2584,12 @@ function DetailMenu({
             borderRadius: t.radius.md, paddingVertical: t.space(1),
           }}
         >
+          {onDetails ? (
+            <Pressable testID="detail-details" onPress={() => { close(); onDetails(); }} style={rowStyle}>
+              <Icon name="fileText" size={15} color={t.color.textSecondary} />
+              <Text variant="sm">Details</Text>
+            </Pressable>
+          ) : null}
           {onRename ? (
             <Pressable testID="detail-rename" onPress={() => { close(); onRename(); }} style={rowStyle}>
               <Icon name="file" size={15} color={t.color.textSecondary} />
@@ -2558,6 +2725,7 @@ function EntryDetail({
   entry,
   documentActions,
   onEntryDraft,
+  onFieldFocus,
   renderField,
   onSaveEntry,
   readOnly = false,
@@ -2565,8 +2733,10 @@ function EntryDetail({
   onDeleteEntry,
   onRename,
   onMove,
+  collection,
   collectionPath,
   folderOptions,
+  history,
   active,
   onActivate,
   onCollapse,
@@ -2579,6 +2749,8 @@ function EntryDetail({
   documentActions?: (entry: CmsEntry) => React.ReactNode;
   // Debounced in-flight draft (see ContentBrowserProps.onEntryDraft).
   onEntryDraft?: (draft: EntrySaveChange, entry: CmsEntry) => void;
+  // The focused field's path, or null (see ContentBrowserProps.onFieldFocus).
+  onFieldFocus?: (entryId: string, path: string | null) => void;
   renderField?: RenderField;
   onSaveEntry?: SaveEntry;
   readOnly?: boolean;
@@ -2586,9 +2758,15 @@ function EntryDetail({
   onDeleteEntry?: (entry: CmsEntry) => Promise<void> | void;
   onRename?: (entry: CmsEntry, filename: string) => Promise<void> | void;
   onMove?: (entry: CmsEntry, folder: string) => Promise<void> | void;
+  // The collection the document belongs to, shown in its Details.
+  collection?: string;
   collectionPath?: string;
   // Existing folders (relative to the glob base) offered by the move autocomplete.
   folderOptions?: string[];
+  // The document-history seam. Provided → a history button appears in this
+  // document's header and its column can show the version browser. Omitted →
+  // the header renders exactly as it did before history existed.
+  history?: HistoryApi;
   // Desktop columns: `active` marks the focused column (accent + header press
   // activates it via onActivate); onCollapse/onClose add the header rail/close
   // controls. All omitted on mobile → unchanged single-detail behavior.
@@ -2609,6 +2787,36 @@ function EntryDetail({
   const canRename = !readOnly && !!onRename;
   const canMove = !readOnly && !!onMove && glob.hierarchical;
   const [prompt, setPrompt] = useState<"rename" | "move" | null>(null);
+  // The Details modal: metadata and references, opened from the menu.
+  const [showDetails, setShowDetails] = useState(false);
+  // A header action that failed — a delete refused because other documents
+  // reference this one — reported inline, where the Delete was pressed.
+  const [actionError, setActionError] = useState<string | null>(null);
+  const deleteEntry = onDeleteEntry
+    ? () => {
+        setActionError(null);
+        Promise.resolve(onDeleteEntry(entry)).catch((e: unknown) => {
+          setActionError(e instanceof Error ? e.message : "Couldn’t delete the document.");
+        });
+      }
+    : undefined;
+  // Per-field "your value was replaced" counters, bumped by a restore. Only the
+  // host-supplied body editor reads them (see FieldSlotArgs.resetNonce); every
+  // built-in control is controlled and needs no telling.
+  const [resetNonces, setResetNonces] = useState<Record<string, number>>({});
+
+  // Whether this column is showing the version browser instead of the form.
+  // Deliberately per-column and ephemeral: history is something you open, read
+  // and close, so it lives and dies with the column rather than in the URL.
+  const [showHistory, setShowHistory] = useState(false);
+  // A column reused for another document (the "preview tab" behavior) must not
+  // carry the previous document's history view onto it — you asked to see that
+  // document, not this one's past.
+  const historyFor = useRef(entry.id);
+  if (historyFor.current !== entry.id) {
+    historyFor.current = entry.id;
+    if (showHistory) setShowHistory(false);
+  }
 
   // Both branches share one value map. The title+body branch is modeled as a
   // single body-source field so autosave logic is uniform.
@@ -2791,6 +2999,112 @@ function EntryDetail({
     [commit],
   );
 
+  // Publish a value map the form did NOT arrive at by typing — a restore from a
+  // past version, or a discard back to the saved document.
+  //
+  // Both used to write local state and stop there, which is only half the job in
+  // a live session. The shared document is the source of truth there: every
+  // collab control prefers its binding to the value handed to it, so a replaced
+  // value was displayed for one frame and then overwritten by the room's
+  // unchanged one, and no peer ever saw it. Anything that replaces values
+  // wholesale has to come through here.
+  //
+  // `names` are the fields whose values were replaced; unchanged ones are left
+  // alone so a replacement never churns the room (or nudges a peer's cursor)
+  // over a value that did not move.
+  const publishReplacement = useCallback(
+    (previous: Record<string, unknown>, next: Record<string, unknown>, names: string[]) => {
+      const moved = names.filter((name) => !sameValue(previous[name], next[name]));
+      if (moved.length === 0) return;
+
+      if (entry.collab) {
+        for (const name of moved) {
+          // A body is a ProseMirror fragment rather than a field binding, so it
+          // is not written here — its editor is told instead, by the nonce below.
+          if (editFields.find((f) => f.name === name)?.source === "body") continue;
+          writeCollabValue(entry.collab, name, previous[name], next[name]);
+        }
+      }
+
+      // Tell the replaced fields their value came from outside. Keyed per field
+      // rather than one counter for the document: the body editor acts on this,
+      // and replacing some unrelated field must not make it rebuild a body a
+      // peer may be mid-sentence in.
+      setResetNonces((prev) => {
+        const bumped = { ...prev };
+        for (const name of moved) bumped[name] = (bumped[name] ?? 0) + 1;
+        return bumped;
+      });
+    },
+    // editFields is derived from entry, captured by id.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [entry.id, entry.collab],
+  );
+
+  // Values taken from a past version and put back into the form.
+  //
+  // It is an edit like any other: the restored fields land in `values`, the
+  // document goes unsaved, and the author saves it (or discards it) themselves.
+  // Nothing is written to git here — history is a place you read, and rewriting
+  // the document from it should still pass through the same review a typed edit
+  // does.
+  const restoreValues = useCallback(
+    (restored: { fields: Record<string, unknown>; body?: string | null }) => {
+      const previous = valuesRef.current;
+      const next = { ...previous, ...restored.fields };
+      // The body is a field in the form like any other; which one it is comes
+      // from the schema (`source: "body"`), the same mapping buildChange uses in
+      // the other direction. A document whose model has no body field simply
+      // has no body to restore.
+      const bodyField = "body" in restored ? editFields.find((f) => f.source === "body") : undefined;
+      if (bodyField) next[bodyField.name] = restored.body ?? "";
+
+      const replaced = Object.keys(restored.fields);
+      if (bodyField) replaced.push(bodyField.name);
+
+      // Touched under the first restored name so a restore that leaves a
+      // required field empty shows its error immediately, rather than looking
+      // saveable until Save is pressed.
+      //
+      // Committed BEFORE publishing: a collab control observing the room echoes
+      // what it sees back through onChange, and that echo builds its next map by
+      // spreading the current one. Publishing first would have it spread the
+      // pre-restore map.
+      commit(next, replaced[0] ?? SYNTHETIC_BODY);
+      publishReplacement(previous, next, replaced);
+      // Drilled-into groups address the pre-restore shape; a restored group
+      // object can have different children entirely.
+      setGroupPath([]);
+    },
+    // editFields is derived from entry, which commit already captures by id.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [commit, entry.id, publishReplacement],
+  );
+
+  // Throw away everything unsaved and go back to the document as stored.
+  //
+  // In a live session that is a change to the ROOM, not just to this screen: the
+  // unsaved work is the collective state every client is looking at, and a
+  // discard that only reverted the local form would leave the document it just
+  // claimed to restore sitting in the CRDT, ready to come straight back.
+  const discardEdits = useCallback(() => {
+    const previous = valuesRef.current;
+    const restored = seed();
+    valuesRef.current = restored;
+    setValues(restored);
+    setTouched({});
+    // The preview is rendering the draft being thrown away, and nothing else
+    // will tell it otherwise: it is fed from edits, and a discard is the one
+    // change to a document that produces no edit. Without this the preview
+    // keeps showing work the author just deleted, until they type again.
+    emitDraft(buildChange(entry.id, editFields, restored), entry);
+    discard();
+    publishReplacement(previous, restored, editFields.map((f) => f.name));
+    setGroupPath([]);
+    // seed/editFields derive from entry, captured by id.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [entry.id, discard, emitDraft, publishReplacement]);
+
   // A field edit within the active group-drill frame: write the value at the
   // frame's nested path, then commit the whole map (buildChange serializes it).
   const changeInFrame = useCallback(
@@ -2805,8 +3119,54 @@ function EntryDetail({
   // The field list + nested value object for the active frame.
   const frame = resolveFrame(editFields, values, groupPath);
 
+  // Which field has the keyboard. One pair of DOM focus listeners on the
+  // column rather than an onFocus on every control: the controls are many
+  // (inputs, selects, the ProseMirror body, plugin fields) and every one of
+  // them renders inside the FieldControl wrapper that carries the path as
+  // `data-cms-field` — so the element the focus landed in is enough.
+  //
+  // focusout fires before the next focusin, so a blur is reported a tick
+  // late and cancelled if focus went straight to another field: moving
+  // between two controls reads as one change, not a flicker through null.
+  const focusRoot = useRef<View>(null);
+  const fieldFocus = useRef(onFieldFocus);
+  fieldFocus.current = onFieldFocus;
+  const entryId = entry.id;
+  useEffect(() => {
+    if (Platform.OS !== "web") return;
+    const node = focusRoot.current as unknown as HTMLElement | null;
+    if (!node || typeof node.addEventListener !== "function") return;
+    let pending: ReturnType<typeof setTimeout> | null = null;
+    let last: string | null = null;
+    const report = (path: string | null) => {
+      if (path === last) return;
+      last = path;
+      fieldFocus.current?.(entryId, path);
+    };
+    const onFocusIn = (ev: Event) => {
+      if (pending) { clearTimeout(pending); pending = null; }
+      const target = ev.target as Element | null;
+      const el = target && typeof target.closest === "function" ? target.closest("[data-cms-field]") : null;
+      report(el?.getAttribute("data-cms-field") || null);
+    };
+    const onFocusOut = () => {
+      if (pending) clearTimeout(pending);
+      pending = setTimeout(() => { pending = null; report(null); }, 0);
+    };
+    node.addEventListener("focusin", onFocusIn);
+    node.addEventListener("focusout", onFocusOut);
+    return () => {
+      node.removeEventListener("focusin", onFocusIn);
+      node.removeEventListener("focusout", onFocusOut);
+      if (pending) clearTimeout(pending);
+      // The column is going away with the field still focused: nothing in
+      // this document has focus any more.
+      if (last !== null) fieldFocus.current?.(entryId, null);
+    };
+  }, [entryId]);
+
   return (
-    <View style={{ flex: 1 }}>
+    <View style={{ flex: 1 }} ref={focusRoot}>
       {/* breadcrumb + actions. position/zIndex lift this row (and the "..." menu
           dropdown it hosts) above the content pane so the menu receives clicks. */}
       <View
@@ -2854,19 +3214,7 @@ function EntryDetail({
         {saveHandler && dirty ? (
           <Pressable
             testID="discard-changes"
-            onPress={() => {
-              const restored = seed();
-              valuesRef.current = restored;
-              setValues(restored);
-              setTouched({});
-              // The preview is rendering the draft that is being thrown away,
-              // and nothing else will tell it otherwise: it is fed from edits,
-              // and a discard is the one change to a document that produces no
-              // edit. Without this the preview keeps showing work the author
-              // just deleted, until they type again.
-              emitDraft(buildChange(entry.id, editFields, restored), entry);
-              discard();
-            }}
+            onPress={discardEdits}
             style={{ paddingHorizontal: t.space(2), paddingVertical: t.space(1) }}
           >
             <Text variant="monoSm" color="tertiary">Discard</Text>
@@ -2894,13 +3242,26 @@ function EntryDetail({
             document's own actions, while the menu holds the destructive and
             path-changing ones that should stay one level down. */}
         {documentActions?.(entry)}
-        {canRename || canMove || (canDelete && onDeleteEntry) ? (
-          <DetailMenu
-            onRename={canRename ? () => setPrompt("rename") : undefined}
-            onMove={canMove ? () => setPrompt("move") : undefined}
-            onDelete={canDelete && onDeleteEntry ? () => onDeleteEntry(entry) : undefined}
+        {/* History is a read of this document, not a change to it, so it sits
+            out here with the other non-destructive actions rather than in the
+            menu beside Delete. It toggles: pressing it again returns the column
+            to the form. */}
+        {history ? (
+          <IconButton
+            name="history"
+            size="sm"
+            active={showHistory}
+            label={showHistory ? "Close history" : "Document history"}
+            onPress={() => setShowHistory((v) => !v)}
+            testID="document-history-toggle"
           />
         ) : null}
+        <DetailMenu
+          onDetails={() => setShowDetails(true)}
+          onRename={canRename ? () => setPrompt("rename") : undefined}
+          onMove={canMove ? () => setPrompt("move") : undefined}
+          onDelete={canDelete && deleteEntry ? deleteEntry : undefined}
+        />
         {onCollapse ? (
           <IconButton name="panelLeft" size="sm" label="Collapse column" onPress={onCollapse} testID="column-collapse" />
         ) : null}
@@ -2909,10 +3270,35 @@ function EntryDetail({
         ) : null}
       </View>
 
-      {/* Keyed by entry.id so controls (incl. the markdown editor) remount with
+      {/* History takes over the column's body, keeping its header: the header
+          is what says which document you are looking at, and it carries the
+          control that got you here and gets you back. */}
+      {showHistory && history ? (
+        <DocumentHistory
+          documentId={entry.id}
+          documentPath={entry.path}
+          history={history}
+          onClose={() => setShowHistory(false)}
+          // Restoring needs somewhere for the values to go: a document that is
+          // read-only, or that this host never wired a save for, gets the
+          // history with no selection boxes at all rather than a form it can
+          // dirty and never save. (saveHandler is already undefined when
+          // readOnly, so this covers both.)
+          onRestore={
+            !saveHandler
+              ? undefined
+              : (restored) => {
+                  restoreValues(restored);
+                  // Back to the form, which is where the restored values now
+                  // are and where the decision to keep them is made.
+                  setShowHistory(false);
+                }
+          }
+        />
+      ) : /* Keyed by entry.id so controls (incl. the markdown editor) remount with
           fresh initial values (and the scroll resets to top) when the selected
-          document changes. The header above stays put; only the body scrolls. */}
-      {hasFields ? (
+          document changes. The header above stays put; only the body scrolls. */
+      hasFields ? (
         // The document's path reaches media fields at any nesting depth through
         // context: a picker inside a group or a list item needs it to interpret
         // relative references, and drilling it through every level would touch
@@ -2925,6 +3311,7 @@ function EntryDetail({
           contentContainerStyle={{ padding: t.space(5), gap: t.space(4) }}
         >
           {saveHandler && error ? <FormAlert message={error} onDismiss={clearError} /> : null}
+          {actionError ? <FormAlert message={actionError} onDismiss={() => setActionError(null)} /> : null}
           {groupPath.length > 0 ? (
             <Pressable
               testID="group-back"
@@ -2935,6 +3322,8 @@ function EntryDetail({
               <Text variant="monoSm" color="tertiary">{frame.labels.join(" / ")}</Text>
             </Pressable>
           ) : null}
+          {/* Drilled into a group, every field's path starts with the group's. */}
+          <FieldPathContext.Provider value={groupPath.join(".")}>
           {frame.fields.map((f) => (
             <FieldControl
               key={f.name}
@@ -2950,13 +3339,19 @@ function EntryDetail({
               collab={entry.collab}
               path={[...groupPath, f.name].join(".")}
               focusSignal={focusTarget && focusTarget.name === f.name ? focusTarget.nonce : undefined}
+              resetNonce={resetNonces[f.name]}
             />
           ))}
+          </FieldPathContext.Provider>
         </ScrollView>
         </DocumentPathProvider>
       ) : (
+        // The body editor resolves the images it embeds relative to this
+        // document, the same way a media field does.
+        <DocumentPathProvider path={entry.path}>
         <View key={entry.id} style={{ padding: t.space(5), gap: t.space(4), flex: 1 }}>
           {saveHandler && error ? <FormAlert message={error} onDismiss={clearError} /> : null}
+          {actionError ? <FormAlert message={actionError} onDismiss={() => setActionError(null)} /> : null}
           <View style={{ gap: t.space(2) }}>
             <Text variant="label" color="tertiary">Title</Text>
             <Text variant="h2">{entry.title}</Text>
@@ -2968,8 +3363,12 @@ function EntryDetail({
             readOnly={readOnly}
           />
         </View>
+        </DocumentPathProvider>
       )}
 
+      {showDetails ? (
+        <DocumentDetails entry={entry} collection={collection} onClose={() => setShowDetails(false)} />
+      ) : null}
       {prompt === "rename" && onRename ? (
         <PromptDialog
           title="Rename file"
@@ -3029,27 +3428,6 @@ function useMultiSelect(resetKey: string) {
   return { checked, toggle, clear, checkedIds, checkedFolders, toggleFolder, checkedFolderKeys };
 }
 
-// CheckBox is the row-selection control for multi-select.
-function CheckBox({ value, onToggle }: { value: boolean; onToggle: () => void }) {
-  const t = useTheme();
-  return (
-    <Pressable
-      // Stop the press from bubbling to the row's open handler (the checkbox
-      // sits inside the row Pressable) so toggling never also opens the entry.
-      onPress={(e?: { stopPropagation?: () => void }) => { e?.stopPropagation?.(); onToggle(); }}
-      testID="entry-checkbox"
-      style={{
-        width: 18, height: 18, borderRadius: t.radius.sm, borderWidth: 1,
-        borderColor: value ? t.color.borderStrong : t.color.borderDefault,
-        backgroundColor: value ? t.color.surfaceInverted : t.color.surfaceRaised,
-        alignItems: "center", justifyContent: "center",
-      }}
-    >
-      {value ? <Icon name="check" size={12} color={t.color.textInverted} /> : null}
-    </Pressable>
-  );
-}
-
 // SelectionBar appears above the entry list when rows are checked; it offers a
 // bulk move and/or delete plus a clear action (each shown only when wired).
 function SelectionBar({ count, onMove, onDelete, onClear }: { count: number; onMove?: () => void; onDelete?: () => void; onClear: () => void }) {
@@ -3093,6 +3471,8 @@ type ColumnModel = {
   canDelete?: boolean;
   canRename: boolean;
   canMove: boolean;
+  // The tab's collection key, for the document's Details.
+  collection?: string;
   collectionPath?: string;
   /** Set for a custom column (see OpenTab.content); `entry` is then unused. */
   content?: React.ReactNode;
@@ -3192,7 +3572,7 @@ function EntriesList({
             <View style={{ flexDirection: "row", alignItems: "center" }}>
               {showChecks ? (
                 <View style={{ paddingLeft: t.space(4) }}>
-                  <CheckBox value={!!checked?.[e.id]} onToggle={() => onToggleEntry?.(e.id)} />
+                  <CheckBox value={!!checked?.[e.id]} onToggle={() => onToggleEntry?.(e.id)} testID="entry-checkbox" />
                 </View>
               ) : null}
               <View style={{ flex: 1 }}>
@@ -3567,9 +3947,28 @@ function ReadOnlyBanner({ notice, actionLabel, onAction }: { notice?: string; ac
   );
 }
 
-// ApplyModalOverlay renders the apply-changes / change-request modal as a
-// full-screen overlay. Shared by both layouts so the modal (and its "learn more"
-// change-request link) is reachable on mobile too.
+// ModalOverlays renders the browser's full-screen modals — apply changes /
+// change request, and the protected-branch save prompt. Shared by both layouts
+// so every modal is reachable on mobile too.
+function ModalOverlays(props: ContentBrowserProps) {
+  return (
+    <>
+      <ApplyModalOverlay {...props} />
+      {props.protectedBranch ? (
+        <ProtectedBranchModal
+          branch={props.protectedBranch}
+          documentLabel={props.protectedBranchDocument}
+          suggestedName={props.protectedBranchSuggestedName}
+          busy={props.creatingProtectedBranch}
+          error={props.protectedBranchError}
+          onCreate={props.onCreateBranchAndSave ?? (() => {})}
+          onCancel={props.onCancelProtectedSave ?? (() => {})}
+        />
+      ) : null}
+    </>
+  );
+}
+
 function ApplyModalOverlay(props: ContentBrowserProps) {
   if (!props.applyOpen) return null;
   return (
@@ -3577,6 +3976,7 @@ function ApplyModalOverlay(props: ContentBrowserProps) {
       sourceBranch={props.workspace.branch}
       targetBranch={props.targetBranch ?? props.defaultBranch ?? ""}
       summary={props.applySummary}
+      reviewReason={props.applyReviewReason}
       progress={props.applyProgress}
       conflictCount={props.applyConflictCount}
       changeRequestOpen={props.changeRequestOpen}
@@ -3756,6 +4156,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
         canDelete: tab.canDelete,
         canRename: !!tab.canRename,
         canMove: !!tab.canMove,
+        collection: tab.collection,
         collectionPath: tab.collectionPath,
         content: tab.content,
         title: tab.title,
@@ -3937,7 +4338,9 @@ function DesktopBrowser(props: ContentBrowserProps) {
         <EntryDetail
           entry={col.entry}
           documentActions={props.documentActions}
+          history={props.history}
           onEntryDraft={props.onEntryDraft}
+          onFieldFocus={props.onFieldFocus}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}
           readOnly={col.readOnly}
@@ -3945,6 +4348,9 @@ function DesktopBrowser(props: ContentBrowserProps) {
           onDeleteEntry={onDeleteEntry}
           onRename={col.canRename ? onRename : undefined}
           onMove={col.canMove ? onMove : undefined}
+          // A host-managed tab names its collection; a column the browser opened
+          // itself (uncontrolled selection) belongs to the active one.
+          collection={navLabelFor(props.sections, col.collection || props.activeNavKey) ?? (col.collection || props.activeNavKey)}
           collectionPath={col.collectionPath}
           folderOptions={moveFolders}
           active={!showCreate && col.active}
@@ -4066,7 +4472,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
   const readOnlyBanner = (
     <ReadOnlyBanner notice={props.readOnlyNotice} actionLabel={props.readOnlyNoticeActionLabel} onAction={props.onReadOnlyNoticeAction} />
   );
-  const applyModal = <ApplyModalOverlay {...props} />;
+  const modalOverlays = <ModalOverlays {...props} />;
 
   // The changes surface reuses the same three-pane model as Edit, so switching
   // between them doesn't relayout the screen — only what each pane contains
@@ -4119,7 +4525,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           conflicts={props.selectedConflicts}
           onResolveConflict={props.onResolveConflict}
         />
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4134,7 +4540,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
         <Pane flex={1} testID="pane-plugin" scroll={false}>
           {props.contentSlot}
         </Pane>
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4174,7 +4580,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           <View style={{ flex: 1, alignItems: "center", justifyContent: "center", padding: t.space(6) }}>
             <Text variant="body" color="tertiary" testID="forms-empty">Select a form</Text>
           </View>
-          {applyModal}
+          {modalOverlays}
         </AppShell>
       );
     }
@@ -4192,7 +4598,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
             variant="desktop"
           />
         </Pane>
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4219,7 +4625,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
             <Text variant="body" color="tertiary" testID="media-sets-empty">Select a media collection</Text>
           </View>
         )}
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4420,7 +4826,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           onClose={() => setMovePrompt(false)}
         />
       ) : null}
-      {applyModal}
+      {modalOverlays}
     </AppShell>
   );
 }
@@ -4496,7 +4902,7 @@ function MobileBrowser(props: ContentBrowserProps) {
   const readOnlyBanner = (
     <ReadOnlyBanner notice={props.readOnlyNotice} actionLabel={props.readOnlyNoticeActionLabel} onAction={props.onReadOnlyNoticeAction} />
   );
-  const applyModal = <ApplyModalOverlay {...props} />;
+  const modalOverlays = <ModalOverlays {...props} />;
 
   // Media drills the same way a collection does — nav → list → detail — so the
   // back arrow means the same thing at every level. Pressing Media lists the
@@ -4622,7 +5028,7 @@ function MobileBrowser(props: ContentBrowserProps) {
         testID="mobile-shell"
         header={header}
         title={props.surface === "changes" ? "Changes" : "Content"}
-        overlay={applyModal}
+        overlay={modalOverlays}
       >
         {/* Edit / Changes surface toggle (fits its content) with the Apply button
             to its right on the changes surface. The read-only notice sits below. */}
@@ -4703,7 +5109,7 @@ function MobileBrowser(props: ContentBrowserProps) {
         testID="mobile-entries"
         scroll={false}
         banner={readOnlyBanner}
-        overlay={applyModal}
+        overlay={modalOverlays}
         header={
           search.open ? (
             <SearchHeaderBar search={search} showFilter={facetFields.length > 0} />
@@ -4784,7 +5190,7 @@ function MobileBrowser(props: ContentBrowserProps) {
     <MobileScreen
       testID="mobile-entry"
       banner={readOnlyBanner}
-      overlay={applyModal}
+      overlay={modalOverlays}
       header={
         <>
           <IconButton name="chevronLeft" onPress={backToEntries} size="md" label="Back" />
@@ -4812,7 +5218,9 @@ function MobileBrowser(props: ContentBrowserProps) {
         <EntryDetail
           entry={entry}
           documentActions={props.documentActions}
+          history={props.history}
           onEntryDraft={props.onEntryDraft}
+          onFieldFocus={props.onFieldFocus}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}
           readOnly={readOnly}
@@ -4820,6 +5228,7 @@ function MobileBrowser(props: ContentBrowserProps) {
           onDeleteEntry={onDeleteEntry}
           onRename={onRename}
           onMove={onMove}
+          collection={navLabelFor(props.sections, props.activeNavKey) ?? props.activeNavKey}
           collectionPath={collectionPath}
           folderOptions={moveFolders}
         />
@@ -5071,7 +5480,9 @@ export function ContentBrowser(props: ContentBrowserProps) {
   // object store) renders media fields read-only.
   return (
     <MediaProvider api={props.media}>
-      {isDesktop ? <DesktopBrowser {...withSections} /> : <MobileBrowser {...withSections} />}
+      <ReferenceProvider api={props.references}>
+        {isDesktop ? <DesktopBrowser {...withSections} /> : <MobileBrowser {...withSections} />}
+      </ReferenceProvider>
     </MediaProvider>
   );
 }
@@ -5082,14 +5493,20 @@ function mediaSetLabel(sets: MediaSetInfo[], name: string): string {
   return set ? titleCaseWord(set.name) : titleCaseWord(name);
 }
 
-// PaneTitle is the content pane's heading, matching the entry list's header
-// height so the panes line up when switching between content and media.
+// PaneTitle is the content pane's heading for the surfaces with no controls
+// beside it — Changes, Media, Forms.
+//
+// Deliberately the same Text the collection header uses (`listHeader`), and
+// nothing else. Pane's header row already supplies the height, the horizontal
+// padding and the rule beneath, so the padded wrapper this used to add sat
+// inside that padding and pushed the title a step right of every collection's —
+// at `body` rather than `h3`, so it read a size smaller too. Switching between
+// Posts and Media moved the heading twice over.
 function PaneTitle({ title }: { title: string }) {
-  const t = useTheme();
   return (
-    <View style={{ paddingHorizontal: t.space(4), paddingVertical: t.space(3) }}>
-      <Text variant="body" weight="semibold">{title}</Text>
-    </View>
+    <Text variant="h3" weight="semibold" style={{ flex: 1 }}>
+      {title}
+    </Text>
   );
 }