@eva/plugin-worker 2.0.1-beta.26 → 2.0.1-beta.28

package/dist/plugin-worker.esm.js

@@ -1,14 +1,35 @@
 import { Ticker, UPDATE_PRIORITY, Point, warn, ExtensionType, extensions, Container, DOMAdapter, WebWorkerAdapter } from 'pixi.js';
 import EventEmitter from 'eventemitter3';
 
+/**
+ * 事件时钟类
+ *
+ * EventsTicker 用于在指针静止时自动触发指针事件，
+ * 确保即使指针不移动，移动的对象也能正确触发悬停测试。
+ * 这对于实现动态对象的鼠标交互至关重要。
+ *
+ * @example
+ * ```typescript
+ * EventsTicker.init(eventSystem);
+ * EventsTicker.addTickerListener();
+ * EventsTicker.pointerMoved(); // 标记指针已移动
+ * ```
+ *
+ * @since 7.2.0
+ */
 class EventsTickerClass {
     constructor() {
+        /** 触发模拟事件的频率（毫秒） */
         this.interactionFrequency = 10;
         this._deltaTime = 0;
         this._didMove = false;
         this._tickerAdded = false;
         this._pauseUpdate = true;
     }
+    /**
+     * Initializes the event ticker.
+     * @param events - The event system.
+     */
     init(events) {
         this.removeTickerListener();
         this.events = events;
@@ -18,12 +39,14 @@ class EventsTickerClass {
         this._tickerAdded = false;
         this._pauseUpdate = true;
     }
+    /** Whether to pause the update checks or not. */
     get pauseUpdate() {
         return this._pauseUpdate;
     }
     set pauseUpdate(paused) {
         this._pauseUpdate = paused;
     }
+    /** Adds the ticker listener. */
     addTickerListener() {
         if (this._tickerAdded || !this.domElement) {
             return;
@@ -31,6 +54,7 @@ class EventsTickerClass {
         Ticker.system.add(this._tickerUpdate, this, UPDATE_PRIORITY.INTERACTION);
         this._tickerAdded = true;
     }
+    /** Removes the ticker listener. */
     removeTickerListener() {
         if (!this._tickerAdded) {
             return;
@@ -38,17 +62,21 @@ class EventsTickerClass {
         Ticker.system.remove(this._tickerUpdate, this);
         this._tickerAdded = false;
     }
+    /** Sets flag to not fire extra events when the user has already moved there mouse */
     pointerMoved() {
         this._didMove = true;
     }
+    /** Updates the state of interactive objects. */
     _update() {
         if (!this.domElement || this._pauseUpdate) {
             return;
         }
+        // if the user move the mouse this check has already been done using the mouse move!
         if (this._didMove) {
             this._didMove = false;
             return;
         }
+        // eslint-disable-next-line dot-notation
         const rootPointerEvent = this.events['_rootPointerEvent'];
         if (this.events.supportsTouchEvents && rootPointerEvent.pointerType === 'touch') {
             return;
@@ -60,6 +88,13 @@ class EventsTickerClass {
             pointerId: rootPointerEvent.pointerId,
         }));
     }
+    /**
+     * Updates the state of interactive objects if at least {@link interactionFrequency}
+     * milliseconds have passed since the last invocation.
+     *
+     * Invoked by a throttled ticker update from {@link Ticker.system}.
+     * @param ticker - The throttled ticker.
+     */
     _tickerUpdate(ticker) {
         this._deltaTime += ticker.deltaTime;
         if (this._deltaTime < this.interactionFrequency) {
@@ -71,17 +106,64 @@ class EventsTickerClass {
 }
 const EventsTicker = new EventsTickerClass();
 
+/**
+ * 联合事件类
+ *
+ * FederatedEvent 是一个兼容 DOM 的合成事件实现，
+ * 代表原始的 FederatedEvent 或原生 DOM 事件进行传播。
+ * 它提供了统一的事件接口，抹平了不同浏览器和设备之间的差异。
+ *
+ * 主要特性：
+ * - 兼容 DOM Event API
+ * - 支持事件冒泡和捕获
+ * - 提供事件传播控制
+ * - 记录事件路径
+ *
+ * @typeParam N - 持有的原生事件类型
+ *
+ * @example
+ * ```typescript
+ * sprite.on('pointerdown', (event: FederatedPointerEvent) => {
+ *   console.log('Clicked at:', event.global.x, event.global.y);
+ *   event.stopPropagation(); // 停止事件传播
+ * });
+ * ```
+ */
 class FederatedEvent {
+    /**
+     * @param manager - The event boundary which manages this event. Propagation can only occur
+     *  within the boundary's jurisdiction.
+     */
     constructor(manager) {
+        /** 事件是否冒泡（仅在传播前设置有效） */
         this.bubbles = true;
+        /** @deprecated 自 7.0.0 起弃用 */
         this.cancelBubble = true;
+        /**
+         * 事件是否可以被取消
+         * @readonly
+         */
         this.cancelable = false;
+        /**
+         * Flag added for compatibility with DOM {@code Event}. It is not used in the Federated Events
+         * API.
+         * @see https://dom.spec.whatwg.org/#dom-event-composed
+         */
         this.composed = false;
+        /** Flags whether the default response of the user agent was prevent through this event. */
         this.defaultPrevented = false;
+        /**
+         * The propagation phase.
+         * @default {@link FederatedEvent.NONE}
+         */
         this.eventPhase = FederatedEvent.prototype.NONE;
+        /** Flags whether propagation was stopped. */
         this.propagationStopped = false;
+        /** Flags whether propagation was immediately stopped. */
         this.propagationImmediatelyStopped = false;
+        /** The coordinates of the event relative to the nearest DOM layer. This is a non-standard property. */
         this.layer = new Point();
+        /** The coordinates of the event relative to the DOM document. This is a non-standard property. */
         this.page = new Point();
         this.NONE = 0;
         this.CAPTURING_PHASE = 1;
@@ -89,147 +171,373 @@ class FederatedEvent {
         this.BUBBLING_PHASE = 3;
         this.manager = manager;
     }
+    /** @readonly */
     get layerX() {
         return this.layer.x;
     }
+    /** @readonly */
     get layerY() {
         return this.layer.y;
     }
+    /** @readonly */
     get pageX() {
         return this.page.x;
     }
+    /** @readonly */
     get pageY() {
         return this.page.y;
     }
+    /**
+     * Fallback for the deprecated @code{InteractionEvent.data}.
+     * @deprecated since 7.0.0
+     */
     get data() {
         return this;
     }
+    /** The propagation path for this event. Alias for {@link EventBoundary.propagationPath}. */
     composedPath() {
+        // Find the propagation path if it isn't cached or if the target has changed since since
+        // the last evaluation.
         if (this.manager && (!this.path || this.path[this.path.length - 1] !== this.target)) {
             this.path = this.target ? this.manager.propagationPath(this.target) : [];
         }
         return this.path;
     }
+    /**
+     * Unimplemented method included for implementing the DOM interface {@code Event}. It will throw an {@code Error}.
+     * @deprecated
+     * @param _type
+     * @param _bubbles
+     * @param _cancelable
+     */
     initEvent(_type, _bubbles, _cancelable) {
         throw new Error('initEvent() is a legacy DOM API. It is not implemented in the Federated Events API.');
     }
+    /**
+     * Unimplemented method included for implementing the DOM interface {@code UIEvent}. It will throw an {@code Error}.
+     * @deprecated
+     * @param _typeArg
+     * @param _bubblesArg
+     * @param _cancelableArg
+     * @param _viewArg
+     * @param _detailArg
+     */
     initUIEvent(_typeArg, _bubblesArg, _cancelableArg, _viewArg, _detailArg) {
         throw new Error('initUIEvent() is a legacy DOM API. It is not implemented in the Federated Events API.');
     }
+    /** Prevent default behavior of PixiJS and the user agent. */
     preventDefault() {
         if (this.nativeEvent instanceof Event && this.nativeEvent.cancelable) {
             this.nativeEvent.preventDefault();
         }
         this.defaultPrevented = true;
     }
+    /**
+     * Stop this event from propagating to any addition listeners, including on the
+     * {@link FederatedEventTarget.currentTarget currentTarget} and also the following
+     * event targets on the propagation path.
+     */
     stopImmediatePropagation() {
         this.propagationImmediatelyStopped = true;
     }
+    /**
+     * Stop this event from propagating to the next {@link FederatedEventTarget}. The rest of the listeners
+     * on the {@link FederatedEventTarget.currentTarget currentTarget} will still be notified.
+     */
     stopPropagation() {
         this.propagationStopped = true;
     }
 }
 
+/**
+ * A {@link FederatedEvent} for mouse events.
+ * @memberof events
+ */
 class FederatedMouseEvent extends FederatedEvent {
     constructor() {
         super(...arguments);
+        /** The coordinates of the mouse event relative to the canvas. */
         this.client = new Point();
+        /** The movement in this pointer relative to the last `mousemove` event. */
         this.movement = new Point();
+        /** The offset of the pointer coordinates w.r.t. target Container in world space. This is not supported at the moment. */
         this.offset = new Point();
+        /** The pointer coordinates in world space. */
         this.global = new Point();
+        /**
+         * The pointer coordinates in the renderer's {@link Renderer.screen screen}. This has slightly
+         * different semantics than native PointerEvent screenX/screenY.
+         */
         this.screen = new Point();
     }
+    /** @readonly */
     get clientX() {
         return this.client.x;
     }
+    /** @readonly */
     get clientY() {
         return this.client.y;
     }
+    /**
+     * Alias for {@link FederatedMouseEvent.clientX this.clientX}.
+     * @readonly
+     */
     get x() {
         return this.clientX;
     }
+    /**
+     * Alias for {@link FederatedMouseEvent.clientY this.clientY}.
+     * @readonly
+     */
     get y() {
         return this.clientY;
     }
+    /** @readonly */
     get movementX() {
         return this.movement.x;
     }
+    /** @readonly */
     get movementY() {
         return this.movement.y;
     }
+    /** @readonly */
     get offsetX() {
         return this.offset.x;
     }
+    /** @readonly */
     get offsetY() {
         return this.offset.y;
     }
+    /** @readonly */
     get globalX() {
         return this.global.x;
     }
+    /** @readonly */
     get globalY() {
         return this.global.y;
     }
+    /**
+     * The pointer coordinates in the renderer's screen. Alias for {@code screen.x}.
+     * @readonly
+     */
     get screenX() {
         return this.screen.x;
     }
+    /**
+     * The pointer coordinates in the renderer's screen. Alias for {@code screen.y}.
+     * @readonly
+     */
     get screenY() {
         return this.screen.y;
     }
+    /**
+     * This will return the local coordinates of the specified container for this InteractionData
+     * @param {Container} container - The Container that you would like the local
+     *  coords off
+     * @param {PointData} point - A Point object in which to store the value, optional (otherwise
+     *  will create a new point)
+     * @param {PointData} globalPos - A Point object containing your custom global coords, optional
+     *  (otherwise will use the current global coords)
+     * @returns - A point containing the coordinates of the InteractionData position relative
+     *  to the Container
+     */
     getLocalPosition(container, point, globalPos) {
         return container.worldTransform.applyInverse(globalPos || this.global, point);
     }
+    /**
+     * Whether the modifier key was pressed when this event natively occurred.
+     * @param key - The modifier key.
+     */
     getModifierState(key) {
         return 'getModifierState' in this.nativeEvent && this.nativeEvent.getModifierState(key);
     }
+    /**
+     * Not supported.
+     * @param _typeArg
+     * @param _canBubbleArg
+     * @param _cancelableArg
+     * @param _viewArg
+     * @param _detailArg
+     * @param _screenXArg
+     * @param _screenYArg
+     * @param _clientXArg
+     * @param _clientYArg
+     * @param _ctrlKeyArg
+     * @param _altKeyArg
+     * @param _shiftKeyArg
+     * @param _metaKeyArg
+     * @param _buttonArg
+     * @param _relatedTargetArg
+     * @deprecated since 7.0.0
+     */
+    // eslint-disable-next-line max-params
     initMouseEvent(_typeArg, _canBubbleArg, _cancelableArg, _viewArg, _detailArg, _screenXArg, _screenYArg, _clientXArg, _clientYArg, _ctrlKeyArg, _altKeyArg, _shiftKeyArg, _metaKeyArg, _buttonArg, _relatedTargetArg) {
         throw new Error('Method not implemented.');
     }
 }
 
+/**
+ * A {@link FederatedEvent} for pointer events.
+ * @memberof events
+ */
 class FederatedPointerEvent extends FederatedMouseEvent {
     constructor() {
         super(...arguments);
+        /**
+         * The width of the pointer's contact along the x-axis, measured in CSS pixels.
+         * radiusX of TouchEvents will be represented by this value.
+         * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/width
+         */
         this.width = 0;
+        /**
+         * The height of the pointer's contact along the y-axis, measured in CSS pixels.
+         * radiusY of TouchEvents will be represented by this value.
+         * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/height
+         */
         this.height = 0;
+        /**
+         * Indicates whether or not the pointer device that created the event is the primary pointer.
+         * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary
+         */
         this.isPrimary = false;
     }
+    // Only included for completeness for now
     getCoalescedEvents() {
         if (this.type === 'pointermove' || this.type === 'mousemove' || this.type === 'touchmove') {
             return [this];
         }
         return [];
     }
+    // Only included for completeness for now
     getPredictedEvents() {
         throw new Error('getPredictedEvents is not supported!');
     }
 }
 
+/**
+ * A {@link FederatedEvent} for wheel events.
+ * @memberof events
+ */
 class FederatedWheelEvent extends FederatedMouseEvent {
     constructor() {
         super(...arguments);
+        /** Units specified in pixels. */
         this.DOM_DELTA_PIXEL = 0;
+        /** Units specified in lines. */
         this.DOM_DELTA_LINE = 1;
+        /** Units specified in pages. */
         this.DOM_DELTA_PAGE = 2;
     }
 }
+/** Units specified in pixels. */
 FederatedWheelEvent.DOM_DELTA_PIXEL = 0;
+/** Units specified in lines. */
 FederatedWheelEvent.DOM_DELTA_LINE = 1;
+/** Units specified in pages. */
 FederatedWheelEvent.DOM_DELTA_PAGE = 2;
 
+// The maximum iterations used in propagation. This prevent infinite loops.
 const PROPAGATION_LIMIT = 2048;
 const tempHitLocation = new Point();
 const tempLocalMapping = new Point();
+/**
+ * Event boundaries are "barriers" where events coming from an upstream scene are modified before downstream propagation.
+ *
+ * ## Root event boundary
+ *
+ * The {@link EventSystem#rootBoundary rootBoundary} handles events coming from the &lt;canvas /&gt;.
+ * {@link EventSystem} handles the normalization from native {@link https://dom.spec.whatwg.org/#event Events}
+ * into {@link FederatedEvent FederatedEvents}. The rootBoundary then does the hit-testing and event dispatch
+ * for the upstream normalized event.
+ *
+ * ## Additional event boundaries
+ *
+ * An additional event boundary may be desired within an application's scene graph. For example, if a portion of the scene is
+ * is flat with many children at one level - a spatial hash maybe needed to accelerate hit testing. In this scenario, the
+ * container can be detached from the scene and glued using a custom event boundary.
+ *
+ * ```ts
+ * import { Container } from 'pixi.js';
+ * import { EventBoundary } from 'pixi.js';
+ * import { SpatialHash } from 'pixi-spatial-hash';
+ *
+ * class HashedHitTestingEventBoundary
+ * {
+ *     private spatialHash: SpatialHash;
+ *
+ *     constructor(scene: Container, spatialHash: SpatialHash)
+ *     {
+ *         super(scene);
+ *         this.spatialHash = spatialHash;
+ *     }
+ *
+ *     hitTestRecursive(...)
+ *     {
+ *         // TODO: If target === this.rootTarget, then use spatial hash to get a
+ *         // list of possible children that match the given (x,y) coordinates.
+ *     }
+ * }
+ *
+ * class VastScene extends Container
+ * {
+ *     protected eventBoundary: EventBoundary;
+ *     protected scene: Container;
+ *     protected spatialHash: SpatialHash;
+ *
+ *     constructor()
+ *     {
+ *         this.scene = new Container();
+ *         this.spatialHash = new SpatialHash();
+ *         this.eventBoundary = new HashedHitTestingEventBoundary(this.scene, this.spatialHash);
+ *
+ *         // Populate this.scene with a ton of children, while updating this.spatialHash
+ *     }
+ * }
+ * ```
+ * @memberof events
+ */
 class EventBoundary {
+    /**
+     * @param rootTarget - The holder of the event boundary.
+     */
     constructor(rootTarget) {
+        /**
+         * Emits events after they were dispatched into the scene graph.
+         *
+         * This can be used for global events listening, regardless of the scene graph being used. It should
+         * not be used by interactive libraries for normal use.
+         *
+         * Special events that do not bubble all the way to the root target are not emitted from here,
+         * e.g. pointerenter, pointerleave, click.
+         */
         this.dispatch = new EventEmitter();
+        /**
+         * This flag would emit `pointermove`, `touchmove`, and `mousemove` events on all Containers.
+         *
+         * The `moveOnAll` semantics mirror those of earlier versions of PixiJS. This was disabled in favor of
+         * the Pointer Event API's approach.
+         */
         this.moveOnAll = false;
+        /** Enables the global move events. `globalpointermove`, `globaltouchmove`, and `globalmousemove` */
         this.enableGlobalMoveEvents = true;
+        /**
+         * State object for mapping methods.
+         * @see EventBoundary#trackingData
+         */
         this.mappingState = {
             trackingData: {},
         };
+        /**
+         * The event pool maps event constructors to an free pool of instances of those specific events.
+         * @see EventBoundary#allocateEvent
+         * @see EventBoundary#freeEvent
+         */
         this.eventPool = new Map();
+        /** Every interactive element gathered from the scene. Only used in `pointermove` */
         this._allInteractiveElements = [];
+        /** Every element that passed the hit test. Only used in `pointermove` */
         this._hitElements = [];
+        /** Whether or not to collect all the interactive elements from the scene. Enabled in `pointermove` */
         this._isPointerMoveEvent = false;
         this.rootTarget = rootTarget;
         this.hitPruneFn = this.hitPruneFn.bind(this);
@@ -251,6 +559,18 @@ class EventBoundary {
         this.addEventMapping('pointerupoutside', this.mapPointerUpOutside);
         this.addEventMapping('wheel', this.mapWheel);
     }
+    /**
+     * Adds an event mapping for the event `type` handled by `fn`.
+     *
+     * Event mappings can be used to implement additional or custom events. They take an event
+     * coming from the upstream scene (or directly from the {@link EventSystem}) and dispatch new downstream events
+     * generally trickling down and bubbling up to {@link EventBoundary.rootTarget this.rootTarget}.
+     *
+     * To modify the semantics of existing events, the built-in mapping methods of EventBoundary should be overridden
+     * instead.
+     * @param type - The type of upstream event to map.
+     * @param fn - The mapping method. The context of this function must be bound manually, if desired.
+     */
     addEventMapping(type, fn) {
         if (!this.mappingTable[type]) {
             this.mappingTable[type] = [];
@@ -261,12 +581,21 @@ class EventBoundary {
         });
         this.mappingTable[type].sort((a, b) => a.priority - b.priority);
     }
+    /**
+     * Dispatches the given event
+     * @param e - The event to dispatch.
+     * @param type - The type of event to dispatch. Defaults to `e.type`.
+     */
     dispatchEvent(e, type) {
         e.propagationStopped = false;
         e.propagationImmediatelyStopped = false;
         this.propagate(e, type);
         this.dispatch.emit(type || e.type, e);
     }
+    /**
+     * Maps the given upstream event through the event boundary and propagates it downstream.
+     * @param e - The event to map.
+     */
     mapEvent(e) {
         if (!this.rootTarget) {
             return;
@@ -278,21 +607,39 @@ class EventBoundary {
             }
         }
         else {
+            // #if _DEBUG
             warn(`[EventBoundary]: Event mapping not defined for ${e.type}`);
+            // #endif
         }
     }
+    /**
+     * Finds the Container that is the target of a event at the given coordinates.
+     *
+     * The passed (x,y) coordinates are in the world space above this event boundary.
+     * @param x - The x coordinate of the event.
+     * @param y - The y coordinate of the event.
+     */
     hitTest(x, y) {
         EventsTicker.pauseUpdate = true;
+        // if we are using global move events, we need to hit test the whole scene graph
         const useMove = this._isPointerMoveEvent && this.enableGlobalMoveEvents;
         const fn = useMove ? 'hitTestMoveRecursive' : 'hitTestRecursive';
         const invertedPath = this[fn](this.rootTarget, this.rootTarget.eventMode, tempHitLocation.set(x, y), this.hitTestFn, this.hitPruneFn);
         return invertedPath && invertedPath[0];
     }
+    /**
+     * Propagate the passed event from from {@link EventBoundary.rootTarget this.rootTarget} to its
+     * target {@code e.target}.
+     * @param e - The event to propagate.
+     * @param type - The type of event to propagate. Defaults to `e.type`.
+     */
     propagate(e, type) {
         if (!e.target) {
+            // This usually occurs when the scene graph is not interactive.
             return;
         }
         const composedPath = e.composedPath();
+        // Capturing phase
         e.eventPhase = e.CAPTURING_PHASE;
         for (let i = 0, j = composedPath.length - 1; i < j; i++) {
             e.currentTarget = composedPath[i];
@@ -300,11 +647,13 @@ class EventBoundary {
             if (e.propagationStopped || e.propagationImmediatelyStopped)
                 return;
         }
+        // At target phase
         e.eventPhase = e.AT_TARGET;
         e.currentTarget = e.target;
         this.notifyTarget(e, type);
         if (e.propagationStopped || e.propagationImmediatelyStopped)
             return;
+        // Bubbling phase
         e.eventPhase = e.BUBBLING_PHASE;
         for (let i = composedPath.length - 2; i >= 0; i--) {
             e.currentTarget = composedPath[i];
@@ -313,11 +662,21 @@ class EventBoundary {
                 return;
         }
     }
+    /**
+     * Emits the event {@code e} to all interactive containers. The event is propagated in the bubbling phase always.
+     *
+     * This is used in the `globalpointermove` event.
+     * @param e - The emitted event.
+     * @param type - The listeners to notify.
+     * @param targets - The targets to notify.
+     */
     all(e, type, targets = this._allInteractiveElements) {
         if (targets.length === 0)
             return;
         e.eventPhase = e.BUBBLING_PHASE;
         const events = Array.isArray(type) ? type : [type];
+        // loop through all interactive elements and notify them of the event
+        // loop through targets backwards
         for (let i = targets.length - 1; i >= 0; i--) {
             events.forEach(event => {
                 e.currentTarget = targets[i];
@@ -325,6 +684,11 @@ class EventBoundary {
             });
         }
     }
+    /**
+     * Finds the propagation path from {@link EventBoundary.rootTarget rootTarget} to the passed
+     * {@code target}. The last element in the path is {@code target}.
+     * @param target - The target to find the propagation path to.
+     */
     propagationPath(target) {
         const propagationPath = [target];
         for (let i = 0; i < PROPAGATION_LIMIT && target !== this.rootTarget && target.parent; i++) {
@@ -339,6 +703,7 @@ class EventBoundary {
     }
     hitTestMoveRecursive(currentTarget, eventMode, location, testFn, pruneFn, ignore = false) {
         let shouldReturn = false;
+        // only bail out early if it is not interactive
         if (this._interactivePrune(currentTarget))
             return null;
         if (currentTarget.eventMode === 'dynamic' || eventMode === 'dynamic') {
@@ -350,15 +715,21 @@ class EventBoundary {
                 const child = children[i];
                 const nestedHit = this.hitTestMoveRecursive(child, this._isInteractive(eventMode) ? eventMode : child.eventMode, location, testFn, pruneFn, ignore || pruneFn(currentTarget, location));
                 if (nestedHit) {
+                    // Its a good idea to check if a child has lost its parent.
+                    // this means it has been removed whilst looping so its best
                     if (nestedHit.length > 0 && !nestedHit[nestedHit.length - 1].parent) {
                         continue;
                     }
+                    // Only add the current hit-test target to the hit-test chain if the chain
+                    // has already started (i.e. the event target has been found) or if the current
+                    // target is interactive (i.e. it becomes the event target).
                     const isInteractive = currentTarget.isInteractive();
                     if (nestedHit.length > 0 || isInteractive) {
                         if (isInteractive)
                             this._allInteractiveElements.push(currentTarget);
                         nestedHit.push(currentTarget);
                     }
+                    // store all hit elements to be returned once we have traversed the whole tree
                     if (this._hitElements.length === 0)
                         this._hitElements = nestedHit;
                     shouldReturn = true;
@@ -369,22 +740,43 @@ class EventBoundary {
         const isInteractiveTarget = currentTarget.isInteractive();
         if (isInteractiveTarget && isInteractiveTarget)
             this._allInteractiveElements.push(currentTarget);
+        // we don't carry on hit testing something once we have found a hit,
+        // now only care about gathering the interactive elements
         if (ignore || this._hitElements.length > 0)
             return null;
         if (shouldReturn)
             return this._hitElements;
+        // Finally, hit test this Container itself.
         if (isInteractiveMode && !pruneFn(currentTarget, location) && testFn(currentTarget, location)) {
+            // The current hit-test target is the event's target only if it is interactive. Otherwise,
+            // the first interactive ancestor will be the event's target.
             return isInteractiveTarget ? [currentTarget] : [];
         }
         return null;
     }
+    /**
+     * Recursive implementation for {@link EventBoundary.hitTest hitTest}.
+     * @param currentTarget - The Container that is to be hit tested.
+     * @param eventMode - The event mode for the `currentTarget` or one of its parents.
+     * @param location - The location that is being tested for overlap.
+     * @param testFn - Callback that determines whether the target passes hit testing. This callback
+     *  can assume that `pruneFn` failed to prune the container.
+     * @param pruneFn - Callback that determiness whether the target and all of its children
+     *  cannot pass the hit test. It is used as a preliminary optimization to prune entire subtrees
+     *  of the scene graph.
+     * @returns An array holding the hit testing target and all its ancestors in order. The first element
+     *  is the target itself and the last is {@link EventBoundary.rootTarget rootTarget}. This is the opposite
+     *  order w.r.t. the propagation path. If no hit testing target is found, null is returned.
+     */
     hitTestRecursive(currentTarget, eventMode, location, testFn, pruneFn) {
+        // Attempt to prune this Container and its subtree as an optimization.
         if (this._interactivePrune(currentTarget) || pruneFn(currentTarget, location)) {
             return null;
         }
         if (currentTarget.eventMode === 'dynamic' || eventMode === 'dynamic') {
             EventsTicker.pauseUpdate = false;
         }
+        // Find a child that passes the hit testing and return one, if any.
         if (currentTarget.interactiveChildren && currentTarget.children) {
             const children = currentTarget.children;
             const relativeLocation = location;
@@ -392,9 +784,14 @@ class EventBoundary {
                 const child = children[i];
                 const nestedHit = this.hitTestRecursive(child, this._isInteractive(eventMode) ? eventMode : child.eventMode, relativeLocation, testFn, pruneFn);
                 if (nestedHit) {
+                    // Its a good idea to check if a child has lost its parent.
+                    // this means it has been removed whilst looping so its best
                     if (nestedHit.length > 0 && !nestedHit[nestedHit.length - 1].parent) {
                         continue;
                     }
+                    // Only add the current hit-test target to the hit-test chain if the chain
+                    // has already started (i.e. the event target has been found) or if the current
+                    // target is interactive (i.e. it becomes the event target).
                     const isInteractive = currentTarget.isInteractive();
                     if (nestedHit.length > 0 || isInteractive)
                         nestedHit.push(currentTarget);
@@ -404,7 +801,10 @@ class EventBoundary {
         }
         const isInteractiveMode = this._isInteractive(eventMode);
         const isInteractiveTarget = currentTarget.isInteractive();
+        // Finally, hit test this Container itself.
         if (isInteractiveMode && testFn(currentTarget, location)) {
+            // The current hit-test target is the event's target only if it is interactive. Otherwise,
+            // the first interactive ancestor will be the event's target.
             return isInteractiveTarget ? [currentTarget] : [];
         }
         return null;
@@ -413,17 +813,28 @@ class EventBoundary {
         return int === 'static' || int === 'dynamic';
     }
     _interactivePrune(container) {
+        // If container is a mask, invisible, or not renderable then it cannot be hit directly.
         if (!container || !container.visible || !container.renderable || !container.measurable) {
             return true;
         }
+        // If this Container is none then it cannot be hit by anything.
         if (container.eventMode === 'none') {
             return true;
         }
+        // If this Container is passive and it has no interactive children then it cannot be hit
         if (container.eventMode === 'passive' && !container.interactiveChildren) {
             return true;
         }
         return false;
     }
+    /**
+     * Checks whether the container or any of its children cannot pass the hit test at all.
+     *
+     * {@link EventBoundary}'s implementation uses the {@link Container.hitArea hitArea}
+     * and {@link Container._maskEffect} for pruning.
+     * @param container - The container to prune.
+     * @param location - The location to test for overlap.
+     */
     hitPruneFn(container, location) {
         if (container.hitArea) {
             container.worldTransform.applyInverse(location, tempLocalMapping);
@@ -444,8 +855,15 @@ class EventBoundary {
         }
         return false;
     }
+    /**
+     * Checks whether the container passes hit testing for the given location.
+     * @param container - The container to test.
+     * @param location - The location to test for overlap.
+     * @returns - Whether `container` passes hit testing for `location`.
+     */
     hitTestFn(container, location) {
         var _a;
+        // If the container failed pruning with a hitArea, then it must pass it.
         if (container.hitArea) {
             return true;
         }
@@ -453,14 +871,24 @@ class EventBoundary {
             container.worldTransform.applyInverse(location, tempLocalMapping);
             return container.containsPoint(tempLocalMapping);
         }
+        // TODO: Should we hit test based on bounds?
         return false;
     }
+    /**
+     * Notify all the listeners to the event's `currentTarget`.
+     *
+     * If the `currentTarget` contains the property `on<type>`, then it is called here,
+     * simulating the behavior from version 6.x and prior.
+     * @param e - The event passed to the target.
+     * @param type - The type of event to notify. Defaults to `e.type`.
+     */
     notifyTarget(e, type) {
         var _a;
         if (!e.currentTarget.isInteractive()) {
             return;
         }
         type = type !== null && type !== void 0 ? type : e.type;
+        // call the `on${type}` for the current target if it exists
         const handlerKey = `on${type}`;
         (_a = e.currentTarget[handlerKey]) === null || _a === void 0 ? void 0 : _a(e);
         const key = e.eventPhase === e.CAPTURING_PHASE || e.eventPhase === e.AT_TARGET ? `${type}capture` : type;
@@ -469,9 +897,17 @@ class EventBoundary {
             this._notifyListeners(e, type);
         }
     }
+    /**
+     * Maps the upstream `pointerdown` events to a downstream `pointerdown` event.
+     *
+     * `touchstart`, `rightdown`, `mousedown` events are also dispatched for specific pointer types.
+     * @param from - The upstream `pointerdown` event.
+     */
     mapPointerDown(from) {
         if (!(from instanceof FederatedPointerEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-pointer event as a pointer event');
+            // #endif
             return;
         }
         const e = this.createPointerEvent(from);
@@ -487,10 +923,19 @@ class EventBoundary {
         trackingData.pressTargetsByButton[from.button] = e.composedPath();
         this.freeEvent(e);
     }
+    /**
+     * Maps the upstream `pointermove` to downstream `pointerout`, `pointerover`, and `pointermove` events, in that order.
+     *
+     * The tracking data for the specific pointer has an updated `overTarget`. `mouseout`, `mouseover`,
+     * `mousemove`, and `touchmove` events are fired as well for specific pointer types.
+     * @param from - The upstream `pointermove` event.
+     */
     mapPointerMove(from) {
         var _a, _b, _c;
         if (!(from instanceof FederatedPointerEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-pointer event as a pointer event');
+            // #endif
             return;
         }
         this._allInteractiveElements.length = 0;
@@ -501,12 +946,16 @@ class EventBoundary {
         const isMouse = e.pointerType === 'mouse' || e.pointerType === 'pen';
         const trackingData = this.trackingData(from.pointerId);
         const outTarget = this.findMountedTarget(trackingData.overTargets);
+        // First pointerout/pointerleave
         if (((_a = trackingData.overTargets) === null || _a === void 0 ? void 0 : _a.length) > 0 && outTarget !== e.target) {
+            // pointerout always occurs on the overTarget when the pointer hovers over another element.
             const outType = from.type === 'mousemove' ? 'mouseout' : 'pointerout';
             const outEvent = this.createPointerEvent(from, outType, outTarget);
             this.dispatchEvent(outEvent, 'pointerout');
             if (isMouse)
                 this.dispatchEvent(outEvent, 'mouseout');
+            // If the pointer exits overTarget and its descendants, then a pointerleave event is also fired. This event
+            // is dispatched to all ancestors that no longer capture the pointer.
             if (!e.composedPath().includes(outTarget)) {
                 const leaveEvent = this.createPointerEvent(from, 'pointerleave', outTarget);
                 leaveEvent.eventPhase = leaveEvent.AT_TARGET;
@@ -521,18 +970,23 @@ class EventBoundary {
             }
             this.freeEvent(outEvent);
         }
+        // Then pointerover
         if (outTarget !== e.target) {
+            // pointerover always occurs on the new overTarget
             const overType = from.type === 'mousemove' ? 'mouseover' : 'pointerover';
-            const overEvent = this.clonePointerEvent(e, overType);
+            const overEvent = this.clonePointerEvent(e, overType); // clone faster
             this.dispatchEvent(overEvent, 'pointerover');
             if (isMouse)
                 this.dispatchEvent(overEvent, 'mouseover');
+            // Probe whether the newly hovered Container is an ancestor of the original overTarget.
             let overTargetAncestor = outTarget === null || outTarget === void 0 ? void 0 : outTarget.parent;
             while (overTargetAncestor && overTargetAncestor !== this.rootTarget.parent) {
                 if (overTargetAncestor === e.target)
                     break;
                 overTargetAncestor = overTargetAncestor.parent;
             }
+            // The pointer has entered a non-ancestor of the original overTarget. This means we need a pointerentered
+            // event.
             const didPointerEnter = !overTargetAncestor || overTargetAncestor === this.rootTarget.parent;
             if (didPointerEnter) {
                 const enterEvent = this.clonePointerEvent(e, 'pointerenter');
@@ -552,6 +1006,7 @@ class EventBoundary {
         const allowGlobalPointerEvents = (_b = this.enableGlobalMoveEvents) !== null && _b !== void 0 ? _b : true;
         this.moveOnAll ? allMethods.push('pointermove') : this.dispatchEvent(e, 'pointermove');
         allowGlobalPointerEvents && allMethods.push('globalpointermove');
+        // Then pointermove
         if (e.pointerType === 'touch') {
             this.moveOnAll ? allMethods.splice(1, 0, 'touchmove') : this.dispatchEvent(e, 'touchmove');
             allowGlobalPointerEvents && allMethods.push('globaltouchmove');
@@ -569,10 +1024,18 @@ class EventBoundary {
         trackingData.overTargets = e.composedPath();
         this.freeEvent(e);
     }
+    /**
+     * Maps the upstream `pointerover` to downstream `pointerover` and `pointerenter` events, in that order.
+     *
+     * The tracking data for the specific pointer gets a new `overTarget`.
+     * @param from - The upstream `pointerover` event.
+     */
     mapPointerOver(from) {
         var _a;
         if (!(from instanceof FederatedPointerEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-pointer event as a pointer event');
+            // #endif
             return;
         }
         const trackingData = this.trackingData(from.pointerId);
@@ -583,6 +1046,7 @@ class EventBoundary {
             this.dispatchEvent(e, 'mouseover');
         if (e.pointerType === 'mouse')
             this.cursor = (_a = e.target) === null || _a === void 0 ? void 0 : _a.cursor;
+        // pointerenter events must be fired since the pointer entered from upstream.
         const enterEvent = this.clonePointerEvent(e, 'pointerenter');
         enterEvent.eventPhase = enterEvent.AT_TARGET;
         while (enterEvent.target && enterEvent.target !== this.rootTarget.parent) {
@@ -596,19 +1060,30 @@ class EventBoundary {
         this.freeEvent(e);
         this.freeEvent(enterEvent);
     }
+    /**
+     * Maps the upstream `pointerout` to downstream `pointerout`, `pointerleave` events, in that order.
+     *
+     * The tracking data for the specific pointer is cleared of a `overTarget`.
+     * @param from - The upstream `pointerout` event.
+     */
     mapPointerOut(from) {
         if (!(from instanceof FederatedPointerEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-pointer event as a pointer event');
+            // #endif
             return;
         }
         const trackingData = this.trackingData(from.pointerId);
         if (trackingData.overTargets) {
             const isMouse = from.pointerType === 'mouse' || from.pointerType === 'pen';
             const outTarget = this.findMountedTarget(trackingData.overTargets);
+            // pointerout first
             const outEvent = this.createPointerEvent(from, 'pointerout', outTarget);
             this.dispatchEvent(outEvent);
             if (isMouse)
                 this.dispatchEvent(outEvent, 'mouseout');
+            // pointerleave(s) are also dispatched b/c the pointer must've left rootTarget and its descendants to
+            // get an upstream pointerout event (upstream events do not know rootTarget has descendants).
             const leaveEvent = this.createPointerEvent(from, 'pointerleave', outTarget);
             leaveEvent.eventPhase = leaveEvent.AT_TARGET;
             while (leaveEvent.target && leaveEvent.target !== this.rootTarget.parent) {
@@ -624,9 +1099,21 @@ class EventBoundary {
         }
         this.cursor = null;
     }
+    /**
+     * Maps the upstream `pointerup` event to downstream `pointerup`, `pointerupoutside`,
+     * and `click`/`rightclick`/`pointertap` events, in that order.
+     *
+     * The `pointerupoutside` event bubbles from the original `pointerdown` target to the most specific
+     * ancestor of the `pointerdown` and `pointerup` targets, which is also the `click` event's target. `touchend`,
+     * `rightup`, `mouseup`, `touchendoutside`, `rightupoutside`, `mouseupoutside`, and `tap` are fired as well for
+     * specific pointer types.
+     * @param from - The upstream `pointerup` event.
+     */
     mapPointerUp(from) {
         if (!(from instanceof FederatedPointerEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-pointer event as a pointer event');
+            // #endif
             return;
         }
         const now = performance.now();
@@ -642,6 +1129,8 @@ class EventBoundary {
         const trackingData = this.trackingData(from.pointerId);
         const pressTarget = this.findMountedTarget(trackingData.pressTargetsByButton[from.button]);
         let clickTarget = pressTarget;
+        // pointerupoutside only bubbles. It only bubbles upto the parent that doesn't contain
+        // the pointerup location.
         if (pressTarget && !e.composedPath().includes(pressTarget)) {
             let currentTarget = pressTarget;
             while (currentTarget && !e.composedPath().includes(currentTarget)) {
@@ -657,8 +1146,11 @@ class EventBoundary {
                 currentTarget = currentTarget.parent;
             }
             delete trackingData.pressTargetsByButton[from.button];
+            // currentTarget is the most specific ancestor holding both the pointerdown and pointerup
+            // targets. That is - it's our click target!
             clickTarget = currentTarget;
         }
+        // click!
         if (clickTarget) {
             const clickEvent = this.clonePointerEvent(e, 'click');
             clickEvent.target = clickTarget;
@@ -692,9 +1184,22 @@ class EventBoundary {
         }
         this.freeEvent(e);
     }
+    /**
+     * Maps the upstream `pointerupoutside` event to a downstream `pointerupoutside` event, bubbling from the original
+     * `pointerdown` target to `rootTarget`.
+     *
+     * (The most specific ancestor of the `pointerdown` event and the `pointerup` event must the
+     * `{@link EventBoundary}'s root because the `pointerup` event occurred outside of the boundary.)
+     *
+     * `touchendoutside`, `mouseupoutside`, and `rightupoutside` events are fired as well for specific pointer
+     * types. The tracking data for the specific pointer is cleared of a `pressTarget`.
+     * @param from - The upstream `pointerupoutside` event.
+     */
     mapPointerUpOutside(from) {
         if (!(from instanceof FederatedPointerEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-pointer event as a pointer event');
+            // #endif
             return;
         }
         const trackingData = this.trackingData(from.pointerId);
@@ -717,21 +1222,37 @@ class EventBoundary {
         }
         this.freeEvent(e);
     }
+    /**
+     * Maps the upstream `wheel` event to a downstream `wheel` event.
+     * @param from - The upstream `wheel` event.
+     */
     mapWheel(from) {
         if (!(from instanceof FederatedWheelEvent)) {
+            // #if _DEBUG
             warn('EventBoundary cannot map a non-wheel event as a wheel event');
+            // #endif
             return;
         }
         const wheelEvent = this.createWheelEvent(from);
         this.dispatchEvent(wheelEvent);
         this.freeEvent(wheelEvent);
     }
+    /**
+     * Finds the most specific event-target in the given propagation path that is still mounted in the scene graph.
+     *
+     * This is used to find the correct `pointerup` and `pointerout` target in the case that the original `pointerdown`
+     * or `pointerover` target was unmounted from the scene graph.
+     * @param propagationPath - The propagation path was valid in the past.
+     * @returns - The most specific event-target still mounted at the same location in the scene graph.
+     */
     findMountedTarget(propagationPath) {
         if (!propagationPath) {
             return null;
         }
         let currentTarget = propagationPath[0];
         for (let i = 1; i < propagationPath.length; i++) {
+            // Set currentTarget to the next target in the path only if it is still attached to the
+            // scene graph (i.e. parent still points to the expected ancestor).
             if (propagationPath[i].parent === currentTarget) {
                 currentTarget = propagationPath[i];
             }
@@ -741,6 +1262,14 @@ class EventBoundary {
         }
         return currentTarget;
     }
+    /**
+     * Creates an event whose {@code originalEvent} is {@code from}, with an optional `type` and `target` override.
+     *
+     * The event is allocated using {@link EventBoundary#allocateEvent this.allocateEvent}.
+     * @param from - The {@code originalEvent} for the returned event.
+     * @param [type=from.type] - The type of the returned event.
+     * @param target - The target of the returned event.
+     */
     createPointerEvent(from, type, target) {
         var _a;
         const event = this.allocateEvent(FederatedPointerEvent);
@@ -755,6 +1284,12 @@ class EventBoundary {
         }
         return event;
     }
+    /**
+     * Creates a wheel event whose {@code originalEvent} is {@code from}.
+     *
+     * The event is allocated using {@link EventBoundary#allocateEvent this.allocateEvent}.
+     * @param from - The upstream wheel event.
+     */
     createWheelEvent(from) {
         const event = this.allocateEvent(FederatedWheelEvent);
         this.copyWheelData(from, event);
@@ -765,6 +1300,13 @@ class EventBoundary {
         event.target = this.hitTest(event.global.x, event.global.y);
         return event;
     }
+    /**
+     * Clones the event {@code from}, with an optional {@code type} override.
+     *
+     * The event is allocated using {@link EventBoundary#allocateEvent this.allocateEvent}.
+     * @param from - The event to clone.
+     * @param [type=from.type] - The type of the returned event.
+     */
     clonePointerEvent(from, type) {
         const event = this.allocateEvent(FederatedPointerEvent);
         event.nativeEvent = from.nativeEvent;
@@ -772,17 +1314,45 @@ class EventBoundary {
         this.copyPointerData(from, event);
         this.copyMouseData(from, event);
         this.copyData(from, event);
+        // copy propagation path for perf
         event.target = from.target;
         event.path = from.composedPath().slice();
         event.type = type !== null && type !== void 0 ? type : event.type;
         return event;
     }
+    /**
+     * Copies wheel {@link FederatedWheelEvent} data from {@code from} into {@code to}.
+     *
+     * The following properties are copied:
+     * + deltaMode
+     * + deltaX
+     * + deltaY
+     * + deltaZ
+     * @param from - The event to copy data from.
+     * @param to - The event to copy data into.
+     */
     copyWheelData(from, to) {
         to.deltaMode = from.deltaMode;
         to.deltaX = from.deltaX;
         to.deltaY = from.deltaY;
         to.deltaZ = from.deltaZ;
     }
+    /**
+     * Copies pointer {@link FederatedPointerEvent} data from {@code from} into {@code to}.
+     *
+     * The following properties are copied:
+     * + pointerId
+     * + width
+     * + height
+     * + isPrimary
+     * + pointerType
+     * + pressure
+     * + tangentialPressure
+     * + tiltX
+     * + tiltY
+     * @param from - The event to copy data from.
+     * @param to - The event to copy data into.
+     */
     copyPointerData(from, to) {
         if (!(from instanceof FederatedPointerEvent && to instanceof FederatedPointerEvent))
             return;
@@ -797,6 +1367,28 @@ class EventBoundary {
         to.tiltY = from.tiltY;
         to.twist = from.twist;
     }
+    /**
+     * Copies mouse {@link FederatedMouseEvent} data from {@code from} to {@code to}.
+     *
+     * The following properties are copied:
+     * + altKey
+     * + button
+     * + buttons
+     * + clientX
+     * + clientY
+     * + metaKey
+     * + movementX
+     * + movementY
+     * + pageX
+     * + pageY
+     * + x
+     * + y
+     * + screen
+     * + shiftKey
+     * + global
+     * @param from - The event to copy data from.
+     * @param to - The event to copy data into.
+     */
     copyMouseData(from, to) {
         if (!(from instanceof FederatedMouseEvent && to instanceof FederatedMouseEvent))
             return;
@@ -811,6 +1403,17 @@ class EventBoundary {
         to.shiftKey = from.shiftKey;
         to.global.copyFrom(from.global);
     }
+    /**
+     * Copies base {@link FederatedEvent} data from {@code from} into {@code to}.
+     *
+     * The following properties are copied:
+     * + isTrusted
+     * + srcElement
+     * + timeStamp
+     * + type
+     * @param from - The event to copy data from.
+     * @param to - The event to copy data into.
+     */
     copyData(from, to) {
         to.isTrusted = from.isTrusted;
         to.srcElement = from.srcElement;
@@ -822,6 +1425,11 @@ class EventBoundary {
         to.layer.copyFrom(from.layer);
         to.page.copyFrom(from.page);
     }
+    /**
+     * @param id - The pointer ID.
+     * @returns The tracking data stored for the given pointer. If no data exists, a blank
+     *  state will be created.
+     */
     trackingData(id) {
         if (!this.mappingState.trackingData[id]) {
             this.mappingState.trackingData[id] = {
@@ -832,6 +1440,13 @@ class EventBoundary {
         }
         return this.mappingState.trackingData[id];
     }
+    /**
+     * Allocate a specific type of event from {@link EventBoundary#eventPool this.eventPool}.
+     *
+     * This allocation is constructor-agnostic, as long as it only takes one argument - this event
+     * boundary.
+     * @param constructor - The event's constructor.
+     */
     allocateEvent(constructor) {
         if (!this.eventPool.has(constructor)) {
             this.eventPool.set(constructor, []);
@@ -844,6 +1459,17 @@ class EventBoundary {
         event.target = null;
         return event;
     }
+    /**
+     * Frees the event and puts it back into the event pool.
+     *
+     * It is illegal to reuse the event until it is allocated again, using `this.allocateEvent`.
+     *
+     * It is also advised that events not allocated from {@link EventBoundary#allocateEvent this.allocateEvent}
+     * not be freed. This is because of the possibility that the same event is freed twice, which can cause
+     * it to be allocated twice & result in overwriting.
+     * @param event - The event to be freed.
+     * @throws Error if the event is managed by another event boundary.
+     */
     freeEvent(event) {
         if (event.manager !== this)
             throw new Error('It is illegal to free an event not managed by this EventBoundary!');
@@ -853,6 +1479,12 @@ class EventBoundary {
         }
         this.eventPool.get(constructor).push(event);
     }
+    /**
+     * Similar to {@link EventEmitter.emit}, except it stops if the `propagationImmediatelyStopped` flag
+     * is set on the event.
+     * @param e - The event to call each listener with.
+     * @param type - The event key.
+     */
     _notifyListeners(e, type) {
         const listeners = e.currentTarget._events[type];
         if (!listeners)
@@ -879,11 +1511,47 @@ const TOUCH_TO_POINTER = {
     touchmove: 'pointermove',
     touchcancel: 'pointercancel',
 };
+/**
+ * 事件系统类
+ *
+ * EventSystem 负责处理所有 UI 交互事件（鼠标、触摸、指针等）。
+ * 它将原生 DOM 事件转换为统一的 FederatedEvent，
+ * 并通过事件边界（EventBoundary）将事件传播到场景图中的对象。
+ *
+ * 支持的事件类型：
+ * - 指针事件：pointerdown、pointermove、pointerup 等
+ * - 鼠标事件：mousedown、mousemove、mouseup 等
+ * - 触摸事件：touchstart、touchmove、touchend 等
+ * - 滚轮事件：wheel
+ *
+ * @example
+ * ```typescript
+ * const eventSystem = new EventSystem(renderer);
+ * eventSystem.init({
+ *   eventMode: 'passive',
+ *   eventFeatures: {
+ *     move: true,
+ *     click: true,
+ *     wheel: true
+ *   }
+ * });
+ * ```
+ */
 class EventSystem {
+    /**
+     * @param {Renderer} renderer
+     */
     constructor(renderer) {
+        /** Does the device support touch events https://www.w3.org/TR/touch-events/ */
         this.supportsTouchEvents = 'ontouchstart' in globalThis;
+        /** Does the device support pointer events https://www.w3.org/Submission/pointer-events/ */
         this.supportsPointerEvents = !!globalThis.PointerEvent;
+        /**
+         * The DOM element to which the root event listeners are bound. This is automatically set to
+         * the renderer's {@link Renderer#view view}.
+         */
         this.domElement = null;
+        /** The resolution used to convert between the DOM client space into world space. */
         this.resolution = 1;
         this.renderer = renderer;
         this.rootBoundary = new EventBoundary(null);
@@ -911,9 +1579,20 @@ class EventSystem {
         this._onPointerOverOut = this._onPointerOverOut.bind(this);
         this.onWheel = this.onWheel.bind(this);
     }
+    /**
+     * The default interaction mode for all display objects.
+     * @see Container.eventMode
+     * @type {EventMode}
+     * @readonly
+     * @since 7.2.0
+     */
     static get defaultEventMode() {
         return this._defaultEventMode;
     }
+    /**
+     * Runner init called, view is available at this point.
+     * @ignore
+     */
     init(options) {
         var _a, _b;
         const { canvas, resolution } = this.renderer;
@@ -923,38 +1602,55 @@ class EventSystem {
         Object.assign(this.features, (_b = options.eventFeatures) !== null && _b !== void 0 ? _b : {});
         this.rootBoundary.enableGlobalMoveEvents = this.features.globalMove;
     }
+    /**
+     * Handle changing resolution.
+     * @ignore
+     */
     resolutionChange(resolution) {
         this.resolution = resolution;
     }
+    /** Destroys all event listeners and detaches the renderer. */
     destroy() {
         this.setTargetElement(null);
         this.renderer = null;
         this._currentCursor = null;
     }
+    /**
+     * Sets the current cursor mode, handling any callbacks or CSS style changes.
+     * @param mode - cursor mode, a key from the cursorStyles dictionary
+     */
     setCursor(mode) {
         if (!mode) {
             mode = 'default';
         }
         let applyStyles = true;
+        // offscreen canvas does not support setting styles, but cursor modes can be functions,
+        // in order to handle pixi rendered cursors, so we can't bail
         if (globalThis.OffscreenCanvas && this.domElement instanceof OffscreenCanvas) {
             applyStyles = false;
         }
+        // if the mode didn't actually change, bail early
         if (this._currentCursor === mode) {
             return;
         }
         this._currentCursor = mode;
         const style = this.cursorStyles[mode];
+        // only do things if there is a cursor style for it
         if (style) {
             switch (typeof style) {
                 case 'string':
+                    // string styles are handled as cursor CSS
                     if (applyStyles) {
                         this.domElement.style.cursor = style;
                     }
                     break;
                 case 'function':
+                    // functions are just called, and passed the cursor mode
                     style(mode);
                     break;
                 case 'object':
+                    // if it is an object, assume that it is a dictionary of CSS styles,
+                    // apply it to the interactionDOMElement
                     if (applyStyles) {
                         Object.assign(this.domElement.style, style);
                     }
@@ -964,17 +1660,34 @@ class EventSystem {
         else if (applyStyles &&
             typeof mode === 'string' &&
             !Object.prototype.hasOwnProperty.call(this.cursorStyles, mode)) {
+            // if it mode is a string (not a Symbol) and cursorStyles doesn't have any entry
+            // for the mode, then assume that the dev wants it to be CSS for the cursor.
             this.domElement.style.cursor = mode;
         }
     }
+    /**
+     * The global pointer event.
+     * Useful for getting the pointer position without listening to events.
+     * @since 7.2.0
+     */
     get pointer() {
         return this._rootPointerEvent;
     }
+    /**
+     * Event handler for pointer down events on {@link EventSystem#domElement this.domElement}.
+     * @param nativeEvent - The native mouse/pointer/touch event.
+     */
     _onPointerDown(nativeEvent) {
         if (!this.features.click)
             return;
         this.rootBoundary.rootTarget = this.renderer.lastObjectRendered;
         const events = this._normalizeToPointerData(nativeEvent);
+        /*
+         * No need to prevent default on natural pointer events, as there are no side effects
+         * Normalized events, however, may have the double mousedown/touchstart issue on the native android browser,
+         * so still need to be prevented.
+         */
+        // Guaranteed that there will be at least one event in events, and all events must have the same pointer type
         if (this.autoPreventDefault && events[0].isNormalized) {
             const cancelable = nativeEvent.cancelable || !('cancelable' in nativeEvent);
             if (cancelable) {
@@ -989,6 +1702,10 @@ class EventSystem {
         }
         this.setCursor(this.rootBoundary.cursor);
     }
+    /**
+     * Event handler for pointer move events on on {@link EventSystem#domElement this.domElement}.
+     * @param nativeEvent - The native mouse/pointer/touch events.
+     */
     _onPointerMove(nativeEvent) {
         if (!this.features.move)
             return;
@@ -1001,6 +1718,10 @@ class EventSystem {
         }
         this.setCursor(this.rootBoundary.cursor);
     }
+    /**
+     * Event handler for pointer up events on {@link EventSystem#domElement this.domElement}.
+     * @param nativeEvent - The native mouse/pointer/touch event.
+     */
     _onPointerUp(nativeEvent) {
         if (!this.features.click)
             return;
@@ -1014,6 +1735,10 @@ class EventSystem {
         }
         this.setCursor(this.rootBoundary.cursor);
     }
+    /**
+     * Event handler for pointer over & out events on {@link EventSystem#domElement this.domElement}.
+     * @param nativeEvent - The native mouse/pointer/touch event.
+     */
     _onPointerOverOut(nativeEvent) {
         if (!this.features.click)
             return;
@@ -1025,6 +1750,10 @@ class EventSystem {
         }
         this.setCursor(this.rootBoundary.cursor);
     }
+    /**
+     * Passive handler for `wheel` events on {@link EventSystem.domElement this.domElement}.
+     * @param nativeEvent - The native wheel event.
+     */
     onWheel(nativeEvent) {
         if (!this.features.wheel)
             return;
@@ -1032,12 +1761,19 @@ class EventSystem {
         this.rootBoundary.rootTarget = this.renderer.lastObjectRendered;
         this.rootBoundary.mapEvent(wheelEvent);
     }
+    /**
+     * Sets the {@link EventSystem#domElement domElement} and binds event listeners.
+     *
+     * To deregister the current DOM element without setting a new one, pass {@code null}.
+     * @param element - The new DOM element.
+     */
     setTargetElement(element) {
         this._removeEvents();
         this.domElement = element;
         EventsTicker.domElement = element;
         this._addEvents();
     }
+    /** Register event listeners on {@link Renderer#domElement this.domElement}. */
     _addEvents() {
         if (this._eventsAdded || !this.domElement) {
             return;
@@ -1060,6 +1796,10 @@ class EventSystem {
                 id = key;
             }
         }
+        /*
+         * These events are added first, so that if pointer events are normalized, they are fired
+         * in the same order as non-normalized events. ie. pointer event 1st, mouse / touch 2nd
+         */
         EventSystem.eventsHandler[id] = {
             pointermove: this._onPointerMove.bind(this),
             pointerdown: this._onPointerDown.bind(this),
@@ -1078,12 +1818,14 @@ class EventSystem {
         EventSystem.eventsHandler[id]['wheel'] = this.onWheel.bind(this);
         this._eventsAdded = true;
     }
+    /** Unregister event listeners on {@link EventSystem#domElement this.domElement}. */
     _removeEvents() {
         if (!this._eventsAdded || !this.domElement) {
             return;
         }
         EventsTicker.removeTickerListener();
         const style = this.domElement.style;
+        // offscreen canvas does not have style, so check first
         if (style) {
             if (globalThis.navigator.msPointerEnabled) {
                 style.msContentZooming = '';
@@ -1096,6 +1838,14 @@ class EventSystem {
         this.domElement = null;
         this._eventsAdded = false;
     }
+    /**
+     * Maps x and y coords from a DOM object and maps them correctly to the PixiJS view. The
+     * resulting value is stored in the point. This takes into account the fact that the DOM
+     * element could be scaled and positioned anywhere on the screen.
+     * @param  {PointData} point - the point that the result will be stored in
+     * @param  {number} x - the x coord of the position to map
+     * @param  {number} y - the y coord of the position to map
+     */
     mapPositionToPoint(point, x, y, e) {
         const resolutionMultiplier = 1.0 / this.resolution;
         const rect = e.canvasRect || {
@@ -1110,12 +1860,34 @@ class EventSystem {
         point.x = (x - rect.left) * (domElement.width / rect.width) * resolutionMultiplier;
         point.y = (y - rect.top) * (domElement.height / rect.height) * resolutionMultiplier;
     }
+    /**
+     * Ensures that the original event object contains all data that a regular pointer event would have
+     * @param event - The original event data from a touch or mouse event
+     * @returns An array containing a single normalized pointer event, in the case of a pointer
+     *  or mouse event, or a multiple normalized pointer events if there are multiple changed touches
+     */
     _normalizeToPointerData(event) {
+        // @ts-ignore
         return event.normalizedEvents;
     }
+    /**
+     * Normalizes the native {@link https://w3c.github.io/uievents/#interface-wheelevent WheelEvent}.
+     *
+     * The returned {@link FederatedWheelEvent} is a shared instance. It will not persist across
+     * multiple native wheel events.
+     * @param nativeEvent - The native wheel event that occurred on the canvas.
+     * @returns A federated wheel event.
+     */
     normalizeWheelEvent(nativeEvent) {
         const event = this._rootWheelEvent;
         this._transferMouseData(event, nativeEvent);
+        // When WheelEvent is triggered by scrolling with mouse wheel, reading WheelEvent.deltaMode
+        // before deltaX/deltaY/deltaZ on Firefox will result in WheelEvent.DOM_DELTA_LINE (1),
+        // while reading WheelEvent.deltaMode after deltaX/deltaY/deltaZ on Firefox or reading
+        // in any order on other browsers will result in WheelEvent.DOM_DELTA_PIXEL (0).
+        // Therefore, we need to read WheelEvent.deltaMode after deltaX/deltaY/deltaZ in order to
+        // make its behavior more consistent across browsers.
+        // @see https://github.com/pixijs/pixijs/issues/8970
         event.deltaX = nativeEvent.deltaX;
         event.deltaY = nativeEvent.deltaY;
         event.deltaZ = nativeEvent.deltaZ;
@@ -1127,6 +1899,11 @@ class EventSystem {
         event.type = nativeEvent.type;
         return event;
     }
+    /**
+     * Normalizes the `nativeEvent` into a federateed {@link FederatedPointerEvent}.
+     * @param event
+     * @param nativeEvent
+     */
     _bootstrapEvent(event, nativeEvent, nEvent) {
         event.originalEvent = null;
         event.nativeEvent = nativeEvent;
@@ -1142,8 +1919,8 @@ class EventSystem {
         event.twist = nativeEvent.twist;
         this._transferMouseData(event, nativeEvent);
         this.mapPositionToPoint(event.screen, nativeEvent.clientX, nativeEvent.clientY, nEvent);
-        event.global.copyFrom(event.screen);
-        event.offset.copyFrom(event.screen);
+        event.global.copyFrom(event.screen); // global = screen for top-level
+        event.offset.copyFrom(event.screen); // EventBoundary recalculates using its rootTarget
         event.isTrusted = nativeEvent.isTrusted;
         if (event.type === 'pointerleave') {
             event.type = 'pointerout';
@@ -1156,6 +1933,11 @@ class EventSystem {
         }
         return event;
     }
+    /**
+     * Transfers base & mouse event data from the {@code nativeEvent} to the federated event.
+     * @param event
+     * @param nativeEvent
+     */
     _transferMouseData(event, nativeEvent) {
         event.isTrusted = nativeEvent.isTrusted;
         event.srcElement = nativeEvent.srcElement;
@@ -1176,61 +1958,397 @@ class EventSystem {
         event.shiftKey = nativeEvent.shiftKey;
     }
 }
+/** @ignore */
 EventSystem.extension = {
     name: 'events',
     type: [ExtensionType.WebGLSystem, ExtensionType.CanvasSystem, ExtensionType.WebGPUSystem],
     priority: -1,
 };
+/** 画布映射表 */
 EventSystem.canvasMap = {};
+/** 事件处理器映射表 */
 EventSystem.eventsHandler = {};
+/**
+ * 事件系统的默认功能配置
+ * @since 7.2.0
+ */
 EventSystem.defaultEventFeatures = {
+    /** 启用指针移动相关事件 */
     move: true,
+    /** 启用全局指针移动事件 */
     globalMove: true,
+    /** 启用点击相关事件 */
     click: true,
+    /** 启用滚轮事件 */
     wheel: true,
 };
 
 const FederatedContainer = {
+    /**
+     * Property-based event handler for the `click` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onclick = (event) => {
+     *  //some function here that happens on click
+     * }
+     */
     onclick: null,
+    /**
+     * Property-based event handler for the `mousedown` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmousedown = (event) => {
+     *  //some function here that happens on mousedown
+     * }
+     */
     onmousedown: null,
+    /**
+     * Property-based event handler for the `mouseenter` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmouseenter = (event) => {
+     *  //some function here that happens on mouseenter
+     * }
+     */
     onmouseenter: null,
+    /**
+     * Property-based event handler for the `mouseleave` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmouseleave = (event) => {
+     *  //some function here that happens on mouseleave
+     * }
+     */
     onmouseleave: null,
+    /**
+     * Property-based event handler for the `mousemove` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmousemove = (event) => {
+     *  //some function here that happens on mousemove
+     * }
+     */
     onmousemove: null,
+    /**
+     * Property-based event handler for the `globalmousemove` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onglobalmousemove = (event) => {
+     *  //some function here that happens on globalmousemove
+     * }
+     */
     onglobalmousemove: null,
+    /**
+     * Property-based event handler for the `mouseout` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmouseout = (event) => {
+     *  //some function here that happens on mouseout
+     * }
+     */
     onmouseout: null,
+    /**
+     * Property-based event handler for the `mouseover` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmouseover = (event) => {
+     *  //some function here that happens on mouseover
+     * }
+     */
     onmouseover: null,
+    /**
+     * Property-based event handler for the `mouseup` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmouseup = (event) => {
+     *  //some function here that happens on mouseup
+     * }
+     */
     onmouseup: null,
+    /**
+     * Property-based event handler for the `mouseupoutside` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onmouseupoutside = (event) => {
+     *  //some function here that happens on mouseupoutside
+     * }
+     */
     onmouseupoutside: null,
+    /**
+     * Property-based event handler for the `pointercancel` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointercancel = (event) => {
+     *  //some function here that happens on pointercancel
+     * }
+     */
     onpointercancel: null,
+    /**
+     * Property-based event handler for the `pointerdown` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerdown = (event) => {
+     *  //some function here that happens on pointerdown
+     * }
+     */
     onpointerdown: null,
+    /**
+     * Property-based event handler for the `pointerenter` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerenter = (event) => {
+     *  //some function here that happens on pointerenter
+     * }
+     */
     onpointerenter: null,
+    /**
+     * Property-based event handler for the `pointerleave` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerleave = (event) => {
+     *  //some function here that happens on pointerleave
+     * }
+     */
     onpointerleave: null,
+    /**
+     * Property-based event handler for the `pointermove` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointermove = (event) => {
+     *  //some function here that happens on pointermove
+     * }
+     */
     onpointermove: null,
+    /**
+     * Property-based event handler for the `globalpointermove` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onglobalpointermove = (event) => {
+     *  //some function here that happens on globalpointermove
+     * }
+     */
     onglobalpointermove: null,
+    /**
+     * Property-based event handler for the `pointerout` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerout = (event) => {
+     *  //some function here that happens on pointerout
+     * }
+     */
     onpointerout: null,
+    /**
+     * Property-based event handler for the `pointerover` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerover = (event) => {
+     *  //some function here that happens on pointerover
+     * }
+     */
     onpointerover: null,
+    /**
+     * Property-based event handler for the `pointertap` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointertap = (event) => {
+     *  //some function here that happens on pointertap
+     * }
+     */
     onpointertap: null,
+    /**
+     * Property-based event handler for the `pointerup` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerup = (event) => {
+     *  //some function here that happens on pointerup
+     * }
+     */
     onpointerup: null,
+    /**
+     * Property-based event handler for the `pointerupoutside` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onpointerupoutside = (event) => {
+     *  //some function here that happens on pointerupoutside
+     * }
+     */
     onpointerupoutside: null,
+    /**
+     * Property-based event handler for the `rightclick` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onrightclick = (event) => {
+     *  //some function here that happens on rightclick
+     * }
+     */
     onrightclick: null,
+    /**
+     * Property-based event handler for the `rightdown` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onrightdown = (event) => {
+     *  //some function here that happens on rightdown
+     * }
+     */
     onrightdown: null,
+    /**
+     * Property-based event handler for the `rightup` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onrightup = (event) => {
+     *  //some function here that happens on rightup
+     * }
+     */
     onrightup: null,
+    /**
+     * Property-based event handler for the `rightupoutside` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onrightupoutside = (event) => {
+     *  //some function here that happens on rightupoutside
+     * }
+     */
     onrightupoutside: null,
+    /**
+     * Property-based event handler for the `tap` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.ontap = (event) => {
+     *  //some function here that happens on tap
+     * }
+     */
     ontap: null,
+    /**
+     * Property-based event handler for the `touchcancel` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.ontouchcancel = (event) => {
+     *  //some function here that happens on touchcancel
+     * }
+     */
     ontouchcancel: null,
+    /**
+     * Property-based event handler for the `touchend` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.ontouchend = (event) => {
+     *  //some function here that happens on touchend
+     * }
+     */
     ontouchend: null,
+    /**
+     * Property-based event handler for the `touchendoutside` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.ontouchendoutside = (event) => {
+     *  //some function here that happens on touchendoutside
+     * }
+     */
     ontouchendoutside: null,
+    /**
+     * Property-based event handler for the `touchmove` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.ontouchmove = (event) => {
+     *  //some function here that happens on touchmove
+     * }
+     */
     ontouchmove: null,
+    /**
+     * Property-based event handler for the `globaltouchmove` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onglobaltouchmove = (event) => {
+     *  //some function here that happens on globaltouchmove
+     * }
+     */
     onglobaltouchmove: null,
+    /**
+     * Property-based event handler for the `touchstart` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.ontouchstart = (event) => {
+     *  //some function here that happens on touchstart
+     * }
+     */
     ontouchstart: null,
+    /**
+     * Property-based event handler for the `wheel` event.
+     * @memberof scene.Container#
+     * @default null
+     * @example
+     * this.onwheel = (event) => {
+     *  //some function here that happens on wheel
+     * }
+     */
     onwheel: null,
+    /**
+     * Enable interaction events for the Container. Touch, pointer and mouse
+     * @memberof scene.Container#
+     */
     get interactive() {
         return this.eventMode === 'dynamic' || this.eventMode === 'static';
     },
     set interactive(value) {
         this.eventMode = value ? 'static' : 'passive';
     },
+    /**
+     * @ignore
+     */
     _internalEventMode: undefined,
+    /**
+     * Enable interaction events for the Container. Touch, pointer and mouse.
+     * There are 5 types of interaction settings:
+     * - `'none'`: Ignores all interaction events, even on its children.
+     * - `'passive'`: **(default)** Does not emit events and ignores all hit testing on itself and non-interactive children.
+     * Interactive children will still emit events.
+     * - `'auto'`: Does not emit events but is hit tested if parent is interactive. Same as `interactive = false` in v7
+     * - `'static'`: Emit events and is hit tested. Same as `interaction = true` in v7
+     * - `'dynamic'`: Emits events and is hit tested but will also receive mock interaction events fired from a ticker to
+     * allow for interaction when the mouse isn't moving
+     * @example
+     * import { Sprite } from 'pixi.js';
+     *
+     * const sprite = new Sprite(texture);
+     * sprite.eventMode = 'static';
+     * sprite.on('tap', (event) => {
+     *     // Handle event
+     * });
+     * @memberof scene.Container#
+     * @since 7.2.0
+     */
     get eventMode() {
         var _a;
         return (_a = this._internalEventMode) !== null && _a !== void 0 ? _a : EventSystem.defaultEventMode;
@@ -1238,11 +2356,84 @@ const FederatedContainer = {
     set eventMode(value) {
         this._internalEventMode = value;
     },
+    /**
+     * Determines if the container is interactive or not
+     * @returns {boolean} Whether the container is interactive or not
+     * @memberof scene.Container#
+     * @since 7.2.0
+     * @example
+     * import { Sprite } from 'pixi.js';
+     *
+     * const sprite = new Sprite(texture);
+     * sprite.eventMode = 'static';
+     * sprite.isInteractive(); // true
+     *
+     * sprite.eventMode = 'dynamic';
+     * sprite.isInteractive(); // true
+     *
+     * sprite.eventMode = 'none';
+     * sprite.isInteractive(); // false
+     *
+     * sprite.eventMode = 'passive';
+     * sprite.isInteractive(); // false
+     *
+     * sprite.eventMode = 'auto';
+     * sprite.isInteractive(); // false
+     */
     isInteractive() {
         return this.eventMode === 'static' || this.eventMode === 'dynamic';
     },
+    /**
+     * Determines if the children to the container can be clicked/touched
+     * Setting this to false allows PixiJS to bypass a recursive `hitTest` function
+     * @memberof scene.Container#
+     */
     interactiveChildren: true,
+    /**
+     * Interaction shape. Children will be hit first, then this shape will be checked.
+     * Setting this will cause this shape to be checked in hit tests rather than the container's bounds.
+     * @example
+     * import { Rectangle, Sprite } from 'pixi.js';
+     *
+     * const sprite = new Sprite(texture);
+     * sprite.interactive = true;
+     * sprite.hitArea = new Rectangle(0, 0, 100, 100);
+     * @member {IHitArea}
+     * @memberof scene.Container#
+     */
     hitArea: null,
+    /**
+     * Unlike `on` or `addListener` which are methods from EventEmitter, `addEventListener`
+     * seeks to be compatible with the DOM's `addEventListener` with support for options.
+     * @memberof scene.Container
+     * @param type - The type of event to listen to.
+     * @param listener - The listener callback or object.
+     * @param options - Listener options, used for capture phase.
+     * @example
+     * // Tell the user whether they did a single, double, triple, or nth click.
+     * button.addEventListener('click', {
+     *     handleEvent(e): {
+     *         let prefix;
+     *
+     *         switch (e.detail) {
+     *             case 1: prefix = 'single'; break;
+     *             case 2: prefix = 'double'; break;
+     *             case 3: prefix = 'triple'; break;
+     *             default: prefix = e.detail + 'th'; break;
+     *         }
+     *
+     *         console.log('That was a ' + prefix + 'click');
+     *     }
+     * });
+     *
+     * // But skip the first click!
+     * button.parent.addEventListener('click', function blockClickOnce(e) {
+     *     e.stopImmediatePropagation();
+     *     button.parent.removeEventListener('click', blockClickOnce, true);
+     * }, {
+     *     capture: true,
+     * });
+     */
     addEventListener(type, listener, options) {
         const capture = (typeof options === 'boolean' && options) || (typeof options === 'object' && options.capture);
         const signal = typeof options === 'object' ? options.signal : undefined;
@@ -1263,6 +2454,14 @@ const FederatedContainer = {
             emitter.on(type, listenerFn, context);
         }
     },
+    /**
+     * Unlike `off` or `removeListener` which are methods from EventEmitter, `removeEventListener`
+     * seeks to be compatible with the DOM's `removeEventListener` with support for options.
+     * @memberof scene.Container
+     * @param type - The type of event the listener is bound to.
+     * @param listener - The listener callback or object.
+     * @param options - The original listener options. This is required to deregister a capture phase listener.
+     */
     removeEventListener(type, listener, options) {
         const capture = (typeof options === 'boolean' && options) || (typeof options === 'object' && options.capture);
         const context = typeof listener === 'function' ? undefined : listener;
@@ -1270,6 +2469,17 @@ const FederatedContainer = {
         listener = typeof listener === 'function' ? listener : listener.handleEvent;
         this.off(type, listener, context);
     },
+    /**
+     * Dispatch the event on this {@link Container} using the event's {@link EventBoundary}.
+     *
+     * The target of the event is set to `this` and the `defaultPrevented` flag is cleared before dispatch.
+     * @memberof scene.Container
+     * @param e - The event to dispatch.
+     * @returns Whether the {@link FederatedEvent.preventDefault preventDefault}() method was not invoked.
+     * @example
+     * // Reuse a click event!
+     * button.dispatchEvent(clickEvent);
+     */
     dispatchEvent(e) {
         if (!(e instanceof FederatedEvent)) {
             throw new Error('Container cannot propagate events outside of the Federated Events API');
@@ -1282,6 +2492,101 @@ const FederatedContainer = {
     },
 };
 
+/* eslint-disable max-len */
+/**
+ * PixiJS is primarily a rendering system, but it also includes support for interactivity.
+ * Adding support for mouse and touch events to your project is simple and consistent.
+ *
+ * The new event-based system that replaced InteractionManager from v6 has expanded the definition of what a
+ * Container means to be interactive. With this we have introduced `eventMode` which allows you to control
+ * how an object responds to interaction events.
+ * This is similar to the `interactive` property in v6 but with more options.
+ *
+ * <details id="enabling-interaction">
+ * <summary>Enabling Interaction</summary>
+ *
+ * Any Container-derived object (Sprite, Container, etc.) can become interactive simply by setting its `eventMode` property to any of
+ * the {@link events.EventMode} values. Doing so will cause the object to emit interaction events that can be responded to in order to drive your project's behavior.
+ *
+ * Check out the [interaction example code](/examples/events/click).
+ *
+ * Container-derived objects are based on {@link https://www.npmjs.com/package/eventemitter3|EventEmitter3}
+ * so you can use `on()`, `once()`, `off()` to listen to events.
+ *
+ * For example to respond to clicks and taps, bind to an object ike so:
+ *
+ * ```javascript
+ * let sprite = Sprite.from('/some/texture.png');
+ *
+ * sprite.eventMode = 'static'; // similar to `sprite.interactive = true` in v6
+ * sprite.on('pointerdown', (event) => { alert('clicked!'); });
+ * ```
+ *
+ * Check out the **EventTypes** section below for the full list of interaction events supported.
+ * </details>
+ *
+ * <details id="event-modes">
+ * <summary>Event Modes</summary>
+ *
+ * The new event-based system that replaced InteractionManager from v6 has expanded the definition of what a Container
+ *  means to be interactive. With this we have introduced `eventMode` which allows you to control how an object responds
+ * to interaction events. This is similar to the `interactive` property in v6 but with more options.
+ *
+ * | event mode | Description |
+ * |---|---|
+ * | `none` | Ignores all interaction events, similar to CSS's `pointer-events: none`, good optimization for non-interactive children |
+ * |  `passive`  | Does not emit events and ignores hit testing on itself but does allow for events and hit testing only its interactive children. If you want to be compatible with v6, set this as your default `eventMode` (see options in Renderer, Application, etc) |
+ * |  `auto`  | Does not emit events and but is hit tested if parent is interactive. Same as `interactive = false` in v7 |
+ * |  `static`  | Emit events and is hit tested. Same as `interaction = true` in v7, useful for objects like buttons that do not move. |
+ * |  `dynamic` | Emits events and is hit tested but will also receive mock interaction events fired from a ticker to allow for interaction when the mouse isn't moving. This is useful for elements that independently moving or animating. |
+ * </details>
+ *
+ * <details id="event-types">
+ * <summary>Event Types</summary>
+ *
+ * Pixi supports the following event types for interactive objects:
+ *
+ * | Event Type | Fired When |
+ * |---|---|
+ * | `pointercancel` | Pointer device button is released outside the display object
+ * that initially registered a pointerdown. |
+ * | `pointerdown` | Pointer device button is pressed on the display object. |
+ * | `pointerenter` | Pointer device enters the display object. |
+ * | `pointerleave` | Pointer device leaves the display object. |
+ * | `pointermove` | Pointer device is moved while over the display object. |
+ * | `globalpointermove` | Pointer device is moved, regardless of hit-testing the current object. |
+ * | `pointerout` | Pointer device is moved off the display object. |
+ * | `pointerover` | Pointer device is moved onto the display object. |
+ * | `pointertap` | Pointer device is tapped twice on the display object. |
+ * | `pointerup` | Pointer device button is released over the display object. |
+ * | `pointerupoutside` | Pointer device button is released outside the display object
+ * that initially registered a pointerdown. |
+ * | `mousedown ` | Mouse button is pressed on the display object. |
+ * | `mouseenter` | Mouse cursor enters the display object. |
+ * | `mouseleave` | Mouse cursor leaves the display object. |
+ * | `mousemove ` | Mouse cursor is moved while over the display object. |
+ * | `globalmousemove` | Mouse is moved, regardless of hit-testing the current object. |
+ * | `mouseout ` | Mouse cursor is moved off the display object. |
+ * | `mouseover ` | Mouse cursor is moved onto the display object. |
+ * | `mouseup ` | Mouse button is released over the display object. |
+ * | `mouseupoutside ` | Mouse button is released outside the display object that initially registered a mousedown. |
+ * | `click ` | Mouse button is clicked (pressed and released) over the display object. |
+ * | `touchcancel ` | Touch point is removed outside of the display object that initially registered a touchstart. |
+ * | `touchend ` | Touch point is removed from the display object. |
+ * | `touchendoutside ` | Touch point is removed outside of the display object that initially registered a touchstart. |
+ * | `touchmove ` | Touch point is moved along the display object. |
+ * | `globaltouchmove` | Touch point is moved, regardless of hit-testing the current object. |
+ * | `touchstart ` | Touch point is placed on the display object. |
+ * | `tap ` | Touch point is tapped twice on the display object. |
+ * | `wheel ` | Mouse wheel is spun over the display object. |
+ * | `rightclick ` | Right mouse button is clicked (pressed and released) over the display object. |
+ * | `rightdown ` | Right mouse button is pressed on the display object. |
+ * | `rightup ` | Right mouse button is released over the display object. |
+ * | `rightupoutside ` | Right mouse button is released outside the display object that initially registered a rightdown. |
+ * </details>
+ * @namespace events
+ */
+/* eslint-enable max-len */
 const init = () => {
     extensions.add(EventSystem);
     extensions.mixin(Container, FederatedContainer);