@vunk/plus 1.6.8 → 1.6.10

package/components/browserAll.mjs

@@ -1,12 +1,12 @@
-import { P as Point, r as removeItems, E as ExtensionType, T as Ticker, U as UPDATE_PRIORITY, a as EventEmitter, w as warn, e as extensions, C as Container } from './index2.mjs';
+import { P as Point, E as ExtensionType, r as removeItems, T as Ticker, U as UPDATE_PRIORITY, a as EventEmitter, w as warn, e as extensions, C as Container } from './index2.mjs';
 import './init.mjs';
 import 'vue';
 import '@vunk/shared/enum';
 import '@vunk/shared/promise';
 import './_commonjsHelpers.mjs';
+import './_plugin-vue_export-helper.mjs';
 import '@vunk/core/composables';
 import '@vunk/shared/object';
-import './_plugin-vue_export-helper.mjs';
 import './colorToUniform.mjs';
 
 class FederatedEvent {
@@ -25,9 +25,10 @@ class FederatedEvent {
      */
     this.cancelable = false;
     /**
-     * Flag added for compatibility with DOM {@code Event}. It is not used in the Federated Events
+     * Flag added for compatibility with DOM `Event`. It is not used in the Federated Events
      * API.
      * @see https://dom.spec.whatwg.org/#dom-event-composed
+     * @ignore
      */
     this.composed = false;
     /** Flags whether the default response of the user agent was prevent through this event. */
@@ -45,9 +46,29 @@ class FederatedEvent {
     this.layer = new Point();
     /** The coordinates of the event relative to the DOM document. This is a non-standard property. */
     this.page = new Point();
+    /**
+     * The event propagation phase NONE that indicates that the event is not in any phase.
+     * @default 0
+     * @advanced
+     */
     this.NONE = 0;
+    /**
+     * The event propagation phase CAPTURING_PHASE that indicates that the event is in the capturing phase.
+     * @default 1
+     * @advanced
+     */
     this.CAPTURING_PHASE = 1;
+    /**
+     * The event propagation phase AT_TARGET that indicates that the event is at the target.
+     * @default 2
+     * @advanced
+     */
     this.AT_TARGET = 2;
+    /**
+     * The event propagation phase BUBBLING_PHASE that indicates that the event is in the bubbling phase.
+     * @default 3
+     * @advanced
+     */
     this.BUBBLING_PHASE = 3;
     this.manager = manager;
   }
@@ -68,13 +89,16 @@ class FederatedEvent {
     return this.page.y;
   }
   /**
-   * Fallback for the deprecated @code{InteractionEvent.data}.
+   * Fallback for the deprecated `InteractionEvent.data`.
    * @deprecated since 7.0.0
    */
   get data() {
     return this;
   }
-  /** The propagation path for this event. Alias for {@link EventBoundary.propagationPath}. */
+  /**
+   * The propagation path for this event. Alias for {@link EventBoundary.propagationPath}.
+   * @advanced
+   */
   composedPath() {
     if (this.manager && (!this.path || this.path[this.path.length - 1] !== this.target)) {
       this.path = this.target ? this.manager.propagationPath(this.target) : [];
@@ -82,8 +106,9 @@ class FederatedEvent {
     return this.path;
   }
   /**
-   * Unimplemented method included for implementing the DOM interface {@code Event}. It will throw an {@code Error}.
+   * Unimplemented method included for implementing the DOM interface `Event`. It will throw an `Error`.
    * @deprecated
+   * @ignore
    * @param _type
    * @param _bubbles
    * @param _cancelable
@@ -92,7 +117,8 @@ class FederatedEvent {
     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}.
+   * Unimplemented method included for implementing the DOM interface `UIEvent`. It will throw an `Error`.
+   * @ignore
    * @deprecated
    * @param _typeArg
    * @param _bubblesArg
@@ -103,7 +129,23 @@ class FederatedEvent {
   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. */
+  /**
+   * Prevent default behavior of both PixiJS and the user agent.
+   * @example
+   * ```ts
+   * sprite.on('click', (event) => {
+   *     // Prevent both browser's default click behavior
+   *     // and PixiJS's default handling
+   *     event.preventDefault();
+   *
+   *     // Custom handling
+   *     customClickHandler();
+   * });
+   * ```
+   * @remarks
+   * - Only works if the native event is cancelable
+   * - Does not stop event propagation
+   */
   preventDefault() {
     if (this.nativeEvent instanceof Event && this.nativeEvent.cancelable) {
       this.nativeEvent.preventDefault();
@@ -111,16 +153,49 @@ class FederatedEvent {
     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.
+   * Stop this event from propagating to any additional listeners, including those
+   * on the current target and any following targets in the propagation path.
+   * @example
+   * ```ts
+   * container.on('pointerdown', (event) => {
+   *     // Stop all further event handling
+   *     event.stopImmediatePropagation();
+   *
+   *     // These handlers won't be called:
+   *     // - Other pointerdown listeners on this container
+   *     // - Any pointerdown listeners on parent containers
+   * });
+   * ```
+   * @remarks
+   * - Immediately stops all event propagation
+   * - Prevents other listeners on same target from being called
+   * - More aggressive than stopPropagation()
    */
   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.
+   * Stop this event from propagating to the next target in the propagation path.
+   * The rest of the listeners on the current target will still be notified.
+   * @example
+   * ```ts
+   * child.on('pointermove', (event) => {
+   *     // Handle event on child
+   *     updateChild();
+   *
+   *     // Prevent parent handlers from being called
+   *     event.stopPropagation();
+   * });
+   *
+   * // This won't be called if child handles the event
+   * parent.on('pointermove', (event) => {
+   *     updateParent();
+   * });
+   * ```
+   * @remarks
+   * - Stops event bubbling to parent containers
+   * - Does not prevent other listeners on same target
+   * - Less aggressive than stopImmediatePropagation()
    */
   stopPropagation() {
     this.propagationStopped = true;
@@ -302,7 +377,7 @@ const _AccessibilitySystem = class _AccessibilitySystem {
   }
   /**
    * Value of `true` if accessibility is currently active and accessibility layers are showing.
-   * @member {boolean}
+   * @type {boolean}
    * @readonly
    */
   get isActive() {
@@ -310,12 +385,16 @@ const _AccessibilitySystem = class _AccessibilitySystem {
   }
   /**
    * Value of `true` if accessibility is enabled for touch devices.
-   * @member {boolean}
+   * @type {boolean}
    * @readonly
    */
   get isMobileAccessibility() {
     return this._isMobileAccessibility;
   }
+  /**
+   * The DOM element that will sit over the PixiJS element. This is where the div overlays will go.
+   * @readonly
+   */
   get hookDiv() {
     return this._hookDiv;
   }
@@ -719,7 +798,11 @@ const _AccessibilitySystem = class _AccessibilitySystem {
     }
     this._deactivate();
   }
-  /** Destroys the accessibility system. Removes all elements and listeners. */
+  /**
+   * Destroys the accessibility system. Removes all elements and listeners.
+   * > [!IMPORTANT] This is typically called automatically when the {@link Application} is destroyed.
+   * > A typically user should not need to call this method directly.
+   */
   destroy() {
     this._deactivate();
     this._destroyTouchHook();
@@ -734,6 +817,11 @@ const _AccessibilitySystem = class _AccessibilitySystem {
   /**
    * Enables or disables the accessibility system.
    * @param enabled - Whether to enable or disable accessibility.
+   * @example
+   * ```js
+   * app.renderer.accessibility.setAccessibilityEnabled(true); // Enable accessibility
+   * app.renderer.accessibility.setAccessibilityEnabled(false); // Disable accessibility
+   * ```
    */
   setAccessibilityEnabled(enabled) {
     if (enabled) {
@@ -751,7 +839,19 @@ _AccessibilitySystem.extension = {
   ],
   name: "accessibility"
 };
-/** default options used by the system */
+/**
+ * The default options used by the system.
+ * You can set these before initializing the {@link Application} to change the default behavior.
+ * @example
+ * ```js
+ * import { AccessibilitySystem } from 'pixi.js';
+ *
+ * AccessibilitySystem.defaultOptions.enabledByDefault = true;
+ *
+ * const app = new Application()
+ * app.init()
+ * ```
+ */
 _AccessibilitySystem.defaultOptions = {
   /**
    * Whether to enable accessibility features on initialization
@@ -777,78 +877,16 @@ _AccessibilitySystem.defaultOptions = {
 let AccessibilitySystem = _AccessibilitySystem;
 
 const accessibilityTarget = {
-  /**
-   * Flag for if the object is accessible. If true AccessibilityManager will overlay a
-   * shadow div with attributes set
-   * @member {boolean}
-   * @memberof scene.Container#
-   */
   accessible: false,
-  /**
-   * Sets the title attribute of the shadow div
-   * If accessibleTitle AND accessibleHint has not been this will default to 'container [tabIndex]'
-   * @member {string}
-   * @memberof scene.Container#
-   */
   accessibleTitle: null,
-  /**
-   * Sets the aria-label attribute of the shadow div
-   * @member {string}
-   * @memberof scene.Container#
-   */
   accessibleHint: null,
-  /**
-   * @member {number}
-   * @memberof scene.Container#
-   * @todo Needs docs.
-   */
   tabIndex: 0,
-  /**
-   * @member {boolean}
-   * @memberof scene.Container#
-   * @private
-   */
-  _accessibleActive: false,
-  /**
-   * @memberof scene.Container#
-   * @private
-   */
-  _accessibleDiv: null,
-  /**
-   * Specify the type of div the accessible layer is. Screen readers treat the element differently
-   * depending on this type. Defaults to button.
-   * @member {string}
-   * @memberof scene.Container#
-   * @default 'button'
-   */
   accessibleType: "button",
-  /**
-   * Sets the text content of the shadow div
-   * @member {string}
-   * @memberof scene.Container#
-   */
   accessibleText: null,
-  /**
-   * Specify the pointer-events the accessible div will use
-   * Defaults to auto.
-   * @type {PointerEvents}
-   * @memberof scene.Container#
-   * @default 'auto'
-   */
   accessiblePointerEvents: "auto",
-  /**
-   * Setting to false will prevent any children inside this container to
-   * be accessible. Defaults to true.
-   * @member {boolean}
-   * @memberof scene.Container#
-   * @default true
-   */
   accessibleChildren: true,
-  /**
-   * @member {number}
-   * @memberof scene.Container#
-   * @private
-   */
+  _accessibleActive: false,
+  _accessibleDiv: null,
   _renderId: -1
 };
 
@@ -858,7 +896,6 @@ class DOMPipe {
    * @param renderer - The renderer instance that this DOMPipe will be associated with.
    */
   constructor(renderer) {
-    this._destroyRenderableBound = this.destroyRenderable.bind(this);
     /** Array to keep track of attached DOM elements */
     this._attachedDomElements = [];
     this._renderer = renderer;
@@ -878,7 +915,6 @@ class DOMPipe {
   addRenderable(domContainer, _instructionSet) {
     if (!this._attachedDomElements.includes(domContainer)) {
       this._attachedDomElements.push(domContainer);
-      domContainer.on("destroyed", this._destroyRenderableBound);
     }
   }
   /**
@@ -895,17 +931,6 @@ class DOMPipe {
   validateRenderable(_domContainer) {
     return true;
   }
-  /**
-   * Destroys a renderable DOM container, removing it from the list of attached elements.
-   * @param domContainer - The DOM container to be destroyed.
-   */
-  destroyRenderable(domContainer) {
-    const index = this._attachedDomElements.indexOf(domContainer);
-    if (index !== -1) {
-      this._attachedDomElements.splice(index, 1);
-    }
-    domContainer.off("destroyed", this._destroyRenderableBound);
-  }
   /** Handles the post-rendering process, ensuring DOM elements are correctly positioned and visible. */
   postrender() {
     const attachedDomElements = this._attachedDomElements;
@@ -917,12 +942,14 @@ class DOMPipe {
     if (this._domElement.parentNode !== canvas.parentNode) {
       canvas.parentNode?.appendChild(this._domElement);
     }
-    this._domElement.style.transform = `translate(${canvas.offsetLeft}px, ${canvas.offsetTop}px)`;
+    const sx = parseFloat(canvas.style.width) / canvas.width * this._renderer.resolution;
+    const sy = parseFloat(canvas.style.height) / canvas.height * this._renderer.resolution;
+    this._domElement.style.transform = `translate(${canvas.offsetLeft}px, ${canvas.offsetTop}px) scale(${sx}, ${sy})`;
     for (let i = 0; i < attachedDomElements.length; i++) {
       const domContainer = attachedDomElements[i];
       const element = domContainer.element;
       if (!domContainer.parent || domContainer.globalDisplayStatus < 7) {
-        element.remove();
+        element?.remove();
         attachedDomElements.splice(i, 1);
         i--;
       } else {
@@ -946,8 +973,7 @@ class DOMPipe {
     this._renderer.runners.postrender.remove(this);
     for (let i = 0; i < this._attachedDomElements.length; i++) {
       const domContainer = this._attachedDomElements[i];
-      domContainer.off("destroyed", this._destroyRenderableBound);
-      domContainer.element.remove();
+      domContainer.element?.remove();
     }
     this._attachedDomElements.length = 0;
     this._domElement.remove();
@@ -1029,11 +1055,14 @@ class EventsTickerClass {
     if (this.events.supportsTouchEvents && rootPointerEvent.pointerType === "touch") {
       return;
     }
-    globalThis.document.dispatchEvent(new PointerEvent("pointermove", {
+    globalThis.document.dispatchEvent(this.events.supportsPointerEvents ? new PointerEvent("pointermove", {
       clientX: rootPointerEvent.clientX,
       clientY: rootPointerEvent.clientY,
       pointerType: rootPointerEvent.pointerType,
       pointerId: rootPointerEvent.pointerId
+    }) : new MouseEvent("mousemove", {
+      clientX: rootPointerEvent.clientX,
+      clientY: rootPointerEvent.clientY
     }));
   }
   /**
@@ -1066,7 +1095,7 @@ class FederatedMouseEvent extends FederatedEvent {
     /** The pointer coordinates in world space. */
     this.global = new Point();
     /**
-     * The pointer coordinates in the renderer's {@link Renderer.screen screen}. This has slightly
+     * The pointer coordinates in the renderer's {@link AbstractRenderer.screen screen}. This has slightly
      * different semantics than native PointerEvent screenX/screenY.
      */
     this.screen = new Point();
@@ -1118,29 +1147,46 @@ class FederatedMouseEvent extends FederatedEvent {
     return this.global.y;
   }
   /**
-   * The pointer coordinates in the renderer's screen. Alias for {@code screen.x}.
+   * The pointer coordinates in the renderer's screen. Alias for `screen.x`.
    * @readonly
    */
   get screenX() {
     return this.screen.x;
   }
   /**
-   * The pointer coordinates in the renderer's screen. Alias for {@code screen.y}.
+   * The pointer coordinates in the renderer's screen. Alias for `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
+   * Converts global coordinates into container-local coordinates.
+   *
+   * This method transforms coordinates from world space to a container's local space,
+   * useful for precise positioning and hit testing.
+   * @param container - The Container to get local coordinates for
+   * @param point - Optional Point object to store the result. If not provided, a new Point will be created
+   * @param globalPos - Optional custom global coordinates. If not provided, the event's global position is used
+   * @returns The local coordinates as a Point object
+   * @example
+   * ```ts
+   * // Basic usage - get local coordinates relative to a container
+   * sprite.on('pointermove', (event: FederatedMouseEvent) => {
+   *     // Get position relative to the sprite
+   *     const localPos = event.getLocalPosition(sprite);
+   *     console.log('Local position:', localPos.x, localPos.y);
+   * });
+   * // Using custom global coordinates
+   * const customGlobal = new Point(100, 100);
+   * sprite.on('pointermove', (event: FederatedMouseEvent) => {
+   *     // Transform custom coordinates
+   *     const localPos = event.getLocalPosition(sprite, undefined, customGlobal);
+   *     console.log('Custom local position:', localPos.x, localPos.y);
+   * });
+   * ```
+   * @see {@link Container.worldTransform} For the transformation matrix
+   * @see {@link Point} For the point class used to store coordinates
    */
   getLocalPosition(container, point, globalPos) {
     return container.worldTransform.applyInverse(globalPos || this.global, point);
@@ -1170,6 +1216,7 @@ class FederatedMouseEvent extends FederatedEvent {
    * @param _buttonArg
    * @param _relatedTargetArg
    * @deprecated since 7.0.0
+   * @ignore
    */
   // eslint-disable-next-line max-params
   initMouseEvent(_typeArg, _canBubbleArg, _cancelableArg, _viewArg, _detailArg, _screenXArg, _screenYArg, _clientXArg, _clientYArg, _ctrlKeyArg, _altKeyArg, _shiftKeyArg, _metaKeyArg, _buttonArg, _relatedTargetArg) {
@@ -1198,14 +1245,20 @@ class FederatedPointerEvent extends FederatedMouseEvent {
      */
     this.isPrimary = false;
   }
-  // Only included for completeness for now
+  /**
+   * Only included for completeness for now
+   * @ignore
+   */
   getCoalescedEvents() {
     if (this.type === "pointermove" || this.type === "mousemove" || this.type === "touchmove") {
       return [this];
     }
     return [];
   }
-  // Only included for completeness for now
+  /**
+   * Only included for completeness for now
+   * @ignore
+   */
   getPredictedEvents() {
     throw new Error("getPredictedEvents is not supported!");
   }
@@ -1214,19 +1267,37 @@ class FederatedPointerEvent extends FederatedMouseEvent {
 class FederatedWheelEvent extends FederatedMouseEvent {
   constructor() {
     super(...arguments);
-    /** Units specified in pixels. */
+    /**
+     * Units specified in pixels.
+     * @ignore
+     */
     this.DOM_DELTA_PIXEL = 0;
-    /** Units specified in lines. */
+    /**
+     * Units specified in lines.
+     * @ignore
+     */
     this.DOM_DELTA_LINE = 1;
-    /** Units specified in pages. */
+    /**
+     * Units specified in pages.
+     * @ignore
+     */
     this.DOM_DELTA_PAGE = 2;
   }
 }
-/** Units specified in pixels. */
+/**
+ * Units specified in pixels.
+ * @ignore
+ */
 FederatedWheelEvent.DOM_DELTA_PIXEL = 0;
-/** Units specified in lines. */
+/**
+ * Units specified in lines.
+ * @ignore
+ */
 FederatedWheelEvent.DOM_DELTA_LINE = 1;
-/** Units specified in pages. */
+/**
+ * Units specified in pages.
+ * @ignore
+ */
 FederatedWheelEvent.DOM_DELTA_PAGE = 2;
 
 const PROPAGATION_LIMIT = 2048;
@@ -1367,7 +1438,7 @@ class EventBoundary {
   }
   /**
    * Propagate the passed event from from {@link EventBoundary.rootTarget this.rootTarget} to its
-   * target {@code e.target}.
+   * target `e.target`.
    * @param e - The event to propagate.
    * @param type - The type of event to propagate. Defaults to `e.type`.
    */
@@ -1397,7 +1468,7 @@ class EventBoundary {
     }
   }
   /**
-   * Emits the event {@code e} to all interactive containers. The event is propagated in the bubbling phase always.
+   * Emits the event `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.
@@ -1418,7 +1489,7 @@ 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}.
+   * `target`. The last element in the path is `target`.
    * @param target - The target to find the propagation path to.
    */
   propagationPath(target) {
@@ -1934,10 +2005,10 @@ class EventBoundary {
     return currentTarget;
   }
   /**
-   * Creates an event whose {@code originalEvent} is {@code from}, with an optional `type` and `target` override.
+   * Creates an event whose `originalEvent` is `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 from - The `originalEvent` for the returned event.
    * @param [type=from.type] - The type of the returned event.
    * @param target - The target of the returned event.
    */
@@ -1955,7 +2026,7 @@ class EventBoundary {
     return event;
   }
   /**
-   * Creates a wheel event whose {@code originalEvent} is {@code from}.
+   * Creates a wheel event whose `originalEvent` is `from`.
    *
    * The event is allocated using {@link EventBoundary#allocateEvent this.allocateEvent}.
    * @param from - The upstream wheel event.
@@ -1971,7 +2042,7 @@ class EventBoundary {
     return event;
   }
   /**
-   * Clones the event {@code from}, with an optional {@code type} override.
+   * Clones the event `from`, with an optional `type` override.
    *
    * The event is allocated using {@link EventBoundary#allocateEvent this.allocateEvent}.
    * @param from - The event to clone.
@@ -1990,7 +2061,7 @@ class EventBoundary {
     return event;
   }
   /**
-   * Copies wheel {@link FederatedWheelEvent} data from {@code from} into {@code to}.
+   * Copies wheel {@link FederatedWheelEvent} data from `from` into `to`.
    *
    * The following properties are copied:
    * + deltaMode
@@ -2007,7 +2078,7 @@ class EventBoundary {
     to.deltaZ = from.deltaZ;
   }
   /**
-   * Copies pointer {@link FederatedPointerEvent} data from {@code from} into {@code to}.
+   * Copies pointer {@link FederatedPointerEvent} data from `from` into `to`.
    *
    * The following properties are copied:
    * + pointerId
@@ -2037,7 +2108,7 @@ class EventBoundary {
     to.twist = from.twist;
   }
   /**
-   * Copies mouse {@link FederatedMouseEvent} data from {@code from} to {@code to}.
+   * Copies mouse {@link FederatedMouseEvent} data from `from` to `to`.
    *
    * The following properties are copied:
    * + altKey
@@ -2073,7 +2144,7 @@ class EventBoundary {
     to.global.copyFrom(from.global);
   }
   /**
-   * Copies base {@link FederatedEvent} data from {@code from} into {@code to}.
+   * Copies base {@link FederatedEvent} data from `from` into `to`.
    *
    * The following properties are copied:
    * + isTrusted
@@ -2185,9 +2256,21 @@ const _EventSystem = class _EventSystem {
    * @param {Renderer} renderer
    */
   constructor(renderer) {
-    /** Does the device support touch events https://www.w3.org/TR/touch-events/ */
+    /**
+     * Indicates whether the current device supports touch events according to the W3C Touch Events spec.
+     * This is used to determine the appropriate event handling strategy.
+     * @see {@link https://www.w3.org/TR/touch-events/} W3C Touch Events Specification
+     * @readonly
+     * @default 'ontouchstart' in globalThis
+     */
     this.supportsTouchEvents = "ontouchstart" in globalThis;
-    /** Does the device support pointer events https://www.w3.org/Submission/pointer-events/ */
+    /**
+     * Indicates whether the current device supports pointer events according to the W3C Pointer Events spec.
+     * Used to optimize event handling and provide more consistent cross-device interaction.
+     * @see {@link https://www.w3.org/TR/pointerevents/} W3C Pointer Events Specification
+     * @readonly
+     * @default !!globalThis.PointerEvent
+     */
     this.supportsPointerEvents = !!globalThis.PointerEvent;
     /**
      * The DOM element to which the root event listeners are bound. This is automatically set to
@@ -2259,7 +2342,34 @@ const _EventSystem = class _EventSystem {
   }
   /**
    * Sets the current cursor mode, handling any callbacks or CSS style changes.
-   * @param mode - cursor mode, a key from the cursorStyles dictionary
+   * The cursor can be a CSS cursor string, a custom callback function, or a key from the cursorStyles dictionary.
+   * @param mode - Cursor mode to set. Can be:
+   * - A CSS cursor string (e.g., 'pointer', 'grab')
+   * - A key from the cursorStyles dictionary
+   * - null/undefined to reset to default
+   * @example
+   * ```ts
+   * // Using predefined cursor styles
+   * app.renderer.events.setCursor('pointer');    // Set standard pointer cursor
+   * app.renderer.events.setCursor('grab');       // Set grab cursor
+   * app.renderer.events.setCursor(null);         // Reset to default
+   *
+   * // Using custom cursor styles
+   * app.renderer.events.cursorStyles.custom = 'url("cursor.png"), auto';
+   * app.renderer.events.setCursor('custom');     // Apply custom cursor
+   *
+   * // Using callback-based cursor
+   * app.renderer.events.cursorStyles.dynamic = (mode) => {
+   *     document.body.style.cursor = mode === 'hover' ? 'pointer' : 'default';
+   * };
+   * app.renderer.events.setCursor('dynamic');    // Trigger cursor callback
+   * ```
+   * @remarks
+   * - Has no effect on OffscreenCanvas except for callback-based cursors
+   * - Caches current cursor to avoid unnecessary DOM updates
+   * - Supports CSS cursor values, style objects, and callback functions
+   * @see {@link EventSystem.cursorStyles} For defining custom cursor styles
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor} MDN Cursor Reference
    */
   setCursor(mode) {
     mode || (mode = "default");
@@ -2293,9 +2403,27 @@ const _EventSystem = class _EventSystem {
     }
   }
   /**
-   * The global pointer event.
-   * Useful for getting the pointer position without listening to events.
+   * The global pointer event instance containing the most recent pointer state.
+   * This is useful for accessing pointer information without listening to events.
+   * @example
+   * ```ts
+   * // Access current pointer position at any time
+   * const eventSystem = app.renderer.events;
+   * const pointer = eventSystem.pointer;
+   *
+   * // Get global coordinates
+   * console.log('Position:', pointer.global.x, pointer.global.y);
+   *
+   * // Check button state
+   * console.log('Buttons pressed:', pointer.buttons);
+   *
+   * // Get pointer type and pressure
+   * console.log('Type:', pointer.pointerType);
+   * console.log('Pressure:', pointer.pressure);
+   * ```
+   * @readonly
    * @since 7.2.0
+   * @see {@link FederatedPointerEvent} For all available pointer properties
    */
   get pointer() {
     return this._rootPointerEvent;
@@ -2387,9 +2515,30 @@ const _EventSystem = class _EventSystem {
   }
   /**
    * Sets the {@link EventSystem#domElement domElement} and binds event listeners.
+   * This method manages the DOM event bindings for the event system, allowing you to
+   * change or remove the target element that receives input events.
+   * > [!IMPORTANT] This will default to the canvas element of the renderer, so you
+   * > should not need to call this unless you are using a custom element.
+   * @param element - The new DOM element to bind events to, or null to remove all event bindings
+   * @example
+   * ```ts
+   * // Set a new canvas element as the target
+   * const canvas = document.createElement('canvas');
+   * app.renderer.events.setTargetElement(canvas);
+   *
+   * // Remove all event bindings
+   * app.renderer.events.setTargetElement(null);
    *
-   * To deregister the current DOM element without setting a new one, pass {@code null}.
-   * @param element - The new DOM element.
+   * // Switch to a different canvas
+   * const newCanvas = document.querySelector('#game-canvas');
+   * app.renderer.events.setTargetElement(newCanvas);
+   * ```
+   * @remarks
+   * - Automatically removes event listeners from previous element
+   * - Required for the event system to function
+   * - Safe to call multiple times
+   * @see {@link EventSystem#domElement} The current DOM element
+   * @see {@link EventsTicker} For the ticker system that tracks pointer movement
    */
   setTargetElement(element) {
     this._removeEvents();
@@ -2474,15 +2623,40 @@ const _EventSystem = class _EventSystem {
     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
+   * Maps coordinates from DOM/screen space into PixiJS normalized coordinates.
+   * This takes into account the current scale, position, and resolution of the DOM element.
+   * @param point - The point to store the mapped coordinates in
+   * @param x - The x coordinate in DOM/client space
+   * @param y - The y coordinate in DOM/client space
+   * @example
+   * ```ts
+   * // Map mouse coordinates to PixiJS space
+   * const point = new Point();
+   * app.renderer.events.mapPositionToPoint(
+   *     point,
+   *     event.clientX,
+   *     event.clientY
+   * );
+   * console.log('Mapped position:', point.x, point.y);
+   *
+   * // Using with pointer events
+   * sprite.on('pointermove', (event) => {
+   *     // event.global already contains mapped coordinates
+   *     console.log('Global:', event.global.x, event.global.y);
+   *
+   *     // Map to local coordinates
+   *     const local = event.getLocalPosition(sprite);
+   *     console.log('Local:', local.x, local.y);
+   * });
+   * ```
+   * @remarks
+   * - Accounts for element scaling and positioning
+   * - Adjusts for device pixel ratio/resolution
    */
   mapPositionToPoint(point, x, y) {
     const rect = this.domElement.isConnected ? this.domElement.getBoundingClientRect() : {
+      x: 0,
+      y: 0,
       width: this.domElement.width,
       height: this.domElement.height,
       left: 0,
@@ -2622,7 +2796,7 @@ const _EventSystem = class _EventSystem {
     return event;
   }
   /**
-   * Transfers base & mouse event data from the {@code nativeEvent} to the federated event.
+   * Transfers base & mouse event data from the `nativeEvent` to the federated event.
    * @param event
    * @param nativeEvent
    */
@@ -2658,8 +2832,22 @@ _EventSystem.extension = {
 };
 /**
  * The event features that are enabled by the EventSystem
- * (included in the **pixi.js** and **pixi.js-legacy** bundle), otherwise it will be ignored.
  * @since 7.2.0
+ * @example
+ * ```ts
+ * import { EventSystem, EventSystemFeatures } from 'pixi.js';
+ * // Access the default event features
+ * EventSystem.defaultEventFeatures = {
+ *     // Enable pointer movement events
+ *     move: true,
+ *     // Enable global pointer move events
+ *     globalMove: true,
+ *     // Enable click events
+ *     click: true,
+ *     // Enable wheel events
+ *     wheel: true,
+ * };
+ * ```
  */
 _EventSystem.defaultEventFeatures = {
   /** Enables pointer events associated with pointer movement. */
@@ -2674,455 +2862,57 @@ _EventSystem.defaultEventFeatures = {
 let EventSystem = _EventSystem;
 
 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: void 0,
-  /**
-   * 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() {
     return this._internalEventMode ?? EventSystem.defaultEventMode;
   },
   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 : void 0;
@@ -3142,14 +2932,6 @@ 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" ? void 0 : listener;
@@ -3157,17 +2939,6 @@ 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");