@kurot/core 1.0.12

package/dist/kurot/display/DisplayObject.js

@@ -0,0 +1,833 @@
+import { EventDispatcher } from '../events/EventDispatcher.js';
+import { Event } from '../events/Event.js';
+import { FocusEvent } from '../events/FocusEvent.js';
+import { TouchEvent } from '../events/TouchEvent.js';
+import { Matrix, sharedMatrix } from '../geom/Matrix.js';
+import { Rectangle, sharedRectangle } from '../geom/Rectangle.js';
+import { DisplayList } from '../player/canvas/DisplayList.js';
+import { blendModeToNumber, numberToBlendMode } from './enums/BlendMode.js';
+function clampRotation(value) {
+    value %= 360;
+    if (value > 180) {
+        value -= 360;
+    }
+    else if (value < -180) {
+        value += 360;
+    }
+    return value;
+}
+export class DisplayObject extends EventDispatcher {
+    // ── Static fields ─────────────────────────────────────────────────────────
+    static defaultTouchEnabled = false;
+    static $enterFrameCallBackList = [];
+    static $renderCallBackList = [];
+    static $eventAddToStageList = [];
+    static $eventRemoveFromStageList = [];
+    /**
+     * @internal
+     * Injected by Player at startup. Called when $renderMode changes (visible,
+     * filters, mask, blendMode) so the WebGLRenderer can mark its InstructionSet dirty.
+     *
+     * Single-Player engine: Player assigns this directly in its constructor and
+     * clears it in `destroy()`. There is intentionally no registration API.
+     */
+    static $onStructureChange;
+    /**
+     * @internal
+     * Injected by Player at startup. Called when a DisplayObject's visual data
+     * changes (position, texture, alpha, tint) but the scene structure is unchanged.
+     * The renderer uses this to update the transform snapshot in the InstructionSet
+     * without doing a full rebuild.
+     *
+     * Single-Player engine: Player assigns this directly in its constructor and
+     * clears it in `destroy()`. There is intentionally no registration API.
+     */
+    static $onRenderableDirty;
+    // ── Instance fields ───────────────────────────────────────────────────────
+    // 场景图
+    $hasAddToStage = false;
+    $children;
+    $parent;
+    $stage;
+    $nestLevel = 0;
+    // 变换
+    $x = 0;
+    $y = 0;
+    $anchorOffsetX = 0;
+    $anchorOffsetY = 0;
+    $explicitWidth = NaN;
+    $explicitHeight = NaN;
+    $useTranslate = false;
+    // 外观
+    $visible = true;
+    $alpha = 1;
+    $blendMode = 0;
+    $filters = [];
+    $cacheAsBitmap = false;
+    $touchEnabled = DisplayObject.defaultTouchEnabled;
+    // 遮罩
+    $mask;
+    $maskRect;
+    $scrollRect;
+    $maskedObject;
+    // 渲染状态
+    $renderMode;
+    $renderObjectType = 0 /* RenderObjectType.NONE */;
+    $renderDirty = false;
+    $cacheDirty = false;
+    $displayList;
+    // 世界缓存（$markDirty 更新，O(1) 读取）
+    $worldAlpha = 1;
+    $worldTint = 0xffffff;
+    $tintRGB = 0;
+    // 排序
+    $sortDirty = false;
+    $lastSortedIndex = 0;
+    // bounds 缓存
+    _boundsDirty = true;
+    _cachedBounds = new Rectangle();
+    // 私有
+    _name = '';
+    _matrix = new Matrix();
+    _matrixDirty = false;
+    _concatenatedMatrix;
+    _invertedConcatenatedMatrix;
+    _scaleX = 1;
+    _scaleY = 1;
+    _rotation = 0;
+    _skewX = 0;
+    _skewXdeg = 0;
+    _skewY = 0;
+    _skewYdeg = 0;
+    _tint = 0xffffff;
+    _zIndex = 0;
+    _sortableChildren = false;
+    _graphics;
+    // ── Constructor ───────────────────────────────────────────────────────────
+    constructor() {
+        super();
+        this.tint = 0xffffff;
+    }
+    // ── Getters / Setters ─────────────────────────────────────────────────────
+    get graphics() {
+        return this._graphics;
+    }
+    get name() {
+        return this._name;
+    }
+    set name(value) {
+        this._name = value;
+    }
+    get parent() {
+        return this.$parent;
+    }
+    get stage() {
+        return this.$stage;
+    }
+    get matrix() {
+        return this.$getMatrix().clone();
+    }
+    set matrix(value) {
+        this.$setMatrix(value);
+    }
+    get x() {
+        return this.$x;
+    }
+    set x(value) {
+        this.$setX(value);
+    }
+    get y() {
+        return this.$y;
+    }
+    set y(value) {
+        this.$setY(value);
+    }
+    get scaleX() {
+        return this._scaleX;
+    }
+    set scaleX(value) {
+        this.$setScaleX(value);
+    }
+    get scaleY() {
+        return this._scaleY;
+    }
+    set scaleY(value) {
+        this.$setScaleY(value);
+    }
+    get rotation() {
+        return this._rotation;
+    }
+    set rotation(value) {
+        this.$setRotation(value);
+    }
+    get skewX() {
+        return this._skewXdeg;
+    }
+    set skewX(value) {
+        this.$setSkewX(value);
+    }
+    get skewY() {
+        return this._skewYdeg;
+    }
+    set skewY(value) {
+        this.$setSkewY(value);
+    }
+    get width() {
+        return isNaN(this.$explicitWidth) ? this.$getOriginalBounds().width : this.$explicitWidth;
+    }
+    set width(value) {
+        this.$explicitWidth = isNaN(value) ? NaN : value;
+    }
+    get height() {
+        return isNaN(this.$explicitHeight) ? this.$getOriginalBounds().height : this.$explicitHeight;
+    }
+    set height(value) {
+        this.$explicitHeight = isNaN(value) ? NaN : value;
+    }
+    get measuredWidth() {
+        return this.$getOriginalBounds().width;
+    }
+    get measuredHeight() {
+        return this.$getOriginalBounds().height;
+    }
+    get anchorOffsetX() {
+        return this.$anchorOffsetX;
+    }
+    set anchorOffsetX(value) {
+        this.$setAnchorOffsetX(value);
+    }
+    get anchorOffsetY() {
+        return this.$anchorOffsetY;
+    }
+    set anchorOffsetY(value) {
+        this.$setAnchorOffsetY(value);
+    }
+    get visible() {
+        return this.$visible;
+    }
+    set visible(value) {
+        this.$setVisible(value);
+    }
+    get cacheAsBitmap() {
+        return this.isCachedAsTexture;
+    }
+    set cacheAsBitmap(value) {
+        this.cacheAsTexture(value);
+    }
+    /** PixiJS-style cache API. `cacheAsBitmap` remains an Egret-compatible alias. */
+    cacheAsTexture(value) {
+        if (value === false) {
+            this.$cacheAsBitmap = false;
+            this.$setHasDisplayList(false);
+            return;
+        }
+        this.$cacheAsBitmap = true;
+        this.$setHasDisplayList(true);
+        this.$displayList?.configure(value === true ? {} : value);
+        this.updateCacheTexture();
+    }
+    /** Marks cached content for regeneration on the next render. */
+    updateCacheTexture() {
+        if (!this.$displayList)
+            return;
+        this.$cacheDirty = true;
+        this.$cacheDirtyUp();
+    }
+    get isCachedAsTexture() {
+        return !!this.$displayList;
+    }
+    get filters() {
+        return this.$filters;
+    }
+    set filters(value) {
+        this.$filters = value ? [...value] : [];
+        this.$updateRenderMode();
+        this.$markDirty();
+    }
+    get alpha() {
+        return this.$alpha;
+    }
+    set alpha(value) {
+        this.$setAlpha(value);
+    }
+    get touchEnabled() {
+        return this.$touchEnabled;
+    }
+    set touchEnabled(value) {
+        this.$touchEnabled = !!value;
+    }
+    get scrollRect() {
+        return this.$scrollRect;
+    }
+    set scrollRect(value) {
+        this.$setScrollRect(value);
+    }
+    get blendMode() {
+        return numberToBlendMode(this.$blendMode);
+    }
+    set blendMode(value) {
+        const mode = blendModeToNumber(value);
+        if (this.$blendMode === mode) {
+            return;
+        }
+        this.$blendMode = mode;
+        this.$updateRenderMode();
+        this.$markDirty();
+    }
+    get mask() {
+        return this.$mask ?? this.$maskRect;
+    }
+    set mask(value) {
+        this.$setMask(value);
+    }
+    get tint() {
+        return this._tint;
+    }
+    set tint(value) {
+        this._tint = typeof value === 'number' && value >= 0 && value <= 0xffffff ? value : 0xffffff;
+        this.$tintRGB = (this._tint >> 16) + (this._tint & 0xff00) + ((this._tint & 0xff) << 16);
+        this.$markTransformDirty();
+    }
+    get zIndex() {
+        return this._zIndex;
+    }
+    set zIndex(value) {
+        this._zIndex = value;
+        if (this.parent) {
+            this.parent.$sortDirty = true;
+        }
+    }
+    get sortableChildren() {
+        return this._sortableChildren;
+    }
+    set sortableChildren(value) {
+        this._sortableChildren = value;
+    }
+    // ── Public methods ────────────────────────────────────────────────────────
+    getBounds(resultRect, calculateAnchor = true) {
+        resultRect = this.$getTransformedBoundsInternal(this, resultRect);
+        if (calculateAnchor) {
+            if (this.$anchorOffsetX !== 0) {
+                resultRect.x -= this.$anchorOffsetX;
+            }
+            if (this.$anchorOffsetY !== 0) {
+                resultRect.y -= this.$anchorOffsetY;
+            }
+        }
+        return resultRect;
+    }
+    getTransformedBounds(targetCoordinateSpace, resultRect) {
+        return this.$getTransformedBoundsInternal(targetCoordinateSpace ?? this, resultRect);
+    }
+    globalToLocal(stageX = 0, stageY = 0, resultPoint) {
+        return this.$getInvertedConcatenatedMatrix().transformPoint(stageX, stageY, resultPoint);
+    }
+    localToGlobal(localX = 0, localY = 0, resultPoint) {
+        return this.$getConcatenatedMatrix().transformPoint(localX, localY, resultPoint);
+    }
+    hitTestPoint(x, y, shapeFlag) {
+        if (this._scaleX === 0 || this._scaleY === 0) {
+            return false;
+        }
+        const m = this.$getInvertedConcatenatedMatrix();
+        const bounds = this.getBounds(undefined, false);
+        const localX = m.a * x + m.c * y + m.tx;
+        const localY = m.b * x + m.d * y + m.ty;
+        if (!bounds.contains(localX, localY)) {
+            return false;
+        }
+        const rect = this.$scrollRect ?? this.$maskRect;
+        if (rect && !rect.contains(localX, localY)) {
+            return false;
+        }
+        if (!shapeFlag) {
+            return true;
+        }
+        // Pixel-perfect: delegate to $hitTest which Shape/Sprite override
+        return this.$hitTest(x, y) !== undefined;
+    }
+    sortChildren() {
+        this.$sortDirty = false;
+    }
+    dispatchEvent(event) {
+        if (!event.bubbles) {
+            return super.dispatchEvent(event);
+        }
+        const list = this.$getPropagationList(this);
+        const targetIndex = list.length * 0.5;
+        event.setDispatchContext(this, 2 /* EventPhase.AT_TARGET */);
+        this.$dispatchPropagationEvent(event, list, targetIndex);
+        return !event.isDefaultPrevented();
+    }
+    willTrigger(type) {
+        let node = this;
+        while (node) {
+            if (node.hasEventListener(type)) {
+                return true;
+            }
+            node = node.$parent;
+        }
+        return false;
+    }
+    // Impl: type-erased to satisfy both overloads (see AnyListener in EventDispatcher)
+    addEventListener(type, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    listener, useCapture, priority) {
+        super.addEventListener(type, listener, useCapture, priority);
+        if (type === Event.ENTER_FRAME || type === Event.RENDER) {
+            const list = type === Event.ENTER_FRAME ? DisplayObject.$enterFrameCallBackList : DisplayObject.$renderCallBackList;
+            if (!list.includes(this)) {
+                list.push(this);
+            }
+        }
+    }
+    removeEventListener(type, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    listener, useCapture) {
+        super.removeEventListener(type, listener, useCapture);
+        if ((type === Event.ENTER_FRAME || type === Event.RENDER) && !this.hasEventListener(type)) {
+            const list = type === Event.ENTER_FRAME ? DisplayObject.$enterFrameCallBackList : DisplayObject.$renderCallBackList;
+            const index = list.indexOf(this);
+            if (index !== -1) {
+                list.splice(index, 1);
+            }
+        }
+    }
+    // ── Internal methods (used by subclasses and framework) ───────────────────
+    $setParent(parent) {
+        this.$parent = parent;
+    }
+    $onAddToStage(stage, $nestLevel) {
+        this.$stage = stage;
+        this.$nestLevel = $nestLevel;
+        this.$hasAddToStage = true;
+        DisplayObject.$eventAddToStageList.push(this);
+    }
+    $onRemoveFromStage() {
+        this.$nestLevel = 0;
+        this.$stage = undefined;
+        DisplayObject.$eventRemoveFromStageList.push(this);
+    }
+    $getMatrix() {
+        if (this._matrixDirty) {
+            this._matrixDirty = false;
+            this._matrix.updateScaleAndRotation(this._scaleX, this._scaleY, this._skewX, this._skewY);
+        }
+        this._matrix.tx = this.$x;
+        this._matrix.ty = this.$y;
+        return this._matrix;
+    }
+    $setMatrix(matrix, needUpdateProperties = true) {
+        const m = this._matrix;
+        m.a = matrix.a;
+        m.b = matrix.b;
+        m.c = matrix.c;
+        m.d = matrix.d;
+        this.$x = matrix.tx;
+        this.$y = matrix.ty;
+        this._matrixDirty = false;
+        this.$useTranslate = !(m.a === 1 && m.b === 0 && m.c === 0 && m.d === 1);
+        if (needUpdateProperties) {
+            this._scaleX = m.getScaleX();
+            this._scaleY = m.getScaleY();
+            this._skewX = matrix.getSkewX();
+            this._skewY = matrix.getSkewY();
+            this._skewXdeg = clampRotation((this._skewX * 180) / Math.PI);
+            this._skewYdeg = clampRotation((this._skewY * 180) / Math.PI);
+            this._rotation = clampRotation((this._skewY * 180) / Math.PI);
+        }
+        this.$markTransformDirty();
+    }
+    $getConcatenatedMatrix() {
+        if (!this._concatenatedMatrix) {
+            this._concatenatedMatrix = new Matrix();
+        }
+        const matrix = this._concatenatedMatrix;
+        if (this.$parent) {
+            this.$parent.$getConcatenatedMatrix().preMultiplyInto(this.$getMatrix(), matrix);
+        }
+        else {
+            matrix.copyFrom(this.$getMatrix());
+        }
+        const ox = this.$anchorOffsetX;
+        const oy = this.$anchorOffsetY;
+        const rect = this.$scrollRect;
+        if (rect) {
+            matrix.preMultiplyInto(sharedMatrix.setTo(1, 0, 0, 1, -rect.x - ox, -rect.y - oy), matrix);
+        }
+        else if (ox !== 0 || oy !== 0) {
+            matrix.preMultiplyInto(sharedMatrix.setTo(1, 0, 0, 1, -ox, -oy), matrix);
+        }
+        return matrix;
+    }
+    $getInvertedConcatenatedMatrix() {
+        if (!this._invertedConcatenatedMatrix) {
+            this._invertedConcatenatedMatrix = new Matrix();
+        }
+        this.$getConcatenatedMatrix().invertInto(this._invertedConcatenatedMatrix);
+        return this._invertedConcatenatedMatrix;
+    }
+    $setX(value) {
+        if (this.$x === value) {
+            return false;
+        }
+        this.$x = value;
+        this.$markTransformDirty();
+        return true;
+    }
+    $setY(value) {
+        if (this.$y === value) {
+            return false;
+        }
+        this.$y = value;
+        this.$markTransformDirty();
+        return true;
+    }
+    $setScaleX(value) {
+        if (this._scaleX === value) {
+            return;
+        }
+        this._scaleX = value;
+        this._matrixDirty = true;
+        this.$updateUseTransform();
+        this.$markTransformDirty();
+    }
+    $setScaleY(value) {
+        if (this._scaleY === value) {
+            return;
+        }
+        this._scaleY = value;
+        this._matrixDirty = true;
+        this.$updateUseTransform();
+        this.$markTransformDirty();
+    }
+    $setRotation(value) {
+        value = clampRotation(value);
+        if (value === this._rotation) {
+            return;
+        }
+        const delta = ((value - this._rotation) / 180) * Math.PI;
+        this._skewX += delta;
+        this._skewY += delta;
+        this._rotation = value;
+        this._matrixDirty = true;
+        this.$updateUseTransform();
+        this.$markTransformDirty();
+    }
+    $setSkewX(value) {
+        if (value === this._skewXdeg) {
+            return;
+        }
+        this._skewXdeg = value;
+        this._skewX = (clampRotation(value) / 180) * Math.PI;
+        this._matrixDirty = true;
+        this.$updateUseTransform();
+        this.$markTransformDirty();
+    }
+    $setSkewY(value) {
+        if (value === this._skewYdeg) {
+            return;
+        }
+        this._skewYdeg = value;
+        this._skewY = ((clampRotation(value) + this._rotation) / 180) * Math.PI;
+        this._matrixDirty = true;
+        this.$updateUseTransform();
+        this.$markTransformDirty();
+    }
+    $setAnchorOffsetX(value) {
+        if (this.$anchorOffsetX === value) {
+            return;
+        }
+        this.$anchorOffsetX = value;
+        this.$markTransformDirty();
+    }
+    $setAnchorOffsetY(value) {
+        if (this.$anchorOffsetY === value) {
+            return;
+        }
+        this.$anchorOffsetY = value;
+        this.$markTransformDirty();
+    }
+    $setVisible(value) {
+        if (this.$visible === value) {
+            return;
+        }
+        this.$visible = value;
+        this.$updateRenderMode();
+        this.$markTransformDirty();
+    }
+    $setAlpha(value) {
+        if (this.$alpha === value) {
+            return;
+        }
+        this.$alpha = value;
+        this.$updateRenderMode();
+        this.$markTransformDirty();
+    }
+    $setScrollRect(value) {
+        if (!value && !this.$scrollRect) {
+            return;
+        }
+        if (value) {
+            if (!this.$scrollRect) {
+                this.$scrollRect = new Rectangle();
+            }
+            this.$scrollRect.copyFrom(value);
+        }
+        else {
+            this.$scrollRect = undefined;
+        }
+        this.$updateRenderMode();
+        this.$markDirty();
+    }
+    $setHasDisplayList(value) {
+        const hasDisplayList = !!this.$displayList;
+        if (hasDisplayList === value) {
+            return;
+        }
+        if (value) {
+            const dl = DisplayList.create(this);
+            if (dl) {
+                this.$displayList = dl;
+                this.$cacheDirty = true;
+            }
+        }
+        else {
+            if (this.$displayList) {
+                DisplayList.release(this.$displayList);
+                this.$displayList = undefined;
+            }
+        }
+        // cacheAsBitmap toggle changes the instruction set structure:
+        // the subtree either collapses to a single displayListCache instruction
+        // or expands back to individual leaf instructions.
+        DisplayObject.$onStructureChange?.();
+        this.$markDirty();
+    }
+    $cacheDirtyUp() {
+        const p = this.$parent;
+        if (p && !p.$cacheDirty) {
+            p.$cacheDirty = true;
+            p._boundsDirty = true;
+            p.$cacheDirtyUp();
+        }
+    }
+    $renderDirtyUp() {
+        const p = this.$parent;
+        if (p && !p.$renderDirty) {
+            p.$renderDirty = true;
+            p.$renderDirtyUp();
+        }
+    }
+    $updateUseTransform() {
+        this.$useTranslate = !(this._scaleX === 1 && this._scaleY === 1 && this._skewX === 0 && this._skewY === 0);
+    }
+    $updateRenderMode() {
+        if (!this.$visible || this.$alpha <= 0 || this.$maskedObject) {
+            this.$renderMode = 1 /* RenderMode.NONE */;
+        }
+        else if (this.$filters.length > 0) {
+            this.$renderMode = 2 /* RenderMode.FILTER */;
+        }
+        else if (this.$blendMode !== 0 || (this.$mask && this.$mask.$stage)) {
+            this.$renderMode = 3 /* RenderMode.CLIP */;
+        }
+        else if (this.$scrollRect || this.$maskRect) {
+            this.$renderMode = 4 /* RenderMode.SCROLLRECT */;
+        }
+        else {
+            this.$renderMode = undefined;
+        }
+        // RenderMode change means the instruction set structure is stale.
+        DisplayObject.$onStructureChange?.();
+    }
+    $getOriginalBounds() {
+        if (!this._boundsDirty) {
+            return this._cachedBounds;
+        }
+        const bounds = this.$getContentBounds();
+        this.$measureChildBounds(bounds);
+        this._cachedBounds.copyFrom(bounds);
+        this._boundsDirty = false;
+        return this._cachedBounds;
+    }
+    $measureChildBounds(_bounds) { }
+    $getContentBounds() {
+        const bounds = sharedRectangle;
+        bounds.setEmpty();
+        this.$measureContentBounds(bounds);
+        return bounds;
+    }
+    $measureContentBounds(_bounds) { }
+    $getTransformedBoundsInternal(targetCoordinateSpace, resultRect) {
+        const bounds = this.$getOriginalBounds();
+        if (!resultRect) {
+            resultRect = new Rectangle();
+        }
+        resultRect.copyFrom(bounds);
+        if (targetCoordinateSpace === this) {
+            return resultRect;
+        }
+        const m = sharedMatrix;
+        targetCoordinateSpace.$getInvertedConcatenatedMatrix().preMultiplyInto(this.$getConcatenatedMatrix(), m);
+        m.transformBounds(resultRect);
+        return resultRect;
+    }
+    $getConcatenatedMatrixAt(root, matrix) {
+        const invertMatrix = root.$getInvertedConcatenatedMatrix();
+        if ((invertMatrix.a === 0 || invertMatrix.d === 0) && (invertMatrix.b === 0 || invertMatrix.c === 0)) {
+            let target = this;
+            const rootLevel = root.$nestLevel;
+            matrix.identity();
+            while (target.$nestLevel > rootLevel) {
+                const rect = target.$scrollRect;
+                if (rect)
+                    matrix.concat(sharedMatrix.setTo(1, 0, 0, 1, -rect.x, -rect.y));
+                matrix.concat(target.$getMatrix());
+                target = target.$parent;
+            }
+        }
+        else {
+            invertMatrix.preMultiplyInto(matrix, matrix);
+        }
+    }
+    $hitTest(stageX, stageY) {
+        if (!this.$visible || this._scaleX === 0 || this._scaleY === 0) {
+            return undefined;
+        }
+        const m = this.$getInvertedConcatenatedMatrix();
+        if (m.a === 0 && m.b === 0 && m.c === 0 && m.d === 0) {
+            return undefined;
+        }
+        const bounds = this.$getContentBounds();
+        const localX = m.a * stageX + m.c * stageY + m.tx;
+        const localY = m.b * stageX + m.d * stageY + m.ty;
+        if (bounds.contains(localX, localY)) {
+            if (!this.$children) {
+                const rect = this.$scrollRect ?? this.$maskRect;
+                if (rect && !rect.contains(localX, localY)) {
+                    return undefined;
+                }
+                if (this.$mask && !this.$mask.$hitTest(stageX, stageY)) {
+                    return undefined;
+                }
+            }
+            return this;
+        }
+        return undefined;
+    }
+    $updateRenderNode() { }
+    $getPropagationList(target) {
+        const list = [];
+        let current = target;
+        while (current) {
+            list.push(current);
+            current = current.$parent;
+        }
+        return [...[...list].reverse(), ...list];
+    }
+    $dispatchPropagationEvent(event, list, targetIndex) {
+        for (let i = 0; i < list.length; i++) {
+            const currentTarget = list[i];
+            let phase;
+            if (i < targetIndex - 1) {
+                phase = 1 /* EventPhase.CAPTURING_PHASE */;
+            }
+            else if (i > targetIndex) {
+                phase = 3 /* EventPhase.BUBBLING_PHASE */;
+            }
+            else {
+                phase = 2 /* EventPhase.AT_TARGET */;
+            }
+            event.setCurrentTarget(currentTarget);
+            event.setDispatchContext(currentTarget, phase);
+            currentTarget.notifyListener(event, i < targetIndex);
+            if (event.isPropagationStopped || event.isPropagationImmediateStopped) {
+                return;
+            }
+        }
+    }
+    // ── Private methods ───────────────────────────────────────────────────────
+    $setMask(value) {
+        if (value === this) {
+            return;
+        }
+        const previousMask = this.$mask;
+        if (value instanceof DisplayObject) {
+            if (value === previousMask) {
+                return;
+            }
+            if (value.$maskedObject) {
+                value.$maskedObject.mask = undefined;
+            }
+            if (previousMask) {
+                previousMask.$maskedObject = undefined;
+                previousMask.$updateRenderMode();
+            }
+            value.$maskedObject = this;
+            value.$updateRenderMode();
+            this.$mask = value;
+            this.$maskRect = undefined;
+        }
+        else {
+            if (previousMask) {
+                previousMask.$maskedObject = undefined;
+                previousMask.$updateRenderMode();
+            }
+            this.$mask = undefined;
+            if (value instanceof Rectangle) {
+                if (!this.$maskRect) {
+                    this.$maskRect = new Rectangle();
+                }
+                this.$maskRect.copyFrom(value);
+            }
+            else {
+                this.$maskRect = undefined;
+            }
+        }
+        this.$updateRenderMode();
+        this.$markDirty();
+    }
+    $markDirty() {
+        this.$renderDirty = true;
+        this.$markTransformDirty();
+    }
+    /** Marks world placement/color dirty without invalidating this object's cached pixels. */
+    $markTransformDirty() {
+        this._boundsDirty = true;
+        // Update cached world alpha and tint so _refreshLeafTransform can read
+        // them in O(1) without walking the parent chain.
+        let alpha = this.$alpha;
+        let tint = this.$tintRGB;
+        let p = this.$parent;
+        while (p) {
+            alpha *= p.$alpha;
+            // Rendering applies the closest non-default tint: an object's own tint
+            // overrides its parent, otherwise it inherits the nearest tinted ancestor.
+            if (tint === 0xffffff && p.$tintRGB !== 0xffffff) {
+                tint = p.$tintRGB;
+            }
+            p = p.$parent;
+        }
+        this.$worldAlpha = alpha;
+        this.$worldTint = tint;
+        // Notify the renderer that this object's data changed.
+        DisplayObject.$onRenderableDirty?.(this);
+        const parent = this.$parent;
+        if (parent && !parent.$cacheDirty) {
+            parent.$cacheDirty = true;
+            parent._boundsDirty = true;
+            parent.$cacheDirtyUp();
+        }
+        if (parent && !parent.$renderDirty) {
+            parent.$renderDirty = true;
+            parent.$renderDirtyUp();
+        }
+        const masked = this.$maskedObject;
+        if (masked && !masked.$cacheDirty) {
+            masked.$cacheDirty = true;
+            masked.$cacheDirtyUp();
+        }
+    }
+}
+//# sourceMappingURL=DisplayObject.js.map