Keep Content's Builder saves from snapping back

templates/content/actions/_builder-cms-read-client.test.ts

@@ -151,6 +151,8 @@
     expect(fields).not.toContain("DATA.BLOCKS");
     expect(fields).not.toContain("data.BlocksString");
     expect(fields).not.toContain("sys.sync_state");
+    // The Builder status reads Builder's own autosave flag from every read.
+    expect(fields).toContain("meta.hasAutosaves");
     expect(fields.filter((field) => field === "data.tags")).toHaveLength(1);
     expect(fields).toContain("published");
     expect(fields).toContain("data.published");
@@ -2055,7 +2057,7 @@
       { id: "legacy-entry", title: "Legacy test entry" },
     ]);
     const browseBody = JSON.parse(
       String((fetchImpl.mock.calls[2]?.[1] as RequestInit).body),
     );
     expect(browseBody.params).toMatchObject({
       name: "get_builder_content",
@@ -2120,7 +2122,7 @@
     });
 
     const browseBody = JSON.parse(
       String((fetchImpl.mock.calls[2]?.[1] as RequestInit).body),
     );
     expect(browseBody.params.arguments.limit).toBe(100);
     expect(result).toMatchObject({
@@ -2214,7 +2216,7 @@
     });
     expect(result.entries).toHaveLength(101);
     const secondPageBody = JSON.parse(
       String((fetchImpl.mock.calls[3]?.[1] as RequestInit).body),
     );
     expect(secondPageBody.params.arguments.offset).toBe(100);
   });
@@ -2280,7 +2282,7 @@
       ]),
     });
     const secondPageBody = JSON.parse(
       String((fetchImpl.mock.calls[2]?.[1] as RequestInit).body),
     );
     expect(secondPageBody.params.arguments.offset).toBe(100);
   });
@@ -2598,6 +2600,8 @@
       lastUpdated: 1_786_000_000_000,
       blocksHash: baselineHash,
       id: "builder-entry-1",
+      values: expect.objectContaining({ "data.title": "Builder title" }),
+      hasAutosaves: null,
     });
     expect(fetchImpl).toHaveBeenCalledTimes(2);
     for (const [input] of fetchImpl.mock.calls) {
@@ -2609,6 +2613,58 @@
     }
   });
 
+  it("asks the public-key live read for the fields a save writes", async () => {
+    resolveBuilderCredentialMock.mockImplementation(async (key) =>
+      key === "BUILDER_PUBLIC_KEY" ? "public-key" : null,
+    );
+    // Builder leaves out every data field a projected read doesn't name.
+    const fetchImpl = vi.fn(async (input: URL) => {
+      const fields = (input.searchParams.get("fields") ?? "").split(",");
+      const data = {
+        title: "Builder title",
+        blurb: "Builder blurb",
+        blocks: [],
+      };
+      return new Response(
+        JSON.stringify({
+          id: "builder-entry-1",
+          published: "published",
+          lastUpdated: 1_786_000_000_000,
+          data: Object.fromEntries(
+            Object.entries(data).filter(([name]) =>
+              fields.includes(`data.${name}`),
+            ),
+          ),
+        }),
+        { status: 200 },
+      );
+    });
+
+    const live = await readBuilderCmsEntryLiveState({
+      model: "blog_article",
+      entryId: "builder-entry-1",
+      fieldPaths: ["data.blurb", "__builder.entry.name"],
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(live.values).toMatchObject({
+      "data.title": "Builder title",
+      "data.blurb": "Builder blurb",
+      // An empty body Builder returned, which the save records as such.
+      "__builder.body.blockCount": 0,
+    });
+    const fields =
+      fetchImpl.mock.calls[0]![0].searchParams.get("fields")!.split(",");
+    expect(fields).toEqual(
+      expect.arrayContaining([
+        "data.blurb",
+        "data.blocks",
+        "data.blocksString",
+      ]),
+    );
+    expect(fields).not.toContain("__builder.entry.name");
+  });
+
   it("hydrates an exact entry through MCP with OAuth-only authorization", async () => {
     resolveBuilderRequestAuthorizationMock.mockResolvedValue({
       token: "oauth-access-token",
@@ -3095,7 +3151,7 @@
       }),
     ).resolves.toMatchObject({ state: "found", providerStatus: "mcp_200" });
     const secondPageBody = JSON.parse(
       String((fetchImpl.mock.calls[2]?.[1] as RequestInit).body),
     );
     expect(secondPageBody.params.arguments.offset).toBe(100);
   });
@@ -3150,7 +3206,7 @@
       }),
     ).resolves.toMatchObject({ state: "found" });
     const body = JSON.parse(
       String((fetchImpl.mock.calls[2]?.[1] as RequestInit).body),
     );
     expect(body.params).toMatchObject({
       name: "get_builder_content",
@@ -3571,7 +3627,7 @@
       }),
     ).resolves.toMatchObject({ state: "live", entries: [] });
     const body = JSON.parse(
       String((fetchImpl.mock.calls[2]?.[1] as RequestInit).body),
     );
     expect(body.params).toMatchObject({
       name: "get_builder_content",

templates/content/actions/_builder-cms-read-client.ts

@@ -11,13 +11,16 @@ import type {
   BuilderCmsModelFieldSummary,
   BuilderCmsModelSummary,
   BuilderCmsModelsResponse,
+  DocumentPropertyValue,
 } from "../shared/api.js";
 import {
   builderBlocksHash,
   builderEntryBlocks,
   type BuilderContentEntry,
 } from "../shared/builder-mdx.js";
 import {
+  builderCmsReferenceIdSourceValues,
+  builderEntryHasAutosaves,
   normalizeBuilderCmsApiEntry,
   type BuilderCmsSourceEntry,
 } from "./_builder-cms-source-adapter.js";
@@ -53,6 +56,9 @@ export interface BuilderCmsEntryLiveState {
   lastUpdated: number | string | null;
   blocksHash: string | null;
   id: string | null;
+  /** The entry's source values, normalized as a refresh stores them. */
+  values?: Record<string, DocumentPropertyValue> | null;
+  hasAutosaves?: boolean | null;
 }
 
 export interface BuilderCmsEntryFidelitySummary {
@@ -224,6 +230,7 @@ const BUILDER_CMS_METADATA_ENTRY_FIELD_PATHS = [
   "published",
   "lastUpdated",
   "createdDate",
+  "meta.hasAutosaves",
   "data.title",
   "data.handle",
   "data.url",
@@ -269,7 +276,8 @@ function normalizeBuilderCmsListFieldPath(fieldPath: string) {
   }
   if (
     normalized.includes(".") &&
-    !normalized.toLowerCase().startsWith("data.")
+    !lower.startsWith("data.") &&
+    !BUILDER_CMS_TOP_LEVEL_METADATA_FIELDS.has(lower)
   ) {
     return null;
   }
@@ -319,16 +327,20 @@ export function builderCmsListEntryFields(fieldPaths: readonly string[] = []) {
   return Array.from(fields.values()).join(",");
 }
 
-const BUILDER_CMS_METADATA_ENTRY_FIELDS = builderCmsListEntryFields();
-const BUILDER_CMS_BODY_ENTRY_FIELDS = `${BUILDER_CMS_METADATA_ENTRY_FIELDS},${BUILDER_CMS_HEAVY_BODY_FIELD_PATHS.join(",")}`;
-
-function applyBuilderCmsBodyEntryReadParams(url: URL, publicKey: string) {
+function applyBuilderCmsBodyEntryReadParams(
+  url: URL,
+  publicKey: string,
+  fieldPaths: readonly string[] = [],
+) {
   url.searchParams.set("apiKey", publicKey);
   url.searchParams.set("includeUnpublished", "true");
   url.searchParams.set("enrich", "true");
   url.searchParams.set("noCache", "true");
   url.searchParams.set("cachebust", String(Date.now()));
-  url.searchParams.set("fields", BUILDER_CMS_BODY_ENTRY_FIELDS);
+  url.searchParams.set(
+    "fields",
+    `${builderCmsListEntryFields(fieldPaths)},${BUILDER_CMS_HEAVY_BODY_FIELD_PATHS.join(",")}`,
+  );
 }
 
 function builderContentApiHost() {
@@ -388,10 +400,20 @@ function stringOrNumberFromUnknown(value: unknown) {
   return stringFromUnknown(value);
 }
 
-function liveStateFromBuilderEntry(value: unknown): BuilderCmsEntryLiveState {
+function liveSourceValues(record: Record<string, unknown>, model: string) {
+  const sourceValues = normalizeBuilderCmsApiEntry(record, model)?.sourceValues;
+  return sourceValues
+    ? { ...sourceValues, ...builderCmsReferenceIdSourceValues(record.data) }
+    : null;
+}
+
+function liveStateFromBuilderEntry(
+  value: unknown,
+  model: string,
+): BuilderCmsEntryLiveState {
   if (Array.isArray(value)) {
     return value.length > 0
-      ? liveStateFromBuilderEntry(value[0])
+      ? liveStateFromBuilderEntry(value[0], model)
       : {
           exists: false,
           published: null,
@@ -412,7 +434,7 @@ function liveStateFromBuilderEntry(value: unknown): BuilderCmsEntryLiveState {
 
   const record = value as Record<string, unknown>;
   if (Array.isArray(record.results)) {
-    return liveStateFromBuilderEntry(record.results);
+    return liveStateFromBuilderEntry(record.results, model);
   }
   if (Object.keys(record).length === 0) {
     return {
@@ -456,6 +478,8 @@ function liveStateFromBuilderEntry(value: unknown): BuilderCmsEntryLiveState {
       stringOrNumberFromUnknown(data.updatedAt),
     blocksHash: blocks.length > 0 ? builderBlocksHash(blocks) : null,
     id,
+    values: liveSourceValues(record, model),
+    hasAutosaves: builderEntryHasAutosaves(record),
   };
 }
 
@@ -1744,6 +1768,11 @@ function builderGeneralEntryRequestFailure(error: unknown) {
 export async function readBuilderCmsEntryLiveState(args: {
   model: string;
   entryId: string;
+  /**
+   * Fields a save will write. The public-key read is projected, and a field
+   * it leaves out would read as absent from the live entry.
+   */
+  fieldPaths?: readonly string[];
   expectedSourceSpace?: string | null;
   expectedSourceConnectionId?: string | null;
   requireBoundOAuth?: boolean;
@@ -1793,15 +1822,15 @@ export async function readBuilderCmsEntryLiveState(args: {
     }
     const json = (await response.json()) as unknown;
     const { results } = parseBuilderGeneralQueryDataResponse(json);
-    if (results.length === 0) return liveStateFromBuilderEntry([]);
+    if (results.length === 0) return liveStateFromBuilderEntry([], args.model);
     const entry = normalizeBuilderCmsApiEntry(results[0], args.model);
     if (!entry || entry.id !== args.entryId) {
       fail(
         "Builder CMS live entry read returned an unexpected entry payload.",
         { errorCode: "builder_response_invalid", statusCode: 424 },
       );
     }
-    return liveStateFromBuilderEntry(entry.rawEntry);
+    return liveStateFromBuilderEntry(entry.rawEntry, args.model);
   }
   const publicKey = await resolveBuilderCredential("BUILDER_PUBLIC_KEY");
   if (!publicKey) {
@@ -1816,7 +1845,7 @@ export async function readBuilderCmsEntryLiveState(args: {
     )}`,
     builderContentApiHost(),
   );
-  applyBuilderCmsBodyEntryReadParams(url, publicKey);
+  applyBuilderCmsBodyEntryReadParams(url, publicKey, args.fieldPaths);
 
   const response = await fetchBuilderContentPage({
     fetchImpl: args.fetchImpl ?? fetch,
@@ -1839,7 +1868,7 @@ export async function readBuilderCmsEntryLiveState(args: {
   }
 
   const json = (await response.json()) as unknown;
-  return liveStateFromBuilderEntry(json);
+  return liveStateFromBuilderEntry(json, args.model);
 }
 
 export async function readBuilderCmsContentEntry(args: {

templates/content/actions/_builder-cms-source-adapter.test.ts

@@ -2,6 +2,10 @@ import { describe, expect, it } from "vitest";
 
 import type { ContentDatabaseItem } from "../shared/api";
 import {
+  BUILDER_CMS_BODY_BLOCK_COUNT_KEY,
+  BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+  BUILDER_CMS_ENTRY_NAME_KEY,
+  BUILDER_CMS_HAS_AUTOSAVES_KEY,
   buildBuilderCmsFixtureEntry,
   builderCmsQualifiedId,
   builderCmsSourceFieldKey,
@@ -218,10 +222,54 @@ describe("Builder CMS source adapter", () => {
         "data.handle": "builder-api-title",
         "data.description": "A useful field",
         lastUpdated: "2026-06-08T12:00:00.000Z",
+        [BUILDER_CMS_ENTRY_NAME_KEY]: "Fallback name",
       },
     });
   });
 
+  it("tells an empty body Builder returned apart from a read without the body", () => {
+    const entry = (data: Record<string, unknown>) =>
+      normalizeBuilderCmsApiEntry(
+        { id: "entry-1", published: "published", lastUpdated: 1, data },
+        "blog_article",
+      )?.sourceValues;
+
+    expect(entry({ title: "Title", blocks: [] })).toMatchObject({
+      [BUILDER_CMS_BODY_BLOCK_COUNT_KEY]: 0,
+    });
+    expect(entry({ title: "Title", blocks: [] })).not.toHaveProperty(
+      BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+    );
+    expect(entry({ title: "Title" })).not.toHaveProperty(
+      BUILDER_CMS_BODY_BLOCK_COUNT_KEY,
+    );
+  });
+
+  it("records whether Builder reports unpublished changes on an entry", () => {
+    const entry = (meta: Record<string, unknown>) =>
+      normalizeBuilderCmsApiEntry(
+        {
+          id: "entry-1",
+          published: "published",
+          lastUpdated: 1782328870774,
+          meta,
+          data: { title: "Builder API title" },
+        },
+        "blog_article",
+      )?.sourceValues;
+
+    expect(entry({ hasAutosaves: true })).toMatchObject({
+      [BUILDER_CMS_HAS_AUTOSAVES_KEY]: true,
+    });
+    expect(entry({ hasAutosaves: false })).toMatchObject({
+      [BUILDER_CMS_HAS_AUTOSAVES_KEY]: false,
+    });
+    expect(entry({})).not.toHaveProperty(BUILDER_CMS_HAS_AUTOSAVES_KEY);
+    expect(entry({ hasAutosaves: "yes" })).not.toHaveProperty(
+      BUILDER_CMS_HAS_AUTOSAVES_KEY,
+    );
+  });
+
   it("uses numeric Builder lastUpdated as the row source baseline", () => {
     const lastUpdated = 1782328870774;
     const entry = normalizeBuilderCmsApiEntry(