@gogitcms/design-system 0.16.0-next.4 → 0.16.0-next.6

package/src/__tests__/ContentBrowser.historycollab.test.tsx

@@ -0,0 +1,433 @@
+// Restoring a field from a past version, in a live session.
+//
+// In collab the shared document is the source of truth: every collab control
+// prefers its binding to the value the host passes in. So a restore written only
+// to local form state was displayed for one frame and then overwritten by the
+// CRDT's unchanged value — the field visibly snapped back, and nothing about the
+// restore reached the room or the peers in it.
+
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import {
+  ContentBrowser,
+  type CmsEntry,
+  type CmsNavSection,
+  type CollabApi,
+  type CollabRegister,
+  type CollabText,
+  type FieldSlotArgs,
+} from "../components/ContentBrowser";
+import type { DocumentChange } from "../components/ChangeDetail";
+import type { HistoryApi } from "../history";
+import { refreshDrafts } from "../components/documentDrafts";
+
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+/**
+ * An in-memory stand-in for @gogitcms/realtime's DocCollab, seeded with what the
+ * room already holds. Bindings are memoized per path and the empty peer list is
+ * shared, because useSyncExternalStore re-renders until a snapshot is stable.
+ */
+function fakeCollab(seed: Record<string, unknown> = {}) {
+  const values = new Map<string, unknown>(Object.entries(seed));
+  const listeners = new Map<string, Set<() => void>>();
+  const noPeers: never[] = [];
+
+  const notify = (path: string) => listeners.get(path)?.forEach((l) => l());
+  const listen = (path: string, cb: () => void) => {
+    let set = listeners.get(path);
+    if (!set) listeners.set(path, (set = new Set()));
+    set.add(cb);
+    return () => void set!.delete(cb);
+  };
+
+  const textCache = new Map<string, CollabText>();
+  const text = (path: string): CollabText => {
+    let b = textCache.get(path);
+    if (!b) {
+      textCache.set(path, (b = {
+        get: () => String(values.get(path) ?? ""),
+        set: (next) => { values.set(path, next); notify(path); },
+        peers: () => noPeers,
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return b;
+  };
+
+  const regCache = new Map<string, CollabRegister>();
+  const register = (path: string): CollabRegister => {
+    let b = regCache.get(path);
+    if (!b) {
+      regCache.set(path, (b = {
+        get: () => values.get(path),
+        set: (next) => { values.set(path, next); notify(path); },
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return b;
+  };
+
+  const collab: CollabApi = {
+    text, register,
+    setFocus: () => {},
+    peersAt: () => noPeers,
+    peersUnder: () => noPeers,
+    participants: () => noPeers,
+    awarenessVersion: () => 0,
+    subscribeAwareness: () => () => {},
+    ydoc: {},
+    awareness: {},
+  };
+  return { collab, room: values };
+}
+
+// A restore commits, and committing records a draft. Without clearing them each
+// test seeds its form from the PREVIOUS test's restore — which reads as a field
+// that was already rolled back and so has nothing left to write.
+beforeEach(() => {
+  localStorage.clear();
+  refreshDrafts();
+});
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+];
+
+const version = {
+  sha: "3b7de1098877",
+  shortSha: "3b7de10",
+  message: "Draft the post",
+  authorName: "Ada",
+  authoredAt: "2026-02-01T12:00:00Z",
+  url: "",
+  filesChanged: 1,
+};
+
+function makeApi(detail: DocumentChange): HistoryApi {
+  return { list: jest.fn(async () => [version]), get: jest.fn(async () => detail) };
+}
+
+async function openHistory(entry: CmsEntry, detail: DocumentChange, renderField?: (a: FieldSlotArgs) => React.ReactNode) {
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="posts"
+        onSelectNav={jest.fn()}
+        entries={[entry]}
+        selectedEntryId={entry.id}
+        onSelectEntry={jest.fn()}
+        userInitials="ED"
+        onSaveEntry={jest.fn(async () => {})}
+        renderField={renderField}
+        history={makeApi(detail)}
+      />,
+    ),
+  );
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+  await screen.findByTestId("change-detail");
+}
+
+// The regression, end to end: the restored value has to be what the control
+// shows once the CRDT has had its say — not for one frame before it.
+test("a restored string lands in the room, and stays on screen", async () => {
+  const { collab, room } = fakeCollab({ status: "published" });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [{ name: "status", type: "string", label: "Status", value: "published" }],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-status"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  // Written where a string lives — the Y.Text, which is what the control reads.
+  expect(room.get("status")).toBe("draft");
+  await waitFor(() => expect(screen.getByDisplayValue("draft")).toBeInTheDocument());
+});
+
+// Which shared type a value lives in follows its shape, mirroring what the
+// server seeds: a string is a text, everything else is a register. Writing to
+// the wrong one is not an error anyone sees — it is a value that lands where
+// nothing is looking.
+test("non-string values restore into the register, not the text", async () => {
+  const { collab, room } = fakeCollab({ weight: 20, tags: ["b"], live: true });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [
+      { name: "weight", type: "integer", value: 20 },
+      { name: "tags", type: "array", of: "string", value: ["b"] },
+      { name: "live", type: "boolean", value: true },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [
+      { name: "weight", kind: "changed", before: 10, after: 20 },
+      { name: "tags", kind: "changed", before: ["a"], after: ["b"] },
+      { name: "live", kind: "changed", before: false, after: true },
+    ],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-weight"));
+  fireEvent.click(screen.getByTestId("restore-field-tags"));
+  fireEvent.click(screen.getByTestId("restore-field-live"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  expect(room.get("weight")).toBe(10);
+  expect(room.get("tags")).toEqual(["a"]);
+  expect(room.get("live")).toBe(false);
+});
+
+// A group's children are addressed by dotted path in the room, exactly as the
+// server writes them — a group restored as one object still has to reach the
+// individual leaves its controls read.
+test("a restored group writes its children at their dotted paths", async () => {
+  const { collab, room } = fakeCollab({ "seo.title": "New", "seo.weight": 2 });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [{
+      name: "seo", type: "object", component: "group",
+      fields: [
+        { name: "title", type: "string", value: "New" },
+        { name: "weight", type: "integer", value: 2 },
+      ],
+      value: { title: "New", weight: 2 },
+    }],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{
+      name: "seo", kind: "changed",
+      before: { title: "Old", weight: 1 },
+      after: { title: "New", weight: 2 },
+    }],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-seo"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  expect(room.get("seo.title")).toBe("Old");
+  expect(room.get("seo.weight")).toBe(1);
+});
+
+// Only the new value's leaves say what to write; only the old value's leaves say
+// what to CLEAR. A group that loses a child would otherwise keep a shared value
+// nobody can see any more.
+test("leaves the restored version does not have are cleared in the room", async () => {
+  const { collab, room } = fakeCollab({ "seo.title": "New", "seo.blurb": "extra", subtitle: "here" });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [
+      { name: "seo", type: "object", component: "group", fields: [{ name: "title", type: "string", value: "New" }], value: { title: "New", blurb: "extra" } },
+      { name: "subtitle", type: "string", value: "here" },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [
+      // The old version's group had no `blurb` at all…
+      { name: "seo", kind: "changed", before: { title: "Old" }, after: { title: "New", blurb: "extra" } },
+      // …and had no `subtitle` field whatsoever.
+      { name: "subtitle", kind: "added", before: undefined, after: "here" },
+    ],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-seo"));
+  fireEvent.click(screen.getByTestId("restore-field-subtitle"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  expect(room.get("seo.title")).toBe("Old");
+  // Emptied rather than left holding a value the restored version never had.
+  expect(room.get("seo.blurb")).toBe("");
+  expect(room.get("subtitle")).toBe("");
+});
+
+// The body is a ProseMirror fragment, not a text binding: in a session it
+// ignores the `value` it is handed and mirrors the shared fragment, so "the
+// value changed" is not something it can observe. It is told instead.
+test("restoring the body signals the body editor to replace its content", async () => {
+  const { collab } = fakeCollab({});
+  const seen: FieldSlotArgs[] = [];
+  const renderField = (args: FieldSlotArgs) => {
+    if (args.field.source !== "body") return undefined;
+    seen.push(args);
+    return <div data-testid="body-slot" />;
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "Now.", collab,
+    fields: [
+      { name: "status", type: "string", value: "published" },
+      { name: "content", type: "string", component: "body", source: "body", value: "Now." },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+    bodyBefore: "Then.", bodyAfter: "Now.",
+  }, renderField);
+
+  const before = seen[seen.length - 1].resetNonce;
+
+  fireEvent.click(screen.getByTestId("restore-field-body"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  await waitFor(() => {
+    const last = seen[seen.length - 1];
+    expect(last.value).toBe("Then.");
+    expect(last.resetNonce).not.toBe(before);
+  });
+});
+
+// Restoring some other field must not make the body editor replace itself — a
+// peer could be mid-sentence in it.
+test("restoring another field leaves the body editor's signal alone", async () => {
+  const { collab } = fakeCollab({ status: "published" });
+  const seen: FieldSlotArgs[] = [];
+  const renderField = (args: FieldSlotArgs) => {
+    if (args.field.source !== "body") return undefined;
+    seen.push(args);
+    return <div data-testid="body-slot" />;
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "Now.", collab,
+    fields: [
+      { name: "status", type: "string", value: "published" },
+      { name: "content", type: "string", component: "body", source: "body", value: "Now." },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+    bodyBefore: "Then.", bodyAfter: "Now.",
+  }, renderField);
+
+  const before = seen[seen.length - 1].resetNonce;
+
+  fireEvent.click(screen.getByTestId("restore-field-status"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  await waitFor(() => expect(screen.getByTestId("column-scroll")).toBeInTheDocument());
+  expect(seen[seen.length - 1].resetNonce).toBe(before);
+});
+
+// ---- discard, in a live session -------------------------------------------
+//
+// Discard has the same shape of problem as a restore, and had the same bug: it
+// reverted the local form and left the discarded work sitting in the CRDT,
+// where the control read it straight back. In a session a discard is a change
+// to the ROOM — the unsaved work is the collective state every client is
+// looking at, not one screen's private draft.
+
+async function openEditor(entry: CmsEntry, renderField?: (a: FieldSlotArgs) => React.ReactNode) {
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="posts"
+        onSelectNav={jest.fn()}
+        entries={[entry]}
+        selectedEntryId={entry.id}
+        onSelectEntry={jest.fn()}
+        userInitials="ED"
+        onSaveEntry={jest.fn(async () => {})}
+        renderField={renderField}
+      />,
+    ),
+  );
+  await screen.findByTestId("column-scroll");
+}
+
+test("discarding puts the saved value back in the room, not just on screen", async () => {
+  const { collab, room } = fakeCollab({ status: "published" });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [{ name: "status", type: "string", label: "Status", value: "published" }],
+  };
+  await openEditor(entry);
+
+  fireEvent.change(screen.getByDisplayValue("published"), { target: { value: "scratch" } });
+  await waitFor(() => expect(room.get("status")).toBe("scratch"));
+
+  fireEvent.click(await screen.findByTestId("discard-changes"));
+
+  // The room is back to the document, so the control has nothing to read back.
+  expect(room.get("status")).toBe("published");
+  await waitFor(() => expect(screen.getByDisplayValue("published")).toBeInTheDocument());
+});
+
+// The body is a fragment the editor mirrors, so a discard has to tell it rather
+// than write a binding it does not read.
+test("discarding signals the body editor to rebuild from the saved document", async () => {
+  const { collab } = fakeCollab({ status: "published" });
+  const seen: FieldSlotArgs[] = [];
+  const renderField = (args: FieldSlotArgs) => {
+    if (args.field.source !== "body") return undefined;
+    seen.push(args);
+    return <div data-testid="body-slot" />;
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "Saved.", collab,
+    fields: [
+      { name: "status", type: "string", value: "published" },
+      { name: "content", type: "string", component: "body", source: "body", value: "Saved." },
+    ],
+  };
+  await openEditor(entry, renderField);
+
+  const before = seen[seen.length - 1].resetNonce;
+  // An edit to the body, as the editor itself would report one.
+  seen[seen.length - 1].onChange("Scratch.");
+
+  fireEvent.click(await screen.findByTestId("discard-changes"));
+
+  await waitFor(() => {
+    const last = seen[seen.length - 1];
+    expect(last.value).toBe("Saved.");
+    expect(last.resetNonce).not.toBe(before);
+  });
+});
+
+// A discard replaces the whole document, but only the fields that actually
+// moved should be written: churning the rest costs CRDT operations and can
+// nudge the cursor of a peer working in a field nobody discarded.
+test("discarding leaves untouched fields alone in the room", async () => {
+  const { collab } = fakeCollab({ status: "published", subtitle: "untouched" });
+  const writes: string[] = [];
+  const wrapped: CollabApi = {
+    ...collab,
+    text: (p) => {
+      const b = collab.text(p);
+      return { ...b, set: (n) => { writes.push(p); b.set(n); } };
+    },
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab: wrapped,
+    fields: [
+      { name: "status", type: "string", label: "Status", value: "published" },
+      { name: "subtitle", type: "string", label: "Subtitle", value: "untouched" },
+    ],
+  };
+  await openEditor(entry);
+
+  fireEvent.change(screen.getByDisplayValue("published"), { target: { value: "scratch" } });
+  await waitFor(() => expect(screen.getByDisplayValue("scratch")).toBeInTheDocument());
+  writes.length = 0;
+
+  fireEvent.click(await screen.findByTestId("discard-changes"));
+
+  expect(writes).toContain("status");
+  expect(writes).not.toContain("subtitle");
+});

package/src/components/ChangeDetail.tsx

@@ -5,7 +5,7 @@ import { Text } from "./Text";
 import { Icon } from "./Icon";
 import { Input } from "./Input";
 import { Button } from "./Button";
-import { Badge, DiffStat } from "./primitives";
+import { Badge, CheckBox, DiffStat } from "./primitives";
 
 /** How one field differs between the branch and its base. */
 export type FieldChangeKind = "added" | "removed" | "changed" | "unchanged";
@@ -87,8 +87,29 @@ export type ChangeDetailProps = {
    */
   conflicts?: FieldConflict[];
   onResolveConflict?: (conflict: FieldConflict, choice: ConflictChoice, override?: unknown) => void;
+
+  /**
+   * Per-field selection, for a caller that does something with a subset of the
+   * diff — restoring fields from a past version, in the history pane.
+   *
+   * Only CHANGED fields get a box: an unchanged field's two sides are the same
+   * value, so selecting it could only ever be a no-op dressed up as a choice.
+   * The body is selectable under the name BODY_FIELD.
+   *
+   * Omitting onToggleField leaves the diff exactly as it was — a read-only
+   * comparison, which is what the changes surface wants.
+   */
+  selectedFields?: readonly string[];
+  onToggleField?: (name: string) => void;
 };
 
+/**
+ * The name the body answers to in `selectedFields` — the document body is a
+ * selectable "field" here but has no entry in `fields`, and a real frontmatter
+ * key could otherwise collide with whatever plain string we picked.
+ */
+export const BODY_FIELD = "\u0000body";
+
 const STATUS_LABEL: Record<DocumentChange["status"], string> = {
   A: "Added",
   M: "Modified",
@@ -151,14 +172,29 @@ function ContextValue({ value }: { value: unknown }) {
   );
 }
 
-function FieldRow({ field }: { field: FieldChange }) {
+function FieldRow({
+  field,
+  selected,
+  onToggle,
+}: {
+  field: FieldChange;
+  // Both present or both absent: selection is offered only for a changed field
+  // whose caller wants it (see ChangeDetailProps.onToggleField).
+  selected?: boolean;
+  onToggle?: () => void;
+}) {
   const t = useTheme();
   const changed = field.kind !== "unchanged";
   return (
     <View testID={`change-field-${field.name}`} style={{ gap: t.space(2) }}>
-      <Text variant="label" color="tertiary">
-        {(field.label || field.name).toUpperCase()}
-      </Text>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+        {onToggle ? (
+          <CheckBox value={!!selected} onToggle={onToggle} testID={`restore-field-${field.name}`} />
+        ) : null}
+        <Text variant="label" color="tertiary">
+          {(field.label || field.name).toUpperCase()}
+        </Text>
+      </View>
       {changed ? (
         <View
           style={{
@@ -294,7 +330,17 @@ function ConflictSide({ label, value, chosen }: { label: string; value: unknown;
  * stacked blocks rather than a single line — the whole before and the whole
  * after, each tinted, so a reviewer can read them.
  */
-function BodyDiff({ before, after }: { before?: string | null; after?: string | null }) {
+function BodyDiff({
+  before,
+  after,
+  selected,
+  onToggle,
+}: {
+  before?: string | null;
+  after?: string | null;
+  selected?: boolean;
+  onToggle?: () => void;
+}) {
   const t = useTheme();
   if ((before ?? "") === (after ?? "")) {
     if (!after) return null;
@@ -307,7 +353,12 @@ function BodyDiff({ before, after }: { before?: string | null; after?: string |
   }
   return (
     <View testID="change-body" style={{ gap: t.space(2) }}>
-      <Text variant="label" color="tertiary">BODY</Text>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+        {onToggle ? (
+          <CheckBox value={!!selected} onToggle={onToggle} testID="restore-field-body" />
+        ) : null}
+        <Text variant="label" color="tertiary">BODY</Text>
+      </View>
       <View
         style={{
           borderRadius: t.radius.md,
@@ -383,8 +434,21 @@ function AssetPreview({ preview }: { preview: ChangePreview }) {
  * context. Strictly read-only — editing happens on the Edit surface, and this
  * view describes a comparison rather than a document you can save.
  */
-export function ChangeDetail({ change, loading, emptyMessage = "Select a change", conflicts, onResolveConflict }: ChangeDetailProps) {
+export function ChangeDetail({
+  change,
+  loading,
+  emptyMessage = "Select a change",
+  conflicts,
+  onResolveConflict,
+  selectedFields,
+  onToggleField,
+}: ChangeDetailProps) {
   const t = useTheme();
+  const chosen = new Set(selectedFields ?? []);
+  // A field offers a box only when the caller wants selection AND there is
+  // something to select — an unchanged field's two sides are the same value.
+  const toggleFor = (name: string, changed: boolean) =>
+    onToggleField && changed ? () => onToggleField(name) : undefined;
 
   // Conflicts keyed by field name (and a body flag), so each field can check for
   // one as it renders. The body conflict is looked up separately.
@@ -454,7 +518,12 @@ export function ChangeDetail({ change, loading, emptyMessage = "Select a change"
               onResolve={onResolveConflict ? (choice, override) => onResolveConflict(conflict, choice, override) : undefined}
             />
           ) : (
-            <FieldRow key={f.name} field={f} />
+            <FieldRow
+              key={f.name}
+              field={f}
+              selected={chosen.has(f.name)}
+              onToggle={toggleFor(f.name, f.kind !== "unchanged")}
+            />
           );
         })}
         {/* Conflicts on fields the schema-ordered diff didn't surface (rare). */}
@@ -473,7 +542,12 @@ export function ChangeDetail({ change, loading, emptyMessage = "Select a change"
             onResolve={onResolveConflict ? (choice, override) => onResolveConflict(bodyConflict!, choice, override) : undefined}
           />
         ) : (
-          <BodyDiff before={change.bodyBefore} after={change.bodyAfter} />
+          <BodyDiff
+            before={change.bodyBefore}
+            after={change.bodyAfter}
+            selected={chosen.has(BODY_FIELD)}
+            onToggle={toggleFor(BODY_FIELD, (change.bodyBefore ?? "") !== (change.bodyAfter ?? ""))}
+          />
         )}
       </ScrollView>
     </View>

package/src/components/CollabField.tsx

@@ -386,3 +386,74 @@ export function CollabTextarea({
     </PresenceField>
   );
 }
+
+// ---- writing a whole value into the shared document ------------------------
+
+/**
+ * Where one leaf of a document value lives in the shared doc.
+ *
+ * The split mirrors what the server seeds (collab.go's collectLeaves), because
+ * that is what decides which binding a control actually reads: a string is a
+ * Y.Text, and everything else — numbers, booleans, null, and whole lists — is a
+ * key in the "reg" map. Writing to the other one is not an error anyone sees;
+ * it is a value that silently lands where nothing is looking.
+ */
+type CollabLeaf = { kind: "text"; value: string } | { kind: "reg"; value: unknown };
+
+/**
+ * Flattens a value into the leaves the shared document holds it as, keyed by
+ * dotted path — `seo.title` for a group's child, exactly as the server does.
+ *
+ * `undefined` yields no leaves at all: it means the field is absent, which is
+ * expressed by clearing whatever was there rather than by writing something.
+ */
+function collabLeaves(path: string, value: unknown, into = new Map<string, CollabLeaf>()): Map<string, CollabLeaf> {
+  if (value === undefined) return into;
+  if (typeof value === "string") {
+    into.set(path, { kind: "text", value });
+    return into;
+  }
+  // A list is a whole-value register, matching CollabArrayField — its items are
+  // not addressable leaves, so it is written and cleared in one piece.
+  if (Array.isArray(value) || value === null || typeof value !== "object") {
+    into.set(path, { kind: "reg", value });
+    return into;
+  }
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    collabLeaves(path ? `${path}.${k}` : k, v, into);
+  }
+  return into;
+}
+
+/**
+ * Replaces a field's value in the shared document, so a value written by
+ * something other than typing — restoring a field from a past version — reaches
+ * the room instead of only the local form.
+ *
+ * In a live session the shared document is the source of truth: every collab
+ * control reads its binding in preference to the host's value, so a write that
+ * only touches local state is displayed for an instant and then overwritten by
+ * the CRDT's unchanged value. It has to be written here to be written at all.
+ *
+ * `previous` is what the field held, and is needed rather than inferable: the
+ * new value's leaves say what to write, but only the old value's leaves say
+ * what to CLEAR — a group that loses a child, or a field being cleared outright,
+ * would otherwise keep the shared value nobody can see any more.
+ */
+export function writeCollabValue(collab: CollabApi, path: string, previous: unknown, next: unknown): void {
+  const before = collabLeaves(path, previous);
+  const after = collabLeaves(path, next);
+
+  for (const [leafPath, leaf] of before) {
+    if (after.has(leafPath)) continue;
+    // Clearing is per shared type: a Y.Text empties, a register goes back to
+    // unset (which is what an absent key reads as, and what makes the control
+    // fall back to the document's own value).
+    if (leaf.kind === "text") collab.text(leafPath).set("");
+    else collab.register(leafPath).set(undefined);
+  }
+  for (const [leafPath, leaf] of after) {
+    if (leaf.kind === "text") collab.text(leafPath).set(leaf.value);
+    else collab.register(leafPath).set(leaf.value);
+  }
+}