Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 379 insertions, 0 deletions

diff --git a/devtools/server/actors/highlighters.js b/devtools/server/actors/highlighters.js
new file mode 100644
index 0000000000..a25bae4781
--- /dev/null
+++ b/devtools/server/actors/highlighters.js
@@ -0,0 +1,379 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { Actor } = require("devtools/shared/protocol");
+const { customHighlighterSpec } = require("devtools/shared/specs/highlighters");
+
+const EventEmitter = require("devtools/shared/event-emitter");
+
+loader.lazyRequireGetter(
+  this,
+  "isXUL",
+  "resource://devtools/server/actors/highlighters/utils/markup.js",
+  true
+);
+
+/**
+ * The registration mechanism for highlighters provides a quick way to
+ * have modular highlighters instead of a hard coded list.
+ */
+const highlighterTypes = new Map();
+
+/**
+ * Returns `true` if a highlighter for the given `typeName` is registered,
+ * `false` otherwise.
+ */
+const isTypeRegistered = typeName => highlighterTypes.has(typeName);
+exports.isTypeRegistered = isTypeRegistered;
+
+/**
+ * Registers a given constructor as highlighter, for the `typeName` given.
+ */
+const registerHighlighter = (typeName, modulePath) => {
+  if (highlighterTypes.has(typeName)) {
+    throw Error(`${typeName} is already registered.`);
+  }
+
+  highlighterTypes.set(typeName, modulePath);
+};
+
+/**
+ * CustomHighlighterActor is a generic Actor that instantiates a custom implementation of
+ * a highlighter class given its type name which must be registered in `highlighterTypes`.
+ * CustomHighlighterActor proxies calls to methods of the highlighter class instance:
+ * constructor(targetActor), show(node, options), hide(), destroy()
+ */
+exports.CustomHighlighterActor = class CustomHighligherActor extends Actor {
+  /**
+   * Create a highlighter instance given its typeName.
+   */
+  constructor(parent, typeName) {
+    super(parent.conn, customHighlighterSpec);
+
+    this._parent = parent;
+
+    const modulePath = highlighterTypes.get(typeName);
+    if (!modulePath) {
+      const list = [...highlighterTypes.keys()];
+
+      throw new Error(`${typeName} isn't a valid highlighter class (${list})`);
+    }
+
+    const constructor = require(modulePath)[typeName];
+    // The assumption is that custom highlighters either need the canvasframe
+    // container to append their elements and thus a non-XUL window or they have
+    // to define a static XULSupported flag that indicates that the highlighter
+    // supports XUL windows. Otherwise, bail out.
+    if (!isXUL(this._parent.targetActor.window) || constructor.XULSupported) {
+      this._highlighterEnv = new HighlighterEnvironment();
+      this._highlighterEnv.initFromTargetActor(parent.targetActor);
+      this._highlighter = new constructor(this._highlighterEnv);
+      if (this._highlighter.on) {
+        this._highlighter.on(
+          "highlighter-event",
+          this._onHighlighterEvent.bind(this)
+        );
+      }
+    } else {
+      throw new Error(
+        "Custom " + typeName + "highlighter cannot be created in a XUL window"
+      );
+    }
+  }
+
+  destroy() {
+    super.destroy();
+    this.finalize();
+    this._parent = null;
+  }
+
+  release() {}
+
+  /**
+   * Get current instance of the highlighter object.
+   */
+  get instance() {
+    return this._highlighter;
+  }
+
+  /**
+   * Show the highlighter.
+   * This calls through to the highlighter instance's |show(node, options)|
+   * method.
+   *
+   * Most custom highlighters are made to highlight DOM nodes, hence the first
+   * NodeActor argument (NodeActor as in devtools/server/actor/inspector).
+   * Note however that some highlighters use this argument merely as a context
+   * node: The SelectorHighlighter for instance uses it as a base node to run the
+   * provided CSS selector on.
+   *
+   * @param {NodeActor} The node to be highlighted
+   * @param {Object} Options for the custom highlighter
+   * @return {Boolean} True, if the highlighter has been successfully shown
+   */
+  show(node, options) {
+    if (!this._highlighter) {
+      return null;
+    }
+
+    const rawNode = node?.rawNode;
+
+    return this._highlighter.show(rawNode, options);
+  }
+
+  /**
+   * Hide the highlighter if it was shown before
+   */
+  hide() {
+    if (this._highlighter) {
+      this._highlighter.hide();
+    }
+  }
+
+  /**
+   * Upon receiving an event from the highlighter, forward it to the client.
+   */
+  _onHighlighterEvent(data) {
+    this.emit("highlighter-event", data);
+  }
+
+  /**
+   * Destroy the custom highlighter implementation.
+   * This method is called automatically just before the actor is destroyed.
+   */
+  finalize() {
+    if (this._highlighter) {
+      if (this._highlighter.off) {
+        this._highlighter.off(
+          "highlighter-event",
+          this._onHighlighterEvent.bind(this)
+        );
+      }
+      this._highlighter.destroy();
+      this._highlighter = null;
+    }
+
+    if (this._highlighterEnv) {
+      this._highlighterEnv.destroy();
+      this._highlighterEnv = null;
+    }
+  }
+};
+
+/**
+ * The HighlighterEnvironment is an object that holds all the required data for
+ * highlighters to work: the window, docShell, event listener target, ...
+ * It also emits "will-navigate", "navigate" and "window-ready" events,
+ * similarly to the WindowGlobalTargetActor.
+ *
+ * It can be initialized either from a WindowGlobalTargetActor (which is the
+ * most frequent way of using it, since highlighters are initialized by
+ * CustomHighlighterActor, which has a targetActor reference).
+ * It can also be initialized just with a window object (which is
+ * useful for when a highlighter is used outside of the devtools server context.
+ */
+
+class HighlighterEnvironment extends EventEmitter {
+  initFromTargetActor(targetActor) {
+    this._targetActor = targetActor;
+
+    const relayedEvents = [
+      "window-ready",
+      "navigate",
+      "will-navigate",
+      "use-simple-highlighters-updated",
+    ];
+
+    this._abortController = new AbortController();
+    const signal = this._abortController.signal;
+    for (const event of relayedEvents) {
+      this._targetActor.on(event, this.relayTargetEvent.bind(this, event), {
+        signal,
+      });
+    }
+  }
+
+  initFromWindow(win) {
+    this._win = win;
+
+    // We need a progress listener to know when the window will navigate/has
+    // navigated.
+    const self = this;
+    this.listener = {
+      QueryInterface: ChromeUtils.generateQI([
+        "nsIWebProgressListener",
+        "nsISupportsWeakReference",
+      ]),
+
+      onStateChange(progress, request, flag) {
+        const isStart = flag & Ci.nsIWebProgressListener.STATE_START;
+        const isStop = flag & Ci.nsIWebProgressListener.STATE_STOP;
+        const isWindow = flag & Ci.nsIWebProgressListener.STATE_IS_WINDOW;
+        const isDocument = flag & Ci.nsIWebProgressListener.STATE_IS_DOCUMENT;
+
+        if (progress.DOMWindow !== win) {
+          return;
+        }
+
+        if (isDocument && isStart) {
+          // One of the earliest events that tells us a new URI is being loaded
+          // in this window.
+          self.emit("will-navigate", {
+            window: win,
+            isTopLevel: true,
+          });
+        }
+        if (isWindow && isStop) {
+          self.emit("navigate", {
+            window: win,
+            isTopLevel: true,
+          });
+        }
+      },
+    };
+
+    this.webProgress.addProgressListener(
+      this.listener,
+      Ci.nsIWebProgress.NOTIFY_STATE_WINDOW |
+        Ci.nsIWebProgress.NOTIFY_STATE_DOCUMENT
+    );
+  }
+
+  get isInitialized() {
+    return this._win || this._targetActor;
+  }
+
+  get isXUL() {
+    return isXUL(this.window);
+  }
+
+  get useSimpleHighlightersForReducedMotion() {
+    return this._targetActor?._useSimpleHighlightersForReducedMotion;
+  }
+
+  get window() {
+    if (!this.isInitialized) {
+      throw new Error(
+        "Initialize HighlighterEnvironment with a targetActor " +
+          "or window first"
+      );
+    }
+    const win = this._targetActor ? this._targetActor.window : this._win;
+
+    try {
+      return Cu.isDeadWrapper(win) ? null : win;
+    } catch (e) {
+      // win is null
+      return null;
+    }
+  }
+
+  get document() {
+    return this.window && this.window.document;
+  }
+
+  get docShell() {
+    return this.window && this.window.docShell;
+  }
+
+  get webProgress() {
+    return (
+      this.docShell &&
+      this.docShell
+        .QueryInterface(Ci.nsIInterfaceRequestor)
+        .getInterface(Ci.nsIWebProgress)
+    );
+  }
+
+  /**
+   * Get the right target for listening to events on the page.
+   * - If the environment was initialized from a WindowGlobalTargetActor
+   *   *and* if we're in the Browser Toolbox (to inspect Firefox Desktop): the
+   *   targetActor is the RootActor, in which case, the window property can be
+   *   used to listen to events.
+   * - With Firefox Desktop, the targetActor is a WindowGlobalTargetActor, and we use
+   *   the chromeEventHandler which gives us a target we can use to listen to
+   *   events, even from nested iframes.
+   * - If the environment was initialized from a window, we also use the
+   *   chromeEventHandler.
+   */
+  get pageListenerTarget() {
+    if (this._targetActor && this._targetActor.isRootActor) {
+      return this.window;
+    }
+    return this.docShell && this.docShell.chromeEventHandler;
+  }
+
+  relayTargetEvent(name, data) {
+    this.emit(name, data);
+  }
+
+  destroy() {
+    if (this._abortController) {
+      this._abortController.abort();
+      this._abortController = null;
+    }
+
+    // In case the environment was initialized from a window, we need to remove
+    // the progress listener.
+    if (this._win) {
+      try {
+        this.webProgress.removeProgressListener(this.listener);
+      } catch (e) {
+        // Which may fail in case the window was already destroyed.
+      }
+    }
+
+    this._targetActor = null;
+    this._win = null;
+  }
+}
+exports.HighlighterEnvironment = HighlighterEnvironment;
+
+// This constant object is created to make the calls array more
+// readable. Otherwise, linting rules force some array defs to span 4
+// lines instead, which is much harder to parse.
+const HIGHLIGHTERS = {
+  accessible: "devtools/server/actors/highlighters/accessible",
+  boxModel: "devtools/server/actors/highlighters/box-model",
+  cssGrid: "devtools/server/actors/highlighters/css-grid",
+  cssTransform: "devtools/server/actors/highlighters/css-transform",
+  eyeDropper: "devtools/server/actors/highlighters/eye-dropper",
+  flexbox: "devtools/server/actors/highlighters/flexbox",
+  fonts: "devtools/server/actors/highlighters/fonts",
+  geometryEditor: "devtools/server/actors/highlighters/geometry-editor",
+  measuringTool: "devtools/server/actors/highlighters/measuring-tool",
+  pausedDebugger: "devtools/server/actors/highlighters/paused-debugger",
+  rulers: "devtools/server/actors/highlighters/rulers",
+  selector: "devtools/server/actors/highlighters/selector",
+  shapes: "devtools/server/actors/highlighters/shapes",
+  tabbingOrder: "devtools/server/actors/highlighters/tabbing-order",
+  viewportSize: "devtools/server/actors/highlighters/viewport-size",
+};
+
+// Each array in this array is called as register(arr[0], arr[1]).
+const registerCalls = [
+  ["AccessibleHighlighter", HIGHLIGHTERS.accessible],
+  ["BoxModelHighlighter", HIGHLIGHTERS.boxModel],
+  ["CssGridHighlighter", HIGHLIGHTERS.cssGrid],
+  ["CssTransformHighlighter", HIGHLIGHTERS.cssTransform],
+  ["EyeDropper", HIGHLIGHTERS.eyeDropper],
+  ["FlexboxHighlighter", HIGHLIGHTERS.flexbox],
+  ["FontsHighlighter", HIGHLIGHTERS.fonts],
+  ["GeometryEditorHighlighter", HIGHLIGHTERS.geometryEditor],
+  ["MeasuringToolHighlighter", HIGHLIGHTERS.measuringTool],
+  ["PausedDebuggerOverlay", HIGHLIGHTERS.pausedDebugger],
+  ["RulersHighlighter", HIGHLIGHTERS.rulers],
+  ["SelectorHighlighter", HIGHLIGHTERS.selector],
+  ["ShapesHighlighter", HIGHLIGHTERS.shapes],
+  ["TabbingOrderHighlighter", HIGHLIGHTERS.tabbingOrder],
+  ["ViewportSizeHighlighter", HIGHLIGHTERS.viewportSize],
+];
+
+// Register each highlighter above.
+registerCalls.forEach(arr => {
+  registerHighlighter(arr[0], arr[1]);
+});