@gogitcms/design-system 0.16.0-next.0 → 0.16.0-next.10

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,18 @@ import {
   useCollabPeersUnder,
 } from "./CollabField";
 import { clamp, reorder, slotAtX } from "./reorder";
-import { MediaField, MediaProvider, DocumentPathProvider } from "./MediaField";
+import { MediaField, MediaProvider, DocumentPathProvider, useFieldMedia } from "./MediaField";
 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,
@@ -111,6 +116,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 +341,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;
@@ -339,6 +363,14 @@ export type ContentBrowserProps = {
   // 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 +497,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 +513,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 +791,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 +840,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 +852,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 +870,7 @@ function FieldControl(props: FieldControlProps) {
             custom
           )}
           {errorNode}
+          {fieldMedia.picker}
         </View>
       );
     }
@@ -1592,11 +1683,14 @@ function ListControl({
     ...(field.media ? { component: "media", media: field.media, storeAs: field.storeAs } : {}),
   };
 
+  // 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 +1730,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 +1766,7 @@ function MixedListControl({
                 />
               ) : null}
             </View>
+            </FieldPathContext.Provider>
           </ItemFrame>
         );
       })}
@@ -1697,6 +1802,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 +1812,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={{
@@ -2558,6 +2676,7 @@ function EntryDetail({
   entry,
   documentActions,
   onEntryDraft,
+  onFieldFocus,
   renderField,
   onSaveEntry,
   readOnly = false,
@@ -2567,6 +2686,7 @@ function EntryDetail({
   onMove,
   collectionPath,
   folderOptions,
+  history,
   active,
   onActivate,
   onCollapse,
@@ -2579,6 +2699,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;
@@ -2589,6 +2711,10 @@ function EntryDetail({
   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 +2735,23 @@ function EntryDetail({
   const canRename = !readOnly && !!onRename;
   const canMove = !readOnly && !!onMove && glob.hierarchical;
   const [prompt, setPrompt] = useState<"rename" | "move" | null>(null);
+  // 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 +2934,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 +3054,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 +3149,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,6 +3177,20 @@ function EntryDetail({
             document's own actions, while the menu holds the destructive and
             path-changing ones that should stay one level down. */}
         {documentActions?.(entry)}
+        {/* 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}
         {canRename || canMove || (canDelete && onDeleteEntry) ? (
           <DetailMenu
             onRename={canRename ? () => setPrompt("rename") : undefined}
@@ -2909,10 +3206,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
@@ -2935,6 +3257,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,11 +3274,16 @@ 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}
           <View style={{ gap: t.space(2) }}>
@@ -2968,6 +3297,7 @@ function EntryDetail({
             readOnly={readOnly}
           />
         </View>
+        </DocumentPathProvider>
       )}
 
       {prompt === "rename" && onRename ? (
@@ -3029,27 +3359,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 }) {
@@ -3192,7 +3501,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 +3876,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 +3905,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}
@@ -3937,7 +4266,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}
@@ -4066,7 +4397,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 +4450,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           conflicts={props.selectedConflicts}
           onResolveConflict={props.onResolveConflict}
         />
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4134,7 +4465,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
         <Pane flex={1} testID="pane-plugin" scroll={false}>
           {props.contentSlot}
         </Pane>
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4143,11 +4474,41 @@ function DesktopBrowser(props: ContentBrowserProps) {
   // lists the media sets exactly where a collection's documents would be, and the
   // details pane holds the browser for whichever set is selected. Selecting a set
   // goes through onSelectNav, so it lands in the URL like any other selection.
-  // Forms take the whole content area rather than the three-pane model: the
-  // surface is already two levels deep (forms → submissions → one submission),
-  // and threading that through panes designed for collection → document → editor
-  // would mean a pane whose meaning changes with the level.
+  // Forms enter through the same content column every other surface uses: the
+  // list of forms sits exactly where a collection's documents would, at the
+  // list width, with the empty state beside it. A list of half a dozen rows
+  // stretched across everything after the sidebar reads as a different kind of
+  // screen than Edit, Changes and Media, when it is the same kind of screen.
+  //
+  // Opening a form is where forms stop fitting the three-pane model, and so it
+  // is where they leave it: that surface is two more levels deep (submissions →
+  // one submission), and threading those through panes meant for collection →
+  // document → editor would give a pane whose meaning changes with the level.
+  // FormsBrowser owns its own split from there.
   if (formsShowing && props.forms) {
+    if (!activeForm) {
+      return (
+        <AppShell testID="desktop-shell" topBar={topBar} banner={readOnlyBanner}>
+          {navPane}
+          <ResizeHandle width={navW} min={180} max={420} onChange={setNavW} testID="resize-nav" />
+
+          <Pane width={listW} testID="pane-forms" scroll={false} header={<PaneTitle title="Forms" />}>
+            <FormsBrowser
+              api={props.forms}
+              form={null}
+              onSelectForm={(name) => onSelectNav(name ? formsNavKey(name) : FORMS_NAV_KEY)}
+              variant="desktop"
+            />
+          </Pane>
+          <ResizeHandle width={listW} min={260} max={640} onChange={setListW} testID="resize-forms" />
+
+          <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>
+          {modalOverlays}
+        </AppShell>
+      );
+    }
     return (
       <AppShell testID="desktop-shell" topBar={topBar} banner={readOnlyBanner}>
         {navPane}
@@ -4162,7 +4523,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
             variant="desktop"
           />
         </Pane>
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4189,7 +4550,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
             <Text variant="body" color="tertiary" testID="media-sets-empty">Select a media collection</Text>
           </View>
         )}
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4390,7 +4751,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           onClose={() => setMovePrompt(false)}
         />
       ) : null}
-      {applyModal}
+      {modalOverlays}
     </AppShell>
   );
 }
@@ -4466,7 +4827,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
@@ -4592,7 +4953,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. */}
@@ -4673,7 +5034,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} />
@@ -4754,7 +5115,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" />
@@ -4782,7 +5143,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}
@@ -5052,14 +5415,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>
   );
 }