Add preferred alternatives to problematic terminology, closes #30789

- Add computeInCoordinatingFrame as alias for computeInMasterFrame
- Add coordinator property as alias for master
- Add isCoordinator property as alias for isMaster
- Update documentation to reference preferred alternatives
- Maintain backward compatibility with existing APIs

Author: StarbirdTech

3p/3p.js

@@ -195,6 +195,18 @@ export function computeInMasterFrame(global, taskId, work, cb) {
   });
 }
 
+/**
+ * Preferred alternative to computeInMasterFrame.
+ * @param {!Window} global
+ * @param {string} taskId
+ * @param {function(*)} work
+ * @param {function(*)} cb
+ * @return {undefined}
+ */
+export function computeInCoordinatingFrame(global, taskId, work, cb) {
+  return computeInMasterFrame(global, taskId, work, cb);
+}
+
 /**
  * Validates given data. Throws an exception if the data does not
  * contains a mandatory field. If called with the optional param

3p/ampcontext-integration.js

@@ -1,6 +1,6 @@
 import {dev, user, userAssert} from '#utils/log';
 
-import {computeInMasterFrame} from './3p';
+import {computeInCoordinatingFrame, computeInMasterFrame} from './3p';
 import {AbstractAmpContext} from './ampcontext';
 
 /**
@@ -67,6 +67,11 @@ export class IntegrationAmpContext extends AbstractAmpContext {
     return masterSelection(this.win_, dev().assertString(this.embedType_));
   }
 
+  /** @return {!Window} */
+  get coordinator() {
+    return this.master_();
+  }
+
   /** @return {boolean} */
   get isMaster() {
     return this.isMaster_();
@@ -77,6 +82,11 @@ export class IntegrationAmpContext extends AbstractAmpContext {
     return this.master == this.win_;
   }
 
+  /** @return {boolean} */
+  get isCoordinator() {
+    return this.isMaster_();
+  }
+
   /**
    * @param {number} width
    * @param {number} height
@@ -133,4 +143,15 @@ export class IntegrationAmpContext extends AbstractAmpContext {
   computeInMasterFrame(global, taskId, work, cb) {
     computeInMasterFrame(global, taskId, work, cb);
   }
+
+  /**
+   * Preferred alternative to computeInMasterFrame.
+   * @param {!Window} global
+   * @param {string} taskId
+   * @param {function(*)} work
+   * @param {function(*)} cb
+   */
+  computeInCoordinatingFrame(global, taskId, work, cb) {
+    computeInCoordinatingFrame(global, taskId, work, cb);
+  }
 }

ads/README.md

@@ -281,8 +281,12 @@ documentation with the new behaviors on user's consent choices. You can refer to
 
 To allow ads to bundle HTTP requests across multiple ad units on the same page the object `window.context.master` will contain the window object of the iframe being elected master iframe for the current page. The `window.context.isMaster` property is `true` when the current frame is the master frame.
 
+**Note:** Preferred alternatives are available as `window.context.coordinator` and `window.context.isCoordinator` respectively.
+
 The `computeInMasterFrame` function is designed to make it easy to perform a task only in the master frame and provide the result to all frames. It is also available to custom ad iframes as `window.context.computeInMasterFrame`. See [3p.js](https://github.com/ampproject/amphtml/blob/main/3p/3p.js) for function signature.
 
+**Note:** A preferred alternative is available as `window.context.computeInCoordinatingFrame`.
+
 #### Preconnect and prefetch
 
 Add the JS URLs that an ad **always** fetches or always connects to (if you know the origin but not the path) to [\_config.js](_config.js).

build-system/externs/amp.extern.js

@@ -187,6 +187,8 @@ window.context.sourceUrl;
 window.context.experimentToggles;
 window.context.master;
 window.context.isMaster;
+window.context.coordinator;
+window.context.isCoordinator;
 window.context.ampcontextVersion;
 window.context.ampcontextFilepath;
 window.context.canary;