feat(collab): use three-way merge for component refresh updates

Replace broad refresh/rebuild node diffs with explicit field-level
update_nodes operations so concurrent local edits are preserved.
Reject whole-node update paths on the backend and add regression
tests for refresh, rebuild, and outputs merge behavior.

Author: HzaRashid

src/backend/base/langflow/api/utils/collab/operations.py

@@ -26,6 +26,7 @@
     from langflow.services.storage.service import StorageService
 
 
+TEMPLATE_PATH_LENGTH = 3
 TEMPLATE_FIELD_PATH_LENGTH = 4
 TEMPLATE_FIELD_VALUE_PATH_LENGTH = 5
 
@@ -113,32 +114,17 @@ def _remove_api_keys_from_inner_node(inner_node: dict[str, Any]) -> None:
 def _sanitize_update_node_value(update: dict[str, Any], flow_data: dict[str, Any]) -> None:
     path = tuple(update["path"])
     value = update["value"]
-    if path == ("data",):
-        if isinstance(value, dict):
-            _remove_api_keys_from_node_data(value)
+    if len(path) <= TEMPLATE_PATH_LENGTH or path[:TEMPLATE_PATH_LENGTH] != ("data", "node", "template"):
         return
-    if path == ("data", "node"):
-        if isinstance(value, dict):
-            _remove_api_keys_from_inner_node(value)
-        return
-    if path == ("data", "node", "template"):
-        if isinstance(value, dict):
-            remove_api_keys_from_template(value)
-        return
-    if (
-        len(path) == TEMPLATE_FIELD_PATH_LENGTH
-        and path[:3] == ("data", "node", "template")
-        and isinstance(path[3], str)
-    ):
-        if is_api_key_template_field(value):
-            value["value"] = None
+
+    template_field_name = path[TEMPLATE_PATH_LENGTH]
+    if len(path) == TEMPLATE_FIELD_PATH_LENGTH and is_api_key_template_field(value):
+        value["value"] = None
         return
     if (
         len(path) == TEMPLATE_FIELD_VALUE_PATH_LENGTH
-        and path[:3] == ("data", "node", "template")
-        and isinstance(path[3], str)
         and path[4] == "value"
-        and _is_api_key_template_value_update(flow_data, update["id"], path[3])
+        and _is_api_key_template_value_update(flow_data, update["id"], template_field_name)
     ):
         update["value"] = None
 

src/backend/tests/unit/services/test_flow_operations.py

@@ -387,7 +387,7 @@ def test_delete_nodes_removes_incident_edges(self):
     def test_delete_nodes_rejects_missing_ids(self):
         flow_data = _base_flow_data()
 
-        with pytest.raises(FlowOperationValidationError, match="node was not in base flow"):
+        with pytest.raises(FlowOperationValidationError, match="does not exist in the original flow"):
             apply_flow_operations(flow_data, [{"type": "delete_nodes", "ids": ["missing"]}])
 
     def test_delete_edges_ignores_missing_ids(self):
@@ -432,7 +432,7 @@ def test_rejects_update_node_added_earlier_in_same_batch(self):
         flow_data = _base_flow_data()
         new_node = {"id": "c", "type": "generic", "position": {"x": 0, "y": 0}, "data": {}}
 
-        with pytest.raises(FlowOperationValidationError, match="cannot update node added earlier"):
+        with pytest.raises(FlowOperationValidationError, match="does not exist in the original flow"):
             apply_flow_operations(
                 flow_data,
                 [
@@ -448,7 +448,7 @@ def test_rejects_delete_node_added_earlier_in_same_batch(self):
         flow_data = _base_flow_data()
         new_node = {"id": "c", "type": "generic", "position": {"x": 0, "y": 0}, "data": {}}
 
-        with pytest.raises(FlowOperationValidationError, match="node was not in base flow"):
+        with pytest.raises(FlowOperationValidationError, match="does not exist in the original flow"):
             apply_flow_operations(
                 flow_data,
                 [
@@ -520,6 +520,34 @@ def test_rejects_invalid_update_node_paths(self, path, message):
                 [{"type": "update_nodes", "updates": [{"id": "a", "op": "set_field", "path": path, "value": 1}]}],
             )
 
+    @pytest.mark.parametrize("path", [["data"], ["data", "node"], ["data", "node", "template"]])
+    def test_rejects_broad_node_refresh_roots(self, path):
+        flow_data = _base_flow_data()
+        flow_data["nodes"][0]["data"]["node"] = {"template": {}, "outputs": []}
+
+        with pytest.raises(FlowOperationValidationError, match="cannot update entire node data objects"):
+            apply_flow_operations(
+                flow_data,
+                [{"type": "update_nodes", "updates": [{"id": "a", "op": "set_field", "path": path, "value": {}}]}],
+            )
+
+    def test_update_nodes_allows_merged_outputs_array(self):
+        flow_data = _base_flow_data()
+        flow_data["nodes"][0]["data"]["node"] = {"template": {}, "outputs": []}
+        outputs = [{"name": "result", "display_name": "Result", "types": ["Message"]}]
+        result = apply_flow_operations(
+            flow_data,
+            [
+                {
+                    "type": "update_nodes",
+                    "updates": [{"id": "a", "op": "set_field", "path": ["data", "node", "outputs"], "value": outputs}],
+                }
+            ],
+        )
+
+        stored = next(node for node in result.flow_data["nodes"] if node["id"] == "a")
+        assert stored["data"]["node"]["outputs"] == outputs
+
     def test_rejects_array_delete(self):
         flow_data = _base_flow_data()
         flow_data["nodes"][0]["data"]["items"] = ["a", "b"]

src/frontend/src/CustomNodes/helpers/__tests__/mutate-template.test.ts

@@ -0,0 +1,118 @@
+import type { UseMutationResult } from "@tanstack/react-query";
+import type { APIClassType, ResponseErrorDetailAPI } from "@/types/api";
+import type { AllNodeType } from "@/types/flow";
+import { mutateTemplate } from "../mutate-template";
+
+const mockSetNode = jest.fn();
+let mockLatestNode: AllNodeType | undefined;
+
+jest.mock("@/constants/constants", () => ({
+  SAVE_DEBOUNCE_TIME: 0,
+}));
+
+jest.mock("@/stores/flowStore", () => ({
+  __esModule: true,
+  default: {
+    getState: () => ({
+      getNode: () => mockLatestNode,
+      setNode: mockSetNode,
+    }),
+  },
+}));
+
+describe("mutateTemplate", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+    mockLatestNode = {
+      id: "node-1",
+      type: "genericNode",
+      position: { x: 0, y: 0 },
+      data: {
+        id: "node-1",
+        type: "TestComponent",
+        node: {
+          display_name: "Test Component",
+          template: {
+            prompt: { value: "local prompt", show: true },
+            other: { value: "local other" },
+          },
+          outputs: [{ name: "result", display_name: "Result", types: ["str"] }],
+        },
+      },
+    } as unknown as AllNodeType;
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("applies refresh responses through explicit three-way collaboration updates", async () => {
+    const baseNode = {
+      display_name: "Test Component",
+      template: {
+        prompt: { value: "base prompt", show: true },
+        other: { value: "base other" },
+      },
+      outputs: [{ name: "result", display_name: "Result", types: ["str"] }],
+    } as unknown as APIClassType;
+    const postTemplateValue = {
+      mutateAsync: jest.fn().mockResolvedValue({
+        template: {
+          prompt: { value: "generated prompt", show: false },
+          other: { value: "generated other" },
+        },
+        outputs: [
+          {
+            name: "result",
+            display_name: "Generated Result",
+            types: ["Message"],
+          },
+        ],
+        last_updated: "2026-06-08T00:00:00Z",
+      }),
+    } as unknown as UseMutationResult<
+      APIClassType | undefined,
+      ResponseErrorDetailAPI,
+      unknown
+    >;
+    const setNodeClass = jest.fn();
+    const setErrorData = jest.fn();
+
+    await mutateTemplate(
+      "next prompt",
+      "node-1",
+      baseNode,
+      setNodeClass,
+      postTemplateValue,
+      setErrorData,
+      "prompt",
+    );
+    await jest.runOnlyPendingTimersAsync();
+
+    const updatedNode = mockSetNode.mock.calls[0][1] as AllNodeType;
+    const mutationOptions = mockSetNode.mock.calls[0][4];
+
+    expect(updatedNode.data.node!.template.prompt.value).toBe("local prompt");
+    expect(updatedNode.data.node!.template.prompt.show).toBe(false);
+    expect(updatedNode.data.node!.template.other.value).toBe("local other");
+    expect(mutationOptions.collaborationUpdates).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          path: ["data", "node", "template", "prompt", "show"],
+          value: false,
+        }),
+        expect.objectContaining({
+          path: ["data", "node", "outputs"],
+        }),
+      ]),
+    );
+    expect(
+      mutationOptions.collaborationUpdates.some(
+        (update) => update.path.join(".") === "data.node.template",
+      ),
+    ).toBe(false);
+    expect(setNodeClass).toHaveBeenCalledWith(updatedNode.data.node);
+    expect(setErrorData).not.toHaveBeenCalled();
+  });
+});

src/frontend/src/CustomNodes/helpers/mutate-template.ts

@@ -1,23 +1,75 @@
 import type { UseMutationResult } from "@tanstack/react-query";
 import { cloneDeep, debounce } from "lodash";
 import { SAVE_DEBOUNCE_TIME } from "@/constants/constants";
-import i18n from "../../i18n";
+import {
+  applyNodeFieldUpdates,
+  buildThreeWayComponentNodeUpdates,
+  type ThreeWayComponentDiffPolicy,
+} from "@/hooks/flows/flow-operation-diff";
+import useFlowStore from "@/stores/flowStore";
 import type { APIClassType, ResponseErrorDetailAPI } from "@/types/api";
+import type { AllNodeType } from "@/types/flow";
+import type { NodeFieldPath } from "@/types/flow-operations";
+import i18n from "../../i18n";
 import { updateHiddenOutputs } from "./update-hidden-outputs";
 
 // Map to store debounced functions for each node ID + parameter combination
 const debouncedFunctions = new Map<string, ReturnType<typeof debounce>>();
 
+type PostTemplateValueVariables = {
+  value: unknown;
+  field_name?: string;
+  tool_mode?: boolean;
+  is_refresh?: boolean;
+};
+
+type PostTemplateValueMutation = UseMutationResult<
+  APIClassType | undefined,
+  ResponseErrorDetailAPI,
+  PostTemplateValueVariables
+>;
+
+function pathStartsWith(path: NodeFieldPath, prefix: string[]): boolean {
+  return prefix.every((segment, index) => path[index] === segment);
+}
+
+function buildRefreshPolicy(
+  parameterName?: string,
+  toolMode?: boolean,
+  isRefresh?: boolean,
+): ThreeWayComponentDiffPolicy {
+  return {
+    generatedWinsOnOverlap: (path) => {
+      if (parameterName === "tool_mode" && toolMode !== undefined) {
+        return (
+          pathStartsWith(path, ["data", "node", "tool_mode"]) ||
+          pathStartsWith(path, ["data", "node", "outputs"])
+        );
+      }
+      if (
+        parameterName &&
+        (isRefresh ||
+          parameterName.includes("auth") ||
+          parameterName.includes("connection"))
+      ) {
+        return pathStartsWith(path, [
+          "data",
+          "node",
+          "template",
+          parameterName,
+        ]);
+      }
+      return false;
+    },
+  };
+}
+
 export const mutateTemplate = async (
   newValue,
   nodeId: string,
   node: APIClassType,
   setNodeClass,
-  postTemplateValue: UseMutationResult<
-    APIClassType | undefined,
-    ResponseErrorDetailAPI,
-    any
-  >,
+  postTemplateValue: PostTemplateValueMutation,
   setErrorData,
   parameterName?: string,
   callback?: () => void,
@@ -35,11 +87,7 @@ export const mutateTemplate = async (
           newValue,
           node: APIClassType,
           setNodeClass,
-          postTemplateValue: UseMutationResult<
-            APIClassType | undefined,
-            ResponseErrorDetailAPI,
-            any
-          >,
+          postTemplateValue: PostTemplateValueMutation,
           setErrorData,
           parameterName?: string,
           callback?: () => void,
@@ -56,14 +104,45 @@ export const mutateTemplate = async (
             });
             if (newTemplate) {
               newNode.template = newTemplate.template;
-              newNode.outputs = updateHiddenOutputs(
-                newNode.outputs ?? [],
-                newTemplate.outputs ?? [],
-              );
+              newNode.outputs = newTemplate.outputs;
               newNode.tool_mode = toolMode ?? node.tool_mode;
               newNode.last_updated = newTemplate.last_updated;
+              const localGraphNode = useFlowStore.getState().getNode(nodeId);
+              const localNode =
+                (localGraphNode?.data?.node as APIClassType | undefined) ??
+                node;
+              const collaborationUpdates = buildThreeWayComponentNodeUpdates(
+                nodeId,
+                node as unknown as Record<string, unknown>,
+                localNode as unknown as Record<string, unknown>,
+                newNode as unknown as Record<string, unknown>,
+                buildRefreshPolicy(parameterName, toolMode, isRefresh),
+              );
               try {
-                setNodeClass(newNode);
+                if (localGraphNode) {
+                  const mergedGraphNode = applyNodeFieldUpdates(
+                    localGraphNode as unknown as Record<string, unknown>,
+                    collaborationUpdates,
+                  ) as unknown as AllNodeType;
+                  useFlowStore
+                    .getState()
+                    .setNode(
+                      nodeId,
+                      mergedGraphNode as typeof localGraphNode,
+                      true,
+                      undefined,
+                      collaborationUpdates.length > 0
+                        ? { collaborationUpdates }
+                        : undefined,
+                    );
+                  setNodeClass(mergedGraphNode.data.node);
+                } else {
+                  newNode.outputs = updateHiddenOutputs(
+                    node.outputs ?? [],
+                    newTemplate.outputs ?? [],
+                  );
+                  setNodeClass(newNode);
+                }
               } catch (e) {
                 if (e instanceof Error && e.message === "Node not found") {
                   console.error("Node not found");