Finish BuilderSync publication flow

.changeset/bright-pages-persist.md

@@ -0,0 +1,5 @@
+---
+"@agent-native/toolkit": patch
+---
+
+Allow the first local edit in a newly synced empty collaborative document to reach the host application's canonical save path.

.changeset/quiet-owls-relay.md

@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Route Builder authorization callbacks for Netlify previews through the immutable deployment URL while returning popup status to the visible preview.

packages/core/src/deploy/build.ts

@@ -3705,6 +3705,14 @@ export default bundle;
       "virtual:agents-bundle": agentsBundleModuleSource,
     },
     replace: {
+      // Netlify exposes DEPLOY_ID only while building. Embed it into the Nitro
+      // function so preview OAuth relays can target this immutable deployment
+      // even though the value is unavailable in the function runtime.
+      "process.env.AGENT_NATIVE_BUILD_ID": JSON.stringify(
+        process.env.DEPLOY_ID?.trim() ||
+          process.env.AGENT_NATIVE_BUILD_ID?.trim() ||
+          "",
+      ),
       "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(
         process.env.GA_MEASUREMENT_ID?.trim() || "",
       ),

packages/core/src/server/builder-browser.spec.ts

@@ -25,6 +25,8 @@ import {
   getBuilderBrowserStatusForEvent,
   isBuilderBranchingEnabled,
   resolveBuilderCallbackReturnUrl,
+  resolveBuilderPreviewRelayParentOrigin,
+  resolveBuilderPreviewRelayTargetOrigin,
   runBuilderAgent,
   signBuilderConnectToken,
   signBuilderCallbackState,
@@ -585,6 +587,74 @@ describe("Builder callback CSRF state", () => {
       ).toBeNull();
     });
 
+    it("uses the immutable Netlify deploy URL as the relay destination", () => {
+      process.env.AGENT_NATIVE_BUILD_ID = "6a62ed72f518f00008436fa3";
+      process.env.SITE_NAME = "agent-native-content";
+
+      expect(
+        resolveBuilderPreviewRelayTargetOrigin(
+          "https://deploy-preview-2382--agent-native-content.netlify.app",
+        ),
+      ).toBe(
+        "https://6a62ed72f518f00008436fa3--agent-native-content.netlify.app",
+      );
+    });
+
+    it("rejects an immutable Netlify deploy URL for a different site", () => {
+      process.env.AGENT_NATIVE_BUILD_ID = "6a62ed72f518f00008436fa3";
+      process.env.SITE_NAME = "different-site";
+      const previewOrigin =
+        "https://deploy-preview-2382--agent-native-content.netlify.app";
+
+      expect(resolveBuilderPreviewRelayTargetOrigin(previewOrigin)).toBe(
+        previewOrigin,
+      );
+    });
+
+    it("leaves non-Netlify preview origins unchanged", () => {
+      process.env.AGENT_NATIVE_BUILD_ID = "6a62ed72f518f00008436fa3";
+      process.env.SITE_NAME = "agent-native-content";
+      const previewOrigin = "https://preview-example.builderio.xyz";
+
+      expect(resolveBuilderPreviewRelayTargetOrigin(previewOrigin)).toBe(
+        previewOrigin,
+      );
+    });
+
+    it("keeps the visible preview opener separate from the immutable relay target", () => {
+      expect(
+        resolveBuilderPreviewRelayParentOrigin({
+          openerOrigin:
+            "https://deploy-preview-2382--agent-native-content.netlify.app",
+          targetOrigin:
+            "https://6a62ed72f518f00008436fa3--agent-native-content.netlify.app",
+        }),
+      ).toBe("https://deploy-preview-2382--agent-native-content.netlify.app");
+    });
+
+    it("falls back to the signed relay target for an unsafe opener", () => {
+      const targetOrigin =
+        "https://6a62ed72f518f00008436fa3--agent-native-content.netlify.app";
+      expect(
+        resolveBuilderPreviewRelayParentOrigin({
+          openerOrigin: "https://attacker.example",
+          targetOrigin,
+        }),
+      ).toBe(targetOrigin);
+    });
+
+    it("rejects an unsigned Netlify opener for a different site", () => {
+      const targetOrigin =
+        "https://6a62ed72f518f00008436fa3--agent-native-content.netlify.app";
+      expect(
+        resolveBuilderPreviewRelayParentOrigin({
+          openerOrigin:
+            "https://deploy-preview-2382--attacker-site.netlify.app",
+          targetOrigin,
+        }),
+      ).toBe(targetOrigin);
+    });
+
     it("returns users to the preview opener after a gateway callback", () => {
       process.env.NODE_ENV = "production";
       process.env.AGENT_NATIVE_WORKSPACE = "1";

packages/core/src/server/builder-browser.ts

@@ -36,6 +36,10 @@ const BUILDER_RELAY_PURPOSE = "builder-preview-callback-relay";
 const BUILDER_RELAY_STATE_VERSION = 1;
 const BUILDER_RELAY_TTL_MS = 10 * 60 * 1000;
 const BUILDER_RELAY_REQUEST_SKEW_MS = 2 * 60 * 1000;
+const IMMUTABLE_NETLIFY_RELAY_HOST =
+  /^(?<deploy>[a-f0-9]{24})--(?<site>[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.netlify\.app$/;
+const NETLIFY_DEPLOY_PREVIEW_HOST =
+  /^deploy-preview-\d+--(?<site>[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.netlify\.app$/;
 
 export interface BuilderPreviewRelayState {
   v: 1;
@@ -165,6 +169,45 @@ export function isTrustedBuilderRelayTargetOrigin(value: string): boolean {
     )
   );
 }
+
+/**
+ * Netlify's deploy-preview alias is convenient for people but mutable, so it
+ * must never be the signed relay destination. The deploy builder embeds
+ * Netlify's DEPLOY_ID into the Nitro server bundle, while SITE_NAME remains
+ * available to Functions at runtime. Use that pair only when it
+ * identifies the same site as the visible preview alias; otherwise preserve
+ * the visible origin so callback validation fails closed.
+ */
+export function resolveBuilderPreviewRelayTargetOrigin(
+  previewOrigin: string,
+): string {
+  let previewUrl: URL;
+  try {
+    previewUrl = new URL(previewOrigin);
+  } catch {
+    return previewOrigin;
+  }
+  const previewMatch = NETLIFY_DEPLOY_PREVIEW_HOST.exec(
+    previewUrl.hostname.toLowerCase(),
+  );
+  if (!previewMatch?.groups?.site) return previewOrigin;
+
+  const buildId = process.env.AGENT_NATIVE_BUILD_ID?.trim().toLowerCase();
+  const siteName = process.env.SITE_NAME?.trim().toLowerCase();
+  if (
+    !buildId ||
+    !siteName ||
+    !/^[a-f0-9]{24}$/.test(buildId) ||
+    siteName !== previewMatch.groups.site
+  ) {
+    return previewOrigin;
+  }
+
+  const immutableOrigin = `https://${buildId}--${siteName}.netlify.app`;
+  return IMMUTABLE_NETLIFY_RELAY_HOST.test(new URL(immutableOrigin).hostname)
+    ? immutableOrigin
+    : previewOrigin;
+}
 export function signBuilderPreviewRelayState(input: {
   ownerEmail: string;
   targetOrigin: string;
@@ -1228,6 +1271,39 @@ export function resolveSafePreviewUrl(
   return getBuilderBrowserOriginForEvent(event);
 }
 
+export function resolveBuilderPreviewRelayParentOrigin(options: {
+  openerOrigin?: string | null;
+  targetOrigin: string;
+}): string {
+  if (!options.openerOrigin) return options.targetOrigin;
+  let openerUrl: URL;
+  let targetUrl: URL;
+  try {
+    openerUrl = new URL(options.openerOrigin);
+    targetUrl = new URL(options.targetOrigin);
+  } catch {
+    return options.targetOrigin;
+  }
+  if (
+    openerUrl.origin !== options.openerOrigin ||
+    !isSafeBuilderRelayTargetOrigin(openerUrl.origin)
+  ) {
+    return options.targetOrigin;
+  }
+  if (openerUrl.origin === targetUrl.origin) return openerUrl.origin;
+
+  const openerMatch = NETLIFY_DEPLOY_PREVIEW_HOST.exec(
+    openerUrl.hostname.toLowerCase(),
+  );
+  const targetMatch = IMMUTABLE_NETLIFY_RELAY_HOST.exec(
+    targetUrl.hostname.toLowerCase(),
+  );
+  return openerMatch?.groups?.site &&
+    openerMatch.groups.site === targetMatch?.groups?.site
+    ? openerUrl.origin
+    : options.targetOrigin;
+}
+
 export function resolveBuilderCallbackReturnUrl(options: {
   event: H3Event;
   openerOrigin?: string | null;

packages/core/src/server/core-routes-plugin.ts

@@ -127,6 +127,8 @@ import {
   resolveBuilderCallbackReturnUrl,
   getBuilderBrowserStatusForEvent,
   resolveBuilderBranchProjectId,
+  resolveBuilderPreviewRelayParentOrigin,
+  resolveBuilderPreviewRelayTargetOrigin,
   resolveSafePreviewUrl,
   runBuilderAgent,
   signBuilderCallbackState,
@@ -2049,7 +2051,8 @@ export function createCoreRoutesPlugin(
             try {
               relay = signBuilderPreviewRelayState({
                 ownerEmail,
-                targetOrigin: previewOrigin,
+                targetOrigin:
+                  resolveBuilderPreviewRelayTargetOrigin(previewOrigin),
                 basePath: getAppBasePath(),
               });
             } catch (err) {
@@ -2422,6 +2425,13 @@ export function createCoreRoutesPlugin(
               );
             }
 
+            const relayOpenerOrigin =
+              requestUrl.searchParams.get(BUILDER_OPENER_PARAM);
+            const relayParentOrigin = resolveBuilderPreviewRelayParentOrigin({
+              openerOrigin: relayOpenerOrigin,
+              targetOrigin: relayPayload.targetOrigin,
+            });
+
             const privateKey = requestUrl.searchParams.get("p-key");
             const publicKey = requestUrl.searchParams.get("api-key");
             if (!privateKey || !publicKey) {
@@ -2433,7 +2443,7 @@ export function createCoreRoutesPlugin(
               );
               return createBuilderBrowserCallbackErrorPage(
                 "Builder didn't return credentials. Restart the connect flow from settings.",
-                { parentOrigin: relayPayload.targetOrigin },
+                { parentOrigin: relayParentOrigin },
               );
             }
 
@@ -2489,7 +2499,7 @@ export function createCoreRoutesPlugin(
                 "text/html; charset=utf-8",
               );
               return createBuilderBrowserCallbackErrorPage(message, {
-                parentOrigin: relayPayload.targetOrigin,
+                parentOrigin: relayParentOrigin,
               });
             }
 
@@ -2499,8 +2509,8 @@ export function createCoreRoutesPlugin(
               "text/html; charset=utf-8",
             );
             return createBuilderBrowserCallbackPage(
-              `${relayPayload.targetOrigin}${relayPayload.basePath || "/"}`,
-              { parentOrigin: relayPayload.targetOrigin },
+              `${relayParentOrigin}${relayPayload.basePath || "/"}`,
+              { parentOrigin: relayParentOrigin },
             );
           }
 

packages/toolkit/src/editor/useCollabReconcile.concurrent.spec.ts

@@ -4,6 +4,7 @@ import { useEditor, type Editor } from "@tiptap/react";
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import * as Y from "yjs";
 
 import { createRichMarkdownExtensions } from "./RichMarkdownEditor.js";
 import { useCollabReconcile, getEditorMarkdown } from "./useCollabReconcile.js";
@@ -179,6 +180,52 @@ function render(
 }
 
 describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
+  it("persists the first local edit after a synced empty collaborative document", async () => {
+    const captured: Captured = {
+      editor: null,
+      emitted: [],
+      setContentCalls: 0,
+    };
+
+    function EmptyDocumentHarness() {
+      const guardsRef = React.useRef<ReturnType<
+        typeof useCollabReconcile
+      > | null>(null);
+      const ydoc = React.useMemo(() => new Y.Doc(), []);
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({ dialect: "gfm", ydoc }),
+        onUpdate: ({ editor, transaction }) => {
+          const guards = guardsRef.current;
+          if (!guards || guards.shouldIgnoreUpdate(transaction)) return;
+          const markdown = getEditorMarkdown(editor);
+          if (!guards.registerEmitted(markdown)) return;
+          captured.emitted.push(markdown);
+        },
+      });
+      captured.editor = editor;
+      guardsRef.current = useCollabReconcile({
+        editor,
+        ydoc,
+        collabSynced: true,
+        value: "",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+        getMarkdown: getEditorMarkdown,
+      });
+      return React.createElement("div", null);
+    }
+
+    act(() => root.render(React.createElement(EmptyDocumentHarness)));
+    await flush();
+
+    act(() => {
+      captured.editor?.commands.insertContent("First persisted edit");
+    });
+    await flush();
+
+    expect(captured.emitted).toContain("First persisted edit");
+  });
+
   it("does not seed until initial collab sync has completed", async () => {
     const { captured, Harness } = makeCollabSeedHarness();
 
@@ -330,6 +377,36 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     expect(results).toEqual([true]);
   });
 
+  it("allows a local edit that arrives as a synced empty document finishes mounting", async () => {
+    const results: boolean[] = [];
+
+    function Probe() {
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({ dialect: "gfm" }),
+        content: "",
+      });
+      const fakeYdoc = { clientID: 1, getXmlFragment: () => ({ length: 0 }) };
+      const guards = useCollabReconcile({
+        editor,
+        ydoc: fakeYdoc as never,
+        collabSynced: true,
+        value: "",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+      });
+      // Runs during render, before the passive empty-seed completion effect.
+      if (editor && results.length === 0) {
+        results.push(guards.shouldIgnoreUpdate(editor.state.tr));
+      }
+      return React.createElement("div", null);
+    }
+
+    act(() => root.render(React.createElement(Probe)));
+    await flush();
+
+    expect(results).toEqual([false]);
+  });
+
   it("refuses to persist an empty doc in collab mode (registerEmitted guard)", async () => {
     // Directly exercise the guard contract: in collab mode an empty markdown
     // string must not be registered/persisted (would clobber stored content