Re-factor how "internal" EventBus listeners are handled in the viewer

Currently the viewer uses semi-private `EventBus.prototype.{_on, _off}` methods, to try and ensure that all internal viewer state is updated *before* any "external" listeners are invoked.
For all use-cases outside of the viewer, e.g in the integration-tests, the `EventBus.prototype.{on, off}` methods are supposed to be used instead.

Unfortunately this isn't currently enforced in any way, except (hopefully) during review, and generally speaking it's not really possible to prevent the semi-private methods being used (e.g. by third-party users).
Hence this patch adds a new `INTERNAL_EVT` property which is *not* exposed anywhere (neither in the API nor globally), and whose value is generated at build-time, that the viewer uses to mark its `EventBus` listeners are internal.
This allows us to remove the semi-private `EventBus` methods, which helps to simplify that class a little bit.

Author: Snuffleupagus

gulpfile.mjs

@@ -116,6 +116,7 @@ const DEFINES = Object.freeze({
   WORKER_THREAD: false,
   TESTING: undefined,
   COVERAGE: undefined,
+  INTERNAL_EVT: crypto.randomUUID(),
   // The main build targets:
   GENERIC: false,
   MOZCENTRAL: false,

src/display/editor/tools.js

@@ -36,6 +36,7 @@ import {
   stopEvent,
 } from "../display_utils.js";
 import { FloatingToolbar } from "./toolbar.js";
+import { internalOpt } from "../../shared/internal_evt.js";
 
 function bindEvents(obj, element, names) {
   for (const name of names) {
@@ -939,17 +940,21 @@ class AnnotationEditorUIManager {
     this.#signatureManager = signatureManager;
     this.#pdfDocument = pdfDocument;
     this._eventBus = eventBus;
-    eventBus._on("editingaction", this.onEditingAction.bind(this), { signal });
-    eventBus._on("pagechanging", this.onPageChanging.bind(this), { signal });
-    eventBus._on("scalechanging", this.onScaleChanging.bind(this), { signal });
-    eventBus._on("rotationchanging", this.onRotationChanging.bind(this), {
-      signal,
-    });
-    eventBus._on("setpreference", this.onSetPreference.bind(this), { signal });
-    eventBus._on(
+
+    const evtOpts = { signal, ...internalOpt };
+    eventBus.on("editingaction", this.onEditingAction.bind(this), evtOpts);
+    eventBus.on("pagechanging", this.onPageChanging.bind(this), evtOpts);
+    eventBus.on("scalechanging", this.onScaleChanging.bind(this), evtOpts);
+    eventBus.on(
+      "rotationchanging",
+      this.onRotationChanging.bind(this),
+      evtOpts
+    );
+    eventBus.on("setpreference", this.onSetPreference.bind(this), evtOpts);
+    eventBus.on(
       "switchannotationeditorparams",
       evt => this.updateParams(evt.type, evt.value),
-      { signal }
+      evtOpts
     );
     window.addEventListener(
       "pointerdown",
@@ -1222,7 +1227,7 @@ class AnnotationEditorUIManager {
     const { resolve, promise } = Promise.withResolvers();
     const onEditorsRendered = evt => {
       if (evt.pageNumber === pageNumber) {
-        this._eventBus._off("editorsrendered", onEditorsRendered);
+        this._eventBus.off("editorsrendered", onEditorsRendered);
         resolve();
       }
     };

src/shared/internal_evt.js

@@ -0,0 +1,27 @@
+/* Copyright 2026 Mozilla Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Keep this file in sync with `web/internal_evt.js`.
+ */
+
+const INTERNAL_EVT =
+  typeof PDFJSDev !== "undefined" && !PDFJSDev.test("TESTING")
+    ? PDFJSDev.eval("INTERNAL_EVT")
+    : "internalEvent";
+
+const internalOpt = Object.freeze({ internal: INTERNAL_EVT });
+
+export { INTERNAL_EVT, internalOpt };

test/integration/reorganize_pages_spec.mjs

@@ -3556,7 +3556,7 @@ describe("Reorganize Pages View", () => {
           await waitAndClick(page, getThumbnailSelector(2));
 
           const handleMerged = await createPromise(page, resolve => {
-            window.PDFViewerApplication.eventBus._on(
+            window.PDFViewerApplication.eventBus.on(
               "thumbnailsloaded",
               resolve,
               { once: true }
@@ -3628,7 +3628,7 @@ describe("Reorganize Pages View", () => {
           await waitForThumbnailVisible(page, 1);
 
           const handleMerged = await createPromise(page, resolve => {
-            window.PDFViewerApplication.eventBus._on(
+            window.PDFViewerApplication.eventBus.on(
               "thumbnailsloaded",
               resolve,
               { once: true }

web/alt_text_manager.js

@@ -14,6 +14,7 @@
  */
 
 import { DOMSVGFactory } from "pdfjs-lib";
+import { internalOpt } from "./internal_evt.js";
 
 class AltTextManager {
   #clickAC = null;
@@ -170,8 +171,9 @@ class AltTextManager {
     this.#uiManager.removeEditListeners();
 
     this.#resizeAC = new AbortController();
-    this.#eventBus._on("resize", this.#setPosition.bind(this), {
+    this.#eventBus.on("resize", this.#setPosition.bind(this), {
       signal: this.#resizeAC.signal,
+      ...internalOpt,
     });
 
     try {

web/annotation_editor_params.js

@@ -21,6 +21,7 @@ import {
   getRGBA,
   Util,
 } from "pdfjs-lib";
+import { internalOpt } from "./internal_evt.js";
 
 /**
  * @typedef {Object} AnnotationEditorParamsOptions
@@ -155,42 +156,46 @@ class AnnotationEditorParams {
       dispatchEvent("CREATE");
     });
 
-    eventBus._on("annotationeditorparamschanged", evt => {
-      for (const [type, value] of evt.details) {
-        switch (type) {
-          case AnnotationEditorParamsType.FREETEXT_SIZE:
-            editorFreeTextFontSize.value = value;
-            break;
-          case AnnotationEditorParamsType.FREETEXT_COLOR:
-            editorFreeTextColor.value = value;
-            break;
-          case AnnotationEditorParamsType.INK_COLOR:
-            updateInkColor(value);
-            break;
-          case AnnotationEditorParamsType.INK_THICKNESS:
-            editorInkThickness.value = value;
-            break;
-          case AnnotationEditorParamsType.INK_OPACITY:
-            updateInkOpacity(value);
-            break;
-          case AnnotationEditorParamsType.HIGHLIGHT_COLOR:
-            eventBus.dispatch("mainhighlightcolorpickerupdatecolor", {
-              source: this,
-              value,
-            });
-            break;
-          case AnnotationEditorParamsType.HIGHLIGHT_THICKNESS:
-            editorFreeHighlightThickness.value = value;
-            break;
-          case AnnotationEditorParamsType.HIGHLIGHT_FREE:
-            editorFreeHighlightThickness.disabled = !value;
-            break;
-          case AnnotationEditorParamsType.HIGHLIGHT_SHOW_ALL:
-            editorHighlightShowAll.setAttribute("aria-pressed", value);
-            break;
+    eventBus.on(
+      "annotationeditorparamschanged",
+      evt => {
+        for (const [type, value] of evt.details) {
+          switch (type) {
+            case AnnotationEditorParamsType.FREETEXT_SIZE:
+              editorFreeTextFontSize.value = value;
+              break;
+            case AnnotationEditorParamsType.FREETEXT_COLOR:
+              editorFreeTextColor.value = value;
+              break;
+            case AnnotationEditorParamsType.INK_COLOR:
+              updateInkColor(value);
+              break;
+            case AnnotationEditorParamsType.INK_THICKNESS:
+              editorInkThickness.value = value;
+              break;
+            case AnnotationEditorParamsType.INK_OPACITY:
+              updateInkOpacity(value);
+              break;
+            case AnnotationEditorParamsType.HIGHLIGHT_COLOR:
+              eventBus.dispatch("mainhighlightcolorpickerupdatecolor", {
+                source: this,
+                value,
+              });
+              break;
+            case AnnotationEditorParamsType.HIGHLIGHT_THICKNESS:
+              editorFreeHighlightThickness.value = value;
+              break;
+            case AnnotationEditorParamsType.HIGHLIGHT_FREE:
+              editorFreeHighlightThickness.disabled = !value;
+              break;
+            case AnnotationEditorParamsType.HIGHLIGHT_SHOW_ALL:
+              editorHighlightShowAll.setAttribute("aria-pressed", value);
+              break;
+          }
         }
-      }
-    });
+      },
+      internalOpt
+    );
   }
 }
 

web/annotation_layer_builder.js

@@ -35,6 +35,7 @@ import {
   setLayerDimensions,
   Util,
 } from "pdfjs-lib";
+import { internalOpt } from "./internal_evt.js";
 import { PresentationModeState } from "./ui_utils.js";
 
 /**
@@ -75,7 +76,7 @@ class AnnotationLayerBuilder {
 
   #onAppend = null;
 
-  #eventAbortController = null;
+  #eventAC = null;
 
   #linksInjected = false;
 
@@ -190,15 +191,15 @@ class AnnotationLayerBuilder {
     if (this.linkService.isInPresentationMode) {
       this.#updatePresentationModeState(PresentationModeState.FULLSCREEN);
     }
-    if (!this.#eventAbortController) {
-      this.#eventAbortController = new AbortController();
+    if (!this.#eventAC) {
+      this.#eventAC = new AbortController();
 
-      this._eventBus?._on(
+      this._eventBus?.on(
         "presentationmodechanged",
         evt => {
           this.#updatePresentationModeState(evt.state);
         },
-        { signal: this.#eventAbortController.signal }
+        { signal: this.#eventAC.signal, ...internalOpt }
       );
     }
   }
@@ -221,8 +222,8 @@ class AnnotationLayerBuilder {
   cancel() {
     this._cancelled = true;
 
-    this.#eventAbortController?.abort();
-    this.#eventAbortController = null;
+    this.#eventAC?.abort();
+    this.#eventAC = null;
   }
 
   hide(internal = false) {